tokensave

面向 AI 编码代理的语义代码智能

更少令牌 • 更少工具调用 • 100% 本地化

为什么选择 tokensave？

AI 编码代理在探索代码库时浪费大量令牌。每次 grep、glob 和文件读取都要花费成本。在复杂任务中，代理会生成多个 Explore 子代理，仅为了构建上下文就扫描数百个文件。

tokensave 为代理提供预索引的语义知识图谱。 代理无需扫描文件，而是查询图谱并即时获得结构化答案——正确的符号、它们之间的关系以及源代码，一次调用即可完成。

工作原理

┌──────────────────────────────────────────────────────────────┐
│  AI Coding Agent (Claude Code, Codex, Gemini, Cursor, ...)   │
│                                                              │
│  "Implement user authentication"                             │
│        │                                                     │
│        ▼                                                     │
│  ┌─────────────────┐       ┌─────────────────┐               │
│  │  Sub-agent      │ ───── │  Sub-agent      │               │
│  └────────┬────────┘       └─────────┬───────┘               │
└───────────┼──────────────────────────┼───────────────────────┘
            │                          │
            ▼                          ▼
┌──────────────────────────────────────────────────────────────┐
│  tokensave MCP Server                                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐           │
│  │   Search    │  │   Callers   │  │   Context   │           │
│  │   "auth"    │  │  "login()"  │  │   for task  │           │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘           │
│         └────────────────┼────────────────┘                  │
│                          ▼                                   │
│              ┌───────────────────────┐                       │
│              │   libSQL Graph DB     │                       │
│              │   • Instant lookups   │                       │
│              │   • FTS5 search       │                       │
│              └───────────────────────┘                       │
└──────────────────────────────────────────────────────────────┘

没有 tokensave： 代理使用 grep、glob 和 Read 扫描文件——大量 API 调用，高令牌消耗。

使用 tokensave： 代理通过 MCP 工具查询图谱——即时结果、本地处理、更少令牌。

主要特性

快速开始

1. 安装

Homebrew（macOS）：

brew install aovestdipaperino/tap/tokensave

Scoop（Windows）：

scoop bucket add tokensave https://github.com/aovestdipaperino/scoop-bucket
scoop install tokensave

Cargo / cargo-binstall（任何平台）：

# Fast install prebuilt binary without compiling:
cargo binstall tokensave

# Or compile from source:
cargo install tokensave                          # full (50+ languages, default)
cargo install tokensave --features medium        # medium tier
cargo install tokensave --no-default-features    # lite (smallest binary)

预构建二进制文件（Linux、Windows、macOS）：

从最新版本下载，并将二进制文件放入您的 PATH。

2. 配置您的代理

tokensave install                         # auto-detects installed agents
tokensave install --agent antigravity     # Google Antigravity (formerly Windsurf)
tokensave install --agent auggie          # AugmentCode
tokensave install --agent claude          # Claude Code
tokensave install --agent cline           # Cline
tokensave install --agent codex           # OpenAI Codex CLI
tokensave install --agent copilot         # GitHub Copilot
tokensave install --agent cursor          # Cursor
tokensave install --agent droid           # Factory Droid
tokensave install --agent gemini          # Gemini CLI
tokensave install --agent kilo            # Kilo CLI
tokensave install --agent kiro            # AWS Kiro
tokensave install --agent kimi            # Moonshot Kimi CLI
tokensave install --agent omp             # Oh My Pi (OMP)
tokensave install --agent opencode        # OpenCode
tokensave install --agent pi              # Pi (pi.dev)
tokensave install --agent plank           # Plank (macOS only)
tokensave install --agent qwen            # Qwen Code
tokensave install --agent roo-code        # Roo Code
tokensave install --agent vibe            # Mistral Vibe
tokensave install --agent zed             # Zed
tokensave install --agent grok            # Grok Build (xAI)
tokensave install --git-hook yes           # auto-install the global post-commit and post-checkout hooks (no prompt)
tokensave install --git-hook no            # skip the post-commit and post-checkout hooks (no prompt)
tokensave githooks                         # show which global git hooks tokensave owns
tokensave githooks off                     # remove them, leaving any hook content you wrote

每个代理都以原生配置格式注册其 MCP 服务器。Claude Code 额外获得 PreToolUse 钩子（阻止浪费的 Explore 代理）、UserPromptSubmit 钩子、Stop 钩子、CLAUDE.md 中的提示规则以及自动允许的工具权限。Kiro 获得全局 MCP 配置、作为资源加载的 tokensave.md 引导，以及一个由 tokensave 管理的默认代理，具有宽松的内置/tokensave 工具审批、委派护栏钩子和写入后同步；用户管理的 Kiro 代理会被保留。

全局 OMP 安装针对裸 omp config path 报告的配置文件，写入 <resolved-agent-dir>/mcp.json 和 <resolved-agent-dir>/rules/tokensave.md。安装到命名配置文件时，导出 OMP_PROFILE 或 OMP 兼容的 PI_PROFILE；OMP 的解析器也遵循 PI_CONFIG_DIR 和 PI_CODING_AGENT_DIR。Tokensave 信任该原生解析器，而不是复制 OMP 的配置文件逻辑。Tokensave 为 OMP 安装 MCP 和咨询规则；它不安装 OMP 钩子强制执行。

