tokensave

AI 程式碼智能，專為 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-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 hook（阻擋浪費資源的 Explore 代理）、UserPromptSubmit hook、Stop hook、CLAUDE.md 中的提示規則，以及自動允許的工具權限。Kiro 獲得全域 MCP 設定、以資源載入的 tokensave.md 導向，以及 tokensave 管理的預設代理，具備寬鬆的內建/tokensave 工具核准、委派護欄 hook 和寫入後同步；使用者管理的 Kiro 代理會被保留。

全域 OMP 安裝目標是裸 omp config path 回報的 profile，寫入 <resolved-agent-dir>/mcp.json 和 <resolved-agent-dir>/rules/tokensave.md。安裝到具名 profile 時，匯出 OMP_PROFILE 或 OMP 相容的 PI_PROFILE；OMP 的解析器也遵循 PI_CONFIG_DIR 和 PI_CODING_AGENT_DIR。Tokensave 信任該原生解析器，而非重複 OMP 的 profile 邏輯。Tokensave 為 OMP 安裝 MCP 和建議規則；它不安裝 OMP hook 強制執行。

所有變更都是冪等的——升級後再次執行是安全的。代理設定完成後，你會獲得全域 git post-commit 和 post-checkout hooks 的選項。tokensave uninstall 會移除這些 hooks 以及代理整合；傳入 --keep-git-hooks 以保留它們，或使用 tokensave githooks 自行管理。

專案本地安裝

預設情況下，tokensave install 會在你的全域代理設定（例如 ~/.claude.json）中註冊 MCP 伺服器。若要僅為目前專案註冊 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 hooks 在你從未打算索引的儲存庫中默默建立資料庫。在 init 之後，使用 tokensave sync 進行增量更新——只有變更的檔案會被重新索引。

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

崩潰韌性同步

Tree-sitter 文法是編譯的 C/C++ 程式碼。它們偶爾會觸發內部斷言，或以 Rust panic 處理無法攔截的路徑終止程序。自 v4.3.0 起，每個檔案都在短命的 worker 子程序中解析：如果文法 segfault、呼叫 abort() 或遇到堆疊溢位，只有該 worker 會死亡。池會重新產生它，有問題的檔案會被記錄並跳過，sync 會繼續執行。

該 worker 是一個隱藏的 extract-worker 子命令，透過每次產生的 256 位元 token 對父程序進行驗證，該 token 既是 TOKENSAVE_WORKER_TOKEN 環境變數，也是 stdin 上接收的前 32 個位元組。使用者直接呼叫會失敗。預設為 available_parallelism() 個 worker；使用 TOKENSAVE_DISABLE_SUBPROCESS=1 選擇退出。

編輯原語（tokensave_str_replace、tokensave_insert_at 等）仍在程序內執行：它們一次針對一個檔案，子程序開銷會主導，而萃取器崩潰會立即對代理可見。

多分支索引（選擇性）

tokensave 可以選擇性地為每個 git 分支維護獨立的程式碼圖譜。啟用後，切換分支絕不會給你過期結果，也絕不會重新索引你在另一個分支上已解析的檔案。多分支追蹤是選擇性加入——沒有它，tokensave 對所有分支使用單一資料庫。

運作方式

當你追蹤一個分支時，tokensave 會複製最近的祖先 DB，並只同步不同的檔案。這意味著追蹤從 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 工具讓你在不切換 checkout 的情況下進行跨分支查詢：

• tokensave_branch_search —— 在另一個分支的圖譜中搜尋符號
• tokensave_branch_diff —— 比較兩個分支之間的程式碼圖譜：新增、移除和變更（簽名不同）的符號。支援檔案和種類篩選器。
• tokensave_branch_list —— 列出已追蹤的分支，含 DB 大小、父分支和同步時間

分支回退

當 MCP 伺服器找不到目前分支的 DB 時，它會從最近的祖先分支 DB 提供服務，並在每個工具回應中包含警告，建議你執行 tokensave branch add。

自動分支追蹤（v7.3.0）

一旦多分支模式被引導（第一次手動 tokensave branch add 建立了分支中繼資料），新分支就可以自動追蹤，而非回退到祖先 DB。兩個獨立機制涵蓋此情況；單一 DB 模式的專案絕不受影響，且任一機制都絕不會觸及預設分支的資料庫。 Git hook（於分支簽出時）。 post-checkout 所設定的 tokensave install hook 會辨識 分支 簽出（相對於檔案簽出），並在背景執行 tokensave branch add。當分支已被追蹤或是預設分支時，該指令為無操作（no-op），因此在已知分支之間的一般切換不會產生任何成本。全新 git clone 與新 git worktree add 的初始簽出也屬於分支簽出，且可能落在非預設分支上（git clone -b feature、git worktree add -b feature）；此時 hook 會先執行 tokensave init，再依序執行 tokensave branch add。由較早版本寫入的 hook 會保留其安裝時的主體——安裝程式絕不會改寫既有的 hook——因此在這些安裝環境中，新的工作樹仍需要下方的 auto_track，或手動執行 tokensave branch add。

