Token Savior

---

このリポジトリにスターを付けたのは誰ですか？

2026 年 6 月 30 日、GitHub はリポジトリの管理者とコラボレーター以外がスターを付けたユーザーやウォッチャーのリストを見られないように制限し、「自分のリポジトリにスターを付けたのは誰か」を調べるツールが一斉に使えなくなりました。自分が所有するか、プッシュ権限を持つリポジトリだけを読み取る仕組みだからこそ、今も使えるツールを作り直しました。starscope は、リポジトリにスターを付けた人やフォークした人を影響力順に表示し、GitHub プロフィールで公開している場合は、その人のソーシャルアカウントも表示します。

このリポジトリで starscope が算出した数値は、1,147 人、公開ソーシャルアカウントを持つ人が 27%、最もフォロワー数が多い人は 18,922 人です。氏名の一覧を見られるのはリポジトリの所有者だけです。公開ページには集計結果のみが表示されます。

新機能

リリースノートは、コードとの不整合が生じない場所で管理されています。

• 全履歴についてはCHANGELOG.md
• タグ付きビルドについてはリリース
• pipで実際にインストールされるものについてはPyPI

---

クイックスタート

pip install "token-savior-recall[mcp]"

MCP の設定に追加します（例：Claude Code）。

{
  "mcpServers": {
    "token-savior-recall": {
      "command": "/path/to/venv/bin/token-savior",
      "alwaysLoad": true,
      "env": {
        "WORKSPACE_ROOTS": "/path/to/project1,/path/to/project2",
        "TOKEN_SAVIOR_CLIENT": "claude-code",
        "TOKEN_SAVIOR_PROFILE": "optimized"
      }
    }
  }
}

"alwaysLoad": true は Claude Code（2.1.28x 以降）で重要です。これがないと、サーバーのすべてのツールが ToolSearch の背後に置かれ、モデルはすでに読み込まれている Read や Grep を使おうとします。このオプションが存在する前に、このプロジェクトのベンチマークで測定したところ、143 セッション中 Token Savior ツールを呼び出したのは 1 セッションだけでした。このオプションを有効にすると、マニフェストのコストは 1 セッションあたり数千のキャッシュ済みトークンで済みます。

これだけです。TOKEN_SAVIOR_PROFILE=optimized は、tsbench で最高の結果を出すパレート最適な設定を提供します。以下をまとめています。

• tiny_plus（15 個の高頻度ツールのマニフェスト）
• 薄型の inputSchema（マニフェストを -44% 削減）
• キャプチャサンドボックスを無効化
• プロジェクト間の安全性を確保するため、メモリフックを制限

ほかに調整は必要ありません。

---

有効化（Bash の圧縮＋書き換え）

Bash の圧縮と PreToolUse リライターはオプトインです。2 つの環境変数と CLI の呼び出しが必要です。

export TS_BASH_COMPACT=1       # PostToolUse output compactors (34 of them)
export TS_BASH_REWRITE=1       # PreToolUse command rewriter (10 rules)

ts init --agent claude --yes   # auto-merge hooks into ~/.claude/settings.json

ts init はべき等です。既存のフック項目を検出し、(matcher, command) で重複を排除して、統合差分を表示します。書き込み前に settings.json を .bak-YYYYMMDD-HHMMSS（UTC）にバックアップします。対応エージェントは以下のとおりです。 claude、cursor、gemini、codex、openclaw。プレビューするには --dry-run を、ユーザーレベルの設定に書き込むには --global を指定してください。

書き換えをすべて記録するオプションの監査ログ：

export TS_BASH_REWRITE_LOG=$HOME/.local/state/token-savior/rewrites.jsonl

---

コンパクターカタログ（34）

ファミリー	コンパクター
git	status、diff、log、push/pull、commit、add、fetch、checkout、branch、worktree list、stash list
gh	run list、run view、pr diff、pr view、issue view、repo view
test/lint	pytest、jest、vitest、eslint、biome、cargo test、cargo build/clippy、tsc
cloud	kubectl get、kubectl logs、aws sts、aws ec2、aws lambda、aws logs、aws iam、aws dynamodb、aws s3
docker	docker ps、docker logs
packaging	npm/yarn/pnpm list、pip list/show
shell catch-alls	grep、find、cat、curl