所有更改都是幂等的——升级后再次运行是安全的。代理设置后，您将获得全局 git post-commit 和 post-checkout 钩子的选项。tokensave uninstall 会移除这些钩子以及代理集成；传递 --keep-git-hooks 以保留它们，或使用 tokensave githooks 单独管理它们。

项目本地安装

默认情况下，tokensave install 在您的全局代理配置中注册 MCP 服务器（例如 ~/.claude.json）。要仅为当前项目注册 tokensave，请添加 --local：

tokensave install --local --agent claude
tokensave install --local --agent omp

这会写入项目范围的配置，您可以提交并与团队共享。对于 Claude，那是 ./.mcp.json、./.claude/settings.json 和 ./CLAUDE.md；OMP 使用 ./.omp/mcp.json 和 ./.omp/rules/tokensave.md，无需调用 OMP CLI。支持的代理：claude、cursor、droid、gemini、zed、opencode、roo-code、kiro、auggie、omp、plank（每个都写入自己的项目文件，例如 plank 的 .cursor/mcp.json、.factory/mcp.json、.gemini/settings.json、.zed/settings.json、opencode.json、.roo/mcp.json、.kiro/settings/mcp.json、.augment/settings.json、.omp/mcp.json、.mcp.json）。其他代理没有项目范围的配置，并会以 --local 报告错误。

使用 tokensave uninstall --local 移除项目本地安装。

3. 索引您的项目

cd /path/to/your/project
tokensave init

这会创建一个包含知识图谱数据库的 .tokensave/ 目录。初始化和同步是分开的命令：init 是每个项目的一次性选择加入，而 sync 只更新已初始化的项目。这可以防止全局 git 钩子在您从未打算索引的仓库中静默创建数据库。在 init 之后，使用 tokensave sync 进行增量更新——只有更改的文件会被重新索引。

{
  "mcpServers": {
    "tokensave": {
      "command": "/path/to/tokensave",
      "args": ["serve"]
    }
  }
}

崩溃弹性同步

Tree-sitter 语法是编译的 C/C++ 代码。它们偶尔会触发内部断言或以 Rust 恐慌处理无法拦截的路径终止进程。从 v4.3.0 开始，每个文件都在短生命周期的 worker 子进程中解析：如果语法段错误、调用 abort() 或遇到堆栈溢出，只有 worker 会死亡。池会重新生成它，有问题的文件会被记录并跳过，sync 继续运行。

worker 是一个隐藏的 extract-worker 子命令，通过每个生成的 256 位令牌对父进程进行身份验证，该令牌既作为 TOKENSAVE_WORKER_TOKEN 环境变量要求，也作为 stdin 上接收的前 32 个字节要求。用户直接调用会失败。默认为 available_parallelism() 个 worker；使用 TOKENSAVE_DISABLE_SUBPROCESS=1 选择退出。

编辑原语（tokensave_str_replace、tokensave_insert_at 等）仍在进程内运行：它们一次针对一个文件，子进程开销会占主导地位，并且那里的提取器崩溃会立即对代理可见。

多分支索引（可选）

tokensave 可以选择为每个 git 分支维护单独的代码图。启用后，切换分支永远不会给您过时的结果，也永远不会重新索引您已在另一个分支上解析的文件。多分支跟踪是选择加入的——没有它，tokensave 为所有分支使用单个数据库。

工作原理

当您跟踪一个分支时，tokensave 会复制最近的祖先数据库，并且只同步不同的文件。这意味着跟踪从 main 分出的功能分支几乎是即时的——它只解析您更改的文件。

CLI 命令

tokensave branch add              # track the current branch
tokensave branch list             # see tracked branches and DB sizes
tokensave branch remove <name>    # stop tracking a branch
tokensave branch removeall        # remove all tracked branches except default
tokensave branch gc               # clean up branches deleted from git

跨分支 MCP 工具

三个 MCP 工具支持跨分支查询，无需切换检出：

• tokensave_branch_search -- 在另一个分支的图中搜索符号
• tokensave_branch_diff -- 比较两个分支之间的代码图：添加、删除和更改的符号（签名不同）。支持文件和种类过滤器。
• tokensave_branch_list -- 列出跟踪的分支及其数据库大小、父分支和同步时间

分支回退

当 MCP 服务器找不到当前分支的数据库时，它会从最近的祖先分支的数据库提供服务，并在每个工具响应中包含警告，建议您运行 tokensave branch add。

自动分支跟踪（v7.3.0）

一旦多分支模式被引导（第一次手动 tokensave branch add 创建了分支元数据），新分支可以自动跟踪，而不是回退到祖先数据库。两个独立机制覆盖了这一点；单数据库模式下的项目永远不会受影响，并且任一机制都不会触及默认分支的数据库。 Git 钩子（分支检出时）。 post-checkout 钩子由 tokensave install 设置，能够识别分支检出（区别于文件检出），并在后台运行 tokensave branch add。当分支已被跟踪或是默认分支时，该命令为空操作，因此在已知分支之间进行普通切换不会产生任何开销。全新 git clone 和新的 git worktree add 的初始检出也属于分支检出，并且可能落在非默认分支上（git clone -b feature、git worktree add -b feature）；此时钩子会先运行 tokensave init，再运行 tokensave branch add，顺序固定。由旧版本写入的钩子会保留其安装时的内容——安装程序从不重写已有钩子——因此在这些安装中，新的工作树仍需要下面的 auto_track，或手动执行 tokensave branch add。

