tokensave

AI 編碼代理的語義程式碼智慧

更少的 token • 更少的工具呼叫 • 100% 本機

為什麼選擇 tokensave？

AI 編碼代理在探索程式碼庫時浪費了大量 token。每次 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 呼叫，高 token 使用量。

有了 tokensave： 代理透過 MCP 工具查詢圖譜——即時結果、本機處理、更少的 token。

主要功能

快速入門

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 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 opencode        # OpenCode
tokensave install --agent pi              # Pi (pi.dev)
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)

每個代理會在其原生設定格式中註冊 MCP 伺服器。Claude Code 還會額外獲得一個 PreToolUse 鉤子（阻止浪費的 Explore 代理）、一個 UserPromptSubmit 鉤子、一個 Stop 鉤子、CLAUDE.md 中的提示規則，以及自動允許的工具權限。Kiro 會獲得全域 MCP 設定、作為資源載入的 tokensave.md 引導，以及一個由 tokensave 管理的預設代理，具有寬鬆的內建/tokensave 工具批准、委派防護鉤子和寫入後同步；使用者管理的 Kiro 代理將被保留。

所有變更都是冪等的——升級後再次執行是安全的。代理設定完成後，系統會向您提供全域 git post-commit 和 post-checkout 鉤子。

專案本機安裝

預設情況下，tokensave install 會在您的全域代理設定（例如 ~/.claude.json）中註冊 MCP 伺服器。若要改為僅為目前專案註冊 tokensave，請新增 --local：

tokensave install --local --agent claude

這會寫入專案範圍的設定，您可以提交並與團隊分享。對於 Claude，即 ./.mcp.json、./.claude/settings.json 和 ./CLAUDE.md。支援的代理：claude、cursor、droid、gemini、zed、opencode、roo-code、kiro、auggie（每個代理都會寫入自己的專案檔案，例如 .cursor/mcp.json、.factory/mcp.json、.gemini/settings.json、.zed/settings.json、opencode.json、.roo/mcp.json、.kiro/settings/mcp.json、.augment/settings.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 開始，每個檔案都在一個短暫的工作子程序內部進行解析：如果語法發生 segfault、呼叫 abort() 或遇到堆疊溢位，只有工作程序會終止。程序池會重新生成它，有問題的檔案會被記錄並跳過，而 sync 會繼續執行。

工作程序是一個隱藏的 extract-worker 子指令，透過每次生成一個 256 位元的 token 對父程序進行驗證，該 token 需要同時作為 TOKENSAVE_WORKER_TOKEN 環境變數和透過 stdin 接收的前 32 個位元組。使用者直接調用會失敗。預設為 available_parallelism() 個工作程序；使用 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 鉤子（分支檢出時）。 tokensave install 設定的 post-checkout 鉤子會識別分支檢出（相對於檔案檢出），並在背景執行 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 後，即使在檢出之外建立的分支（例如在新的 worktree 中）也會在 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、限定名稱、檔案 glob 等）在每個儲存庫中從索引圖中取樣一次，因此計時結果在不同執行之間是可重現的。

儲存庫和固定參考版本（定義於 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 / 5 秒），這使得每個查詢的計時測量大約有 30 秒的時間 — 足以讓像 polkadot-sdk 上的 tokensave_context 這類慢速工具產生穩定的數據。

執行方式：

# Required: a writable cache directory for the cloned repos + their indexes.
# 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，因此它們會繞過用戶端的工具搜尋往返過程。

探索

呼叫圖與影響

程式碼品質

程式碼健康分析

五個工具從現有圖表中呈現結構品質訊號。綜合分數使用跨獨立維度的幾何平均值，因此無法針對單一維度進行操弄。

工作階段

在 AI 編碼工作階段開始時擷取健康度量快照，然後在結束時進行差異比較，以查看哪些方面有所改善或退步。

編輯原語

四個寫入工具，讓代理程式無需使用正則表達式或 Shell 引用風險即可修改檔案。每個工具都是單一檔案、基於錨點，並在寫入後觸發就地重新索引，確保圖譜永遠不會過時。

Git 與工作流程

型別系統

移植

