tokensave

AIコーディングエージェントのためのセマンティックコードインテリジェンス

より少ないトークン • より少ないツール呼び出し • 100%ローカル

なぜtokensaveなのか？

AIコーディングエージェントはコードベースの探索にトークンを浪費します。すべてのgrep、glob、ファイル読み取りにコストがかかります。複雑なタスクでは、エージェントはコンテキストを構築するためだけに数百のファイルをスキャンする複数のExploreサブエージェントを生成します。

tokensaveはエージェントに事前にインデックス化されたセマンティックナレッジグラフを提供します。 ファイルをスキャンする代わりに、エージェントはグラフにクエリを実行し、適切なシンボル、それらの関係、ソースコードを1回の呼び出しで即座に構造化された回答として取得します。

仕組み

┌──────────────────────────────────────────────────────────────┐
│  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 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はMCPサーバーをグローバルエージェント設定（例：~/.claude.json）に登録します。代わりに現在のプロジェクトにのみ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はプロジェクトごとの1回限りのオプトインであり、syncは既に初期化されたプロジェクトのみを更新します。これにより、グローバルgitフックが、インデックス作成を意図していなかったリポジトリにデータベースをサイレントに作成するのを防ぎます。initの後、tokensave syncを使用して増分更新します -- 変更されたファイルのみが再インデックス化されます。

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

クラッシュ耐性のある同期

Tree-sitter文法はコンパイルされたC/C++コードです。内部アサーションにヒットしたり、Rustのパニック処理では捕捉できないパスでプロセスを終了させたりすることがあります。v4.3.0以降、すべてのファイルは短命のワーカーサブプロセス内で解析されます。文法がセグメンテーション違反を起こしたり、abort()を呼び出したり、スタックオーバーフローを起こしたりした場合、ワーカーのみが停止します。プールがそれを再生成し、問題のファイルはログに記録されてスキップされ、syncは続行されます。

ワーカーは隠しextract-workerサブコマンドであり、生成ごとの256ビットトークンを使用して親に対して認証されます。これはTOKENSAVE_WORKER_TOKEN環境変数として、またstdinで受信する最初の32バイトとして必要です。ユーザーによる直接呼び出しは失敗します。デフォルトはavailable_parallelism()ワーカーです。TOKENSAVE_DISABLE_SUBPROCESS=1でオプトアウトします。

編集プリミティブ（tokensave_str_replace、tokensave_insert_atなど）は引き続きインプロセスで実行されます。これらは一度に1つのファイルを対象とするため、サブプロセスのオーバーヘッドが支配的になり、抽出クラッシュはエージェントに即座に表示されます。

マルチブランチインデックス作成（オプション）

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ツール

3つのMCPツールにより、チェックアウトを切り替えずにクロスブランチクエリが可能になります。

• tokensave_branch_search -- 別のブランチのグラフでシンボルを検索します
• tokensave_branch_diff -- 2つのブランチ間のコードグラフを比較します：追加、削除、変更されたシンボル（シグネチャが異なる）。ファイルおよび種類フィルターをサポートします。
• tokensave_branch_list -- DBサイズ、親ブランチ、同期時間を含む追跡ブランチを一覧表示します

ブランチフォールバック

MCPサーバーが現在のブランチのデータベースを見つけられない場合、最も近い祖先ブランチのDBから提供し、すべてのツール応答にtokensave branch addの実行を提案する警告を含めます。

自動ブランチ追跡 (v7.3.0)

マルチブランチモードがブートストラップされると（最初の手動tokensave branch addでブランチメタデータが作成される）、新しいブランチは祖先DBにフォールバックする代わりに自動的に追跡できます。2つの独立したメカニズムがこれをカバーします。シングルDBモードのプロジェクトは影響を受けず、どちらのメカニズムもデフォルトブランチのデータベースには決して触れません。

Gitフック（ブランチチェックアウト時）。 tokensave installがセットアップするpost-checkoutフックは、ブランチチェックアウト（ファイルチェックアウトとは対照的）を認識し、バックグラウンドでtokensave branch addを実行します。このコマンドは、ブランチが既に追跡されているかデフォルトブランチである場合は何も行わないため、既知のブランチ間の通常の切り替えにはコストがかかりません。

