context-doctor

context-doctor 🩺

AI エージェントのトークンがどこに使われているかを把握し、何の役にも立たないトークンへの支払いをやめましょう。

AI エージェントはメッセージを送るたびに、古いツール出力、貼り付けたファイル、長い指示など、コンテキスト全体を再送します。50万トークンのセッションでは、コーヒーブレイクの後にプロンプトキャッシュが期限切れになると、すべてに再び通常料金がかかります。context-doctor は、実際のセッションで発生している無駄を金額で測定し、効果があるタイミング、つまりコンテキストに入る前、コンテキスト内にある間、そしてリクエストのたびに削減します。お使いのマシン上で動作し、API キーは不要で、テレメトリーも送信しません。Claude Code（ターミナル、IDE、デスクトップアプリ）、Claude Desktop、ChatGPT、Codex、Cursor、Gemini CLI、GitHub Copilot、Anthropic、OpenAI、Gemini API を使うあらゆるアプリ、さらに CI にも対応しています。MIT ライセンスで、Node 20 以降に対応し、macOS、Linux、Windows で動作します。

npx context-doctor savings     # what your recent sessions cost, and what each fix would have saved

どの context-doctor ですか？ 同じ名前のプロジェクトが複数あります。これはnpm の context-doctorで、公式 MCP Registry では io.github.KushalP1/context-doctor として登録されています（登録内容はこちら）。レジストリはサービスであり、GitHub リポジトリ内の一覧ではありません。modelcontextprotocol/servers リポジトリにはリファレンスサーバーのみが含まれており、それ以外はレジストリを参照するよう案内されています。gAI Ventures が開発・保守しています。

クイックスタート

作業場所を選んでください。どの方法も約1分で完了し、いつでも元に戻せます。

使用するもの	操作
Claude Code（ターミナル、IDE、デスクトップアプリ）	Claude Code 内で、/plugin marketplace add KushalP1/context-doctor を実行し、続けて /plugin install context-doctor@context-doctor を実行します。毎回のプロンプトのチェック、コンパクションフック、MCP ツール、および /context-doctor:savings、:checkup、:overhead、:pack、:autopilot、:compact-window が使えるようになります
このマシン上のすべてを一度に	npm install -g context-doctor && context-doctor install を実行すると、Claude Code、Claude Desktop、Cursor、Codex、Gemini CLI、Google Antigravity、GitHub Copilot に MCP サーバー、スキル、フックが設定されます（書き込み内容）。context-doctor doctor で確認し、context-doctor uninstall で削除できます。その後、ターミナルまたは IDE で Claude Code を使う場合は、context-doctor autopilot on を実行します
Claude Desktop、Cursor、または任意の MCP クライアント	クライアントの MCP 設定にサーバーを追加します（または Claude Desktop で最新リリースからワンクリックの .mcpb をインストールします）： {"mcpServers": {"context-doctor": {"command": "npx", "args": ["-y", "context-doctor", "mcp"]}}}
claude.ai、ChatGPT、スマートフォンアプリ	npx context-doctor instructions --copy を実行し、アプリの個人設定に貼り付けます（貼り付け先が案内されます）。ChatGPT からは URL 経由で MCP サーバーに接続することもできます（方法）
LLM API を使う独自アプリ	npx context-doctor proxy --autopilot を実行し、ANTHROPIC_BASE_URL、OPENAI_BASE_URL（/v1 を追加）、または GOOGLE_GEMINI_BASE_URL を http://127.0.0.1:8787 に設定します。プロキシを使えない場合は、SDK クライアントをラップします：withContextDoctor(new Anthropic())（ライブラリ）
Python / RAG パイプライン	pip install "git+https://github.com/KushalP1/context-doctor#subdirectory=python" を実行します（PyPI 版は近日公開予定）。その後、pack_documents(retrieved_docs, question, budget=4000) を使うと、LangChain または LlamaIndex の結果から重要なチャンクだけが残るように整理できます。Python README
GitHub のプルリクエスト	uses: KushalP1/[email protected] を使うと、CLAUDE.md、AGENTS.md、ルールの追加によるプルリクエストの増加量をコメントで知らせ、予算を超えた場合に失敗させることもできます（設定方法）

できること

自分の履歴を使って、コストをドル単位で測定（プロファイリング）

