TokenSave

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

トークンを削減 • ツール呼び出しを削減 • 100% ローカル

tokensave を選ぶ理由

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

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

仕組み

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

**tokensave を使わない場合：**エージェントは grep、glob、Read を使ってファイルをスキャンするため、API 呼び出しが多く、トークン使用量も増えます。

**tokensave を使う場合：**エージェントは MCP ツールを使ってグラフを検索するため、結果を即座に取得でき、ローカルで処理され、トークンを節約できます。

主な機能

クイックスタート

1. インストール

Homebrew（macOS）：

brew install aovestdipaperino/tap/tokensave

Scoop（Windows）：

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

Cargo／cargo-binstall（すべてのプラットフォーム）：

# Fast install prebuilt binary without compiling:
cargo binstall tokensave

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

ビルド済みバイナリ（Linux、Windows、macOS）：

最新リリースからダウンロードし、バイナリを PATH に配置します。

2. エージェントを設定する

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

各エージェントには、ネイティブの設定形式で MCP サーバーが登録されます。Claude Code にはさらに、PreToolUse フック（無駄な Explore エージェントをブロック）、UserPromptSubmit フック、Stop フック、CLAUDE.md のプロンプトルール、自動許可されるツール権限が追加されます。Kiro にはグローバル MCP 設定、リソースとして読み込まれる tokensave.md のステアリング、組み込みツールと tokensave ツールの承認を広く許可する、tokensave 管理のデフォルトエージェント、委譲ガードレールのフック、書き込み後の同期が追加されます。ユーザー管理の Kiro エージェントは保持されます。

グローバルな OMP インストールでは、omp config path のみを実行したときに表示されるプロファイルを対象とし、<resolved-agent-dir>/mcp.json と <resolved-agent-dir>/rules/tokensave.md に書き込みます。名前付きプロファイルにインストールする場合は、OMP_PROFILE または OMP と互換性のある PI_PROFILE をエクスポートしてください。OMP のリゾルバーは PI_CONFIG_DIR と PI_CODING_AGENT_DIR も参照します。Tokensave は OMP のプロファイルロジックを複製せず、このネイティブリゾルバーを使用します。Tokensave は OMP 用に MCP と参考ルールをインストールしますが、OMP のフックによる強制はインストールしません。

すべての変更は冪等であり、アップグレード後に再実行しても安全です。エージェントの設定後、グローバルな git post-commit フックと post-checkout フックの導入が提案されます。tokensave uninstall はエージェント連携と合わせてこれらのフックも削除します。フックを残すには --keep-git-hooks を指定するか、tokensave githooks で個別に管理してください。

複数のエージェントに一括インストールする

--agent を繰り返し指定すると、1 回の実行で複数のエージェントにインストールできます。リストするエージェントの数にかかわらず、権限の付与、git フックの導入提案、グローバル設定への書き込みはそれぞれ 1 回だけ行われます。

tokensave install --agent claude --agent cursor --agent droid

プロジェクト単位でインストールする

デフォルトでは、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、plank 用の .mcp.json）。その他のエージェントにはプロジェクトスコープの設定がないため、--local を指定するとエラーが報告されます。

プロジェクト単位のインストールを削除するには、tokensave uninstall --local を実行します。

3. プロジェクトをインデックス化する

cd /path/to/your/project
tokensave init

これにより、ナレッジグラフのデータベースを格納する .tokensave/ ディレクトリが作成されます。初期化と同期は別々のコマンドです。init はプロジェクトごとに一度だけ行うオプトイン操作で、sync はすでに初期化されたプロジェクトのみを更新します。これにより、グローバル git フックが、インデックス化するつもりのなかったリポジトリにデータベースを意図せず作成するのを防ぎます。init の後は tokensave sync を実行して差分更新します。変更されたファイルだけが再インデックス化されます。

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