多分支

MCP 資源

透過 resources/list 和 resources/read 公開了四個資源：

• tokensave://status -- JSON 格式的圖譜統計資料
• tokensave://files -- 按目錄分組的已索引檔案樹
• tokensave://overview -- 專案摘要，包含語言分佈和符號類型
• tokensave://branches -- 已追蹤的分支，包含資料庫大小和父項資訊

Token 追蹤

tokensave 會測量每次 MCP 工具呼叫所節省的 token。每個工具回應都包含一個 tokensave_metrics: before=N after=M 行，顯示該特定呼叫避免了讀取多少原始檔案 token。

成本可觀測性

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 天總計和效率比（節省的 token / 總 token）。tokensave monitor TUI 會在節省資訊饋送旁邊顯示一個即時成本面板。在每個 Claude Code 工作階段結束時，hook_stop 處理常式會向終端機列印一行收據。

任務分類類別：編碼、除錯、功能開發、重構、測試、探索、規劃、委派、Git 操作、建置/部署、腦力激盪、對話、一般。分類是確定性的（基於工具名稱和 Bash 命令的模式比對），無需 LLM 呼叫，並改編自 AgentSeal/codeburn。

即時監控器

tokensave monitor

一個全域 TUI，透過位於 ~/.tokensave/monitor.mmap 的共享記憶體映射環形緩衝區，即時顯示來自所有專案的 MCP 工具呼叫。每個條目顯示專案名稱、工具名稱和 token 差異。頂部的成本面板顯示今日花費、節省、效率和頂級模型（每 30 秒更新一次）。

工作階段和生命週期計數器

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 工作樹。 當多個代理程式同時在同一個專案上工作時，強烈假設是每個代理程式都在自己的 git 工作樹中操作。工作樹是同一個儲存庫的獨立檔案系統檢出：代理程式 A 和代理程式 B 各自擁有每個檔案的副本，因此它們永遠不會覆蓋彼此進行中的編輯。tokensave 會自動偵測查詢是否來自嵌套在主檢出內的工作樹，並從正確的分支圖譜提供結果。變更會獨立累積，並最終透過 git 合併或變基進行協調——這與任何其他平行開發所使用的流程相同。此設計避免了在共享可變目錄上進行跨代理程式鎖定的複雜性和失敗模式。

僅限 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.0 中移除（它在具有深層 node_modules 或 target 樹的大型單一儲存庫上導致 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 發行版下載正確的平台二進位檔，並就地替換執行中的二進位檔。獨立支援穩定版和測試版頻道。

版本管理與升級

tokensave 的版本號看起來像 SemVer，但並未遵循它：變更的元件編碼了更新所需的維護，tokensave 會在下一次啟動時自動執行——您永遠不需要手動執行重新安裝或重新索引。

全域重新安裝。 在首次執行新的次要或主要版本時，tokensave 會默默地為其已註冊的每個代理程式重新執行 install，因此代理程式配置始終指向目前的二進位檔並公開目前的工具集。修補版本會跳過此步驟——僅會推進執行中的版本標記。

每個專案的強制重新索引（僅限主要版本）。 主要版本變更意味著必須重建專案索引。tokensave 會以惰性且按專案的方式執行此操作：在主要升級後，於專案中的第一次 MCP 工具呼叫時，它會生成一個背景完全重新索引（等同於 tokensave sync --force），該操作絕不會阻塞工具回應。

Brew / cargo 回退。 在 tokensave upgrade 之外替換二進位檔的外部升級——brew upgrade tokensave 或 cargo install tokensave——會以相同方式偵測：如果執行中的版本比上次執行安裝的版本更新，則會在下一次啟動時執行重新安裝，就像自我升級後一樣。

請參閱 TOKENSAVE-VERSIONING.md，了解 tokensave 為何偏離 SemVer（在版本中編碼維護是實現零接觸升級的原因）、標記機制、獨立的資料庫架構版本，以及維護人員發布版本的規則。

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                    # Start MCP server
tokensave monitor                  # Live TUI showing MCP calls across all projects
tokensave upgrade                  # Self-update to latest version
tokensave channel [stable|beta]    # Show or switch update channel
tokensave doctor [--agent NAME]    # Check installation health
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 子命令，並自動修復損壞的 hooks。