開啟時自動追蹤（選擇性啟用）。 當 TokenSave::open 執行時——無論是 CLI 指令或 MCP 伺服器啟動——若目前作用中的分支未被追蹤，tokensave 可以當場追蹤它，方法是複製最近被追蹤的祖先分支的資料庫，並將其記錄在分支中繼資料中。此功能由 auto_track 設定欄位（預設為 false）或 TOKENSAVE_AUTO_TRACK 環境變數控制，後者會每次執行時覆寫設定（任何值皆可啟用，除了 0、false、no、off 或空值以外）。此複製動作與手動執行 branch add 時所做的近即時祖先資料庫複製相同；此時不會執行同步——post-commit hook 會在你提交時保持新分支資料庫的新鮮度，或執行 tokensave sync 以立即重新整理。自動追蹤嚴格來說是盡力而為：任何失敗都會回報為警告，且 open() 會以一般的祖先分支遞補方式繼續進行，因此絕不會中斷工具呼叫。

簡而言之：安裝 hook 後，簽出新的功能分支——包括全新 clone 或 worktree 起始所在的分支——會透明地賦予其各自的每分支圖表；若啟用 auto_track，即使在簽出之外建立的分支，也會在 tokensave 首次於該分支上開啟專案時被納入。

完整指南請參閱 docs/BRANCHING-USER-GUIDE.md。

跨工作階段記憶

三個 MCP 工具會在工作階段之間持久化決策與程式碼區域脈絡，儲存於每個專案的 .tokensave/tokensave.db 中。

請善用這些工具，讓代理程式不必在每次工作階段之間重新解釋架構選擇。

節省帳本

每次 MCP 呼叫都會將一列僅附加（append-only）的記錄寫入 ~/.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 tokens）。

預設查詢集針對大多數應用程式碼庫中常見的模式（CLI、daemon、服務）。使用 tokensave bench 在您自己的專案上執行以查看您的數據，或撰寫自訂查詢檔案（--queries my.toml）以獲得更精確的回憶。

針對大型真實世界儲存庫的 Criterion 基準測試

benches/large_repos.rs 是一個 criterion 微基準測試，針對四個釘選在固定 refs 的大型開源程式碼庫，端對端地演練 MCP 工具。每個工具由至少 5 個查詢驅動，引數（節點 ID、限定名稱、檔案 glob 等）從每個儲存庫的索引圖表中取樣一次，因此計時結果在不同執行之間是可重現的。

儲存庫與釘選 refs（定義於 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，使工作樹回到釘選的 ref。

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/ 下。

若要變更釘選的 refs（例如更新到較新版本或特定 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 量測釘選 refs 上聚焦工具集的每次迭代延遲，並在 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。

選擇器刻意不提供給會寫入、執行外部指令、或依賴目前 checkout 的工具：編輯原語、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 編碼工作階段開始時快照健康度指標，然後在結束時比對差異，看看哪些改善了或退步了。

編輯原語

四個寫入工具，讓代理程式可以在沒有 regex 或 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。

關閉回報。 指標行，加上 MCP instructions 中的一句話，會要求代理程式向你回報節省量——這表示模型會花費輸出 token 來敘述 tokensave 在輸入 token 上節省的內容。輸出 token 是較昂貴的種類，因此如果你的代理程式幾乎每一輪都提到 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 天總計與效率比（節省的 token／總 token）。tokensave monitor TUI 會在節省摘要旁顯示即時成本面板。在每個 Claude Code 工作階段結束時，hook_stop 處理器會在終端機列印一行收據。

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

即時監控

tokensave monitor

一個全域 TUI，透過位於 ~/.tokensave/monitor.mmap 的共享記憶體映射環形緩衝區，即時顯示所有專案的 MCP 工具呼叫。每個項目顯示專案名稱、工具名稱與 token 差異。頂部的成本面板顯示今日花費、節省量、效率與主要模型（每 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 以在每次 commit 或 clone 後自動保持索引新鮮：

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-VERSIONING.md 了解 tokensave 為何偏離 SemVer（將維護編碼在版本中正是實現零接觸升級的關鍵）、標記機制、獨立的資料庫 schema 版本，以及維護者發布版本的規則。

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 子命令，並自動修復損壞的 hooks。

與 Claude Code 的運作方式

設定完成後，Claude Code 在需要理解你的程式碼庫時，會自動使用 tokensave 而非讀取原始檔案。三層互相強化：

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

網路呼叫與隱私

tokensave 的核心功能（索引、搜尋、圖形查詢、MCP 伺服器）100% 在本機——你的程式碼永遠不會離開你的機器。

全球計數器上傳傳送單一 HTTP POST，JSON body 如 {"amount": 4823}。無 cookies、無追蹤、無使用者 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 擷取器進行 script-block 擷取，無需額外的語法依賴）。

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

完整（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 獲得 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 使用過多 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