このフックは tokensave hook-pre-tool-use を実行します。これはネイティブの Rust コマンドであり、bash や jq は不要です。Agent、Grep、Glob、Bash のツール呼び出しをインターセプトします。Explore エージェントは無条件にブロックされ、シンボル形式の grep/rg/ag 呼び出し（通常の識別子、選択肢、\b で囲まれた名前）は、対応する tokensave MCP ツールにリダイレクトされます。また、コード拡張子に対するパス形式の検索（Glob、find -name、fd --extension）は tokensave_files にリダイレクトされます。正規表現パターン、git grep、パイプでつないだコマンド、コード以外の拡張子、インデックス外の検索ルート、コマンドの動作を変える find の述語（-exec、-delete、-mtime）はすべて変更されずに実行されます。シェルごとに無効化するには TOKENSAVE_DISABLE_GREP_HOOK=1 を設定してください。

フィルターは、より具体的なものから順に評価されます。明示的な type が最優先され、次に明示的なファイル glob、その次に検索パスが評価されます。そのため、glob: "**/*.md" を指定したドキュメント検索（たとえば path: "."）は、広いパスに対するコード検索とは見なされず、そのまま実行されます。一方、コードのみの glob（**/*.rs）は、コード以外のパスであってもリダイレクトされます。複数種の glob（**/*.{rs,md}）はドキュメントを返す可能性があるため、そのまま実行されます。

ヘッドレス／サブエージェントのディスパッチ（claude -p）。 オーケストレーションを行うセッションからディスパッチされた子プロセスは、このフックを含む ~/.claude/settings.json を継承します。子プロセスで生の検索を実行できるようにするには、子プロセスの環境で TOKENSAVE_DISABLE_GREP_HOOK=1 を設定してください。ネイティブバイナリはこれを認識し、すべてのパス（Grep、Glob、Bash、Agent）をそのまま実行するため、すべてのフックを削除する強引な --settings '{"hooks": {}}' は不要です。このガードレールはステートレスです。引用履歴を参照することはなく、上記のシンボル形式の検索のみをリダイレクトし、型が指定されていない調査のファンアウトを誘導します。通常のコマンドには、対話型セッションでもヘッドレスセッションでも影響しません。

CLAUDE.md のルール

~/.claude/CLAUDE.md に指示を追記し、Explore エージェントやファイルの直接読み込みを使う前に、tokensave ツールを使用するよう Claude に伝えます。

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

Tree-sitter の文法は、コンパイルされた C/C++ コードです。内部アサーションに失敗したり、Rust のパニック処理では捕捉できない経路でプロセスを終了させたりすることがあります。v4.3.0 以降、各ファイルは短命のワーカサブプロセス内で解析されます。文法がセグフォルトを起こしたり、abort() を呼び出したり、スタックオーバーフローを起こしたりしても、終了するのはワーカーだけです。プールはワーカーを再起動し、問題のファイルを記録してスキップし、sync は処理を続行します。

ワーカーは非公開の extract-worker サブコマンドです。起動ごとに生成される256ビットのトークンを使って親プロセスに対する認証を行います。このトークンは TOKENSAVE_WORKER_TOKEN 環境変数として設定するほか、標準入力で最初に受け取る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 を実行します。このコマンドは、ブランチがすでに追跡されている場合やデフォルトブランチの場合は何も行わないため、追跡済みブランチ間の通常の切り替えにはコストがかかりません。新しい 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 に保存されます。

これらを使用すると、セッションごとにエージェントがアーキテクチャ上の選択を再説明する必要がなくなります。

Savings Ledger

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、修飾名、ファイル glob など）を使い、少なくとも 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 / 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 が設定されていない場合、ベンチマークは通知を出してベンチマークを 0 件登録します（そのため、開発者のマシンで 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/ は、tokensave serve を stdio 経由で、設定可能な実際のリポジトリ群に対して駆動し、各言語ごとに 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 は固定された ref 上の限定的なツールセットに対してイテレーションごとのレイテンシを測定し、target/criterion/ 以下に統計レポートを生成します。mcp_probe は、指定したリポジトリに対してより広範なクエリセットで全ツールを実行し、測定精度よりもカバレッジの広さを優先します。

80 以上の MCP ツール