オープン時自動追跡（オプトイン）。 TokenSave::openが実行されるとき（CLIコマンドまたはMCPサーバー起動時）、アクティブなブランチが追跡されていない場合、tokensaveは最も近い追跡された祖先のDBをコピーし、ブランチメタデータに記録することで、その場で追跡できます。これは、auto_track設定フィールド（デフォルトfalse）またはTOKENSAVE_AUTO_TRACK環境変数によって制御されます。環境変数は実行ごとに設定を上書きします（0、false、no、off、または空を除く任意の値で有効になります）。コピーは、手動のbranch addが実行するのと同じほぼ瞬時の祖先DBコピーです。その時点では同期は実行されません。post-commitフックがコミット時に新しいブランチDBを最新に保つか、tokensave syncを実行してすぐに更新します。自動追跡は厳密にベストエフォートです。失敗は警告として報告され、open()は通常の祖先フォールバックで続行されるため、ツール呼び出しが中断されることはありません。

要するに、フックがインストールされている場合、新しいフィーチャーブランチをチェックアウトすると、透過的に独自のブランチごとのグラフが提供されます。auto_trackが有効になっている場合、チェックアウト外で作成されたブランチ（例：新しいワークツリー内）でも、tokensaveがそのプロジェクトを最初に開いたときに取得されます。

完全なガイドについては、docs/BRANCHING-USER-GUIDE.mdを参照してください。

クロスセッションメモリ

3つの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トークン）。

デフォルトのクエリセットは、ほとんどのアプリケーションコードベース（CLI、デーモン、サービス）に存在するパターンを対象としています。tokensave bench を使用して自身のプロジェクトで実行し、数値を確認するか、より厳密な再現率のために調整されたクエリファイル（--queries my.toml）を作成してください。

大規模な実世界のリポジトリに対するCriterionベンチマーク

benches/large_repos.rs は、固定参照にピン留めされた4つの大規模なオープンソースコードベースに対して、MCPツールをエンドツーエンドで実行するcriterionマイクロベンチマークです。各ツールは、リポジトリごとに一度インデックス付きグラフからサンプリングされた引数（ノードID、修飾名、ファイルグロブなど）を使用した少なくとも5つのクエリによって駆動されるため、実行間でタイミングが再現可能です。

リポジトリと固定参照（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 に相当する処理を実行し（index_all()、.tokensave/ の鮮度に関わらず）、タイミングが常に固定されたソースを反映するようにします。

書き込みベンチマークとクリーンアップ。 書き込みツールはファイルを変更します。「一致は一意でなければならない」という前提条件を維持するために、ハーネスは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/ は、設定可能な実際のリポジトリセットに対してstdio経由で tokensave serve を駆動し、言語ごとに5つのクエリバリアントですべての読み取り専用MCPツールを実行し、ツール/リポジトリごとのステータステーブルを生成するPythonハーネスです。同じハーネスが2つの目的を果たします：

• リグレッションスイープ。 新しい言語サポート、新しいツール、またはリファクタリング — マトリックスを再実行し、新たにエラー、タイムアウト、または空の結果を返すセルがあれば、🚩として目立ちます。
• パフォーマンスプローブ。 呼び出しごとのタイミングが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 にない場合は1つ少なくなります）。以下の表は、最も一般的に使用されるものをカテゴリ別にグループ化したものです。ほとんどは読み取り専用で、並列呼び出しが安全であり、readOnlyHint で注釈が付けられています。編集プリミティブは単一ファイルにスコープされ、インプレースで再インデックスされます。セッションベースラインとメモリ記録ツールもローカルの .tokensave 状態を変更し、非読み取り専用として注釈が付けられています。3つのコアツール（tokensave_context、tokensave_search、tokensave_status）は anthropic/alwaysLoad とマークされているため、クライアントのツール検索ラウンドトリップをバイパスします。

検出

コールグラフと影響

コード品質

コードヘルス分析

5つのツールが、既存のグラフから構造的な品質シグナルを表面化します。複合スコアは独立した次元にわたる幾何平均を使用するため、単一のものを操作することはできません。

セッション