• savings：最近の Claude Code セッションにかかった費用と、以下の各対策で削減できたはずの費用を、請求額に照らしてリクエストごとに再生します。
• overhead：メッセージの前に各リクエストで再読み込みされるもの（システムプロンプト、ツール、MCP サーバー、CLAUDE.md、ルール、メモリ）と、各ファイルの月額コストです。
• tasks、reads、subagents、compactions：コミットあたりのコスト、セッションをまたいで読み込まれたファイル、各サブエージェントが親エージェントで同じ手順を実行するより安かったかどうか、コンパクション後にセッションの作業効率が落ちるかどうかを確認できます。
• cache-misses：プロンプトキャッシュがまだ有効なはずのときに書き換えられたリクエストを、モデルとコンテキストサイズ別にコスト換算し、トランスクリプトから原因が分かる場合はその原因も表示します。
• limits：プランの5時間および週ごとの利用枠（Claude Pro/Max の場合はステータス行に記録）と Codex の利用枠、それぞれの消費ペースと上限に達する時期、各種類の100万トークンが利用枠の何％に相当するかを、自分の測定値に合わせて算出し、誤差も表示します。
• cache-plan <request.json>：Anthropic API リクエストのどこに cache_control を設定すべきか、また N 回の呼び出しでどれだけ節約できるかを確認できます。
• session、watch、analyze、report、dashboard：任意のセッション、会話ファイル、エージェントのトレースについて、トークンの内訳と無駄なコンテキストを確認できます。

コンテキストから無駄を取り除く（パックとオーバーヘッド）

• pack（および pack_context MCP ツール）：大きな文書、PDF、ログ、コードベース全体ではなく、質問に必要な箇所だけをトークン予算内で抽出します。
• recall（および recall MCP ツール）：コンパクションで要約されてしまったターンや、オートパイロットが消去したツール出力を含め、質問に必要なこのセッションのトランスクリプトの数行を、時刻と位置とともに取得します。シークレットはマスクされます。
• overhead split：大きな CLAUDE.md やメモリファイルを、内容を一語一句変えずに、簡潔なファイルとエージェントが必要に応じて開く参照ファイルに分割します。
• ci と GitHub Action：他のコストと同じように、メモリファイルの増加を確認できます。

無駄を自動的に削減

• モデル切り替え警告（PreModelSwitch、Claude Code 2.1.251 以降）は、/model の切り替え前にそのコストを表示します。コンテキスト全体が新しいモデルのキャッシュに再書き込みされます。
• サブエージェントの料金表示（Agent ツールの PreToolUse）は、サブエージェントの開始前に、その種類における自分の中央値を使ってコストを表示します（作者の場合：汎用は $3.99、Explore は $1.43、30日間で422回実行）。Opus または Fable で実行する場合の Sonnet の料金と、起動が集中した場合の合計も表示します。処理をブロックすることはありません。
• コンパクションフック（PreCompact）は、Claude Code の各コンパクションに、セッションで失ってはならない情報（変更したファイル、未完了のタスク、指示、失敗したテスト）を伝えます。スレッドを失わずにトークンを節約できます。
• 各プロンプトで動作するフック（Claude Code、Codex、Gemini CLI の場合。Cursor では各ツール呼び出し後）は、実際のコンテキストサイズと最大の無駄をモデルに伝え、キャッシュの有効期限が切れた後に大きなセッションへ戻った際は /compact を提案します。
• compact-window：自分の履歴をもとに測定したうえで、Claude Code 独自の自動コンパクション用ウィンドウを設定します。デスクトップアプリでも動作します。
• オートパイロット：プロンプトキャッシュが無効な場合に限り、古くなったツール出力を消去するローカルプロキシ（または SDK ラッパー）です。リクエストのコストが増えることはありません。

節約できるコスト

作者のマシン上にあるすべての Claude Code セッション（主に1Mウィンドウの Opus 5 と Fable 5）で実測した値です。プロンプトキャッシュの課金方式（キャッシュ読み取りは各モデルの読み取り料金、入力料金の2.5～10％。書き込みは5分キャッシュで入力料金の1.25倍、1時間キャッシュで2倍）に基づき、API の標準価格で算出しています。2026-10-13 に、各リクエストで使用したモデルと現行価格に基づいて再測定しました（Opus 5.5 は入力トークン100万個あたり $4、読み取りは $0.20）。context-doctor savings を実行すると、同じ測定を自分のデータに対して行えます。 1. 戻ってきたときの圧縮（Claude Code のすべての利用環境。デスクトップアプリを含みます）。133 日間で、プロンプトキャッシュの有効期限が切れた後に 15 万トークンを超えるセッションへ戻ったケースは 479 回でした（1 時間キャッシュでは 65 分、Claude Code 2.1.295 がよく書き込む 5 分キャッシュでは 10 分のアイドル時間後）。戻った時点のコンテキストの中央値は 52 万 2,000 トークンでした。