各コンパクターは純粋関数（I/O なし、グローバル変数なし）で、トークン効率の高い形式を返します。マッチャーが一致しない場合、ディスパッチャーは None を返し、既存のサンドボックス経路はそのまま維持されます。複合コマンド（cd ... && cmd）は、最後の意味のあるセグメントにフォールバックします。

これらは PostToolUse で実行されるため、現在のターンを短縮しません。 フックはツールの実行後に呼び出されるため、コンテキストを追加することはできますが、削除することはできません。コンパクトな形式は生の出力の下に追加され、生の出力も残ります。得られるのは永続性です。完全な出力はキャプチャサンドボックスに送られ、コンテキストの圧縮後も保持されます。モデルに届く情報を実際に減らすには、PreToolUse リライター（TS_BASH_REWRITE=1）を使用してください。実行前にコマンドを書き換えます。

---

ts_discover -- 見逃した TS の活用機会を発見

エージェントが実際に行った操作よりも TS ツールのほうが低コストで済んだパターンを探すために、Claude Code のトランスクリプトをスキャンする新しい MCP ツールです。

ts_discover()                       # active project, last 30 days
ts_discover(project=None)           # ALL transcript projects
ts_discover(format="adoption")      # TS vs native ratio per session
ts_discover(format="adoption_json") # same, JSON

検出対象：Read->Grep->Read の連鎖、連続した find_symbol、get_edit_context を使わない編集、memory_index を使わない memory_search、コードファイルに対するネイティブシェルの使用。引数は処理の要となるキーに絞り込まれます（PII セーフ）。mtime による高速スキップに対応した JSONL ストリームを出力します。

---

ts init CLI

ts init --agent claude [--global] [--dry-run] [--yes]
ts init --agent cursor
ts init --agent gemini
ts init --agent codex
ts init --agent openclaw

対象エージェントの設定ファイルの場所を検出し、Token Savior のフック設定（PostToolUse と PreToolUse）をディープマージして、既存のフックを保持し、重複を排除して、統合差分を表示します。settings.json.bak-YYYYMMDD-HHMMSS（UTC）にバックアップします。再実行しても何も変更されません。

---

概要

Claude Code は、3行について質問に答えるためにファイル全体を読み込み、セッションが終わるとすべてを忘れてしまいます。Token Savior はこの両方を解決します。さらに第3の軸として、コードを読み取る合間にターンの予算を膨らませる、ノイズの多い Bash 出力を、コマンドの実行前に書き換えることで抑制します。

関数、クラス、インポート、呼び出しグラフなどのシンボル単位でコードベースにインデックスを作成するため、モデルは cat ではなくポインターを使って移動できます。実測で、170以上の実セッションにおいて注入される文字数を97％削減しました。

その上に、永続メモリエンジンを搭載しています。すべての判断、バグ修正、規約、ガードレール、セッションの要約を SQLite WAL + FTS5 + ベクトル埋め込みに保存し、ベイズ的な有効性とROIに基づいて順位付けして、次のセッションの開始時にコンパクトな差分として再注入します。

さらにその上に、v4.1以降では Bash コンパクターと PreToolUse リライターを搭載しています。ベンチマークの数値は上記をご覧ください。

この2つのうち、実際にターンを短縮するのはどちらで、短縮しないのはどちらか。 2026-08-09に測定しました。この違いは明白ではないため、はっきり述べておく価値があります。

• PreToolUse リライターは、コマンドの実行前にコマンドを書き換えるため、より小さな出力が生成され、より小さな出力がモデルに届きます。これは現在のターンを実際に削減します。
• PostToolUse コンパクターは、ツールの処理が返ってきた後に実行されます。PostToolUse フックにできるのはコンテキストの追加だけです。フックが実行される時点で、未加工の出力はすでに送信されています。コンパクトな表示は追加されるだけで、元の出力を置き換えるものではありません。コンパクターが実際にもたらす価値は別のものであり、それでも有用です。出力全体がキャプチャサンドボックスに保持され、コンテキストの圧縮後も残るため、再実行せずに後から照会できます。