AIコーディングセッションの開始時にヘルスメトリクスのスナップショットを取得し、終了時に差分を確認して、何が改善または悪化したかを確認します。

編集プリミティブ

エージェントが正規表現やシェルのクォートに関する危険なしにファイルを変更できる4つのライター系ツール。各ツールは単一ファイル、アンカー付きで、書き込み後にインプレースで再インデックスをトリガーするため、グラフが古くなることはありません。

Git とワークフロー

型システム

移植

マルチブランチ

MCP リソース

resources/list と resources/read を通じて4つのリソースが公開されます。

• tokensave://status -- JSON形式のグラフ統計
• tokensave://files -- ディレクトリでグループ化されたインデックス済みファイルツリー
• tokensave://overview -- 言語分布とシンボル種別を含むプロジェクトサマリー
• tokensave://branches -- DBサイズと親情報を含む追跡対象ブランチ

トークン追跡

tokensaveは、すべてのMCPツール呼び出しで節約されたトークンを測定します。各ツールの応答には、その特定の呼び出しで回避された生ファイルのトークン数を示す tokensave_metrics: before=N after=M 行が含まれます。

コストの可観測性

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 に保存します。価格は LiteLLM から24時間ごとに更新され、オフライン時は組み込みテーブルにフォールバックします。

tokensave status ヘッダーには、本日の支出、7日間の合計、効率比（節約されたトークン / 総トークン）を示すコスト行が含まれます。tokensave monitor TUIは、節約フィードと並んでライブコストパネルを表示します。各Claude Codeセッションの終了時に、hook_stop ハンドラは1行のレシートをターミナルに出力します。

タスク分類カテゴリ: コーディング、デバッグ、機能開発、リファクタリング、テスト、探索、計画、委任、Git操作、ビルド/デプロイ、ブレインストーミング、会話、一般。分類は決定論的であり（ツール名とBashコマンドのパターンマッチング）、LLM呼び出しを必要とせず、AgentSeal/codeburn から適応されています。

ライブモニター

tokensave monitor

~/.tokensave/monitor.mmap にある共有メモリマップドリングバッファを介して、すべてのプロジェクトからのMCPツール呼び出しをリアルタイムで表示するグローバルTUI。各エントリには、プロジェクト名、ツール名、トークンデルタが表示されます。上部のコストパネルには、本日の支出、節約、効率、トップモデルが表示されます（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は、バックグラウンドデーモンやOSレベルのファイルウォッチャーなしでグラフを最新の状態に保ちます。

オンデマンドの陳腐化チェック。 すべてのMCPツール呼び出しは、最後の同期以降にインデックスされたファイルが変更されたかどうかをチェックします。古いファイルが見つかった場合、ツールの応答が返される前に再抽出されます。30秒のクールダウンにより、連続した呼び出しがキーストロークごとにツリーを再ウォークするのを防ぎます。

接続時のキャッチアップ同期。 MCPサーバーが起動すると、エージェントが接続されていない間に行われた変更（git pull、IDE編集、ビルドステップなど）をすぐに非ブロッキングのキャッチアップ同期で取得するため、セッションの最初のツール呼び出しで最新のインデックスが表示されます。

マルチエージェント作業とgitワークツリー。 複数のエージェントが同じプロジェクトで同時に作業する場合、各エージェントが独自のgitワークツリーで動作するという強い前提があります。ワークツリーは同じリポジトリの独立したファイルシステムチェックアウトです。エージェントAとエージェントBはそれぞれすべてのファイルの独自のコピーを持つため、互いの進行中の編集を上書きすることはありません。tokensaveは、クエリがメインチェックアウト内にネストされたワークツリーから来たことを自動的に検出し、正しいブランチグラフから結果を提供します。変更は独立して蓄積され、最終的にgit mergeまたはrebase（他の並行開発に使用されるのと同じプロセス）を介して調整されます。この設計は、共有された可変ディレクトリを介したクロスエージェントロックの複雑さと障害モードを回避します。

CLIのみのワークフロー。 エージェントが接続されていない状態で tokensave コマンドを実行する場合（MCPサーバーなし）、コマンド間で陳腐化チェックは実行されません。コミットまたはクローンのたびにインデックスを自動的に最新に保つためにgitフックをインストールします。

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 Service自動起動は6.0.0で削除されました。デーモンを置き換えた組み込みのOSレベルファイルウォッチャー自体も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が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                    # 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