打开时自动跟踪（可选）。 当 TokenSave::open 运行时——无论是 CLI 命令还是 MCP 服务器启动——如果当前活动分支未被跟踪，tokensave 可以通过复制最近的已跟踪祖先的数据库并将其记录到分支元数据中，立即跟踪该分支。此功能由 auto_track 配置字段（默认 false）或 TOKENSAVE_AUTO_TRACK 环境变量控制，环境变量会覆盖每次运行的配置（除 0、false、no、off 或空值外，任何值都会启用该功能）。该复制与手动执行 branch add 时进行的近即时祖先数据库复制相同；此时不会运行同步——post-commit 钩子会在你提交时保持新分支数据库的新鲜度，或运行 tokensave sync 立即刷新。自动跟踪严格尽力而为：任何失败都会报告为警告，open() 会继续使用通常的祖先回退，因此绝不会破坏工具调用。

简而言之：安装了钩子后，检出新的功能分支——包括全新克隆或工作树启动时所在的分支——会透明地为其提供独立的按分支图；启用 auto_track 后，即使在检出之外创建的分支，也会在 tokensave 首次在该分支上打开项目时被捕获。

完整指南请参阅 docs/BRANCHING-USER-GUIDE.md。

跨会话记忆

三个 MCP 工具会在会话之间持久化决策和代码区域上下文，存储在每项目的 .tokensave/tokensave.db 中。

使用这些工具，代理无需在每次会话中重新解释架构选择。

节省账本

每次 MCP 调用都会向 ~/.tokensave/global.db（savings_ledger 表）写入一行追加记录。使用 tokensave gain 检查：

tokensave gain                    # current project, last 30 days
tokensave gain --all              # all projects
tokensave gain --history --range 7d
tokensave gain --json

美元估算使用现有的定价模块（Sonnet 输入定价，通过 LiteLLM 每日刷新）。

可复现基准测试

tokensave bench 通过 tokensave_context 运行固定查询集，并报告与全文件基线相比的检索节省（镜像 CCE 方法论）：

tokensave bench                                    # ships with 10 default queries
tokensave bench --queries my-queries.toml --json
tokensave bench --max-nodes 5

针对此仓库（tokensave 本身）使用随附的通用查询集进行测量：

汇总： 平均检索节省 88%（10 个查询中从 142.8k 降至 5.5k 个 token）。

默认查询集针对大多数应用程序代码库中存在的模式（CLI、守护进程、服务）。使用 tokensave bench 在您自己的项目上运行以查看您的数字，或编写定制的查询文件（--queries my.toml）以获得更精确的召回。

针对大型真实世界仓库的 Criterion 基准

benches/large_repos.rs 是一个 criterion 微基准测试，针对四个固定在常量引用的大型开源代码库端到端地运行 MCP 工具。每个工具由至少 5 个查询驱动，参数（节点 ID、限定名称、文件通配符等）从每个仓库的索引图中采样一次，因此计时在多次运行中可重现。

仓库和固定引用（在 benches/repos.rs 中定义）：

每个仓库在首次使用时进行浅克隆（git init + git fetch --progress --depth 1 origin <ref> + checkout FETCH_HEAD）并缓存在本地；后续运行重用检出。Git 输出流式传输到终端，因此多 GB 的获取会显示实时进度。

覆盖的工具（每个 5 个查询）。 读取工具 — search、context、callers、callees、node、by_qualified_name、signature、impact、body、files、complexity、doc_coverage、largest、hotspots、god_class、module_api、derives、dead_code、rank、coupling、circular。写入工具 — str_replace、multi_str_replace、insert_at，以及（如果 ast-grep 在 PATH 上）ast_grep_rewrite。

每次运行强制同步。 在任何基准测试触发之前，测试框架会在每个仓库上运行等效于 tokensave sync --force 的操作（无论 .tokensave/ 的新鲜度如何，都执行 index_all()），因此计时始终反映固定的源代码。

写入基准和清理。 写入工具会修改文件。为了保持“匹配必须唯一”的前提条件，测试框架使用 criterion 的 iter_batched — 在 <repo>/.tokensave-bench-scratch/ 下的一个小型临时文件在每次计时迭代之前用已知内容重写，然后编辑工具针对它运行。所有基准测试完成后，测试框架在每个准备好的仓库内运行 git stash --include-untracked && git stash drop，使工作树返回到固定引用。

Criterion 配置。 基准测试将 criterion 的默认值覆盖为 sample_size = 10 和 measurement_time = 30s（相对于默认的 100 / 5s），这为每个查询计时提供约 30 秒的测量时间——足以让像 polkadot-sdk 上的 tokensave_context 这样的慢速工具产生稳定的数字。

运行它：

# Required: a writable cache directory for the cloned repos + their indexes.

<p align="center">
  <a href="https://ai.enzolombardi.net/"><img src="https://img.shields.io/badge/built%20with-AI-D97757?style=flat-square&labelColor=101010&logo=anthropic&logoColor=white" alt="Built with AI — part of Enzo Lombardi's AI portfolio"></a>
</p>

# Expect several GB of disk and a long first run (shallow clone + full index of each repo).
export TOKENSAVE_BENCH_REPOS_DIR=~/tokensave-bench-cache

cargo bench --bench large_repos

如果 TOKENSAVE_BENCH_REPOS_DIR 未设置，基准测试会打印通知并注册零个基准（因此 cargo bench --all 在贡献者的机器上保持低成本）。

