使用说明
TokenPilot
自动令牌优化 克劳德代码。通过减少每个维度上的浪费令牌来延长会话持续时间——努力调优、冗余文件读取、工具成本路由、上下文健康跟踪和智能任务分类。
构建为Claude Code挂钩+MCP服务器系统。一起工作 实时动态测量 用于壳体压缩和 MCP压缩机 用于模式缩减。
运作原理
TokenPilot分为四层运行：
- 钩子 --拦截Claude代码生命周期事件（会话开始、提示提交、工具使用前/后）
- MCP服务器 --公开用于实时控制和监控的工具
- SQLite数据库 --使用WAL模式+可序列化隔离跨钩子子进程调用持久化会话状态
- 工具注册表 --将已知工具映射到估计成本和更便宜的替代方案
┌── Claude Code Hooks ──────────────────────────────────────┐
│ │
│ SessionStart → init session, inject hints │
│ UserPromptSubmit → classify task → suggest effort │
│ PreToolUse (Read) → dedup file reads + suggest cheaper │
│ PostToolUse (all) → track real tool output token costs │
│ │
└────────────────┬───────────────────────────────────────────┘
│
┌────────────▼──────────────────┐
│ TokenPilot MCP Server │
│ │
│ set_level(1-10) │ Aggressiveness dial
│ get_stats() │ Live session metrics
│ get_savings() │ Token savings report
│ get_context_health() │ Context window status
│ get_tool_report() │ Most expensive tools
│ get_file_report(path) │ File read history
│ explain_classification(p) │ Debug classifier
│ reset_file_tracking() │ Clear dedup cache
│ │
│ SQLite + Tool Registry │ Persistent state
└───────────────────────────────┘
攻击性量表
违约： 4 （保守平衡）。可随时通过以下方式调节1-10 /tp level N.
| 级别 | 努力建议 | 文件读取扣除 | 思维上限 | 紧凑提醒 |
|---|---|---|---|---|
| 1-2 | 从不 | 仅通知 | 无上限 | 90%上下文 |
| 3-4 | 仅限琐碎任务 | 警告冗余 | 无上限 | 75%上下文 |
| 5-6 | 所有任务 | 警告+建议替代方案 | 自适应（10-30K） | 65%上下文 |
| 7-8 | 强烈推荐 | 区块重读 | 自适应（6-18K） | 55%上下文 |
| 9-10 | 强制 | 阻止+自动范围 | 自适应（4-12K） | 45%上下文 |
思维上限具有适应性 --它们根据任务复杂度和分类器置信度进行缩放。“琐碎”的任务比“复杂”的任务受到更严格的限制。如果分类器不确定（置信度<0.5），则不应用上限。
任务分类器（v2）
轻量级正则表达式+关键字分类器，具有否定检测、邻接评分和引用代码过滤功能。无LLM调用，执行时间<10ms。
| 类别 | 努力 | 模型提示 | 示例 |
|---|---|---|---|
trivial |
low | haiku | “修复README中的拼写错误” |
research |
介质 | 十四行诗 | “解释API路由如何工作” |
standard |
中号 | 十四行诗 | “添加加载旋转器” |
complex |
high | opus | “跨所有微服务重构身份验证” |
v2改进：
- 否定检测：“不要重构”不再与重构模式匹配
- 引用代码过滤：回溯包装的代码在分类前被剥离
- 邻近性评分：“向12条路由添加auth”可以正确检测关键字对的复杂性
- 置信度校准：非常短的提示获得低置信度（0.3），而不是虚假的高置信度
使用调试任何分类 /tp explain <prompt>.
工具成本注册表
TokenPilot知道常用工具的估计代币成本，并建议更便宜的替代方案：
| 工具 | 平均代币 | 替代品 | 替代代币 | 节省 |
|---|---|---|---|---|
| 读取 | ~2000 | jCodeMunch符号查找 | ~200 | 90% |
| WebSearch | ~2000 | Context7文档查询 | ~800 | 60% |
| WebFetch | ~3000 | Context7文档查询 | ~800 | 73% |
在5+级别，TokenPilot建议使用更便宜的工具来完成这项工作。
安装
先决条件
设置
- 克隆到MCPs目录：
git clone https://github.com/rish-e/tokenpilot.git ~/MCPs/tokenpilot
- 安装依赖项：
pip3 install -r ~/MCPs/tokenpilot/requirements.txt
- 将钩子和MCP服务器添加到
~/.claude/settings.json:
{
"hooks": {
"SessionStart": [
{
"hooks": [
{ "type": "command", "command": "~/MCPs/tokenpilot/hooks/session_start.sh", "timeout": 5 }
]
}
],
"UserPromptSubmit": [
{
"hooks": [
{ "type": "command", "command": "~/MCPs/tokenpilot/hooks/classify.sh", "timeout": 5 }
]
}
],
"PreToolUse": [
{
"matcher": "Read",
"hooks": [
{ "type": "command", "command": "~/MCPs/tokenpilot/hooks/check_read.sh", "timeout": 5 }
]
}
],
"PostToolUse": [
{
"matcher": ".*",
"hooks": [
{ "type": "command", "command": "~/MCPs/tokenpilot/hooks/post_tool.sh", "timeout": 3 }
]
}
]
},
"mcpServers": {
"tokenpilot": {
"command": "python3",
"args": ["~/MCPs/tokenpilot/server.py"],
"env": { "PYTHONPATH": "~/MCPs/tokenpilot" }
}
}
}
- 安装
/tp斜线命令：
cp ~/MCPs/tokenpilot/commands/tp.md ~/.claude/commands/tp.md
- 重新启动克劳德代码。
可选：RTK用于壳体压缩
brew install rtk-ai/tap/rtk
rtk init -g
在shell输出（构建日志、测试输出、git）上节省60-90%的令牌。
用法
TokenPilot在安装后自动运行。你会看到的 [TokenPilot] 当它检测到优化机会时，会发送消息。
斜杠命令
5个命令。就这样
| 命令 | 它的作用 |
|---|---|
/tp <1-10> |
设置攻击性级别 |
/tp on / off |
启用/禁用tokusanpilot |
/tp stats |
完整会话控制面板 |
/tp note <text> |
在项目大脑中添加注释 |
/tp explain <prompt> |
调试提示分类的原因 |
MCP工具
对于高级用户，所有工具都可以直接调用：
set_level toggle get_stats get_savings get_context_health get_tool_report get_file_report explain_classification add_note reset_file_tracking
CLI（用于测试）
cd ~/MCPs/tokenpilot
python3 server.py init 4 # Initialize session
python3 server.py classify "fix typo" # Classify prompt
python3 server.py classify_debug "fix typo" # Debug classification
python3 server.py check_file "/src/app.py" # Check file dedup
python3 server.py context_health # Context window status
项目大脑
TokenPilot自动维护 tpcontext.md 每个项目根目录中的文件。这是Claude Code会话中的持久内存——当你开始一个新的聊天时，Claude会立即知道你在哪里停了下来。
全自动：
- 首次安装 --从git历史中引导（提交、活动文件、分支）
- 每次会话开始 --自动保存前一个会话，将大脑加载到上下文中
- 无需手动保存 --它只是工作
它捕捉到了什么：
- 修改的文件（来自git diff）
- 最近的提交
- 用户备注（通过
/tp note "...") - 会话统计数据（持续时间、提示计数）
- 最活跃的文件
为未来的会议添加上下文：
/tp note "switched to GraphQL — don't touch REST endpoints"
保持在2K代币以下。保留最后5个会话，旧会话轮换。
智能警告
TokenPilot会自动检测并警告令牌浪费模式：
- 快速射击提示 --连续3条以上的短信会触发“批量提问”建议
- 会话年龄 --每15个提示，建议
/compact或重新开始 - 高峰时段 --太平洋时间工作日上午5点至11点，每节课警告一次（高峰时段人为烧伤限制更快）
所有警告显示为 [TokenPilot] 消息，并尊重开/关切换。
文件结构
tokenpilot/
├── server.py # FastMCP server + CLI entry point
├── classifier.py # Task classifier (v2: negation, adjacency, debug)
├── config.py # Aggressiveness scale + adaptive thinking caps
├── db.py # SQLite persistence (WAL, indexed, serializable)
├── brain.py # Project Brain — auto-generated tpcontext.md
├── tool_registry.py # Tool cost estimates + cheaper alternatives
├── tracker.py # In-memory tracker (used by MCP server process)
├── requirements.txt
├── commands/
│ └── tp.md # /tp slash command (copy to ~/.claude/commands/)
├── hooks/
│ ├── session_start.sh # SessionStart — init + load brain
│ ├── classify.sh # UserPromptSubmit — classify + rapid-fire + peak hours + session age
│ ├── check_read.sh # PreToolUse (Read) — dedup + tool routing
│ └── post_tool.sh # PostToolUse — real token tracking
└── templates/
└── claudeignore-default
代币储蓄如何堆叠
| 图层 | 内容 | 节省 |
|---|---|---|
| TokenPilot分类器 | 每个任务的正确努力水平 | 思考令牌减少 |
| TokenPilot文件去重 | 跳过冗余文件读取 | 每次阻止读取约2K个令牌 |
| TokenPilot工具路由 | 建议更便宜的工具替代品 | 每次替换60-90% |
| TokenPilot PostToolUse | 跟踪实际令牌成本（可见性） | 通过测量实现优化 |
| TokenPilot智能警告 | 批量提示、会话时间、高峰时段 | 防止上下文爆炸 |
| TokenPilot项目大脑 | 恢复会话而不重新解释上下文 | 每次会话开始保存3-5条消息 |
| RTK | 压缩shell输出 | Bash结果的60-90% |
| MCP压缩器 | 压缩MCP工具模式 | 每个包装服务器70-97% |
| .claudeignore | 从搜索中排除构建工件 | 30-40%用于探索 |
许可证
麻省理工学院