チェック内容: バイナリの場所、プロジェクトインデックス、グローバルDB、ユーザー設定、エージェント統合（MCPサーバー、フック、権限、プロンプトルール）、ネットワーク接続。アップグレード後にツールの権限が不足している場合は、tokensave install を実行するように指示します。特定のエージェントのみをチェックするには --agent を使用します。

Doctorは、インストールされている各フックが正しいtokensaveサブコマンドを使用しているかどうかも検証し、壊れたフックを自動修復します。

Claude Codeとの連携方法

一度設定すると、Claude Codeはコードベースを理解する必要がある場合に、生ファイルを読み取る代わりに自動的にtokensaveを使用します。3つのレイヤーが相互に強化します。

結果: Claudeは、はるかに少ないトークンで同じコード理解を得られます。典型的なExploreエージェントは20〜50ファイルを読み取りますが、tokensaveは事前に構築されたインデックスから関連するシンボル、関係、コードスニペットを返します。

ネットワーク呼び出しとプライバシー

tokensaveのコア機能（インデックス作成、検索、グラフクエリ、MCPサーバー）は100%ローカルです -- コードがマシンから離れることはありません。| 呼び出し | 送信データ | タイミング | オプトアウト | |------|-----------|------|---------| | 全世界カウンターアップロード | トークン数 (数値) + 国 (IPから) | sync, status, MCPセッション | tokensave disable-upload-counter | | 全世界カウンター読み取り | なし (GETリクエスト) | status | N/A (読み取り専用、1秒タイムアウト) | | バージョンチェック | なし (GETリクエスト) | status (5分キャッシュ), sync (並列) | N/A (1秒タイムアウト、失敗時は何もしない) | | モデル価格更新 | なし (GETリクエスト) | tokensave cost (24時間キャッシュ) | N/A (5秒タイムアウト、失敗時は組み込み価格にフォールバック) |

全世界カウンターアップロードは、{"amount": 4823} のようなJSONボディを含む単一のHTTP POSTを送信します。Cookie、トラッキング、ユーザーIDはありません。Cloudflare Workerは、集計された地理統計のために、リクエストヘッダーから取得したあなたのIPアドレスの国をログに記録します -- 実際のIPアドレスは保存されません。

モデル価格更新は、tokensave cost のClaudeモデル価格を最新に保つために、GitHub (raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json) から公開JSONファイルを取得します。データは送信されません -- プレーンなHTTPS GETです。レスポンスは ~/.tokensave/pricing.json に24時間キャッシュされます。取得に失敗した場合、tokensaveはコンパイル済みの価格テーブルを使用します。

50以上の言語

tokensaveは、Cargoフィーチャーフラグで制御される3つのティアに編成された50以上のプログラミング言語をサポートします。各ティアには、その下のティアのすべての言語が含まれます。Markdownヘッダーは、階層的な Contains エッジを持つ Module ノードとして抽出されるため、ドキュメント構造がソースコードと共にグラフクエリに参加します。

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

すべてのエクストラクタは、関数、クラス、メソッド、フィールド、インポート、コールグラフ、継承チェーン、docstring、複雑度メトリクス、デコレータ/アノテーション抽出、およびファイル間の依存関係追跡という同じ深さを共有します。

tokensave vs 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コーディングエージェントのトークン使用量を削減するツールはいくつかあります。tokensaveが際立つ理由は次のとおりです。

単一のネイティブバイナリ、依存関係ゼロ

すべての代替ツールはランタイムを必要とします: Python、Node.js、またはその両方。tokensaveは、50以上のtree-sitter文法すべてをバンドルした約25 MBの単一Rustバイナリとして提供されます。他にインストールするものはありません。

最も深いコードインテリジェンス