配置（全部可选，通过环境变量）：

过滤基准测试 使用标准 criterion CLI — 例如，仅在 scipy 上的 search 工具：

cargo bench --bench large_repos -- 'scipy/tokensave_search'

报告（HTML + 原始样本）位于 target/criterion/ 下。

要更改固定引用（例如更新版本或特定 SHA），编辑 benches/repos.rs 中的 REPOS，并删除相应的 $TOKENSAVE_BENCH_REPOS_DIR/<repo>/.bench-ref 标记，以便下次运行重新获取。如果跳过运行后清理（例如在基准测试中途 Ctrl-C），在每个仓库目录内运行 git stash --include-untracked && git stash drop 可手动恢复。

MCP 测试矩阵探针（scripts/mcp_probe）

scripts/mcp_probe/ 是一个 Python 测试框架，通过 stdio 驱动 tokensave serve 针对一组可配置的真实仓库，并对每种语言使用 5 个查询变体运行每个只读 MCP 工具，生成按工具/按仓库的状态表。同一测试框架有两个用途：

• 回归扫描。 新的语言支持、新工具或重构 — 重新运行矩阵，任何新出现错误、超时或返回空结果的单元格都会以 🚩 突出显示。
• 性能探针。 每次调用的计时记录在 TSV 中；相同的固定仓库语料库兼作粗略的跨版本比较。当前的 tokensave_inheritance_depth 周期错误就是由该测试框架发现的，当时 polkadot-sdk 上的单个工具在 >60 秒时超时。

布局 — probe.py 是驱动程序（ID 匹配的 JSON-RPC，因此慢速工具不会污染后续调用），isolated.py 使用每次调用的新服务器重新运行单个工具（避免服务器排队），build_matrix.py 读取 TSV 并生成 markdown，tools/<lang>.py 模块贡献每种语言的查询集（已提供 Rust；通过添加新模块添加 Python/Go/…），repos.toml 列出目标仓库（通过 $TOKENSAVE_PROBE_REPOS 覆盖）。

快速运行：

cargo build --release --bin tokensave
python3 scripts/mcp_probe/probe.py
python3 scripts/mcp_probe/build_matrix.py > matrix.md

输出单元格为 ✓ 5/5（干净）、🐛 e/N（错误）、⏱ N/N（超时）、∅ E/N（空）、🐢 ok/slow（>10 秒调用）。任何带有错误或超时的单元格在最右侧列中都会获得 🚩。每次调用的详细信息以及每个错误的前 100 个字符记录在 TSV 日志中供后续处理。

与上面的 criterion 基准不同：criterion 测量固定引用上聚焦工具集的每次迭代延迟，并在 target/criterion/ 下生成统计报告；mcp_probe 使用更广泛的查询集在您指向的任何仓库上运行每个工具，优化覆盖广度而非测量精度。

80+ 个 MCP 工具

服务器暴露了 80 多个工具（当可选的 ast-grep 二进制不在 PATH 上时少一个）；下表按类别对最常用的工具进行分组。大多数是只读的，可以安全地并行调用，并带有 readOnlyHint 注释。编辑原语限于单个文件并就地重新索引；会话基线和记忆记录工具也会修改本地 .tokensave 状态，并注释为非只读。三个核心工具（tokensave_context、tokensave_search、tokensave_status）标记为 anthropic/alwaysLoad，以便绕过客户端的工具搜索往返。

查询另一个已初始化的项目

语义读取工具可以查询显式选择的本地图，而无需重启 MCP 服务器：

{
  "query": "screenGate",
  "graph_root": "/absolute/path/to/typewhisper"
}

选择的结果包括规范的根/分支来源。节点 ID 命名空间到该图，匹配的选择器必须在后续调用中重复。例如，对分支选择查询的后续调用包括两个值：

{
  "node_id": "graph:<fingerprint>:function:<raw-id>",
  "graph_root": "/absolute/path/to/typewhisper",
  "graph_branch": "feature/auth"
}

graph_root 必须是已初始化项目的精确绝对根目录。graph_branch 是可选的，如果提供，必须命名一个已跟踪的分支。选择打开是只读的：它们从不初始化、同步、迁移、自动跟踪或写入图/源代码数据。它们也不计入节省核算。没有选择器的调用行为与之前完全相同。 graph_root 只有在你知道另一个项目存在时才有用，因此服务器会告诉你：位于服务根目录正旁边的已初始化项目会列在 MCP instructions、tokensave_status 以及空的 tokensave_search / tokensave_context 结果中——此时会话通常会得出“符号不存在”的结论，而不是查看相邻项目（#375）。只提供直接相邻的项目，最多五个，并且不会为它们打开或索引任何内容；查询其中一个仍然需要显式的 graph_root。

选择器有意在写入、执行 shell 或依赖当前检出状态的工具上不可用：编辑原语、VCS 和分支工具、诊断和测试执行、依赖和运行时内省、工作流和会话记忆工具、持久缓存工具（tokensave_redundancy）以及服务器管理。这些工具会拒绝选择器，而不是静默忽略它。

发现

非代码工件