最初の返信後に /compact を実行していた場合の純節約額	$2,993（1 か月あたり約 $675）
費用対効果があった復帰回数	479 回中 342 回
最悪の単一ケース	−$1.79（数メッセージ後に離れたセッション）

各復帰で数えるのは、次の復帰までのメッセージだけです。圧縮リクエストもコストとして計上しています。圧縮後にモデルが再読込する可能性のあるファイルと、要約で省かれる内容は計上していません。そのため、これは数字を添えたアドバイスであり、代わりに実行するものではありません。

2. オートパイロット（ターミナルまたは IDE での Claude Code、API アプリ）。133 日間の 67 セッションを、実際のタイムスタンプを使って、公開済みのオートパイロットコードで再生しました。

	オートパイロットなし	オートパイロットあり	節約額
API の定価での入力コスト	$11,347	$9,905	$1,442（12.7％、1 か月あたり約 $325）
コストが増えたセッション			67 回中 0 回

67 セッション中 30 セッションで節約でき、最大の節約率は 34.9％でした。アイドル状態になる長時間セッションで、最も効果があります。これらのセッションはデスクトップアプリで実行されており、オートパイロットからはアクセスできません。そのため、作者にとってこれは、同じセッションをターミナルで実行した場合の節約額です。context-doctor savings では、両者を分けて確認できます。仕組み →

3. より早い段階での圧縮 （自動、Claude Code のすべての利用環境。デスクトップアプリを含みます）。1 で紹介したのはアドバイスですが、作者のマシンでは 33 回中 1 回しか実行されませんでした。Claude Code には、誰かが実行する必要のないネイティブ設定があります。~/.claude/settings.json の autoCompactWindow を設定すると、ウィンドウがそのサイズであるかのように圧縮します。context-doctor compact-window は、各セッションのリクエストを複数のサイズで再生し、キャッシュの課金方式に基づいて価格を計算します（シミュレーション上の各圧縮では、リクエスト料金と出力料金での 2 万トークンの要約料金が発生します）。サイズを選ぶまでは何も変更しません。

ウィンドウ	直近 30 日間の入力コスト	節約額	週あたりの圧縮回数
現在の設定（約 970k）	$3,648		4.7
600k	$2,242	$1,405（39％）	6.5
400k	$1,814	$1,833（50％）	14.2
300k	$1,664	$1,983（54％）	25.2
200k	$1,501	$2,146（59％）	48.1

41 セッション。コストは実際に発生します。圧縮するたびにセッションの履歴が要約に置き換わるため、ウィンドウを小さくすると、詳細さと引き換えに費用を節約できます。そのため、このコマンドはまず表を表示し、サイズを指定した場合にのみウィンドウを設定します（context-doctor compact-window 400k。off で元に戻せます。settings.json のバックアップも保持されます）。

そのほかの測定結果：

• パック： このリポジトリについての 10 個の質問のうち 9 個に、トークンの 0.6％ で回答できました。詳細 →
• Claude の正確なカウント： 現行の Claude モデルは、文章では 1 トークンあたり 2.75 文字（コードでは 2.4 文字）を処理します。多くのツールが想定する 4 文字ではありません。つまり、一般的な「4 文字で 1 トークン」というルールより、Claude は約 40％多くのトークンをカウントします（文章では約 45％、コードでは約 33％）。context-doctor accuracy では、独自のセッションで比率を再確認できます。理由 →

Claude のサブスクリプションでは定価を支払うのではなく、同じトークン数が利用上限から差し引かれます。Anthropic はキャッシュされたトークンが利用上限にどう反映されるかを公開していないため、金額は請求額ではなく、効果の大きさとしてご覧ください。

対応環境