サーバーは 80 以上のツールを公開しています (オプションの ast-grep バイナリが PATH 上にない場合は 1 つ少なくなります)。7.14.0 以降、デフォルトでは 11 のコアツールと tokensave_more のみがリストされます。残りは tokensave_more を通じてオンデマンドでリストされ、名前で呼び出し可能なままであり、"tools": "full" ですべてリストされます。以下の表は、最もよく使用されるものをカテゴリ別にグループ化したものです。ほとんどは読み取り専用で、並列呼び出しが安全であり、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、.bnd、.bndrun）はパスで追跡されるため、「ログインフローの .feature ファイルはどこにありますか？」といった質問にも、find を実行できない状況でも、グラフによる回答を返せます（#323）。これらのファイルは解析されず、シンボルも生成しません。kind: "artifact" と kind: "code" でそれぞれを絞り込めます。「コード」を対象とする分析では、アーティファクトは除外されます。言語エクストラクターがすでに処理している拡張子はこのリストでは無視されるため、拡張子をここに追加しても、その言語の解析を止めることはできません。

このリストは、リテラル検索の対象にできるファイルも決定します（#442）。tokensave_search のリテラル検索（literal: true）は、シンボルではなくバイト列を読み取るため、パーサーは必要ありません。ただし、インデックスに登録されたファイルを順に処理するので、インデックスに行があるファイルだけが対象になります。追跡対象の .rst ドキュメントや .tmpl テンプレートには、エクストラクターもデフォルトのアーティファクト登録もないため、そのファイル内の一致箇所は見つかりません。このリストに拡張子を追加して tokensave sync -f を実行すると、ほかのファイルと同じようにそのファイルの行も検索されます。シンボルのコンテキストがないため、enclosing: null として報告されます。リテラル検索で追跡対象の全ファイルを調べられなかった場合は、unscanned ブロックに件数と拡張子が示されるため、不完全な回答が完全なものとして提示されることはありません。

呼び出しグラフと影響範囲

コード品質

コード品質分析

既存のグラフから構造品質の指標を抽出する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 という行が含まれ、その呼び出しによって生のファイルからのトークンを何個回避できたかが示されます。

レポートを無効にする。 メトリクス行と 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 です。

デフォルトではコアツールのみが一覧表示されます。 MCP クライアントは、ツールを呼び出す前に、一覧にあるすべてのツールのスキーマを毎ターン送信します。tokensave の全機能のスキーマは約 89 KB あり、コンテキストの小さいモデルではウィンドウの半分を超えることがあります（#576）。そのため、tools/list が送信するのはコアツールのみです。対象は context、search、status、read、body、files、callers、callees、impact、str_replace、multi_str_replace です（tokensave_more を含めて約 17 KB）。initialize の指示文には、これらのツールと tokensave_more で一覧表示できる領域が記載されるため、ツールスキーマの取得を遅延するクライアントでも、ほかのツールが存在することは分かります。この設定が選ぶのはサーバーが一覧表示する内容であり、実行できる内容ではありません。一覧にないツールも名前を指定して呼び出せば応答するため、エージェントの権限リストやフックは引き続き機能します。すべてのツールを一覧表示するには、.tokensave/config.json で "tools": "full" を設定するか、MCP サーバーの環境で TOKENSAVE_TOOLS=full を設定します。環境変数はファイルより優先されます。すべての設定ファイルにこの値を書き込んでいた 7.13.0 が記録した "tools": "full" は、以前のデフォルトとして読み込まれます。アップグレード後も全ツールの一覧を維持するには、再度設定してください。

コアツールセットでは、サーバーは tokensave_more も一覧表示します。area（analysis、edit、git、memory、navigate、all のいずれか）を指定して呼び出すと、その領域のツールがセッションの残りの間一覧に追加され、サーバーは notifications/tools/list_changed を送信して、クライアントに一覧を再取得させます。セッションで使用する領域の分だけ負荷がかかります。git 領域では約 6 KB 追加されます。list_changed を無視するクライアントには、コアツールの一覧がそのまま表示されます。tokensave install は tokensave_more をほかのすべてのツールとともに許可するため、確認を求めません。このリリース以前にインストールした場合は、tokensave reinstall を実行するか、アップグレード時に再同期するまで、1 回だけ確認が求められます。

コストの可視化

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

Claude Code のセッショントランスクリプト（~/.claude/projects/**/*.jsonl）を解析し、各 API ターンを13のタスクカテゴリに分類して、モデルの料金に基づいてコストを計算し、高速な集計クエリのために結果を ~/.tokensave/global.db に保存します。料金は24時間ごとに LiteLLM から更新され、オフライン時は組み込みのテーブルにフォールバックします。

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