tokensave_files 涵盖的不只是源代码。扩展名列在 artifact_extensions（默认情况下为 .feature、.json、.yaml、.yml、.sql、.toml、.proto、.graphql、.md）中的文件会按路径跟踪，因此像“登录流程的 .feature 文件在哪里？”这样的问题可以得到图形式的答案，而不是被阻塞的 find（#323）。它们永远不会被解析，也不会贡献符号；kind: "artifact" 和 kind: "code" 在两者之间过滤，而含义为“代码”的分析会排除它们。语言提取器已处理的扩展名会在此列表中忽略，因此不能用来阻止语言被解析。

该列表还决定了字面搜索可以查看哪些内容（#442）。对 tokensave_search 进行的字面（literal: true）搜索读取的是字节而不是符号，因此不需要解析器——但它会遍历已索引的文件，所以只能访问索引中持有行的文件。受跟踪的 .html 模板或 .css 样式表既没有提取器，也没有默认的工件条目，因此其匹配会缺失；在此处添加扩展名并运行 tokensave sync -f，其行就会像其他文件一样被搜索，并报告为 enclosing: null，因为没有符号上下文。无法覆盖每个受跟踪文件的字面响应会在 unscanned 块中说明数量和扩展名，因此部分答案永远不会被呈现为完整答案。

调用图与影响

代码质量

代码健康分析

五个工具从现有图中呈现结构质量信号。综合评分使用独立维度上的几何平均值，因此没有任何单一维度可以被操纵。

会话

在 AI 编码会话开始时快照健康指标，然后在结束时进行差异比较，看看哪些改进或退步了。

编辑原语

四个写入工具让代理无需正则表达式或 shell 引用风险即可修改文件。每个都是单文件、锚定的，并在写入后触发就地重新索引，因此图永远不会过时。

Git 与工作流

类型系统

移植

多分支

MCP 资源

通过 resources/list 和 resources/read 暴露了四个资源：

• tokensave://status —— 图形统计信息（JSON 格式）
• tokensave://files —— 按目录分组的已索引文件树
• tokensave://overview —— 项目摘要，包含语言分布和符号种类
• tokensave://branches —— 受跟踪的分支，包含数据库大小和父信息

令牌跟踪

tokensave 会衡量它在每次 MCP 工具调用中节省的令牌。每个工具响应都包含一个 tokensave_metrics: before=N after=M 行，显示该特定调用避免了多少原始文件令牌。

关闭报告。 指标行以及 MCP instructions 中的一句话会要求代理向你报告节省量——这意味着模型会花费输出令牌来叙述 tokensave 在输入令牌上节省的量。输出令牌是更昂贵的那种，因此如果你的代理几乎每轮都提到 tokensave，这种叙述可能会抵消收益（#356）。在 .tokensave/config.json 中将 report_savings 设置为 false，或者设置 TOKENSAVE_REPORT_SAVINGS 环境变量以按运行覆盖（除 0、false、no、off 或空值外的任何值都会启用它）。指标行和指令都会消失；tokensave install 同样会停止将报告规则写入代理提示文件。测量在任何情况下都不受影响——每次调用仍然会记录在节省账本中，因此 tokensave gain、tokensave list、status 和 monitor 会像以前一样继续报告。默认值保持为 true。

成本可观测性

tokensave cost                     # 7-day cost summary (default)
tokensave cost today               # today only
tokensave cost --by-model          # breakdown by Claude model
tokensave cost --by-task           # breakdown by task category (coding, debugging, exploration, ...)
tokensave cost --export json       # JSON export to stdout
tokensave cost --export csv        # CSV export to stdout

解析 Claude Code 会话记录（~/.claude/projects/**/*.jsonl），将每个 API 轮次分类为 13 个任务类别之一，使用模型定价计算美元成本，并将结果存储在 ~/.tokensave/global.db 中以进行快速聚合查询。定价每 24 小时从 LiteLLM 刷新一次，离线时回退到嵌入式表。

tokensave status 标头包含一个成本行，显示今天的支出、7 天总计和效率比（节省的令牌 / 总令牌）。tokensave monitor TUI 在节省信息流旁边显示实时成本面板。在每个 Claude Code 会话结束时，hook_stop 处理程序会在终端打印一行收据。

任务分类类别：编码、调试、功能开发、重构、测试、探索、规划、委派、Git 操作、构建/部署、头脑风暴、对话、通用。分类是确定性的（基于工具名称和 Bash 命令的模式匹配），不需要 LLM 调用，改编自 AgentSeal/codeburn。

实时监视器

tokensave monitor

一个全局 TUI，通过位于 ~/.tokensave/monitor.mmap 的共享内存映射环形缓冲区实时显示所有项目的 MCP 工具调用。每个条目显示项目名称、工具名称和令牌增量。顶部的成本面板显示今天的支出、节省量、效率和顶级模型（每 30 秒刷新一次）。

内存诊断

tokensave memory [--clean]

一份面向所有 tokensave 进程（MCP 服务器、同步、索引运行）的机器级内存报告，通过位于 ~/.tokensave/memory.mmap 的共享内存映射表实现。每个实例在启动时、每次 MCP 工具调用时以及同步/解析阶段前后，都会尽力自采样其 RSS，因此报告会显示当前和峰值 RSS 以及产生峰值的阶段——这是归因高内存使用所需的数据（参见 #253）。行会被标记为 alive、dead（被 OOM 杀死的进程会将其峰值/阶段作为取证记录保留下来）或 orphan（仍在运行但已重新父进程化为 init）。--clean 会清除失效的槽位。

