Configuration

Configuration File

RTK reads configuration from ~/.config/rtk/config.toml. The file is optional — RTK uses sensible defaults if not present.

Location

~/.config/rtk/config.toml

On macOS/Linux, this resolves to:

macOS: /Users/<username>/.config/rtk/config.toml
Linux: /home/<username>/.config/rtk/config.toml

View Current Config

rtk config

Output:

Config: /Users/you/.config/rtk/config.toml

[tracking]
enabled = true
history_days = 90

[display]
colors = true
emoji = true
max_width = 120

[filters]
ignore_dirs = [".git", "node_modules", "target", "__pycache__", ".venv", "vendor"]
ignore_files = ["*.lock", "*.min.js", "*.min.css"]

[tee]
enabled = true
mode = "failures"
max_files = 20
max_file_size = 1048576

Create Default Config

rtk config --create

This writes the default configuration to ~/.config/rtk/config.toml if it doesn’t exist.

Configuration Sections

Tracking

Controls token savings tracking and analytics.

[tracking]
enabled = true          # Enable/disable tracking
history_days = 90       # Retention period (days)
database_path = "/custom/path/history.db"  # Optional: custom DB location

Options

enabled (boolean): Enable token tracking. Default: true
history_days (integer): How long to retain tracking data. Default: 90
database_path (string): Custom database location. Default: ~/.local/share/rtk/history.db

Disabling tracking (enabled = false) disables rtk gain and all analytics commands.

Display

Controls output formatting.

[display]
colors = true           # ANSI colors in output
emoji = true            # Emoji in output (✅ ❌ ✓)
max_width = 120         # Max line width for wrapping

Options

colors (boolean): Use ANSI colors. Default: true
emoji (boolean): Use emoji in output. Default: true
max_width (integer): Max line width before wrapping. Default: 120

Filters

Controls which files/directories to ignore in rtk ls, rtk grep, etc.

[filters]
ignore_dirs = [
  ".git",
  "node_modules",
  "target",
  "__pycache__",
  ".venv",
  "vendor"
]
ignore_files = [
  "*.lock",
  "*.min.js",
  "*.min.css"
]

Options

ignore_dirs (array of strings): Directory names to skip
ignore_files (array of strings): File patterns to skip (supports * wildcards)

Tee

Controls full output recovery for commands that fail.

[tee]
enabled = true          # Enable tee feature
mode = "failures"       # When to save: "failures", "always", "never"
max_files = 20          # Max files to keep (oldest rotated out)
max_file_size = 1048576 # 1MB max per file
# directory = "/custom/path"  # Optional: custom tee directory

Options

enabled (boolean): Enable tee feature. Default: true
mode (string): When to save output:
- "failures": Only on non-zero exit code (default)
- "always": Save all command outputs
- "never": Disable tee completely
max_files (integer): Max files to keep. Default: 20
max_file_size (integer): Max bytes per file. Default: 1048576 (1MB)
directory (string): Custom tee directory. Default: ~/.local/share/rtk/tee/

Tee saves raw unfiltered output to a file when commands fail, so LLMs can read the full error instead of re-running the command.

Environment Variables

Environment variables override config file settings.

Database Path

RTK_DB_PATH: Override tracking database location.

export RTK_DB_PATH="/tmp/rtk-test.db"
rtk gain  # Uses /tmp/rtk-test.db instead of default

Priority: RTK_DB_PATH > config.toml:tracking.database_path > default location

Tee Configuration

RTK_TEE: Enable/disable tee feature.

export RTK_TEE=0
rtk cargo test  # Tee disabled for this session

RTK_TEE_DIR: Override tee output directory.

export RTK_TEE_DIR="/tmp/rtk-tee"
rtk cargo test  # Saves tee files to /tmp/rtk-tee/

Hook Audit Logging

RTK_HOOK_AUDIT: Enable hook audit logging.

export RTK_HOOK_AUDIT=1
# All hook invocations logged to ~/.local/share/rtk/hook-audit.log

RTK_AUDIT_DIR: Override audit log directory.

export RTK_AUDIT_DIR="/tmp/rtk-audit"
export RTK_HOOK_AUDIT=1
# Logs to /tmp/rtk-audit/hook-audit.log