タスク分類のカテゴリは次のとおりです：コーディング、デバッグ、機能開発、リファクタリング、テスト、調査、計画、委任、Git 操作、ビルド／デプロイ、ブレインストーミング、会話、一般。分類は決定的で（ツール名と Bash コマンドのパターンマッチングに基づきます）、LLM の呼び出しは不要です。AgentSeal/codeburn を参考に調整されています。

ライブモニター

tokensave monitor

共有のメモリマップドリングバッファ ~/.tokensave/monitor.mmap を介して、すべてのプロジェクトの MCP ツール呼び出しをリアルタイムで表示するグローバル TUI です。各エントリにはプロジェクト名、ツール名、トークンの増減が表示されます。上部のコストパネルには、今日の支出額、節約額、効率、使用頻度の高いモデルが表示されます（30秒ごとに更新）。

メモリ診断

tokensave memory [--clean]

共有のメモリマップドテーブル ~/.tokensave/memory.mmap を介して、マシン全体の各 tokensave プロセス（MCP サーバー、同期、インデックス作成）のメモリレポートを表示します。各インスタンスは、起動時、MCP ツール呼び出しごと、同期／解決フェーズの前後に、可能な範囲で自身の RSS をサンプリングします。そのためレポートには、現在の 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 worktree。 複数のエージェントが同じプロジェクトで同時に作業する場合、各エージェントはそれぞれ独自の git worktree で作業することを前提とします。worktree は同じリポジトリの独立したファイルシステム上のチェックアウトです。エージェント A とエージェント B は各ファイルのコピーをそれぞれ持つため、進行中の編集を互いに上書きすることはありません。tokensave は、クエリがメインのチェックアウト内にネストされた worktree から送られたことを自動的に検出し、正しいブランチグラフの結果を返します。変更は個別に蓄積され、他の並行開発と同じく、最終的には 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 Service による自動起動は 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 のように見えますが、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 を実行してください。どちらの場合もバージョンマーカーは更新されるため、書き込みできない設定パスは、後続のコマンドのたびに再試行されるのではなく、アップグレードごとに一度だけ報告されます。

プロジェクトごとの強制再インデックス（メジャーのみ）。 メジャー更新では、プロジェクトのインデックスを再構築する必要があります。tokensave はこれを遅延実行し、プロジェクトごとに行います。メジャーアップグレード後にプロジェクトで最初の MCP ツール呼び出しが行われると、バックグラウンドで完全な再インデックス（tokensave sync --force 相当）を開始し、ツールの応答をブロックすることはありません。

Brew／cargo によるフォールバック。 brew upgrade tokensave や cargo install tokensave など、tokensave upgrade 以外でバイナリを置き換える外部アップグレードも同じ方法で検出されます。実行中のバージョンが、最後にインストールを実行したバージョンより新しい場合、セルフアップグレード後と同様に、次回の起動時に再インストールが実行されます。

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

Doctor は、インストール済みの各フックが正しい 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 アドレスは保存されません。

モデル価格の更新では、tokensave cost で Claude モデルの価格を最新に保つため、GitHub から公開 JSON ファイル（raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.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

ERB および Slim テンプレートは、インデックス作成時に Ruby やテンプレート用 gem を必要とせず、Ruby の文法を使用します。テンプレート呼び出しはファイルノードに属し、元の行とバイト単位の列を保持します。ERB はコード／出力タグ、トリムマーカー、コメント、エスケープされたタグに対応しています。Slim は制御／出力行、インデントベースのブロック、属性（複数行の属性リストを含む）、テキスト補間、ruby: ブロックに対応しています。

カスタム Slim ショートカットと、埋め込み言語のコンパイルには対応していません。レンダリング時に Rails が提供するローカル変数は、単独のヘルパー呼び出しと区別できません。テンプレート内で代入または束縛された名前は、保守的に除外されます。コントローラーからビューへの関係とパーシャルのレンダリング関係には、別途 Rails のセマンティックな接続が必要です。

Full（Medium + その他すべて） -- デフォルト

完全なティアを有効にせず、個別の言語を選んで追加することもできます。

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

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