PEAK PHASE 命名的是最高样本，因此其精度仅与采样精度相当。增量同步按顺序记录：sync:extract、sync:resolve:load_nodes、sync:resolve:build_caches、sync:resolve:refs、sync:variants、sync:done。完整索引记录 index:extract、index:resolve:build_caches、index:resolve:refs、index:resolve:done、index:insert、index:done。

每一项都在其所命名的工作完成之后记录。 它们过去是在工作之前记录的，因此每个样本都会在下一步的标签下报告上一步的 RSS——这导致将 73 MiB 归因于节点加载，而实际上该内存属于加载未解析引用，而这一步根本没有样本，并使内存调查在数月内指向了错误的子系统（#409）。如果你添加一个阶段，请在工作之后采样，而不是之前，并为任何大到足以容纳峰值的步骤添加一个样本。

会话和生命周期计数器

tokensave current-counter          # show per-project session counter
tokensave reset-counter            # reset the session counter
tokensave status                   # shows project + global lifetime totals + cost

tokensave status 渲染项目索引统计、语言分布、成本行（今日 / 7 天 / 效率）以及项目 + 全球生命周期总计：

全球计数器

所有 tokensave 用户都会为一个匿名聚合计数器做出贡献。tokensave status 同时显示你的项目总计和全球总计。上传仅发送一个数字（例如 4823），不包含任何身份信息。可通过 tokensave disable-upload-counter 选择退出。

索引新鲜度

tokensave 无需后台守护进程或操作系统级文件监视器即可保持图的最新状态。

按需过期检查。 每次 MCP 工具调用都会检查自上次同步以来是否有任何索引文件被修改。如果发现过期文件，会在返回工具响应之前重新提取它们。30 秒的冷却时间可防止连续调用在每次按键时重新遍历树。

连接时追赶同步。 当 MCP 服务器启动时，它会立即运行一个非阻塞的追赶同步，以拾取在没有代理连接时发生的任何更改——例如 git pull、IDE 编辑、构建步骤——因此会话的第一次工具调用会看到新鲜的索引。

多代理工作和 git worktree。 当多个代理同时处理同一项目时，一个强假设是每个代理都在自己的 git worktree 中操作。Worktree 是同一仓库的独立文件系统检出：代理 A 和代理 B 各自拥有每个文件的副本，因此它们永远不会覆盖彼此进行中的编辑。tokensave 会自动检测查询是否来自主检出目录内嵌套的 worktree，并从正确的分支图提供结果。更改会独立累积，并最终通过 git merge 或 rebase 进行协调——这与任何其他并行开发使用的过程相同。这种设计避免了跨代理锁定共享可变目录的复杂性和故障模式。

仅 CLI 工作流。 如果你在没有附加代理（无 MCP 服务器）的情况下运行 tokensave 命令，则命令之间不会运行过期检查。安装 git hooks 以在每次提交或克隆后自动保持索引新鲜：

cp scripts/post-commit scripts/post-checkout .git/hooks/
chmod +x .git/hooks/post-commit .git/hooks/post-checkout

从 5.x 升级

独立的 tokensave daemon 命令及其 launchd/systemd/Windows 服务自动启动已在 6.0.0 中移除。取代守护进程的嵌入式操作系统级文件监视器本身也在 6.1.1 中被移除（它在具有深层 node_modules 或 target 树的大型 monorepo 上导致 CPU 和内存失控）。上述按需过期模型是当前的设计。

如果你仍有 5.x 的守护进程自动启动，请将其移除：

• macOS：launchctl unload ~/Library/LaunchAgents/com.tokensave.daemon.plist && rm ~/Library/LaunchAgents/com.tokensave.daemon.plist
• Linux：systemctl --user disable --now tokensave-daemon && rm ~/.config/systemd/user/tokensave-daemon.service
• Windows：sc.exe delete tokensave-daemon（从提升的终端）

如果你不记得确切名称：launchctl list | grep tokensave / systemctl --user list-units | grep tokensave / sc.exe query state= all | findstr -i tokensave。

自我升级

tokensave upgrade                  # upgrade to latest in current channel
tokensave channel                  # show current channel (stable/beta)
tokensave channel beta             # switch to beta channel
tokensave channel stable           # switch back to stable

tokensave upgrade 从 GitHub releases 下载正确的平台二进制文件，并就地替换正在运行的二进制文件。独立支持稳定版和测试版频道。

版本与升级

tokensave 版本号看起来像 SemVer，但并不遵循它：变化的组件编码了更新所需的维护工作，tokensave 会在下次启动时自动执行这些维护——你永远不需要手动重新安装或重新索引。

全局重新安装。 在新的次要或主要构建首次运行时，tokensave 会静默地为每个已注册的代理重新运行 install，以便代理配置始终指向当前二进制文件并暴露当前工具集。补丁版本提升会跳过此步骤——运行版本标记只是简单地推进。

重新安装是真正静默的：显式运行 tokensave install 时看到的每个代理设置输出在此处被抑制，因此它永远不会出现在普通的 tokensave init 或 tokensave sync 之前。如果代理的配置无法刷新——应用未安装，或其配置位于只读位置——你会看到一行列出失败的代理：

warning: could not refresh tokensave config for: copilot.
  Run tokensave install to see the error.

运行 tokensave install 以查看底层错误。版本标记无论如何都会推进，因此永远无法写入的配置路径会在每次升级时报告一次，而不是在后续每个命令中重试。

