AST 기반의 구조적 읽기 및 도구 인터셉트 훅을 사용하여 AI 코딩 토큰 소비를 최대 90%까지 절감합니다.
다른 이름 Digital-Threads/token-pilot
- 스타
- 5
- Tools
- —
- 다운로드, 30일
- —
- 최신 버전
- 2.0.0
- 마지막 커밋
- 2026년 11월 6일
- 라이선스
- —
token-pilot MCP란?
AST 기반의 구조적 읽기 및 도구 인터셉트 훅을 사용하여 AI 코딩 토큰 소비를 최대 90%까지 절감합니다.
프로젝트 README에서 생성된 요약
token-pilot MCP server 정보
Token Pilot은 AI 코딩 어시스턴트의 토큰 소비를 최대 90%까지 줄이도록 설계된 특화 도구입니다. 무거운 전체 파일 읽기 대신 AST 기반의 구조적 작업을 수행하여 토큰을 절약합니다. 이를 통해 개발자는 고가의 프론티어 모델이 방대한 양의 중복 코드 컨텍스트를 처리하는 대신 추론에 집중할 수 있도록 할 수 있습니다. 이 시스템은 타겟 데이터 검색을 위한 25개의 MCP tools 세트와 비효율적인 네이티브 명령을 가로채서 리다이렉트하는 PreToolUse 훅이라는 두 가지 주요 레이어를 통해 작동합니다.
사용자는 npx를 사용하여 이 서버를 로컬에 배포하고 설정을 초기화할 수 있습니다. 고급 훅 시스템을 통해 Claude Code 및 Codex CLI에 최적화되어 있지만, Cursor, Cline, Gemini CLI와 같은 other 클라이언트를 위한 표준 MCP tools도 제공합니다. 이 서버는 TypeScript, Python, Go, Rust, Java를 포함한 다양한 프로그래밍 언어를 지원합니다. advisory 알림부터 무거운 Grep 또는 Bash 호출을 차단하고 예산 준수를 위해 출력 제한을 적용하는 strict 모드까지 다양한 강제 적용 모드를 제공합니다.
활용 사례
- 1컨텍스트 윈도우 사용량 감소개발자가 수백 줄의 코드를 로드하는 대신 파일의 구조적 개요를 요청할 수 있습니다.
- 2타겟 심볼 검색AI가 모듈 전체를 읽는 대신 편집에 필요한 특정 함수만 가져올 수 있습니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
token-pilot MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 token-pilot MCP 설치
$ claude mcp add token-pilot -- npx -y token-pilotCursor에 token-pilot MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"token-pilot": {
"command": "npx",
"args": [
"-y",
"token-pilot"
]
}
}
}VS Code에 token-pilot MCP 설치
.vscode/mcp.json
{
"servers": {
"token-pilot": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"token-pilot"
]
}
}
}VS Code CLI에 token-pilot MCP 설치
$ code --add-mcp '{"name":"token-pilot","type":"stdio","command":"npx","args":["-y","token-pilot"]}'Claude Desktop에 token-pilot MCP 설치
claude_desktop_config.json
{
"mcpServers": {
"token-pilot": {
"command": "npx",
"args": [
"-y",
"token-pilot"
]
}
}
}Codex에 token-pilot MCP 설치
$ codex mcp add token-pilot -- npx -y token-pilotCodex config.toml에 token-pilot MCP 설치
~/.codex/config.toml
[mcp_servers.token-pilot] command = "npx" args = ["-y", "token-pilot"]
Gemini CLI에 token-pilot MCP 설치
$ gemini mcp add -s user token-pilot npx -- -y token-pilotGemini settings.json에 token-pilot MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"token-pilot": {
"command": "npx",
"args": [
"-y",
"token-pilot"
]
}
}
}구성
TOKEN_PILOT_MODE
| 이름 | 설명 | 유형 |
|---|---|---|
| TOKEN_PILOT_MODE | — |
자동 검사
2026년 11월 13일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 이는 보안 감사가 아닙니다. 코드를 직접 읽고 서버에 필요한 최소한의 권한만 부여하십시오. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능digital-threads/token-pilot is public and reachablegithub.com/digital-threads/token-pilot ↗통과
- 패키지가 이 저장소를 소스로 명시token-pilot names digital-threads/token-pilot as sourcenpmjs.com/package/token-pilot ↗통과
- 빌드 출처(Sigstore 증명)No build attestation published for this release검사되지 않음
- 오픈 소스 라이선스 (OSI)No license결함 발견
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-11-06github.com/digital-threads/token-pilot ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음No popular package one edit away from token-pilot통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음116 resolved dependencies checked; no critical advisoryosv.dev ↗통과
- 모델에 대한 숨겨진 지침 없음0 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨검사되지 않음
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기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.
Two layers, each useful on its own, stronger together:
- 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. - PreToolUse hooks — intercept heavy native tool calls (
Readon large files, recursiveGrep, unboundedgit diff) and redirect to token-efficient alternatives.
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_readoutline savings only. Real sessions additionally benefit from session cache,read_symbol, andread_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. 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/Readcalls; redirect to efficient alternatives → hooks & modes - Tool profiles — trim advertised
tools/listto save ~2 k tokens per session → profiles & config
Client Support Matrix
| Client | MCP tools | PreToolUse hooks |
|---|---|---|
| Claude Code | ✅ | ✅ |
| Codex CLI | ✅ | ✅ |
| Cursor | ✅ | ❌ |
| Gemini CLI | ✅ | ❌ |
| Cline (VS Code) | ✅ | ❌ |
| Antigravity | ✅ | ❌ |
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.
On Claude Code 2.1.275 and later the plugin runs its hooks inside Claude Code as a mod — no process per tool call, and a big Read comes back as an outline instead of a refusal. Older versions keep the command hooks → Claude Code mods
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) + refuse an Edit of a code file not prepared with read_for_edit |
TOKEN_PILOT_MODE=strict npx token-pilot
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.
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
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.
-
Cold ast-index calls — raise
MCP_TOOL_TIMEOUT. The firstfind_usages/outline/read_symbolon a large repo triggers an index build. Default per-MCP-tool timeout (60 s) is enough for ~50k-file repos; bigger ones benefit fromMCP_TOOL_TIMEOUT=120000in~/.claude/settings.json. Subsequent calls hit the cache and return in ~50 ms. -
Background sessions with
--mcp-config. Dispatching a worker viaclaude agentsor--bgwith--mcp-config /path/to/other.jsonswaps the MCP set for that session. Iftoken-pilotis not in the override config, MCP tools (smart_read,find_usages, …) are unavailable in that worker. On a Claude Code that loads the token-pilot mod, the hooks (Read / Bash / Grep / Edit in strict mode / Agent) see the tools are missing and step aside. The command hooks of an older Claude Code only see a server turned off in/mcp. Addtoken-pilotto the override config if you want the tools. -
claude plugin details token-pilot. Shows the projected per-turn token cost, the hook event names, and the MCP server entry. The skill 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.
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 a friendly hint when
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
Bash(npm *) # wildcard after "npm "
Bash(git commit *) # specific subcommand
Read(*.ts) # extension
Read(src/**/*.ts) # recursive + extension
Write(src/**) # recursive all files
mcp__token-pilot # all token-pilot MCP tools
mcp__token-pilot__smart_read # one specific MCP tool
* matches inside word boundaries (shell-glob); ** is recursive.
The if field on hooks uses the same syntax.
Experimental: transparent Read rewrite
Set TOKEN_PILOT_HOOK_REWRITE=1 to swap the "deny + suggest" Read
hook behaviour for an updatedInput rewrite — Claude Code's
undocumented field that silently bounds the Read to its first 200
lines instead of bouncing the call. The structural summary still
rides along in additionalContext. Default OFF because the field
is undocumented and may change.
Experimental: SubagentStop budget feedback (CC 2.1.163+)
Every subagent completion lands a task-telemetry row via the
SubagentStop hook (that's how stats --tasks knows what you
dispatched). With TOKEN_PILOT_SUBAGENT_FEEDBACK=1 the same hook also
returns additionalContext — when a token-pilot workflow fan-out is
at ≥90 % of its token ceiling, each completing agent gets a wind-down
note so a hundred-agent /workflow run stops before blowing the
budget.
Requires Claude Code 2.1.163+. Returning additionalContext from
SubagentStop is only honoured there; older Claude Code labels it a
hook error. Default OFF for that reason — enable only once
claude --version reports 2.1.163 or later.
What's new for Claude Code 2.1.151+
These notes are about behaviour you'll see automatically once you
update both Claude Code and token-pilot@latest. No extra
configuration required.
Session title badge ([TP] Nk saved)
The SessionStart hook now sets the window/tab title to the cumulative
token savings for the current project, using Claude Code 2.1.152's
hookSpecificOutput.sessionTitle field. You'll see a badge like
[TP] 1.2M saved in the title bar so you can confirm at a glance
that the plugin is doing its job.
Hardened skills (disallowed-tools)
The three bundled skills (guide, install, stats) declare
disallowed-tools (Claude Code 2.1.152+) so a runaway model can't
issue Write / Edit / Task while the skill is on display. The
install skill keeps Bash because it has to run
npx token-pilot install-ast-index; the other two have Bash
disallowed too.
Auto mode on third-party providers
Claude Code 2.1.158 opened auto mode to Bedrock / Vertex / Foundry
on Opus 4.7 + 4.8. If you're on one of those, opt in with
CLAUDE_CODE_ENABLE_AUTO_MODE=1. token-pilot's deny-Read /
deny-Bash gates still run on top — auto mode never bypasses them.
Fleet workflows (v0.38.0)
When you fan a task across many subagents — via Claude Code's
/workflow, the Agent tool, or your own orchestration — token-pilot
can treat the whole run as one budgeted, telemetry-tagged unit.
token-pilot owns the workflow boundary, so this works regardless of whether Claude Code propagates a workflow id. You wrap the batch:
# Start a workflow — prints an export line you eval into your shell
eval "$(token-pilot workflow start "review every PR from last sprint" --budget=2000000)"
# ...now run your fan-out work. Every hook event is tagged with the
# workflow id automatically (TOKEN_PILOT_WORKFLOW_ID is set).
token-pilot workflow status # live budget + task counts
token-pilot workflow list # all recorded workflows
token-pilot workflow end # stamp it finished + print summary
While a workflow is active:
- Every
event:"task"/denied/diagnosticrow inhook-events.jsonlcarriesworkflow_id, so you can slice one fan-out run out of the global log. - The PreToolUse:Agent hook watches the token ceiling. At ≥90 % it
adds a wind-down note ("finish in-flight
work rather than starting new branches") and logs a
workflow_near_budgetdiagnostic — visible inworkflow status. Dispatch is never hard-blocked on budget (a half-finished fan-out is worse than a small overrun). - The window title switches to
[TP] wf · N tasks · X%so a long run shows live progress.
Claude Code's own /workflow (2.1.154+) does not expose a
per-workflow id env var to subagents (verified against the 2.1.161
bundle — it has only a CLAUDE_CODE_WORKFLOWS feature flag). So
token-pilot's workflows are independent: they rely on our own
TOKEN_PILOT_WORKFLOW_ID. If CC adds a per-workflow env var later,
activeWorkflowId() already probes for it — no config change needed.
Troubleshooting
npx token-pilot doctor # diagnose: ast-index, config, upstream drift
# "ast-index not found" → npx token-pilot install-ast-index
# "hooks not firing" → restart your AI assistant
Credits
Built on ast-index · @ast-grep/cli · MCP SDK · chokidar
License
MIT
token-pilot MCP 질문
token-pilot MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add token-pilot -- npx -y token-pilot를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
token-pilot MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
토큰을 얼마나 절약할 수 있나요?
AI 코딩 어시스턴트의 컨텍스트 소비를 최대 90%까지 절약할 수 있습니다.
작은 파일은 어떻게 처리되나요?
200줄 미만의 파일은 추가 오버헤드 없이 전체 내용이 반환됩니다.
어떤 AI 클라이언트를 지원하나요?
Claude Code와 Codex CLI는 전체 MCP tools 및 hooks를 지원하며, Cursor, Gemini CLI, Cline과 같은 클라이언트는 MCP tools를 지원합니다.
강제 적용 모드에는 어떤 것들이 있나요?
advisory(모두 허용), deny(무거운 호출 차단, 기본값), strict(무거운 호출 차단 및 MCP 출력 자동 제한)의 세 가지 모드가 있습니다.