作業環境	リクエストごとに自動で実行	さらに利用できる機能
ターミナル、VS Code、JetBrains の Claude Code	Autopilot が古いツール出力をクリアします（キャッシュがコールド状態の場合のみ。コストは決して増えません）。すべてのプロンプトで Hook を実行し、実際のコンテキストサイズ、最大の無駄、キャッシュの期限切れ後に大きなセッションへ戻った際の /compact の提案を表示します。すべての圧縮で Compaction hook を実行します。設定している場合は compact-window も使用します	npm または プラグインとしてインストールできます。ステータスバーのコンテキストメーター、/context-doctor:savings、session、watch、report、ダッシュボード、MCP ツール
デスクトップアプリの「Code」タブにある Claude Code	上記と同様の Hooks を実行し、キャッシュがコールド状態から再開した際の /compact の提案を、モデルとユーザーの両方に表示します。compact-window を設定している場合は、Claude Code が自動で早めに圧縮します。自動運転ではありません。アプリは独自の API アドレスを設定し、設定内のアドレスを無視します	上記と同じ
Cursor（エージェント）	ネイティブの after-tool-call hook（~/.cursor/hooks.json）を使用します。チャットが大きくなると、エージェントに同じ整理のガイダンスと最大の無駄を、増加率が 40％に達するごとに 1 回表示します。（Cursor の prompt hook はプロンプトの許可またはブロックしかできないため、ガイダンスをモデルに届けるにはこのイベントを使用します）	MCP ツール、エディターのステータスバー拡張機能、cursor プロファイラー。独自の OpenAI キーを使用する場合は、トークン認証付きトンネル経由で Autopilot も利用できます（方法）
Codex（ChatGPT アプリの Codex タブ、IDE 拡張機能、CLI）	API 独自のトークン数を使う、すべてのプロンプトに対する hook	MCP ツール、スキル、Codex のロールアウトを読み取る session。API キーを使う場合は Autopilot も利用できます（autopilot on は ~/.codex/config.toml に openai_base_url を設定します。Codex は OPENAI_BASE_URL を読み取らなくなります）
Gemini CLI	API 独自のトークン数を使う、すべてのプロンプトに対する hook（BeforeAgent）。API キーを使う場合は Autopilot も利用できます：GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:8787（Google サインインのトラフィックは別の経路を通ります）	MCP ツール、チャットを読み取る session と watch、GEMINI.md のサイズを測定する overhead
GitHub Copilot（Copilot CLI、Copilot アプリ、VS Code のエージェントセッション）	session-start hook（~/.copilot/hooks/context-doctor.json）により、新規セッションと再開したセッションすべてに常時適用するルールを渡します。サイズチェックはありません。Copilot は、コンテキストを追加できない hook にのみトランスクリプトを渡します	MCP ツール（~/.copilot/mcp-config.json。VS Code の Copilot セッションも読み取ります）
Anthropic、OpenAI、Gemini API を使う独自アプリ	/v1/messages、/v1/chat/completions、/v1/responses、Gemini の generateContent で Autopilot を使用します（ANTHROPIC_BASE_URL／OPENAI_BASE_URL／GOOGLE_GEMINI_BASE_URL）。または最適化プロキシを使用します（キャッシュされたトラフィックではコストが増える場合があります）。プロキシを使えない場合（サーバーレス、エッジなど）は、withContextDoctor(client) で SDK クライアント内の Autopilot を実行します	/stats で正確な使用量とキャッシュヒット率を確認できます。プロンプトキャッシュの配置に関するアドバイスも利用できます（プロキシ）
Claude Desktop のチャット	以下の 6 つの常時適用ルールをすべてのチャットに送信します（従来の Chat がそれをモデルに表示するかは未確認です。理由）。モデルは約 30 ターン後とコストに関する質問時に、低コストの profile_context を 1 回呼び出します。大きなローカルファイルを丸ごと読み取る代わりに pack_context を使います。チャット履歴は切り詰められず、新しいチャットは作成できるため、チャットが長くなったらハンドオフを 1 回提案します	ワンクリックで .mcpb をインストールできます。context_checkup、handoff、ask_file の各プロンプト、次のチャットに添付する handoff://latest を利用できます（ハンドオフ）
claude.ai、ChatGPT、スマートフォンアプリ	アカウントの常時適用設定を一度貼り付けます（クイックスタート）	エクスポートしたチャットを analyze または session でプロファイル分析できます。ChatGPT の開発者モードでは、URL の MCP ツールと pack_context へのアップロードを利用できます（方法）
CI	analyze --fail-over-budget は、プロンプトが予算を超えて増大したビルドを失敗させます。GitHub Action はメモリファイルの増大を制限します	.contextdoctorrc の予算とプリセット（CI）
ご利用のマシン上でこれらのリクエストを送信するプロセスがないため、対象外です。Claude Desktop のチャット、claude.ai、ChatGPT、Cursor 独自のサブスクリプションモデル、または ChatGPT にサインインした状態の Codex 内でのトリミングは対象外です。これらには、上記のルールと測定結果が適用されますが、自動処理は行われません。

MCP サーバーは、有効になっているすべてのチャットに、以下の常設ルールをそのまま渡します（Cursor と Claude Code ではモデルに送る前に提示します。Claude Desktop の従来型チャットについては、未確認です）。

