Token Pilot

Token Pilot

强制实现 Token 高效的 AI 编码。 在不改变工作方式的前提下，将 AI 编码助手的上下文消耗最多减少 90%。

**为什么现在更重要：**随着前沿模型价格上涨，你不花在阅读代码上的 Token 更值钱了，而不是更不值钱。节省的是 Token；价值则是 Token × 价格。Token Pilot 让昂贵的主线程保持精简，使高级模型能把预算用于推理，而不是重新阅读文件。

三个层次，各自都很有用，组合起来效果更强：

1. MCP 工具 — 结构化读取（smart_read、read_symbol、read_for_edit，……）。可以请求大纲，或按名称加载单个函数，而不是读取整个文件。
2. PreToolUse hooks — 拦截繁重的原生工具调用（对大型文件执行 Read、递归 Grep、无边界的 git diff），并将其重定向到 Token 高效的替代方案。
3. tp-* 子 Agent — Claude Code 委派任务时采用 MCP 优先的行为，并严格限制响应预算。

工作原理

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

200 行以下的文件会完整返回——小文件零额外开销。

基准测试

在公开的开源代码仓库上测量。仅统计行数 ≥50 的文件：

仓库	文件数	原始 Token	大纲 Token	节省比例
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%
总计	104	244,743	19,764	92%

这里只计算 smart_read 的大纲节省量。实际会话还会受益于会话缓存、read_symbol 和 read_for_edit。复现方法：npx tsx scripts/benchmark.ts。

快速开始

npx -y token-pilot init

创建（或合并到）.mcp.json，其中包含 token-pilot 和 context-mode，然后提示安装 tp-* 子 Agent。重启 AI 助手即可启用。

可获得的功能

• 25 个 MCP 工具 — 结构化读取、符号搜索、Git 分析、模块路由、会话分析 → 工具参考
• PreToolUse hooks — 阻止繁重的 Grep/Bash/Read 调用；重定向到高效替代方案 → hooks 与模式
• 25 个 tp-* 子 Agent（仅限 Claude Code）— MCP 优先的委派 Agent，提供 haiku/sonnet 模型层级并强制执行预算 → Agent 参考
• 工具配置档案 — 精简公布的 tools/list，每个会话可节省约 2 k 个 Token → 配置档案与配置

客户端支持矩阵

客户端	MCP 工具	PreToolUse hooks	tp-* 子 Agent
Claude Code	✅	✅	✅
Codex CLI	✅	✅	❌
Cursor	✅	❌	❌
Gemini CLI	✅	❌	❌
Cline (VS Code)	✅	❌	❌
Antigravity	✅	❌	❌

Hooks 面向 Claude Code 编写（插件自带的 hooks/hooks.json，或通过 npm 安装时使用 ~/.claude/settings.json），也支持 Codex CLI （运行 npx token-pilot install-hook --client=codex，然后在 Codex 中使用 /hooks 信任这些 hooks）。其他客户端可使用 MCP 工具；它们也有自己的 hook 系统，但 token-pilot 目前尚未向其中写入配置。

在 Claude Code 2.1.275 及更高版本中，插件会以 mod 形式在 Claude Code 内运行 hooks——每次工具调用无需启动独立进程，大型 Read 调用会返回大纲而非拒绝读取，会话指南也会放在系统提示词中。旧版本仍使用命令 hooks → Claude Code mods

各客户端的手动配置片段 → 安装指南

强制执行模式

TOKEN_PILOT_MODE 控制 Token Pilot 拦截重型原生工具调用的力度：

值	行为
advisory	全部放行 — 钩子直接通过，仅提供提示
deny (默认)	阻止重型 Grep/Bash 模式；拦截大型 Read 调用
strict	拒绝 + 自动限制 MCP 输出（smart_read ≤ 2 000 个 token，find_usages → 列表模式，smart_log → 20 次提交）

TOKEN_PILOT_MODE=strict npx token-pilot

→ 完整的钩子和模式文档

生态系统

Token Pilot 管理输入 token — Claude 从文件、git 和搜索中读取的内容。会话的另一半（Claude 写回的内容、它如何执行代码，以及如何跨天记忆状态）由其他独立工具管理。它们可以轻松组合：

工具	管理内容	典型节省
Token Pilot	代码读取、git、搜索	60-90% 输入
caveman	Claude 的回复文本（简洁表达技能）	~75% 输出
ast-index	Token Pilot 所依赖的结构化索引器	基础
context-mode	沙盒化 shell / python / js 执行	大型 stdout 可节省 90%+