ターンを短縮したい場合は、TS_BASH_REWRITE=1 に設定します。コンテキストの圧縮をまたいでコマンド出力が失われるのを防ぎたい場合は、TS_BASH_COMPACT=1 に設定します。

---

プロファイルの比較

プロファイル	公開されるツール	マニフェストのトークン数	使用する場面
optimized	15	約1.5 KT	推奨されるデフォルト — tsbench でパレート優位
auto	適応型	約1～2 KT	クライアントごとのテレメトリーベース（実験的）
tiny	6	約0.6 KT	最小限のホットループ
lean	51	約4 KT	レガシー — より広い機能範囲
compact-only	1	約0.3 KT	Bash レイヤーのみ（リライター + キャプチャ） — すでに別の場所でシンボルナビゲーションを実行している場合
full	68	約6 KT	すべてを公開

おそらく optimized が最適です。

---

隣接ツールとの連携

Token Savior は複数のレイヤーにまたがりますが、隣接するツールのほとんどはそのうちの 1 つだけを担います。レイヤーごとに重複を無効にできるため、すでに使っている側を無効にすれば、通常は両方を実行しても問題ありません。これを整理してくれた @chirag127 に感謝します（#45）。

ツール	レイヤー	重複	対応方法
RTK（現在、リポジトリにアクセスできません）	PostToolUse Bash 出力の圧縮	同じレイヤーで、同じ PostToolUse の制限があります。どちらも現在のターンを短縮しません	どちらか一方を選びます。RTK に任せるには TS_BASH_COMPACT=0 を設定します
serena	シンボルグラフナビゲーション	find_symbol / get_dependents と直接重複します	serena をナビゲーターとして使う場合は、TS を compact-only で実行します
codebase-memory	永続的なコードグラフ	メモリエンジンと重複します	TS_MEMORY_DISABLE=1
Ponytail、Caveman	出力側の圧縮（コードと文章）	一部重複します。Token Savior には、ツールに組み込まれた、オプトイン方式の Ponytail スタイルの規律（TS_DISCIPLINE=1）が含まれています	補完的なため、設定は不要です

これらのツールにはない、Token Savior が担うレイヤーは、PreToolUse Bash リライター（出力後ではなく、コマンドの実行前に短縮します）、インデックスとの同期を保つ構造的な編集、そして監査ツール（detect_breaking_changes、find_dead_code、analyze_config）です。

Bash レイヤーだけを使いたい場合は、TOKEN_SAVIOR_PROFILE=compact-only を指定すると、単一のツールだけを公開し、コンパクターとリライターは実行したままにします。この 2 つのうち、現在のターンを短縮するのはリライターです。

---

トークンの削減量

操作	通常の Claude	Token Savior	削減量
find_symbol("send_message")	41M 文字（全体を読み込み）	67 文字	-99.9%
get_function_source("compile")	grep + cat の連鎖	4.5K 文字	直接取得
get_change_impact("LLMClient")	不可能	16K 文字	新機能
96 タスクの tsbench（Opus、通常と ts の比較）	17 221 アクティブ／タスク	3 395 アクティブ／タスク	-80%
7 日間の Bash 出力ベンチマーク（v4.3）	約 30 K トークン／週	約 9.6 K トークン／週	約 20.4 K／週

---

インストール

pip（MCP サーバー）

pip install "token-savior-recall[mcp]"
# Optional hybrid vector search:
pip install "token-savior-recall[mcp,memory-vector]"

uvx（venv、クローン不要）

uvx token-savior-recall

Claude Code のワンライナー

claude mcp add token-savior -- /path/to/venv/bin/token-savior

開発

git clone https://github.com/Mibayy/token-savior
cd token-savior
python3 -m venv .venv
.venv/bin/pip install -e ".[mcp,dev]"
pytest tests/ -q