1. トークン、コスト、速度、または制限について尋ねられた場合、および約30ターンに達したとき、または大きな貼り付けが3回以上あったときは、回答する前に profile_context を呼び出してください。チャットアプリでは sketch を渡します。最上位の指摘に対処してください。トークン数を自分で推定しないでください。
2. チャットが長くなったら、引き継ぎを一度提案してください（save_handoff）。履歴を切り離せるのは新しいチャットだけです。
3. 貼り付け内容またはツールの結果が約2kトークンを超える場合は、必要な要点を要約してください。
4. 以前の内容は名前を挙げて参照してください。再引用したり、base64 をインラインで記載したりしないでください。
5. 編集しない大きなファイルについては、全体を読まずに、質問とともに pack_context を呼び出してください。
6. optimize_context がプルーニングされたターンのダイジェストを返した場合は、その150トークン以下の要約を書いてください。

ルール1～4は、ChatGPT のガイドで単独で記載する必要があるとされている、文字数512ちょうどで終わります。

コマンド

コマンド	機能
context-doctor install / uninstall	検出したすべての設定を適用（または削除）します。Claude Desktop、Claude Code、Cursor、Codex、Gemini CLI、Google Antigravity、GitHub Copilot 用の MCP サーバー、Agent Skill（Claude Code、Codex、Antigravity）、すべてのプロンプトで実行されるフック（Claude Code、Codex、Gemini CLI の BeforeAgent、Cursor の postToolUse、postToolUseFailure、sessionStart）、Claude Code の PreCompact、SessionStart、PreToolUse（サブエージェントの料金）、および 2.1.251 以降の PreModelSwitch フック、Copilot の sessionStart（常時適用ルール）が対象です。--statusline を指定するとステータスバーの行を追加します（詳細）
context-doctor doctor	インストール全体を自己診断します。修正方法とともに、貼り付けて使える ✓／✗ の診断結果を表示します。自動操縦がアクセスできる各環境と、そのポートを使用しているほかのプログラムも確認できます
context-doctor savings [--days n] [--share [--copy]]	最近の Claude Code セッションでかかった費用と、コールド再開時の /compact、自動操縦、より早い自動圧縮ウィンドウによって削減できる費用を、実際の請求使用量に対して同梱コードを実行して再現します。--share は投稿用に合計のみを出力します（プロジェクト名やパスは含みません）。ターミナルで引数なしの context-doctor を実行した場合も同じ内容が表示されます
context-doctor autopilot on|off|pause|resume|status	ターミナルまたは IDE で開始するすべての新しい Claude Code セッションをローカルプロキシ経由にします。プロンプトキャッシュがコールドのときだけ古いツール出力を消去します。入力コストを 12.7% 削減し、悪化したセッションはありません（詳細）
context-doctor proxy --autopilot	独自の Anthropic、OpenAI、Gemini API アプリ向けのローカルプロキシです。プロンプトキャッシュがコールドのときだけ古いツール出力を消去するため、コストが増えることはありません。通常の proxy は最適化戦略（重複排除、トリミング、Base64 の削除）を実行しますが、キャッシュ済みのトラフィックではコストが増える場合があります。公開 URL には --token、累積削減額には /stats を使用します（詳細）
context-doctor compact-window [status|off|<size>]	直近 30 日分を、200k から 800k までの自動圧縮ウィンドウで再現します。入力コスト、削減額、および各設定で増える圧縮回数を表示します。400k（または 250000、0.4m）を指定すると Claude Code の autoCompactWindow をバックアップ付きで設定し、off を指定すると削除します。デスクトップアプリを含む、すべての Claude Code 環境で動作します
context-doctor instructions [--copy]	claude.ai／ChatGPT の設定用の常時適用ルール（約 190 トークン、GPT では約 130 トークン）です。サーバーを実行できないウェブやスマートフォン向けです
context-doctor handoff [list|show <id>|latest] [--copy]	チャットアプリから保存したハンドオフ（handoff プロンプトまたは save_handoff）を一覧表示、印刷、またはコピーします。コピーした内容は新しいチャットの最初のメッセージとして貼り付けられます（ハンドオフ）
context-doctor mcp [--http]	クライアントやレジストリから npx -y context-doctor mcp を起動するための、サブコマンド形式の MCP サーバーです
context-doctor-mcp	MCP サーバー本体です。デフォルトでは stdio（インストーラーが設定する方式）を使用します。--http [--port 8808] [--host H] [--allowed-hosts names] [--allowed-origins list] [--store-handoffs] を指定すると、ChatGPT の開発者モードコネクターのような URL ベースのクライアント向けに /mcp でストリーミング可能な HTTP を提供します（認識済みのホスト名のみが対象です。トンネル経由の場合は、その名前を --allowed-hosts に渡します）
context-doctor session [file]	Claude Code セッションのプロファイルを作成します。実行時のコンテキスト、検出結果、実測トークン数とプロンプトキャッシュのコスト分析、ツールごとの処理時間の内訳、出力と推論がコストに占める割合、繰り返された同一（ポーリング）ツール呼び出しの料金、サブエージェントのコスト（サブエージェント自身のウィンドウと請求額。親のプロファイルには含まれません）を確認できます。Codex のロールアウト、Gemini CLI のチャット、ChatGPT のデータエクスポート（conversations.json）も読み取ります。--list で一覧を表示します
context-doctor watch [file]	増加中のセッショントランスクリプトやエージェントトレース（Claude Code／Codex の JSONL、または OpenAI／Anthropic のプレーンな会話 JSON ファイル）をライブ監視します。変更ごとにトークン数とコストを表示し、検出結果も随時表示します
context-doctor cursor [--list]	Cursor のローカル履歴からチャットのプロファイルを作成します（両方のストレージ形式に対応）
context-doctor analyze <file>	会話のプロファイルを作成します。トークンの内訳、検出結果、コストとレイテンシの推定値を表示します。--exact を追加すると実際のカウントを表示し、CI で違反時に終了コード 1 を返すには --fail-over-budget を指定します
context-doctor optimize <file>	安全な修正を適用します。大きなインラインファイル書き込みには --strategy trim-tool-calls、同意済みの情報損失を伴う圧縮には --strategy prune-history を追加します（各機能の詳細）
context-doctor diff <before> <after>	2 つのプロファイルを比較します。カテゴリごとの変化、解決または新たに発生した検出結果、金額とレイテンシの削減量を表示します
context-doctor overhead [--days n] [--mcp]	メッセージを送る前にリクエストごとに再読み込みされるものを確認します。初回リクエストの実測サイズ（Claude Code、Codex、Gemini CLI のセッション）、各メモリファイル（CLAUDE.md とインポート、ルール、自動メモリ、AGENTS.md、Cursor のルール、GEMINI.md）の月額料金、サーバーごとの MCP 呼び出しを表示します。--mcp を指定すると、設定済み各サーバーのツール定義のサイズを測定し、未使用のものを表示します
context-doctor overhead prune [--days n] [--write] [--undo]	プロジェクトごとに、直近 n 日間のセッションで一度も使われなかった MCP サーバーとスキルを表示します。--write を指定すると、このフォルダーのプロジェクトに対して .claude/settings.local.json で無効化します（バックアップを保持し、すべての項目を記録します）。--undo はその項目だけを元に戻します。アプリのコネクター、プラグイン、context-doctor 自体は対象外です
context-doctor overhead split <file> [--min-tokens n] [--write]	メモリファイル内の大きなセクションやコード量の多いセクションを、文言を変えずに <name>.reference.md へ移し、参照先を残します。インデックスはそのままです。--write を指定するまでは計画のみを表示し、指定すると事前にバックアップを作成します
context-doctor pack <files|dirs|-> -q "…"	大きなドキュメント、ログ、コードから質問に必要なチャンクだけを選び、順位付けして --max-tokens（デフォルトは 4000）に収めます。クエリを指定しない場合は概要を表示します。--ids a#2,b#5 で概要からチャンクを選択できます。--semantic を指定すると、ローカルの Ollama モデルを使って意味に基づく順位付けも行います。オフラインで動作し、キーは不要です
context-doctor recall "<query>" [--session <id|path>]	このセッション自身のディスク上のトランスクリプト（Claude Code または Codex）を検索し、最適な抜粋を時刻と位置とともに表示します。圧縮前のターンや、コンテキストから消去されたツール出力も対象です。秘密情報はマスクされます。--session で指定しない限り、ほかのプロジェクトのセッションは対象になりません。recall MCP ツールとしても利用できます
context-doctor tasks [--days n]	コミットごと、プロジェクトごとのコストを表示します。各セッションの記録済み使用量を、そのセッションで作成したコミットに対して料金換算します
context-doctor reads [--days n] [--limit n]	セッションごとに読み込まれたファイルについて、読み取り数、トークン数、コスト、および CLAUDE.md の要約や pack が効果を発揮するかどうかを表示します
context-doctor subagents [--days n]	費用対効果のあったサブエージェントを表示します。それぞれの請求額を、同じ手順を親セッションで実行した場合と比較します
context-doctor compactions [--days n]	圧縮直後にセッションの作業効率が悪化するかどうかを調べます。各圧縮の前後で、再読み込み、ツールエラー、ユーザーによる修正を比較します
context-doctor cache-misses [--days n]	有効期間内にプロンプトキャッシュを書き換えたリクエスト（圧縮を挟まず、前回のコンテキストが 20k 超で、その 60% 超を書き直したもの）を表示します。モデルとコンテキストサイズごとにキャッシュ読み取りレートを上回る料金を算出し、確認できる場合は原因と、キャッシュミスが少ないモデルのバージョンも表示します。Claude Code のバージョンごとに、アップグレード後の段階的な変化（1 時間キャッシュの比率、初回リクエストのサイズ、モデルのミス率）にフラグを付けます。モデルとバージョンごとの結果には --json を指定します
context-doctor limits [--days n]	プランの上限をそれぞれの単位で表示します。各ウィンドウの使用率、消費ペース、上限到達までの時間（Claude のステータスラインの読み取り値から算出する 5 時間および週単位のウィンドウ、Codex のロールアウトから算出）を示します。また、入力、キャッシュ読み取り、キャッシュ書き込み、出力の 100 万トークンごとの上限に対する割合を、実測値に基づく当てはめとその誤差とともに表示します。データが少なすぎる場合はその旨を示し、数値は表示しません
context-doctor cache-plan <request.json> [--calls n] [--out file] [--explicit]	Anthropic API リクエストで cache_control を設定すべき場所（--explicit を指定しない限り、変動する末尾に対するトップレベルの自動キャッシュ）と、n 回の呼び出しによる削減額を示します。--out を指定すると適用済みの内容を書き出します
context-doctor accuracy	請求対象のうちトランスクリプトで確認できる割合（固定のハーネス基準値と、ターンごとに挿入されるコンテンツ）に加え、トークナイザーを検証します。API 独自のカウントによるモデルごとの実際の文字数／トークン数を、推定器が使う比率と並べて表示します
context-doctor report	マシン全体の影響レポートを表示します（プロキシの削減量は再起動後も保持されます）。プロキシによる正確な削減量、フックの動作状況、コールド再開時の /compact 提案後に圧縮が行われた頻度、最近のセッションで回収可能な無駄を表示します
context-doctor dashboard	ローカルの削減量ダッシュボードを 127.0.0.1 で表示します。1 日あたりの削減トークン数、使用中のコンテキスト別セッションと回収可能なセッション、予算状況を確認できます
context-doctor ci [--base <ref>] [--max-tokens n] [--max-increase n] [--markdown]	HEAD と基準コミットのメモリファイル（CLAUDE.md、AGENTS.md、GEMINI.md、ルール、そのインポート）を比較します。予算超過時は終了コード 1 を返します。GitHub Action の実行内容です（詳細）
context-doctor init [preset]	プリセット（chat、agent、batch）から .contextdoctorrc を作成します。1 つのコマンドで導入でき、後から調整できる予算を設定します
context-doctor experiment --task "…"	同じコミットから、タスクを新しいセッションと --existing からフォークしたセッションでそれぞれ 1 回実行します。モデルとツールをそろえて、請求額、キャッシュの内訳、処理時間、および --check の合否を比較します。費用が発生する唯一のコマンドのため、各条件の支出上限を設定し、作業ツリーが未コミットの変更を含む場合は実行を拒否します（詳細）
context-doctor ab [--lever …] [--yes]	施策によって品質が変化するかを検証します。小規模なコーディングタスク 8 件を、それぞれ非公開チェックで採点する小さなリポジトリ上で実行します。Messages API を使い、常時適用ルール、自動操縦による消去、pack_context、PreCompact の指示の有無を比較します。合格数、トークン数、コストを並べて表示します。ANTHROPIC_API_KEY に課金されます。推定額を表示し、--yes がなければ送信せず、--budget に達すると停止します（詳細）
context-doctor statusline	Claude Code のステータスバーに、実行時のコンテキストとウィンドウ、キャッシュ比率、コストを表示します。さらに Claude Code 2.1.251 以降では、キャッシュが温かい状態を保つ時間と、コールドになった後の次のターンのコストも表示します。install --statusline で設定します。既存の statusLine は上書きしません（詳細）
context-doctor hook	install で登録される、すべてのプロンプトで実行されるフック（Claude Code、Codex、Gemini CLI、Cursor）と Claude Code の圧縮フックです。hook copilot は GitHub Copilot のセッション開始フックです。これらを自分で実行する必要はありません。警告のしきい値は CONTEXT_DOCTOR_WARN_TOKENS で調整できます（デフォルトは 80000）
context-doctor --version	インストール済みのバージョンを表示します。--help で各フラグを一覧表示します
**プライバシー：**すべてお使いのマシン上で実行されます。コア機能に API キーは不要で、データが外部に送信されることも、テレメトリーが収集されることもありません。プロキシはアプリ独自の認証情報をそのまま転送し、プロキシ自身の認証情報は保持しません。