每个项目的强制重新索引（仅主要版本）。 主要版本提升意味着必须重建项目索引。tokensave 会惰性地按项目执行此操作：在主要版本升级后，项目中的第一次 MCP 工具调用时，它会生成一个后台完整重新索引（相当于 tokensave sync --force），绝不会阻塞工具响应。

Brew / cargo 回退。 在 tokensave upgrade 之外替换二进制文件的外部升级——例如 brew upgrade tokensave 或 cargo install tokensave——会以相同方式检测：如果运行版本比上次执行安装的版本更新，则重新安装会在下次启动时运行，就像自我升级后一样。

有关 tokensave 为何偏离 SemVer（将维护编码在版本中正是实现零接触升级的原因）、标记机制、独立的数据库模式版本以及发布版本的维护者规则，请参阅 TOKENSAVE-VERSIONING.md。

CLI 参考

tokensave init [path]              # Initialize a new project (full index)
tokensave sync [path]              # Incremental sync (must be initialized first)
tokensave sync --force [path]      # Force a full re-index
tokensave sync --doctor [path]     # Sync and list added/modified/removed files
tokensave status [path]            # Show statistics + cost summary
tokensave status [path] --json     # Show statistics (JSON output)
tokensave status --details         # Include node-kind breakdown
tokensave cost [range]             # Token cost summary (default: 7d)
tokensave cost --by-model          # Cost grouped by model
tokensave cost --by-task           # Cost grouped by task category
tokensave cost --export json|csv   # Export cost data
tokensave query <search> [path]    # Search symbols
tokensave files [--filter dir] [--pattern glob] [--json]   # List indexed files
tokensave affected <files...> [--stdin] [--depth N]        # Find affected test files
tokensave install [--agent NAME]   # Configure agent integration
tokensave reinstall                # Refresh settings for all installed agents
tokensave uninstall [--agent NAME] # Remove agent integration
tokensave serve [--idle-timeout-secs N]   # Start MCP server (N: exit after N idle seconds)
tokensave servers [--json]         # List running servers and the index each one holds
tokensave monitor                  # Live TUI showing MCP calls across all projects
tokensave memory [--clean]         # Per-instance RSS report for all tokensave processes
tokensave upgrade                  # Self-update to latest version
tokensave channel [stable|beta]    # Show or switch update channel
tokensave doctor [--agent NAME]    # Check installation health
tokensave githooks [on|off] [--local]  # Manage git hooks (--local: this repo only, no core.hooksPath)
tokensave branch add|list|remove|removeall|gc   # Multi-branch management
tokensave current-counter          # Show per-project token counter
tokensave reset-counter            # Reset per-project token counter
tokensave disable-upload-counter   # Opt out of worldwide counter uploads
tokensave enable-upload-counter    # Re-enable worldwide counter uploads

tokensave doctor

对你的 tokensave 安装运行全面的健康检查：

tokensave doctor

检查项：二进制位置、项目索引、全局数据库、用户配置、代理集成（MCP 服务器、hooks、权限、提示规则）以及网络连接。如果升级后缺少任何工具权限，它会告诉你运行 tokensave install。使用 --agent 仅检查特定代理。

Doctor 还会验证每个已安装的 hook 是否使用正确的 tokensave 子命令，并自动修复损坏的 hook。

与 Claude Code 的协作方式

配置完成后，Claude Code 在需要理解你的代码库时会自动使用 tokensave，而不是读取原始文件。三个层次相互强化：

结果：Claude 以更少的 token 获得相同的代码理解。典型的 Explore 代理读取 20-50 个文件；tokensave 从其预构建索引中返回相关符号、关系和代码片段。

网络调用与隐私

tokensave 的核心功能（索引、搜索、图查询、MCP 服务器）100% 本地化——你的代码永远不会离开你的机器。

全球计数器上传发送单个 HTTP POST，JSON 主体类似于 {"amount": 4823}。无 cookie、无跟踪、无用户 ID。Cloudflare Worker 记录你 IP 地址的国家（从请求头派生）用于聚合地理统计——你的实际 IP 地址不会被存储。

模型定价刷新从 GitHub 获取一个公共 JSON 文件（raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json），以保持 Claude 模型定价的最新状态，用于 tokensave cost。不发送任何数据——这是一个普通的 HTTPS GET。响应缓存在 ~/.tokensave/pricing.json 处，持续 24 小时。如果获取失败，tokensave 使用其编译在内的定价表。

50+ 种语言

tokensave 支持超过 50 种编程语言，分为三个层级，由 Cargo feature flags 控制。每个层级包含其下所有层级的语言。Markdown 标题被提取为 Module 节点，带有层级化的 Contains 边，因此文档结构可以像源代码一样参与图查询。

Lite——--no-default-features

始终编译。最流行语言的最小二进制文件，外加 Svelte 和 Astro（通过 TypeScript 提取器进行脚本块提取，无额外语法依赖）。

Medium（Lite + 9 种）——--features medium

完整（中等 + 其他所有）——默认

也可以在不使用完整层级的情况下单独挑选个别语言：

cargo install tokensave --no-default-features --features lang-nix,lang-bash

所有提取器共享相同的深度：函数、类、方法、字段、导入、调用图、继承链、文档字符串、复杂度指标、装饰器/注解提取，以及跨文件依赖跟踪。

tokensave 与 CodeGraph 对比

tokensave 是对 CodeGraph（Node.js/TypeScript）的全新 Rust 重写。两者都为 AI 编码代理构建语义代码图，但在范围和能力上存在显著差异。