テストスイートの結果：main で 1898 件成功、2 件スキップ。Python 3.11 / 3.12 / 3.13 で CI は成功しています。

---

自分でベンチマークを実行する

上記のコンパクターの数値は、実際の Claude Code のトランスクリプトをディスパッチャーで再生して算出しています。scripts/ に 2 つのスクリプトがあります。

python3 scripts/bench_compactors_real.py       # match rate + mean savings
python3 scripts/bench_compactors_unmatched.py  # top unmatched commands

1 つ目は ~/.claude/projects/*/*.jsonl を走査し、すべての Bash 出力をレジストリ経由で再生して、ファミリーごとの削減量と全体の一致率を報告します。2 つ目は一致しなかったコマンドを分類し、ヒストグラムから次のコンパクターの対象がすぐにわかるようにします。

tsbench のスコアを再現する

2026-08-09 に確認した正直な状況： これらの手順が参照していたベンチマークのリポジトリは 404 を返し、上記の BENCHMARK-SUMMARY リンクも同様です。実行できない手順を残すのではなく、数値をその方法に基づいて評価できるよう、ハーネスの動作を以下に示します。

• 4 つの仕掛けを埋め込んだ、生成されたおもちゃのリポジトリ（決定論的なシード）。同じシンボルの二重定義、3 段階の呼び出しチェーン、a -> b -> c -> a のインポート循環、名前に有効な関数名が含まれる未使用の関数です。
• 読み取り専用の 8 つのタスクを、expected リストと forbidden リストに照らして機械的に採点します。重要なのは forbidden リストです。回答に正解と誤答の両方が含まれていても、正解だけを見る採点器なら正解と判定されてしまいます。
• sans_ts の対照群では、通常の Read/Grep/Glob を実行します。これがなければ、ベンチマークは Token Savior のプロファイル同士を比較するだけで、「役に立たない」と結論づけられず、その結果「役に立つ」とも結論づけられません。

再構築する際に知っておくべき注意点が 1 つあります。ハーネスは claude -p を起動し、~/.claude/settings.json を継承します。マシン上で Token Savior の PreToolUse フックが 1 つでも有効になっていると、対照群にも適用され、比較結果が歪められます。両方の群で無効にしてください（TS_GUARD_OFF=1 TS_READ_GUARD=0 TS_BASH_REWRITE=0）。

---

おまけ：MCP を使わないエージェント向け ts CLI

MCP を使わないエージェント（Cursor、Aider、Continue、スクリプト、CI）向けに、ts コマンドから一部のツールをシェル経由で利用できます。

ts use /path/to/project
ts get my_function          # JSON output
ts search 'pattern'
ts daemon start             # ~145ms per call vs 1.5s cold fork
ts init --agent cursor      # wire up Bash hooks for non-Claude agents

Claude Code では、CLI よりもコストが低いことが測定されているため、MCP サーバーの使用を推奨します。CLI は移植性が必要な場合に利用してください。

---

環境変数

すべて任意です。=1 と表示されている値は、他の値を受け付けません。正確に 1 を設定してください。bool と表示されている値は 1／true／yes を受け付けます（記載がある場合は on も受け付けます）。

サーバーとツールのマニフェスト

変数	デフォルト	用途
WORKSPACE_ROOTS	current dir	インデックスを作成するプロジェクトルートをカンマ区切りで指定します。Codex の注意点：Codex は MCP サーバーの環境変数をホワイトリストでフィルタリングするため、エクスポートしたシェル変数は渡されません。config.toml の [mcp_servers.token-savior] env（または env_vars）に設定してください
PROJECT_ROOT	—	WORKSPACE_ROOTS の代わりに単一のルートを指定します
CLAUDE_PROJECT_ROOT	—	意図的にアクティブプロジェクトを上書きします（Token Savior 独自の仕様であり、ホスト側では設定されません）。有効な場合は登録され、他のすべての起動時シグナルより優先されます
TS_STICKY_ACTIVE	off (bool, on ok)	アクティブプロジェクトを固定します。明示的な project= ヒントと絶対パス引数は引き続き各呼び出しを振り分けますが、共有デフォルトを変更する呼び出しはなくなります。兄弟関係にあるワークツリーで並列エージェントを実行する場合に使います
TOKEN_SAVIOR_PROFILE	full	ツールプロファイルです。クイックスタート設定と ts init が推奨する値の optimized は、パレートマニフェストを提供し、薄型スキーマを有効にして、マニフェストからキャプチャツールを除外します
TS_THIN_SCHEMAS=1	off (optimized では on)	冗長なツールスキーマをマニフェストから取り除きます
TS_DISCIPLINE	off (bool)	Ponytail 風のセッション指示です。get_edit_context で範囲を限定した最小限の完全な変更、search_codebase で見つかったものの再利用、スキップした内容を締めくくる一文を求めます。デフォルトではオフです。tsbench では測定可能な効果がない一方、セッションごとに 3〜4％余分にコストがかかります
TS_PROMPTS	on (bool)	review／audit／lean の MCP プロンプト（Claude Code のスラッシュコマンド）です。呼び出すまではコストがかかりません。0 で削除します
TS_AUTO_HOT_K	8	テレメトリ駆動の auto プロファイルで公開されるホットツールの数です（ツールは全部で 13 個）
TS_LEVEL_BANDIT	off	level が指定されていない場合に、Thompson サンプリングのバンディットで get_function_source／get_class_source の詳細レベルを選択します。デフォルトではオフです。ソースの代わりに要約が選ばれる傾向があったためです
TS_EXECUTE_MAX_CHARS	60000	ts_execute の結果の上限です。超過した場合、返される値は切り詰められ、その旨が報告されます
TS_GUARD_READ_FREE_LINES	200	規律ガード：インデックス済みコードのファイル全体を読み取る Read は、この行数まで許可されます
TOKEN_SAVIOR_CHAIN_NUDGE	on	0／false／off で、ツール連鎖の促しを無効にします
TS_MEMORY_DISABLE=1	off	メモリエンジンを無効にします（クリーンコンテキストのワークロード向け）
TS_CAPTURE_DISABLED=1	off	読み取り側のキャプチャサンドボックスをスキップし、マニフェストからキャプチャツールを除外します（これを切り替えるプロファイルはありません。optimized はキャプチャツールを非表示にするだけです）
TS_CODE_MODE_DISABLE=1	off	コードモードツールを無効にします
TS_CODE_MODE_NODE	node	コードモードのサンドボックスで使用する Node バイナリです
TS_RESOURCES_DISABLED	off (bool)	観測結果を ts://obs/{id} MCP リソースとして公開しません
TS_WARM_START	off (bool)	起動時にプロジェクトスロットを事前構築します
TOKEN_SAVIOR_NO_WARMUP	off (bool)	ts_search の埋め込みのウォームアップをスキップします
TS_SEARCH_COLD_DELEGATE	off (bool, on ok)	コールド状態での ts_search 呼び出しを、実行中の ts デーモンに委任します
TS_SOCK	/tmp/ts.sock	ts デーモンの Unix ソケットです（CLI とコールド状態での委任に使用）
TOKEN_SAVIOR_CLIENT	auto-detected	テレメトリ／クライアント検出用のクライアントラベル（claude-code など）です
TOKEN_SAVIOR_SESSION_LABEL	—	セッションテレメトリに付加する自由形式のラベルです

インデックス作成

変数	デフォルト	目的
INCLUDE_PATTERNS	built-in list	コロン区切りの glob。デフォルトのインクルードリストを置き換えます
EXCLUDE_PATTERNS	built-in list	コロン区切りの glob。デフォルトの除外リストを置き換えます
EXCLUDE_EXTRA	—	デフォルトの除外リストに追加される、コロン区切りの glob
TOKEN_SAVIOR_EXCLUDE_PATTERNS	—	インデクサーレベルで追加される、コロン区切りの glob
TOKEN_SAVIOR_MAX_FILE_SIZE	500000	インデックスを作成するファイルの最大サイズ（バイト）
TOKEN_SAVIOR_MAX_FILES	10000	プロジェクトごとの最大ファイル数
TOKEN_SAVIOR_WATCHER	auto	ファイルウォッチャー：auto / on / off
TS_WATCHER_FORCE_POLLING	off	ポーリング方式のウォッチャーバックエンドを強制します

Claude Code のフック

変数	デフォルト	目的
TS_CAPTURE_THRESHOLD_BYTES	4096	サンドボックスに格納するツール出力の最小サイズ
TS_CAPTURE_REPLACE=1	off	強制置換：インライン出力を無視し、URI に対して capture_get を呼び出すようエージェントに指示します
TS_CAPTURE_TTL_DAYS	30	この日数より古いキャプチャは次回の capture_put 時に削除されます。0 にすると GC が無効になります
TS_BASH_COMPACT=1	off	PostToolUse のコンパクター。コンパクション後も出力を保持します。現在のターンは縮小しません（上記の注記を参照）
TS_COMPACT_INLINE_THRESHOLD	4096	ハイブリッドモード：コンパクト化した結果がこのサイズを超えると、元の出力全体もサンドボックスに格納されます
TS_COMPACT_TINY_THRESHOLD	256	ハイブリッドモード：コンパクト化した結果がこのサイズを下回ると、サンドボックスを常にスキップします
TS_BASH_REWRITE=1	off	PreToolUse の Bash コマンド書き換え機能を有効にします
TS_BASH_REWRITE_LOG	—	すべての書き換えを記録する JSONL 監査ログ
TS_HOOK_MINIMAL=1	off	SessionStart のメモリーフックが Memory Index ブロックのみを出力します

メモリー関連の追加設定

変数	デフォルト	目的
TS_VIEWER_PORT	off	観察内容を表示するウェブビューアーのポート（未設定の場合は無効）
TS_AUTO_EXTRACT=1 + TS_API_KEY	off	メモリー観察内容を LLM で自動抽出します（Anthropic API キーが必要）
TS_MODEL	claude-sonnet-4-6	自動抽出モデルの上書き設定
TOKEN_SAVIOR_MEMORY_AUTO_SAVE=1	off	メモリー観察内容を自動保存します
TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID	—	重要な観察内容のフィード

ストレージ、ダッシュボード、デバッグ

変数	デフォルト	目的
TOKEN_SAVIOR_STATS_DIR	~/.local/share/token-savior	テレメトリーと統計データのディレクトリ
TOKEN_SAVIOR_DASHBOARD_HOST	127.0.0.1	ダッシュボードのバインド先ホスト
TOKEN_SAVIOR_DASHBOARD_PORT	8921	ダッシュボードのポート
TOKEN_SAVIOR_INCLUDE_TMP_PROJECTS	off (bool)	ダッシュボードに一時ディレクトリ内のプロジェクトも表示します
TOKEN_SAVIOR_DEBUG=1	off	デバッグログ
TOKEN_SAVIOR_TRACE	off (bool)	MCP リクエストのライフサイクルトレース

設定項目ではありません：CLAUDECODE、CLAUDE_CODE_ENTRYPOINT、CLAUDE_PROJECT_DIR、 CLAUDE_CONTEXT_REMAINING_PCT、CODEX_*、HERMES_* は、ホスト／クライアントの 検出と起動時のプロジェクトヒントに使用されます。これらは環境によって設定されるため、ユーザーが設定するものではありません。 （CLAUDE_PROJECT_DIR は Claude Code が実際にエクスポートする値です。常にメインのチェックアウトを示し、セッションが作業する ワークツリーを示すことはありません。そのため、起動ディレクトリがリンクされたワークツリーである場合は、起動ディレクトリが優先されます。 CLAUDE_PROJECT_ROOT は設定項目の表に移動しました。これを設定するものはなく、設定できるのはユーザーだけです。）

名前に関する注意：ベンチマークのスニペットにある TS_PROFILE はtsbench の変数です。 サーバーが読み取るのは TOKEN_SAVIOR_PROFILE です。

---

ライセンス

MIT