Token Pilot

by Digital-Threads

3 stars

643 downloads

Not rated

GitHub Website

Developer Tools

About

Save 60-80% tokens when AI reads code — MCP server for token-efficient code navigation with AST-aware structural reading

Details

Author: Digital-Threads
GitHub stars: 3
Downloads: 643
Categories: Developer Tools

- 23 MCP tools for structural reads, symbol search, git analysis, session analytics
- PreToolUse hooks intercept heavy Read, Grep, Bash calls and redirect to efficient alternatives
- 25 tp-* subagents (Claude Code only) with MCP-first behavior and budget enforcement
- Three enforcement modes: advisory, deny (default), strict
- Supports TypeScript, JavaScript, Python, Go, Rust, Java, Kotlin, C#, C/C++, PHP, Ruby
- Benchmarks show 92% average token savings across four public repos

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name Token Pilot

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "token pilot": {
            "token-pilot": {
                "command": "npx",
                "args": [
                    "-y",
                    "token-pilot"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "token pilot": {
            "token-pilot": {
                "command": "npx",
                "args": [
                    "-y",
                    "token-pilot"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "token pilot": {
            "token-pilot": {
                "command": "npx",
                "args": [
                    "-y",
                    "token-pilot"
                ]
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "token pilot": {
            "token-pilot": {
                "command": "npx",
                "args": [
                    "-y",
                    "token-pilot"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "token pilot": {
            "token-pilot": {
                "command": "npx",
                "args": [
                    "-y",
                    "token-pilot"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "token pilot": {
            "token-pilot": {
                "command": "npx",
                "args": [
                    "-y",
                    "token-pilot"
                ]
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "token pilot": {
            "token-pilot": {
                "command": "npx",
                "args": [
                    "-y",
                    "token-pilot"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "token pilot": {
            "token-pilot": {
                "command": "npx",
                "args": [
                    "-y",
                    "token-pilot"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "token pilot": {
            "token-pilot": {
                "command": "npx",
                "args": [
                    "-y",
                    "token-pilot"
                ]
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "token pilot": {
            "token-pilot": {
                "command": "npx",
                "args": [
                    "-y",
                    "token-pilot"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "token pilot": {
            "token-pilot": {
                "command": "npx",
                "args": [
                    "-y",
                    "token-pilot"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "token pilot": {
            "token-pilot": {
                "command": "npx",
                "args": [
                    "-y",
                    "token-pilot"
                ]
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "token pilot": {
            "token-pilot": {
                "command": "npx",
                "args": [
                    "-y",
                    "token-pilot"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "token pilot": {
            "token-pilot": {
                "command": "npx",
                "args": [
                    "-y",
                    "token-pilot"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "token pilot": {
            "token-pilot": {
                "command": "npx",
                "args": [
                    "-y",
                    "token-pilot"
                ]
            }
        }
    }
}

From the repository

Run npx -y token-pilot init to create or merge the .mcp.json configuration. Restart your AI assistant to activate. For Claude Code, install via the plugin marketplace with claude plugin marketplace add https://github.com/Digital-Threads/token-pilot then claude plugin install token-pilot@token-pilot.

`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. Supports vitest, jest, pytest, phpunit, go test, cargo test.

`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.

`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 / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "token pilot": {
            "token-pilot": {
                "command": "npx",
                "args": [
                    "-y",
                    "token-pilot"
                ]
            }
        }
    }
}

McpServers

{
    "token-pilot": {
        "command": "npx",
        "args": [
            "-y",
            "token-pilot"
        ]
    }
}

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:

| Repo | Files | Raw Tokens | Outline Tokens | Savings |
|------|------:|----------:|--------------:|--------:|
| token-pilot (TS) | 55 | 102,086 | 8,992 | 91% |
| express (JS) | 6 | 14,421 | 193 | 99% |
| fastify (JS) | 23 | 50,000 | 3,161 | 94% |
| flask (Python) | 20 | 78,236 | 7,418 | 91% |
| Total | 104 | 244,743 | 19,764 | 92% |

> 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

- 23 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

| Client | MCP tools | PreToolUse hooks | tp- subagents |
|--------|:---------:|:----------------:|:----------------:|
| Claude Code | ✅ | ✅ | ✅ |
| Cursor | ✅ | ✅ | ❌ |
| Codex CLI | ✅ | ✅ | ❌ |
| Gemini CLI | ✅ | ✅ | ❌ |
| Cline (VS Code) | ✅ | ✅ | ❌ |
| Antigravity | ✅ | ✅ | ❌ |

Manual config snippets for each client → installation guide

Enforcement Mode

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

| Value | Behaviour |
|-------|-----------|
| advisory | Allow all — hooks pass through, advisory notes only |
| deny (default) | Block heavy Grep/Bash patterns; intercept large Read calls |
| strict | Deny + auto-cap MCP output (smart_read ≤ 2 000 tokens, find_usages → list mode, smart_log → 20 commits) |

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:

| Tool | Owns | Typical savings |
|------|------|----------------:|
| Token Pilot | code reads, git, search | 60-90% input |
| caveman | Claude's response prose (terse-speak skill) | ~75% output |
| ast-index | the structural indexer Token Pilot rides on | foundation |
| context-mode | sandboxed shell / python / js execution | 90%+ on big stdout |

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):
```bash

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

smart_read

read_symbol

read_symbols

read_range

read_section

read_diff

read_for_edit

smart_read_many

find_usages

project_overview

related_files

outline

session_analytics

call_tree

find_unused

code_audit

module_info

module_route

smart_diff

explore_area

explore

smart_log

test_summary

session_snapshot

session_budget

Claude Desktop / Cursor

McpServers

Token Pilot

How It Works

Benchmarks

Quick Start

What You Get

Client Support Matrix

Enforcement Mode

Ecosystem

Supported Languages

Update / New Machine

Install

More like this

Sentry

Github

Git

GitLab

Context 7

Playwright

`smart_read`

`read_symbol`

`read_symbols`

`read_range`

`read_section`

`read_diff`

`read_for_edit`

`smart_read_many`

`find_usages`

`project_overview`

`related_files`

`outline`

`session_analytics`

`call_tree`

`find_unused`

`code_audit`

`module_info`

`module_route`

`smart_diff`

`explore_area`

`explore`

`smart_log`

`test_summary`

`session_snapshot`

`session_budget`