# token-pilot [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/Digital-Threads/token-pilot  
**GitHub Stars:** 5  
**npm Downloads (last month):** 1718  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/token-pilot

## Description
Save up to 80% tokens when AI reads code via AST-aware structural reading

## Tools
Capabilities this server exposes over MCP:

- **smart_read** — Use INSTEAD OF Read/cat for code files. Returns code structure (classes, functions, methods with signatures and line ranges) — 60-80% fewer tokens than raw content. Use read_symbol() to drill into specific code.
- **read_symbol** — Read source code of ONE specific function/method/class — INSTEAD OF reading the whole file. Supports Class.method syntax.
- **read_symbols** — Batch read MULTIPLE symbols from ONE file — saves N-1 round-trips vs calling read_symbol N times. BEST FIT: 3–8 symbols in one file when you need their bodies. For 1–2 symbols use read_symbol (simpler). If you'd request ≥70% of the file's symbols, the handler refuses and points you to smart_read — that's cheaper than a large batch. For edit preparation use read_for_edit.
- **read_range** — Read a specific line range from a file. Use when you know exact lines — lighter than reading the whole file.
- **read_section** — Read a specific section from Markdown, YAML, JSON, or CSV files. Markdown: by heading name. YAML/JSON: by top-level key. CSV: by row range (rows:1-50). Much cheaper than reading the whole file. DOCS/DATA ONLY — `heading` is required; this does NOT read code by line/symbol. For source files use read_range (line range) or read_symbol (one symbol).
- **read_diff** — Use INSTEAD OF re-reading whole file after edits. Shows only changed hunks. REQUIRES: call smart_read or read_for_edit BEFORE editing to create baseline snapshot.
- **read_for_edit** — Use INSTEAD OF Read when preparing an EDIT. Returns exact RAW code around a symbol or line — copy directly as old_string for Edit tool. Supports batch: pass "symbols" array to get multiple edit contexts in one call. Unlike read_symbols (for reading/understanding), this returns unformatted code optimized for copy-paste into Edit. Optional: include_callers, include_tests, include_changes for enriched context.
- **smart_read_many** — Batch smart_read for multiple files at once — INSTEAD OF calling Read on each file. Returns structure for each file. Max 20 files.
- **find_usages** — Use INSTEAD OF Grep for finding symbol references. Semantic search — groups by: definitions, imports, usages. Supports scope, kind, limit, lang filters. Use context_lines to include surrounding code. HINT: for very short / generic symbols (≤4 chars like `id`, `err`, `Cmd`, `db`) Grep is usually cheaper than find_usages — the semantic grouping doesn't pay off when the symbol resolves ambiguously across thousands of files.
- **project_overview** — START HERE for unfamiliar codebases. Shows project type, architecture, framework detection, quality tools, CI, directory map. Use include filter for specific sections.
- **related_files** — Show ranked import graph for a file: imports, importers, and tests scored by relevance (test adjacency, import closeness, recent changes, path proximity). Files ranked into HIGH VALUE / MEDIUM / LOW to prioritize reading.
- **outline** — Use INSTEAD OF listing dir + reading each file. One call returns all symbols (classes, functions, methods, routes) for every code file in a directory. Supports recursive with max_depth.
- **session_analytics** — Show token savings report: calls, tokens saved, per-tool breakdown, top files, cache hits. Use verbose=true for full breakdown (per-intent, decision insights, savings by category).
- **call_tree** — Recursive depth-N call hierarchy for a function. Shows who calls who transitively — complements find_usages (flat one-level refs) by revealing full chains from leaf helpers to entry points. Use for debugging, refactor impact, and verifying reachability.
- **find_unused** — Find dead code — functions, classes, and variables with no references across the project. Use for cleanup and refactoring.
- **code_audit** — Find code quality issues: TODO/FIXME comments, deprecated symbols, structural code patterns (bare except:, print() calls). Use for project-wide audits.
- **module_info** — Analyze module dependencies, dependents, public API, and unused deps. Use for architecture understanding and dependency cleanup.
- **module_route** — Show the transitive dependency path(s) between two modules — how module A reaches module B through the import graph. Use to answer 'how does X depend on Y?', trace coupling, or generate a dependency diagram. format='mermaid'/'dot' emits a diagram; default text lists the hops.
- **smart_diff** — Use INSTEAD OF raw git diff. Shows changed files with AST symbol mapping — which functions/classes were modified/added/removed. Small diffs include hunks, large diffs show summary.
- **explore_area** — One-call exploration of a directory: outline (all symbols), imports (external deps + who imports this area), tests (matching test files), recent git changes. Use INSTEAD OF separate outline + related_files + git log calls. Default since v0.30.0 returns only outline+changes — telemetry showed the all-4 default producing negative token reduction for small areas. Opt into imports/tests explicitly via `include` when you need them.
- **explore** — One-shot ranked context + call/inheritance graph blast-radius for a query. Returns ranked symbols, the source heads of the top-ranked files, graph neighbours (callers + subclasses — the blast radius), and related test files in a single compact block. Use INSTEAD OF separate find_usages + read_symbol + call_tree when you need to understand an area fast — cheaper than chaining those three.
- **smart_log** — Use INSTEAD OF raw git log. Structured commit history with category detection (feat/fix/refactor/docs), file stats, author breakdown. Filters by path and ref. HEADS UP: two verification runs measured this tool at ~39% token reduction (borderline — vs 95-99% for outline/smart_diff). Cumulative data being gathered — tool may be dropped or redesigned in v0.30.0 if numbers don't improve. Prefer scoping with `path` or `count` to tighten savings.
- **test_summary** — Run tests and return structured summary: total/passed/failed/skipped + failure details. 200 lines of raw output → 10-15 lines. Parsers: vitest, jest, pytest, phpunit, go test, cargo test, node --test (rspec/mocha fall back to generic patterns). The command runs through the shell (env prefixes and && work) in the server's environment (normally your terminal's) minus CLAUDE_PLUGIN_* / TOKEN_PILOT_* variables, with CI=1, NO_COLOR=1 and FORCE_COLOR=0 set so runners print plain output and skip watch mode (an env prefix in the command overrides them); on timeout the command and everything it started are killed (its process group; `taskkill /T` on Windows) and the result says TIMEOUT.
- **session_snapshot** — Capture current session state as a compact markdown block (<200 tokens). Call before compaction, when switching direction, or periodically in long sessions. Model provides the facts, tool formats them. Writes the block to .token-pilot/snapshots/<timestamp>.md (last 10 kept) and .token-pilot/snapshots/latest.md, which the next session start points to; pass persist=false to only return it.
- **session_budget** — META / info-only: reports Read-hook pressure for this session (suppressed tokens, reference budget, burn fraction, effective denyThreshold). Does NOT save tokens itself — this is diagnostic, use to decide when to tighten before a big read. NOTE: burnFraction measures hook activity, not actual context-window occupancy.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "token-pilot": {
    "command": "npx",
    "args": ["-y","token-pilot"],
    "env": {
      "TOKEN_PILOT_MODE": "",
      "MCP_TOOL_TIMEOUT": ""
    }
  }
}
```

**Requires environment variables:** `TOKEN_PILOT_MODE`, `MCP_TOOL_TIMEOUT` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What token-pilot MCP server does

The token-pilot MCP server reduces the amount of source code and repository output sent to an AI coding assistant. Its MCP layer exposes 25 tools for structural reading, symbol lookup, git analysis, module routing, and session analytics. Instead of requiring an assistant to load a complete file, the tools can return an outline, a named symbol, or an edit-focused view.

Files shorter than 200 lines are returned in full. For larger files, `smart_read` can provide a compact structural outline, while `read_symbol` loads a specific function, class, or other named element. `read_diff` summarizes changes after editing. The README reports outline-only savings of up to 99% in some benchmark repositories, with 92% across the listed benchmark set; actual session savings also depend on how the assistant uses the other tools.

## How it works

The token-pilot MCP server combines three mechanisms:

- MCP tools replace broad file, search, and git reads with focused operations.
- PreToolUse hooks inspect selected native calls and can allow, block, or redirect large `Read`, recursive `Grep`, and unbounded `git diff`-style operations.
- `tp-*` subagents give Claude Code delegates an MCP-first workflow with model tiers and response budgets.

`TOKEN_PILOT_MODE` controls hook behavior. `advisory` allows calls and adds guidance, `deny` blocks or intercepts configured heavy operations, and `strict` applies the deny behavior plus output caps for selected MCP tools. The default is `deny`. Tool profiles can also reduce the tools advertised through `tools/list`, lowering the initial tool-description context.

Supported code languages include TypeScript, JavaScript, Python, Go, Rust, Java, Kotlin, C#, C/C++, PHP, and Ruby. JSON, YAML, Markdown, and TOML receive structural summaries, while a regex fallback covers many other languages.

## Setup and configuration

Run `npx -y token-pilot init` to create or merge a `.mcp.json` entry and optionally install the `tp-*` subagents. Restart the AI client after setup. Claude Code can instead install the repository as a plugin with its marketplace commands. Other documented installation paths include a global npm installation, `install-hook`, and `install-agents`.

Claude Code receives MCP tools, hooks, and subagents. Codex CLI receives MCP tools and hooks after running the Codex hook installer. Cursor, Gemini CLI, and Cline receive MCP tools but not token-pilot-managed hooks. Hook support is therefore client-specific rather than a general property of every MCP connection.

Large repositories may need a higher `MCP_TOOL_TIMEOUT` during the initial AST index build. Later calls can use the cache. Background Claude Code sessions using an override MCP configuration must include token-pilot in that configuration if they need its tools.

## Tools and capabilities

The token-pilot MCP server includes capabilities for:

- Structural file outlines and targeted symbol reads
- Edit-oriented reads and compact diffs
- Symbol and usage discovery
- Git history and change analysis
- Module and repository navigation
- Session analytics
- Hook-based interception of costly native tool calls
- Claude Code delegation through 25 `tp-*` subagents

Use `smart_read` when an outline is enough, `read_symbol` when a particular declaration is relevant, and `read_diff` when reviewing a recent change. The hooks are intended for environments where assistants otherwise issue broad native file, search, or shell commands.

_Full upstream README: https://allmcps.com/mcp/token-pilot/readme_