Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 12 additions & 6 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,20 +71,22 @@ $ 3 commits ←─ Terminal ←─ Format ←─ Compact Sta
4. **Fail-Safe**: If filtering fails, fall back to original output
5. **Transparent**: Users can always see raw output with `-v` flags

### Hook Architecture (v0.9.5+)
### Hook/Plugin Architecture (v0.9.5+)

The recommended deployment mode uses a Claude Code PreToolUse hook for 100% transparent command rewriting.
The recommended deployment mode uses platform-specific hooks for 100% transparent command rewriting:
- **Claude Code**: PreToolUse hook (`rtk-rewrite.sh`) registered in `settings.json`
- **OpenCode**: TypeScript plugin (`rtk-rewrite.ts`) auto-loaded from `~/.config/opencode/plugins/`

```
┌────────────────────────────────────────────────────────────────────────┐
│ Hook-Based Command Rewriting │
└────────────────────────────────────────────────────────────────────────┘

Claude Code settings.json rtk-rewrite.sh RTK binary
AI Agent Hook/Plugin Rewrite Logic RTK binary
│ │ │ │
│ Bash: "git status" │ │ │
│ ─────────────────────►│ │ │
│ │ PreToolUse hook │ │
│ │ Intercept trigger │ │
│ │ ───────────────────►│ │
│ │ │ detect: git │
│ │ │ rewrite: │
Expand All @@ -99,12 +101,16 @@ Claude Code settings.json rtk-rewrite.sh RTK binary
│◄──────────────────────────────────────────────────────────────────
│ "3 modified, 1 untracked ✓" (~10 tokens vs ~200 raw)
Claude never sees the rewrite — it only sees optimized output.
The agent never sees the rewrite — it only sees optimized output.

Files:
Files (Claude Code):
~/.claude/hooks/rtk-rewrite.sh ← shell script (command detection + rewrite)
~/.claude/settings.json ← hook registry (PreToolUse registration)
~/.claude/RTK.md ← minimal context hint (10 lines)

Files (OpenCode):
~/.config/opencode/plugins/rtk-rewrite.ts ← TS plugin (auto-loaded)
~/.config/opencode/AGENTS.md ← rules file (optional)
```

Two hook strategies:
Expand Down
18 changes: 9 additions & 9 deletions INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ rtk gain # MUST show token savings, not "command not found"
### Which mode to choose?

```
Do you want RTK active across ALL Claude Code projects?
Do you want RTK active across ALL AI agent projects?
├─ YES → rtk init -g (recommended)
│ Hook + RTK.md (~10 tokens in context)
Expand Down Expand Up @@ -110,14 +110,14 @@ rtk init --show # Check hook is installed and executable
**Token savings**: ~99.5% reduction (2000 tokens → 10 tokens in context)

**What is settings.json?**
Claude Code's hook registry. RTK adds a PreToolUse hook that rewrites commands transparently. Without this, Claude won't invoke the hook automatically.
Claude Code's hook registry (OpenCode uses auto-loaded plugins instead). RTK adds a PreToolUse hook that rewrites commands transparently. Without this, the hook won't be invoked automatically.

```
Claude Code settings.json rtk-rewrite.sh RTK binary
AI Agent Hook/Plugin Rewrite Logic RTK binary
│ │ │ │
│ "git status" │ │ │
│ ──────────────────►│ │ │
│ │ PreToolUse trigger │ │
│ │ Intercept trigger │ │
│ │ ───────────────────►│ │
│ │ │ rewrite command │
│ │ │ → rtk git status │
Expand Down Expand Up @@ -172,7 +172,7 @@ rtk init -g
# → Answer 'y' when prompted to patch settings.json
# → Creates backup automatically

# 3. Restart Claude Code
# 3. Restart your AI agent (Claude Code or OpenCode)
# 4. Test: git status (should use rtk)
```

Expand All @@ -191,8 +191,8 @@ rtk init --show | grep "Hook:"
rtk init -g --no-patch

# Review printed JSON snippet
# Manually edit ~/.claude/settings.json
# Restart Claude Code
# Manually edit ~/.claude/settings.json (Claude Code only)
# Restart your AI agent
```

### Temporary Trial
Expand Down Expand Up @@ -237,7 +237,7 @@ rtk init -g --uninstall
# - Reference: @RTK.md line from ~/.claude/CLAUDE.md
# - Registration: RTK hook entry from settings.json

# Restart Claude Code after uninstall
# Restart your AI agent after uninstall
```

**For Local Projects**: Manually remove RTK block from `./CLAUDE.md`
Expand Down Expand Up @@ -309,7 +309,7 @@ rtk gain --history # With command history
| `pnpm list` | ~8,000 tokens | ~2,400 | **-70%** |
| `pnpm outdated` | ~12,000 tokens | ~1,200-2,400 | **-80-90%** |

### Typical Claude Code Session (30 min)
### Typical AI Agent Session (30 min)
- **Without RTK**: ~150,000 tokens
- **With RTK**: ~45,000 tokens
- **Savings**: **70% reduction**
Expand Down
Loading