Token Pilot

Token-efficient AI coding, enforced. Cuts context consumption in AI coding assistants by up to 90% without changing the way you work.

Why it matters more now: as frontier models move up in price, the tokens you don't spend reading code are worth more, not less. The savings are in tokens; the value is in tokens × price. Token Pilot keeps the expensive main thread lean so the premium model spends its budget on reasoning, not on re-reading files.

Three layers, each useful on its own, stronger together:

1. MCP tools — structural reads (smart_read, read_symbol, read_for_edit, …). Ask for an outline or load one function by name instead of the whole file.
2. PreToolUse hooks — intercept heavy native tool calls (Read on large files, recursive Grep, unbounded git diff) and redirect to token-efficient alternatives.
3. tp-* subagents — Claude Code delegates with MCP-first behaviour and tight response budgets.

How It Works

Traditional:  Read("user-service.ts")  →  500 lines  →  ~3000 tokens
Token Pilot:  smart_read("user-service.ts")  →  15-line outline  →  ~200 tokens
              read_symbol("UserService.updateUser")  →  45 lines  →  ~350 tokens
              After edit: read_diff("user-service.ts")  →  ~20 tokens

Files under 200 lines are returned in full — zero overhead for small files.

Benchmarks

Measured on public open-source repos. Files ≥50 lines only:

smart_read outline savings only. Real sessions additionally benefit from session cache, read_symbol, and read_for_edit. Reproduce: npx tsx scripts/benchmark.ts.

Quick Start

npx -y token-pilot init

Creates (or merges into) .mcp.json with token-pilot + context-mode, then prompts to install tp-* subagents. Restart your AI assistant to activate.

What You Get

• 25 MCP tools — structural reads, symbol search, git analysis, module routing, session analytics → tools reference
• PreToolUse hooks — block heavy Grep/Bash/Read calls; redirect to efficient alternatives → hooks & modes
• 25 tp-* subagents (Claude Code only) — MCP-first delegates with haiku/sonnet model tiers and budget enforcement → agents reference
• Tool profiles — trim advertised tools/list to save ~2 k tokens per session → profiles & config

Client Support Matrix

Hooks are written for Claude Code (the plugin's own hooks/hooks.json, or ~/.claude/settings.json for an npm install) and for Codex CLI (npx token-pilot install-hook --client=codex, then /hooks inside Codex to trust them). The other clients get the MCP tools; their hook systems exist but token-pilot does not write to them yet.

Manual config snippets for each client → installation guide

Enforcement Mode

TOKEN_PILOT_MODE controls how aggressively Token Pilot redirects heavy native tool calls:

TOKEN_PILOT_MODE=strict npx token-pilot

→ Full hook & mode docs

Ecosystem

Token Pilot owns input tokens — the stuff Claude reads from files, git, search. The other half of a session (what Claude writes back, how it executes code, how it remembers state across days) is owned by separate tools. They compose cleanly:

A session that pairs token-pilot + caveman typically hits ~85-90% total reduction — each cuts a different half, no overlap. Install what you need; none of them assume the others are present.

→ full ecosystem map

Rules of thumb: read code → smart_read/read_symbol; execute code with big output → context-mode execute; bash-only agent → ast-index CLI. Never copy the whole stack into CLAUDE.md — Token Pilot's doctor warns when CLAUDE.md exceeds 60 lines.

Supported Languages

TypeScript, JavaScript, Python, Go, Rust, Java, Kotlin, C#, C/C++, PHP, Ruby. Non-code (JSON/YAML/Markdown/TOML) gets structural summaries. Regex fallback handles most other languages.

Update / New Machine

Claude Code (plugin — recommended):

# Install on a new machine:
claude plugin marketplace add https://github.com/Digital-Threads/token-pilot
claude plugin install token-pilot@token-pilot

# Update to latest:
claude plugin update token-pilot

Other clients (Cursor, Codex, Cline, …):

# Install on a new machine:
npx -y token-pilot init

# Update to latest — npx always pulls fresh, just restart your client.
# Or if installed globally:
npm i -g token-pilot@latest
npx token-pilot install-hook
npx token-pilot install-agents --scope=user --force

Tips for Claude Code 2.1.139+

The May 2026 Claude Code update changed a few things that affect how token-pilot is invoked. Nothing breaks on older versions — these are quality-of-life notes for the newer ones.

• Run a tp-* agent directly without the plugin: prefix. claude --agent tp-debugger "fix the stack trace" now works the same as --agent token-pilot:tp-debugger. The Task tool dispatcher resolves the short name automatically.

• Cold ast-index calls — raise MCP_TOOL_TIMEOUT. The first find_usages / outline / read_symbol on a large repo triggers an index build. Default per-MCP-tool timeout (60 s) is enough for ~50k-file repos; bigger ones benefit from MCP_TOOL_TIMEOUT=120000 in ~/.claude/settings.json. Subsequent calls hit the cache and return in ~50 ms.

• Background sessions with --mcp-config. Dispatching a worker via claude agents or --bg with --mcp-config /path/to/other.json swaps the MCP set for that session. If token-pilot is not in the override config, MCP tools (smart_read, find_usages, …) are unavailable in that worker even though the hooks (Read / Edit / Bash / Grep / Task) still fire — hooks are project-level, MCP tools are session-level. Add token-pilot to the override config or skip --mcp-config.

• claude plugin details token-pilot. Shows the projected per-turn token cost, the hook event names, and the MCP server entry. The skill list, the agent list, and the LSP list are all auto-discovered from the canonical sub-folders.

Power-user — undocumented Claude Code features that pair with token-pilot

These fields come from reverse-engineering @anthropic-ai/claude-code@2.1.87 source (see the May 2026 Habr write-up). They work today but are not in the official Claude Code docs, so use at your own risk.

Persistent agent memory (memory: project)

Every relevant tp-* agent (onboard, debugger, pr-reviewer, history-explorer, audit-scanner) now ships with memory: project in its frontmatter. Claude Code persists the agent's working notes in the project so the agent gets faster on repeat invocations — tp-onboard remembers your layout, tp-pr-reviewer remembers your flagged patterns, etc. v0.35.0+.

Required MCP gating (requiredMcpServers)

Every tp-* agent declares requiredMcpServers: ["token-pilot"]. Claude Code refuses to load the agent when the MCP server isn't configured, so a stale install never produces a "tools not found" loop. v0.35.0+.

Bootstrap-once hook (once: true)

The plugin ships a SessionStart hook flagged once: true — Claude Code runs it once per project then auto-removes the entry. It surfaces friendly hints when install-agents or install-ast-index hasn't been run yet. v0.35.0+.

Async telemetry (async: true)

PostToolUse hooks (Bash, Task) are marked async: true so they no longer add wall-clock to the hot path — telemetry writes fire in the background.

Auto-mode permissions (user-side)

If you want full auto-approval for safe commands, the YOLO classifier reads natural-language environment descriptions:

{
  "autoMode": {
    "allow": ["Bash(git status)", "Bash(npm test)", "Read", "Grep"],
    "soft_deny": ["Bash(git push *)", "Bash(rm *)", "Write(.env)"],
    "environmentDescription":
      "This is a development laptop. Read-only ops are safe; deny anything touching credentials or production."
  }
}

token-pilot's enforcement still runs on top (raw Read on large files is denied first, regardless of autoMode).

Permission rule syntax cheat-sheet