HTML と CSS は、どちらの言語にも呼び出し可能なシンボルがないため例外です。HTML では id を持つ要素、カスタム要素、ページが読み込むスタイルシートとスクリプトを記録します。CSS ではクラスセレクターと ID セレクター、カスタムプロパティ、@keyframes 名、@import を記録します。どちらも class="..." 属性をスタイルシートのルールに対応付けることはありません。クラス名は通常の単語であり、プロジェクト全体で単独の名前を照合すると、関係を見つけるのではなく、実在しない関係を作り出してしまうためです。

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

並列比較ページ（各ページでは、もう一方のツールが優れている点も説明しています）： Serena · code-review-graph · Graphify · CodeGraph · token-savior · GrapeRoot · LeanCTX · OpenWolf — 一覧は tokensave.dev/vs をご覧ください。

tokensave が他の選択肢より優れている理由

AI コーディングエージェントのトークン使用量を削減するツールはいくつかあります。tokensave が際立っている理由をご紹介します。

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

ほとんどの代替ツールでは、Python、Node.js、またはその両方のランタイムが必要です。tokensave は、50 種類以上の tree-sitter 文法をすべてバンドルした単一の Rust バイナリ（圧縮ダウンロードで約 25 MB）として提供されます。ほかにインストールするものはありません。また、Serena などの LSP ベースのツールとは異なり、言語ごとに言語サーバーをインストール、起動、ウォームアップする必要もありません。パッケージングの点で tokensave に並ぶツールが 2 つあります。CodeGraph は独自のランタイムをバンドルし、LeanCTX も単一の Rust バイナリです。

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

tokensave はシンボルレベルで動作します。関数、構造体、フィールド、呼び出しエッジ、型階層、複雑度メトリクスを扱います。Dual-Graph（GrapeRoot）のような代替ツールはファイルレベルで動作します。どのファイルが存在するかは把握できますが、「この関数を呼び出しているのは誰か？」や「この構造体を変更したら何が壊れるか？」には答えられません。tokensave の 80 種類以上の特化した MCP ツールは、呼び出しグラフのトラバーサル、影響分析、デッドコード検出、テストのマッピング、名前変更のプレビュー、型階層、循環依存検出、複雑度ランキング、コード健全性分析（ジニ係数、DSM、依存関係の深さ、リスク加重テストギャップ）、アトミックな編集プリミティブなどに対応します。最も近い同種のグラフツールである code-review-graph が公開するツールは 30 種類で、ほかのいくつかのツールは意図的な設計により 10 種類未満です。

最も幅広いエージェント対応

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

複数ブランチのインデックス作成

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

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

個々の MCP ツール呼び出しで節約できたトークン数を正確に報告し、すべてのプロジェクトを対象としたライブ TUI モニターと累計カウンターも備える唯一のツールです。

完全なオープンソース

エンドツーエンドで監査可能な、MIT ライセンスの Rust 製ソフトウェアです。Dual-Graph のコアエンジン（PyPI の graperoot）はプロプライエタリで、コードグラフに対して何を行うのか確認できません。OpenWolf は AGPL-3.0 でライセンスされており、派生物をオープンソースにする必要があります。

パフォーマンス

Rust、Java、Scala が混在する 1,782 ファイルのコードベース（57K ノード、103K エッジ）におけるフルインデックスのベンチマーク：

トラブルシューティング

「tokensave が初期化されていません」

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

tokensave init

MCP サーバーが接続されない

AI エージェントに tokensave のツールが表示されません。

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

検索結果にシンボルが見つからない

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

インデックス作成が遅い

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

• 2 回目以降の実行では増分同期が使われるため、大幅に高速化します
• 日常的な更新には --force ではなく tokensave sync を使用します
• エージェントの接続中は、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に移植したものです。この移植版は、パフォーマンスとネイティブのtree-sitterバインディングにRustを活用しながら、同じアーキテクチャとMCPツールインターフェースを維持しています。

ビルド

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

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

開発コマンドではデバッグビルドを使用します。インストールでは、最適化されたリリース出力のみを使用します （cargo install --path . --locked）。target/debugがインストールに使用されることはありません。

Star履歴

スポンサー

SignPath.ioが提供するWindows向けの無料コード署名です。証明書はSignPath Foundationが提供しています。

ライセンス

MITライセンス — 詳細はLICENSEを参照してください。

tokensave.dev