新機能

• 次のリリース（main 上、未リリース）：キャッシュの有効時間、キャッシュミスの理由、Antigravity：Claude Code 2.1.251 以降では、ステータスラインにプロンプトキャッシュが有効な時間と、キャッシュが無効になった後の次のターンにかかるコストが表示されます。cache-misses は、Claude Code 独自の説明（ツールの変更、システムプロンプトの変更、有効期間を過ぎるまでアイドル状態だったこと）とその対処法を示し、キャッシュの有効期限が切れた直後に起動するループも検出します。install は Google Antigravity（MCP サーバーとスキル）も設定し、overhead --mcp はツールリストの変更によってキャッシュが無効になる MCP サーバーにフラグを付けます。
• 0.38 上限をその単位で表示、アップグレード後の回帰、履歴の検索、サブエージェントの料金：context-doctor limits は各プランの期間について、使用率、ペース、使い切るまでの時間（Claude Pro/Max はステータスラインから、Codex はロールアウトから）と、100 万トークンがその上限に占める割合を、お使いの利用状況に基づく誤差とともに表示します。savings も上限と同じ単位で節約額を示します。cache-misses は Claude Code のアップグレード後の急な変化にフラグを付け、recall はセッションのトランスクリプト（圧縮されたターンを含む）を検索します。フックはサブエージェントの開始前に料金を表示します（実行をブロックすることはありません）。overhead prune は、プロジェクトごとに未使用の MCP サーバーとスキルを無効にします。いつでも元に戻せます。OpenAI のキャッシュは最大 24 時間、有効としてカウントされます。独立した QA によるレビューで見つかった問題は、リリース前に修正されました。
• 0.37 デスクトップチャットアプリ：引き継ぎ、アップロード、簡潔な結果、セキュリティレビュー：チャットアプリでは履歴を編集できないため、handoff プロンプト（Claude Desktop の + メニュー）を使ってモデルに 400 トークン以下の要約を作成させ、save_handoff で保存できます（シークレットはマスクされ、次のチャットに添付できる handoff://latest を利用可能。ターンごとの節約量も表示され、52k トークンのチャットが約 600 トークンになります）。ask_file は大きなファイルの内容を pack_context 経由で回答に利用でき、--http 経由では ChatGPT へのファイルアップロードにも対応します。ChatGPT では簡潔な結果が返されます。独立した QA レビューで見つかった 11 件の問題は、テストを追加して修正されました。トンネル経由の場合、--http には --allowed-hosts <tunnel host> が必須になりました（handoff）。