将 token-pilot 与 caveman 配合使用的会话通常可实现总量减少约 85-90% — 两者分别精简不同部分，没有重叠。按需安装；它们都不要求其他工具必须存在。

→ 完整的生态系统图

经验法则：读取代码 → smart_read/read_symbol；执行代码并产生大量输出 → 使用 context-mode execute；仅使用 bash 的 Agent → 使用 ast-index CLI。切勿将整套内容复制到 CLAUDE.md 中 — 当 CLAUDE.md 超过 60 行时，Token Pilot 的 doctor 会发出警告。

支持的语言

TypeScript、JavaScript、Python、Go、Rust、Java、Kotlin、C#、C/C++、PHP、Ruby。非代码文件（JSON/YAML/Markdown/TOML）会生成结构化摘要。正则表达式回退机制可处理大多数其他语言。

更新 / 新设备

Claude Code（插件 — 推荐）：

# 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

其他客户端（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

Claude Code 2.1.139+ 使用提示

2026 年 5 月的 Claude Code 更新改变了几项会影响 token-pilot 调用方式的内容。旧版本不会因此出现问题 — 以下是针对新版本的使用提示。

• 无需 plugin: 前缀，直接运行 tp-* Agent。 现在运行 claude --agent tp-debugger "fix the stack trace" 的效果与 --agent token-pilot:tp-debugger 相同。Task 工具分发器会自动解析简短名称。

• ast-index 冷启动调用 — 调高 MCP_TOOL_TIMEOUT。 在大型代码仓库中首次调用 find_usages / outline / read_symbol 会触发索引构建。默认的 MCP 工具超时时间（60 s）足以应对约 50k 个文件的代码仓库；对于更大的代码仓库，可在 ~/.claude/settings.json 中设置 MCP_TOOL_TIMEOUT=120000。后续调用会命中缓存，并在约 50 ms 内返回。

• 使用 --mcp-config 启动后台会话。 通过 claude agents 或 --bg 分派工作进程时，如果使用 --mcp-config /path/to/other.json，该会话的 MCP 集合就会被替换。如果覆盖配置中没有 token-pilot，该工作进程就无法使用 MCP 工具（smart_read、find_usages 等），即使钩子（Read / Edit / Bash / Grep / Task）仍会触发 — 钩子属于项目级，MCP 工具属于会话级。请将 token-pilot 添加到覆盖配置中，或跳过 --mcp-config。

• claude plugin details token-pilot。 显示每轮预计 token 成本、钩子事件名称以及 MCP 服务条目。技能列表、Agent 列表和 LSP 列表都会从规范子目录中自动发现。

高级用户 — 与 token-pilot 配合使用的未公开 Claude Code 功能

以下字段来自对 @anthropic-ai/[email protected] 源代码的逆向工程（参见 2026 年 5 月的 Habr 文章）。这些功能目前可用，但未列入 Claude Code 官方文档，因此请自行承担使用风险。

持久化 Agent 记忆（memory: project）

每个相关的 tp-* Agent（onboard、debugger、pr-reviewer、 history-explorer、audit-scanner）的 frontmatter 中现在都包含 memory: project。Claude Code 会将 Agent 的工作笔记保存在项目中， 让 Agent 在重复调用时更快——tp-onboard 会记住你的布局，tp-pr-reviewer 会记住 标记过的问题模式，等等。v0.35.0+。

必需的 MCP 门控（requiredMcpServers）

每个 tp-* Agent 都声明了 requiredMcpServers: ["token-pilot"]。 如果未配置 MCP 服务，Claude Code 会拒绝加载该 Agent， 因此过时的安装不会陷入“找不到工具”的循环。v0.35.0+。

仅运行一次的引导钩子（once: true）

该插件提供了一个标记为 once: true 的 SessionStart 钩子—— Claude Code 每个项目运行一次，然后自动移除该条目。 如果尚未运行 install-agents 或 install-ast-index，它会显示友好的提示。v0.35.0+。

异步遥测（async: true）

PostToolUse 钩子（Bash、Task）标记为 async: true，因此 不再增加关键路径的耗时——遥测写入会在后台执行。

自动模式权限（用户端）

如果你希望安全命令获得完全自动批准，YOLO 分类器会读取自然语言的环境描述：