它如何與 Claude Code 協同工作

一旦配置完成，Claude Code 在需要理解您的程式碼庫時，會自動使用 tokensave，而不是讀取原始檔案。三個層次相互加強：

結果：Claude 以更少的 token 獲得相同的程式碼理解。典型的 Explore 代理程式會讀取 20-50 個檔案；tokensave 則從其預先建置的索引中傳回相關的符號、關係和程式碼片段。

網路呼叫與隱私

tokensave 的核心功能（索引、搜尋、圖譜查詢、MCP 伺服器）是100% 本機的——您的程式碼永遠不會離開您的機器。| 呼叫 | 傳送的資料 | 時機 | 退出選項 | |------|-----------|------|---------| | 全球計數器上傳 | Token 數量（一個數字）+ 國家（來自 IP） | 同步、狀態、MCP 工作階段 | tokensave disable-upload-counter | | 全球計數器讀取 | 無（GET 請求） | 狀態 | 不適用（唯讀，1 秒逾時） | | 版本檢查 | 無（GET 請求） | 狀態（快取 5 分鐘）、同步（並行） | 不適用（1 秒逾時，失敗時無操作） | | 模型定價更新 | 無（GET 請求） | tokensave cost（快取 24 小時） | 不適用（5 秒逾時，退回使用內嵌定價） |

全球計數器上傳會傳送一個 HTTP POST，其 JSON 主體類似 {"amount": 4823}。沒有 Cookie、沒有追蹤、沒有使用者 ID。Cloudflare Worker 會記錄您 IP 位址的國家（從請求標頭取得），用於彙總的地理統計資料——您的實際 IP 位址不會被儲存。

模型定價更新會從 GitHub（raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json）擷取一個公開的 JSON 檔案，以便為 tokensave cost 保持 Claude 模型定價的最新狀態。不會傳送任何資料——這只是一個純 HTTPS GET 請求。回應會在 ~/.tokensave/pricing.json 快取 24 小時。如果擷取失敗，tokensave 會使用其編譯時內建的定價表。

50 多種語言

tokensave 支援 50 多種程式語言，並透過 Cargo 功能旗標劃分為三個層級。每個層級都包含其下層級的所有語言。Markdown 標頭會被提取為 Module 節點，並帶有階層式的 Contains 邊，讓文件結構能與原始碼一同參與圖形查詢。

Lite -- --no-default-features

始終編譯。針對最熱門語言的最小執行檔，外加 Svelte 和 Astro（透過 TypeScript 提取器進行腳本區塊提取，無需額外的語法依賴）。

Medium（Lite + 9 種更多語言）-- --features medium

Full（Medium + 所有其他語言）-- 預設

也可以在不選用整個層級的情況下，單獨挑選特定語言：

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

所有提取器共享相同的深度：函式、類別、方法、欄位、匯入、呼叫圖、繼承鏈、文件字串、複雜度指標、裝飾器/註解提取，以及跨檔案依賴追蹤。

tokensave 與 CodeGraph 的比較

tokensave 是從頭開始以 Rust 重寫的 CodeGraph（Node.js/TypeScript）。兩者都為 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 可獲得 hooks、提示規則和自動允許的工具權限。Kiro 可獲得全域 MCP 設定、作為資源載入的 tokensave.md 引導、一個受管理的代理，其具備寬鬆的內建/tokensave 工具核准，以及用於委派防護和寫入後同步的 hooks。其他代理則可在其原生設定格式中獲得 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 使用過多記憶體，可以在 MCP 伺服器環境中設定 DISABLE_TOKENSAVE=true 來針對該專案停用。伺服器會乾淨地退出而不進行初始化。

Claude Code — 加入至專案的 .claude/settings.json：

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

其他代理 — 在代理用來啟動 MCP 伺服器的設定中設定環境變數。

你也可以透過 shell 全域設定（DISABLE_TOKENSAVE=true claude），但這會停用該工作階段中所有專案的 tokensave。

起源

此專案是原始 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