Custom Database Path

By default, RTK stores tracking data in ~/.local/share/rtk/history.db. You can customize this in two ways:

Method 1: Environment Variable

export RTK_DB_PATH="/path/to/custom.db"

Add to shell profile (.bashrc, .zshrc) to persist:

echo 'export RTK_DB_PATH="/path/to/custom.db"' >> ~/.bashrc

Method 2: Config File

Edit ~/.config/rtk/config.toml:

[tracking]
database_path = "/path/to/custom.db"

Priority Order

RTK_DB_PATH environment variable (highest priority)
config.toml tracking.database_path field
Default: ~/.local/share/rtk/history.db

Use Cases

Per-project tracking: export RTK_DB_PATH="./rtk-project.db"
Shared team analytics: export RTK_DB_PATH="/mnt/shared/rtk.db"
Testing: export RTK_DB_PATH="/tmp/rtk-test.db"

Tee Configuration

When RTK filters command output, LLM agents lose failure details (stack traces, assertion messages). The tee feature saves raw output to a file on failure.

How It Works

On command failure (exit code ≠ 0), RTK:

Writes full unfiltered output to ~/.local/share/rtk/tee/<timestamp>_<cmd>.log
Prints a hint: [full output: ~/.local/share/rtk/tee/1707753600_cargo_test.log]
LLM reads the file instead of re-running the command

Result: Token savings without losing error context.

Edit ~/.config/rtk/config.toml:

[tee]
enabled = true          # Enable tee feature
mode = "failures"       # "failures" (default), "always", "never"
max_files = 20          # Max files to keep (FIFO rotation)
max_file_size = 1048576 # 1MB max per file
# directory = "/custom/path"  # Optional: custom directory

Modes

[tee]
mode = "failures"  # Only save output when exit code != 0

[tee]
mode = "always"  # Save all command outputs (use for debugging)

[tee]
mode = "never"  # Disable tee completely

Environment Overrides

# Disable tee for this session
export RTK_TEE=0
rtk cargo test

# Custom tee directory
export RTK_TEE_DIR="/tmp/rtk-tee"
rtk cargo test

Supported Commands

Tee works with:

Cargo: build, test, clippy, check, install, nextest
JavaScript: vitest, playwright, tsc, lint, prettier
Python: pytest, ruff, mypy
Go: go test, go build, go vet, golangci-lint
Generic: rtk test, rtk err

File Rotation

Tee files are automatically rotated:

max_files: Oldest files deleted when limit reached
max_file_size: Outputs larger than limit are truncated

Default: 20 files, 1MB each (20MB total).

Installation Modes and Flags

RTK supports multiple installation modes for Claude Code integration.

Installation Modes

rtk init --global
# Installs: hook + RTK.md + @RTK.md + settings.json
# Context: 10 tokens

rtk init --global --claude-md
# Installs: full injection into CLAUDE.md
# Context: 2000 tokens

rtk init --global --hook-only
# Installs: hook only, no RTK.md
# Context: 0 tokens

rtk init
# Installs: full injection into ./CLAUDE.md
# Scope: current project only

Settings.json Patching Flags

Control how rtk init --global handles ~/.claude/settings.json:

rtk init -g                 # Default: prompt [y/N]
rtk init -g --auto-patch    # Patch immediately without prompting
rtk init -g --no-patch      # Skip patching, print manual instructions

Mode Flags

rtk init -g --claude-md     # Legacy: full 137-line injection
rtk init -g --hook-only     # Hook only, no RTK.md

Uninstall Flag

rtk init -g --uninstall     # Remove all RTK artifacts

Removes:

~/.claude/hooks/rtk-rewrite.sh
~/.claude/RTK.md
@RTK.md reference from ~/.claude/CLAUDE.md
RTK hook entry from ~/.claude/settings.json

Restart Claude Code after uninstalling.

Verification

Check current installation:

rtk init --show

Output shows:

Hook status (installed, executable, guards present)
RTK.md status
Integrity verification
CLAUDE.md status (global and local)
settings.json status

Uninstall Procedure

Complete Removal

rtk init --global --uninstall