各リリースの詳細はこちら：docs/whats-new.md。

ドキュメント

• 「install」の動作：書き込まれるすべてのファイル、その後の各セッションで実行される内容、MCP が必要になるタイミング
• オートパイロット：古くなったツール出力を消去する方法と、追加コストが一切かからない理由
• プロキシ：オートパイロットと API アプリ向けの最適化モード、/stats、キャッシュのアドバイス、Cursor 用の公開 URL
• チャットアプリ：Claude Desktop、ChatGPT、claude.ai、スマートフォンアプリ。自動で動作するものと、促すだけのもの、MCP ツール、プロンプト、リソース
• 引き継ぎ：400 トークン以下の概要を使って、新しいチャットで長いチャットを続ける方法
• プロファイリング：セッション、プロンプトキャッシュの経済性、サブエージェント、tasks、reads、compactions、cache-misses、limits、report
• パックとオーバーヘッド：pack、recall、overhead、overhead split、overhead prune
• 検出と修正：プロファイラーが検出する内容と、各最適化戦略による変更
• ライブラリ：profileConversation、optimizeConversation、packContext、withContextDoctor
• 予算と CI：GitHub Action と .contextdoctorrc
• エディターとステータス行：VS Code ／ Cursor 拡張機能と Claude Code のステータスバー
• トークン数：数値が「~」になる理由、Claude の比率の測定方法、正確な数値
• パフォーマンス：context-doctor 自体にかかるコスト（6 つの MCP ツール定義で最大約 2,344 トークン）
• 実験とA/B テストスイート：コンテキストを小さくすると効果があるか、また、各施策によって品質が損なわれるか。実際のタスクで測定
• 新着情報、ロードマップ、Python パッケージ

貢献

Issue と PR を歓迎します。このツールの信頼性を保つためのルール、チェックの実行方法、リリースの手順については、CONTRIBUTING.mdをご覧ください。今後の予定はROADMAP.mdに記載されています。調査項目とオーナーのアカウントに関する対応待ちの項目（PyPI、エディター拡張機能のマーケットプレイス、署名済み Desktop バンドル、Glama への掲載）をご確認ください。

ライセンス

MIT © gAI Ventures