CodeGraph 开创了这种方法，如果你更喜欢 npm 工具并且只需要 Claude Code 集成，它仍然是一个可靠的选择。tokensave 通过更深入的分析、更多代理、多分支支持以及无运行时依赖的原生二进制扩展了这一概念。

有关与 CodeGraph、Dual-Graph（GrapeRoot）、code-review-graph 和 OpenWolf 的详细比较，请参阅 docs/COMPARABLE-TOOLS.md。

为什么选择 tokensave 而非其他替代方案

有几款工具可以减少 AI 编码代理的 token 使用量。以下是 tokensave 脱颖而出的原因。

单一原生二进制，零依赖

每个替代方案都需要运行时：Python、Node.js 或两者兼有。tokensave 以单个约 25 MB 的 Rust 二进制形式发布，捆绑了所有 50+ 个 tree-sitter 语法。无需安装其他任何东西。

最深入的代码智能

tokensave 在符号级别工作：函数、结构体、字段、调用边、类型层次结构、复杂度指标。像 Dual-Graph（GrapeRoot）这样的替代方案在文件级别工作——它们知道哪些文件存在，但无法回答“谁调用了这个函数？”或“如果我更改这个结构体会破坏什么？”tokensave 的 80+ 个专用 MCP 工具涵盖调用图遍历、影响分析、死代码检测、测试映射、重命名预览、类型层次结构、循环依赖检测、复杂度排名、代码健康分析（Gini、DSM、依赖深度、风险加权测试缺口）、原子编辑原语等。最接近的竞争对手（code-review-graph）有 22 个工具；其他只有 5-9 个。

最广泛的代理支持

超过十二种 AI 编码代理集成，每种都有原生配置格式。没有其他工具能覆盖这么多代理并提供如此深入的集成。Claude Code 获得钩子、提示规则和自动允许的工具权限。Kiro 获得全局 MCP 配置、作为资源加载的 tokensave.md 引导、具有宽松内置/tokensave 工具审批的托管代理，以及用于委派护栏和写入后同步的钩子。其他代理在其原生配置格式中获得 MCP 服务器注册。

多分支索引

该领域唯一提供可选按分支图数据库以及跨分支差异和搜索的工具。启用后，切换分支是即时的——无需重新索引。

每次调用 Token 跟踪

唯一能精确报告每个单独 MCP 工具调用节省了多少 token 的工具，外加跨所有项目的实时 TUI 监视器和生命周期计数器。

完全开源

MIT 许可的 Rust，端到端可审计。Dual-Graph 的核心引擎（PyPI 上的 graperoot）是专有的——你无法看到它对你的代码图做了什么。OpenWolf 是 AGPL-3.0，要求衍生作品开源。

性能

在包含 1,782 个文件的混合 Rust/Java/Scala 代码库（57K 节点、103K 边）上的完整索引基准测试：

故障排除

“tokensave 未初始化”

你的项目中不存在 .tokensave/ 目录。

tokensave init

MCP 服务器未连接

AI 代理看不到 tokensave 工具。

1. 确保代理配置包含 tokensave MCP 服务器（运行 tokensave doctor）
2. 完全重启代理
3. 检查 tokensave 是否在你的 PATH 中：which tokensave

搜索中缺少符号

• 运行 tokensave sync 更新索引
• 检查该语言是否受支持（见上表）
• 验证文件未被 .gitignore 排除

索引缓慢

大型项目在首次完整索引时需要更长时间。

• 后续运行使用增量同步，速度更快
• 对于日常更新，使用 tokensave sync（而不是 --force）
• 代理连接时，每次 MCP 工具调用都会自动检查过期状态

为特定项目禁用 tokensave

如果项目太大且 tokensave 使用过多 RAM，你可以通过在其环境中设置 TOKENSAVE_DISABLE_SERVER=true 来按项目禁用 MCP 服务器。服务器会在不初始化的情况下干净退出。

Claude Code — 添加到你的项目的 .claude/settings.json：

{
  "mcpServers": {
    "tokensave": {
      "command": "tokensave",
      "args": ["serve"],
      "env": {
        "TOKENSAVE_DISABLE_SERVER": "true"
      }
    }
  }
}

其他代理 — 在你的代理用于启动 MCP 服务器的任何配置中设置环境变量。

你也可以通过 shell 全局设置（TOKENSAVE_DISABLE_SERVER=true claude），但这会禁用会话中所有项目的 tokensave MCP 服务器。

DISABLE_TOKENSAVE=true 仍然作为已弃用的兼容别名受支持，用于在此变量命名空间化之前创建的配置。

起源

本项目是原始 CodeGraph TypeScript 实现的 Rust 移植，原作者为 @colbymchenry。该移植保持了相同的架构和 MCP 工具接口，同时利用 Rust 实现性能和原生 tree-sitter 绑定。

构建

cargo build --release                          # full (50+ languages, default)
cargo build --release --features medium        # medium tier
cargo build --release --no-default-features    # lite (smallest binary)

cargo test                                     # run all tests (requires full)
cargo check --no-default-features              # verify lite compiles
cargo clippy --all

Star 历史

赞助商

Windows 上的免费代码签名由 SignPath.io 提供，证书由 SignPath Foundation 颁发

许可证

MIT 许可证——详情请参阅 LICENSE。

tokensave.dev