This removes:

✅ Hook script (~/.claude/hooks/rtk-rewrite.sh)
✅ Integrity hash (SHA-256 baseline for hook verification)
✅ RTK.md (~/.claude/RTK.md)
✅ @RTK.md reference from ~/.claude/CLAUDE.md
✅ Hook entry from ~/.claude/settings.json

Restart Claude Code after uninstalling.

Restore from Backup

If uninstall causes issues, restore settings.json from backup:

cp ~/.claude/settings.json.bak ~/.claude/settings.json

Backups are created automatically by rtk init --global.

Local Projects

For local installations (rtk init without --global):

# Manually remove RTK instructions from CLAUDE.md
rm CLAUDE.md  # or edit to remove RTK block

Binary Removal

To remove the RTK binary:

brew uninstall rtk

cargo uninstall rtk

sudo apt remove rtk

sudo dnf remove rtk

rm ~/.local/bin/rtk

Data Removal

RTK stores data in:

Tracking database: ~/.local/share/rtk/history.db
Tee files: ~/.local/share/rtk/tee/
Config file: ~/.config/rtk/config.toml
Hook audit logs: ~/.local/share/rtk/hook-audit.log

To remove all data:

rm -rf ~/.local/share/rtk
rm -rf ~/.config/rtk

Configuration Examples

Example 1: Minimal Context, No Tracking

[tracking]
enabled = false  # Disable all analytics

[tee]
mode = "never"  # No tee files

Use case: CI/CD, no persistent state.

Example 2: Maximum Debugging

[tracking]
enabled = true

[tee]
mode = "always"  # Save all outputs
max_files = 100  # Keep more files

Environment:

export RTK_HOOK_AUDIT=1  # Enable hook audit logging

Use case: Debugging RTK behavior, investigating filter issues.

Example 3: Team Shared Analytics

[tracking]
database_path = "/mnt/shared/team-rtk.db"

Use case: Centralized token savings analytics for a team.

Example 4: Per-Project Tracking

# In project root:
export RTK_DB_PATH="./rtk-project.db"
rtk gain  # Shows project-specific analytics

Use case: Track token savings per-project without mixing data.

Next Steps

Claude Code Setup

Install RTK hook for Claude Code

Hook Architecture

Learn how auto-rewrite hooks work

​Configuration File

​Location

​View Current Config

​Create Default Config

​Configuration Sections

​Tracking

​Options

​Display

​Options

​Filters

​Options

​Tee

​Options

​Environment Variables

​Database Path

​Tee Configuration

​Hook Audit Logging

​Custom Database Path

​Method 1: Environment Variable

​Method 2: Config File

​Priority Order

​Use Cases

​Tee Configuration

​How It Works

​Configuration

​Modes

​Environment Overrides

​Supported Commands

​File Rotation

​Installation Modes and Flags

​Installation Modes

​Settings.json Patching Flags

​Mode Flags

​Uninstall Flag

​Verification

​Uninstall Procedure

​Complete Removal

​Restore from Backup

​Local Projects

​Binary Removal

​Data Removal

​Configuration Examples

​Example 1: Minimal Context, No Tracking

​Example 2: Maximum Debugging

​Example 3: Team Shared Analytics

​Example 4: Per-Project Tracking

​Next Steps

Claude Code Setup

Hook Architecture

Configuration File

Location

View Current Config

Create Default Config

Configuration Sections

Tracking

Options

Display

Options

Filters

Options

Tee

Options

Environment Variables

Database Path

Tee Configuration

Hook Audit Logging

Custom Database Path

Method 1: Environment Variable

Method 2: Config File

Priority Order

Use Cases

Tee Configuration

How It Works

Configuration

Modes

Environment Overrides

Supported Commands

File Rotation

Installation Modes and Flags

Installation Modes

Settings.json Patching Flags

Mode Flags

Uninstall Flag

Verification

Uninstall Procedure

Complete Removal

Restore from Backup

Local Projects

Binary Removal

Data Removal

Configuration Examples

Example 1: Minimal Context, No Tracking

Example 2: Maximum Debugging

Example 3: Team Shared Analytics

Example 4: Per-Project Tracking

Next Steps