{
  "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 的强制执行仍会在此基础上运行（大型文件的原始 Read 会优先被拒绝，无论 autoMode 如何设置）。

权限规则语法速查表

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

* 会匹配单词边界内的内容（shell-glob）；** 表示递归匹配。 钩子中的 if 字段使用相同的语法。

实验性功能：透明重写 Read

将 TOKEN_PILOT_HOOK_REWRITE=1 设置为用 updatedInput 重写 替代 Read 钩子的“拒绝 + 建议”行为——这是 Claude Code 中未公开的字段， 会将 Read 静默限制为前 200 行，而不是拒绝调用。结构摘要仍会通过 additionalContext 一并提供。默认关闭，因为该字段未公开，且可能会变更。

实验性功能：SubagentStop 预算反馈（CC 2.1.163+）

每个子 Agent 完成时，都会通过 SubagentStop 钩子生成一条任务遥测记录（stats --tasks 就是通过它 获知你派发的任务）。设置 TOKEN_PILOT_SUBAGENT_FEEDBACK=1 后，同一钩子还会 返回 additionalContext——当 token-pilot workflow 扇出任务的 Token 用量达到 上限的 ≥90 % 时，每个完成的 Agent 都会收到一条收尾提示，让包含数百个 Agent 的 /workflow 运行能及时停止，避免超出 预算。

需要 Claude Code 2.1.163+。 只有在该版本中，从 SubagentStop 返回 additionalContext 才会生效；旧版 Claude Code 会将其标记为 钩子错误。因此默认关闭——只有在 claude --version 显示 2.1.163 或更高版本时才启用。

Claude Code 2.1.151+ 新功能

这些说明介绍了在同时更新 Claude Code 和 token-pilot@latest 后 会自动生效的行为。无需额外配置。

会话标题徽标（[TP] Nk saved）

现在，SessionStart 钩子会使用 Claude Code 2.1.152 的 hookSpecificOutput.sessionTitle 字段，将当前项目累计节省的 Token 数设置为窗口或标签页标题。 标题栏中会显示类似 [TP] 1.2M saved 的徽标，让你一眼就能确认 插件正在发挥作用。

加固技能（disallowed-tools）

捆绑的三个技能（guide、install、stats）声明了 disallowed-tools（Claude Code 2.1.152+），防止失控的模型在展示技能时 执行 Write / Edit / Task。安装技能保留了 Bash，因为它必须运行 npx token-pilot install-ast-index；另外两个技能也禁止使用 Bash。

第三方提供商上的自动模式

Claude Code 2.1.158 为 Opus 4.7 + 4.8 上的 Bedrock / Vertex / Foundry 开放了自动模式。 如果你使用其中之一，可通过 CLAUDE_CODE_ENABLE_AUTO_MODE=1 启用。token-pilot 的 deny-Read / deny-Bash 门控仍会继续执行——自动模式无法绕过它们。

Opus 4.8 成为快速模式默认模型

Claude Code 2.1.154 将 Opus 4.8 设为高投入度任务的默认模型。已声明 model: haiku 的 tp-* Agent 仍使用更经济的级别（占 Agent 阵容的 90 %+）；少数使用 sonnet/opus 级别的 Agent 则会自动升级。

Fleet 工作流（v0.38.0）

当你将一项任务分派给多个子 Agent 时——无论通过 Claude Code 的 /workflow、Agent 工具，还是你自己的编排方式——token-pilot 都可以将整个运行视为一个有预算、带遥测标签的单元。

token-pilot 负责工作流边界，因此无论 Claude Code 是否传递工作流 ID，都能正常使用。你只需将批次包装起来：

# 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

工作流运行期间：

• hook-events.jsonl 中每条 event:"task" / denied / diagnostic 记录都会包含 workflow_id，方便你从全局日志中筛选出单次扇出运行。
• PreToolUse:Agent 钩子会监控令牌上限。达到 ≥90 % 时，它会在路由建议中添加一条收尾提示（“完成正在进行的工作，而不是开启新的分支”），并记录一条 workflow_near_budget 诊断信息——可在 workflow status 中查看。预算不会硬性阻止分派（扇出任务只完成一半，比略微超支更糟）。
• 窗口标题会切换为 [TP] wf · N tasks · X%，让长时间运行的任务显示实时进度。

Claude Code 自带的 /workflow（2.1.154+）不会向子 Agent 暴露每个工作流对应的环境变量（已根据 2.1.161 版本包验证——其中只有一个 CLAUDE_CODE_WORKFLOWS 功能标志）。因此 token-pilot 的工作流彼此独立：它们依赖我们自己的 TOKEN_PILOT_WORKFLOW_ID。如果 CC 之后添加了每个工作流对应的环境变量， activeWorkflowId() 已会探测该变量，无需更改配置。

故障排查

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

致谢

基于 ast-index · @ast-grep/cli · MCP SDK · chokidar 构建

许可证

MIT