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-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 CLIを呼び出さずに./.omp/mcp.jsonと./.omp/rules/tokensave.mdを使用します。サポートされているエージェント：claude、cursor、droid、gemini、zed、opencode、roo-code、kiro、auggie、omp、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（plank用））。他のエージェントにはプロジェクトスコープの設定がなく、--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フック（ブランチチェックアウト時）。 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 は最も近い追跡済み祖先の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 は criterion マイクロベンチマークで、4つの大規模なオープンソースコードベース（固定リビジョンにピン留め）に対してMCPツールをエンドツーエンドで実行します。各ツールは、リポジトリごとにインデックスグラフからサンプリングされた引数（ノード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 と同等の処理を実行します（.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.

<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ツールすべてを実行し、ツール別/リポジトリ別のステータステーブルを生成します。同じハーネスは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 としてマークされ、クライアントのツール検索ラウンドトリップをバイパスします。

別の初期化済みプロジェクトをクエリ

セマンティック読み取りツールは、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)。直接の兄弟のみが最大5つ提供され、それらのために何も開かれたりインデックスされたりしません。それらを照会するには、依然として明示的な graph_root が必要です。

セレクタは、書き込み、シェルアウト、または現在のチェックアウトに依存するツールでは意図的に利用できません: 編集プリミティブ、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 ブロックでその旨を伝えるため、部分的な回答が完全なものとして提示されることはありません。

コールグラフと影響

コード品質

コードヘルス分析

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

セッション

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

編集プリミティブ

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

Git とワークフロー

型システム

移植

マルチブランチ

MCP リソース

4 つのリソースが resources/list と resources/read を介して公開されています:

• tokensave://status — グラフ統計を JSON として
• tokensave://files — ディレクトリごとにグループ化されたインデックス付きファイルツリー
• tokensave://overview — 言語分布とシンボル種類を含むプロジェクトサマリー
• tokensave://branches — DB サイズと親情報付きの追跡されたブランチ

トークン追跡

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 に保存して高速な集計クエリを可能にします。価格は 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 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は、バックグラウンドデーモンやOSレベルのファイルウォッチャーなしで、グラフを最新に保ちます。

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

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

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

CLIのみのワークフロー。 接続されたエージェントなしで（MCPサーバーなしで）tokensave コマンドを実行する場合、コマンド間で鮮度チェックは実行されません。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サービス自動起動は、6.0.0で削除されました。デーモンを置き換えた組み込みのOSレベルファイルウォッチャー自体も、6.1.1で削除されました（深い 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 install で表示されるエージェントごとのセットアップ出力はここでは抑制されるため、通常の tokensave init や tokensave sync の前に表示されることはありません。エージェントの設定を更新できない場合（アプリがインストールされていない、または設定が読み取り専用の場所にある）、失敗したエージェントを指定する1行が表示されます:

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

tokensave install を実行して、基になるエラーを確認します。バージョンマーカーはどちらの場合も進むため、書き込めない設定パスは、後続のすべてのコマンドで再試行されるのではなく、アップグレードごとに1回報告されます。

プロジェクトごとの強制再インデックス（メジャーのみ）。 メジャーバンプは、プロジェクトインデックスを再構築する必要があることを意味します。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

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

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

Claude Codeでの動作方法

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

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

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

tokensaveのコア機能（インデックス作成、検索、グラフクエリ、MCPサーバー）は100%ローカルです — コードがマシンを離れることはありません。

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

モデル価格更新は、GitHubから公開JSONファイル（raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json）を取得して、tokensave cost のClaudeモデル価格を最新に保ちます。データは送信されません — これは単純なHTTPS GETです。応答は ~/.tokensave/pricing.json に24時間キャッシュされます。フェッチが失敗した場合、tokensaveはコンパイル済みの価格テーブルを使用します。

50以上の言語

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

Lite — --no-default-features

常にコンパイルされます。最も人気のある言語向けの最小バイナリに加えて、SvelteとAstro（TypeScript抽出器によるスクリプトブロック抽出、追加の文法依存関係なし）。

ミディアム（Lite + 9追加）— --features medium

フル（ミディアム＋その他すべて）— デフォルト

個別の言語は、フルティアなしでピックアップすることもできます:

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

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

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

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

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

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

tokensave はシンボルレベルで動作します: 関数、構造体、フィールド、呼び出しエッジ、型階層、複雑性メトリクス。Dual-Graph（GrapeRoot）などの代替ツールはファイルレベルで動作します — どのファイルが存在するかはわかりますが、「この関数を呼び出しているのは誰か？」や「この構造体を変更したら何が壊れるか？」には答えられません。tokensave の 80 以上の専門 MCP ツールは、コールグラフトラバーサル、影響分析、デッドコード検出、テストマッピング、リネームプレビュー、型階層、循環依存関係検出、複雑性ランキング、コードヘルス分析（Gini、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 によって除外されていないか確認します

インデックスが遅い

大規模プロジェクトでは、最初のフルインデックスに時間がかかります。

• 以降の実行では増分同期が使用され、はるかに高速です
• 日常の更新には 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 サーバーを起動するために使用する設定に環境変数を設定します。

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

DISABLE_TOKENSAVE=true は、この変数が名前空間化される前に作成された設定のための非推奨の互換エイリアスとして引き続きサポートされています。

起源

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

ビルド

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 を参照してください。

tokensave.dev