tokensaveはシンボルレベルで動作します: 関数、構造体、フィールド、コールエッジ、型階層、複雑度メトリクス。Dual-Graph (GrapeRoot) のような代替ツールはファイルレベルで動作します -- どのファイルが存在するかはわかりますが、「誰がこの関数を呼び出すか？」や「この構造体を変更すると何が壊れるか？」には答えられません。tokensaveの80以上の専用MCPツールは、コールグラフトラバーサル、影響分析、デッドコード検出、テストマッピング、名前変更プレビュー、型階層、循環依存検出、複雑度ランキング、コード健全性分析 (ジニ係数、DSM、依存深度、リスク加重テストギャップ)、アトミック編集プリミティブなどをカバーします。最も近い競合 (code-review-graph) は22ツール、他は5～9ツールです。

最も幅広いエージェントサポート

エージェントごとのネイティブ設定形式を備えた12以上のAIコーディングエージェント統合。これほど多くのエージェントをこれほど深く統合してカバーするツールは他にありません。Claude Codeはフック、プロンプトルール、自動許可ツール権限を取得します。KiroはグローバルMCP設定、リソースとしてロードされる tokensave.md ステアリング、許可的な組み込み/tokensaveツール承認を持つ管理エージェント、委任ガードレールと書き込み後同期のためのフックを取得します。他のエージェントは、ネイティブ設定形式でMCPサーバー登録を取得します。

マルチブランチインデックス

この分野で唯一、オプションのブランチごとのグラフデータベースとブランチ間の差分および検索を備えたツールです。有効にすると、ブランチの切り替えは瞬時に行われ、再インデックスは不要です。

呼び出しごとのトークン追跡

個々のMCPツール呼び出しが節約したトークン数を正確に報告する唯一のツールであり、さらに全プロジェクトにわたるライブTUIモニターとライフタイムカウンターを備えています。

完全なオープンソース

MITライセンスのRust、エンドツーエンドで監査可能。Dual-Graphのコアエンジン (PyPIの graperoot) はプロプライエタリです -- コードグラフで何が行われているかを見ることはできません。OpenWolfはAGPL-3.0であり、派生物のオープンソース化が要求されます。

パフォーマンス

1,782ファイルのRust/Java/Scala混在コードベース (57Kノード、103Kエッジ) でのフルインデックスベンチマーク:

トラブルシューティング

"tokensave not initialized"

.tokensave/ ディレクトリがプロジェクトに存在しません。

tokensave init

MCPサーバーが接続しない

AIエージェントがtokensaveツールを認識しません。

1. エージェント設定にtokensave MCPサーバーが含まれていることを確認します (tokensave doctor を実行)
2. エージェントを完全に再起動します
3. tokensave がPATHにあることを確認します: which tokensave

検索でシンボルが見つからない

• tokensave sync を実行してインデックスを更新します
• 言語がサポートされているか確認します (上記の表を参照)
• ファイルが .gitignore によって除外されていないか確認します

インデックスが遅い

大規模なプロジェクトでは、最初のフルインデックスに時間がかかります。- 2回目以降の実行では増分同期が使用され、はるかに高速になります

• 日常的な更新には tokensave sync を使用します（--force ではありません）
• エージェントの接続中は、すべてのMCPツール呼び出しで自動的に最新性がチェックされます

特定のプロジェクトでtokensaveを無効にする

プロジェクトが大きすぎてtokensaveがRAMを多く消費する場合は、MCPサーバー環境で DISABLE_TOKENSAVE=true を設定することでプロジェクトごとに無効にできます。サーバーは初期化せずに正常に終了します。

Claude Code — プロジェクトの .claude/settings.json に以下を追加します:

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

その他のエージェント — エージェントがMCPサーバーを起動するために使用する設定で環境変数を設定します。

シェル経由でグローバルに設定することもできますが（DISABLE_TOKENSAVE=true claude）、これによりセッション内のすべてのプロジェクトでtokensaveが無効になります。

起源

このプロジェクトは、@colbymchenry によるオリジナルの CodeGraph TypeScript実装をRustに移植したものです。この移植版は、パフォーマンスとネイティブのtree-sitterバインディングのためにRustを活用しながら、同じアーキテクチャとMCPツールインターフェースを維持しています。

ビルド

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

スター履歴

スポンサー

Windows向けの無料コード署名は SignPath.io によって提供され、証明書は SignPath Foundation によって提供されています

ライセンス

MIT License — 詳細は LICENSE を参照してください。

tokensave.dev