Token Pilot MCP server

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 (smartread, readsymbol, readforedit, …). 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:

smartread outline savings only. Real sessions additionally benefit from session cache, readsymbol, and readforedit. 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

Manual config snippets for each client → installation guide

Enforcement Mode

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

TOKEN_PILOT_MODE=strict npx token-pilot

→ Full hook & mode docs

Ecosystem

Shortened. The full README is on GitHub.