skim-mcp

skim

エージェント型モデル（Claude Code / デスクトップ版 Claude）向けの、トークン効率に優れた ざっと確認してから展開する I/O です。

独立したコミュニティプロジェクトです。Anthropic との提携、推奨、後援はありません。 テレメトリはなく、すべてお使いのマシン上で実行されます。商標、プライバシー、ライセンスをご覧ください。

大きなファイル全体をコンテキストに読み込む代わりに、モデルは skim_open(path) を呼び出して、構造、シグネチャ、（ログ／データの場合は）ID、数値、日付、エラーコードなどの重要な値を保持したコンパクトな 骨格 と、アンカー ID を取得します。まず骨格を低コストで読み、その後 skim_expand(handle, anchors=[...]) を呼び出して、必要な範囲だけを 原文のまま、欠落なく 取得します。

圧縮は 遅延型 であり、情報を失いません。言い換えたり破棄したりするのではなく、表示を先送りするだけです。展開はいつでも 1 回の呼び出しで行えるため、潜在ベクトルを取り込めないクローズドモデルでも安全に使えます。

ほかのツールにはない機能

主流のツールは コンテキスト内で情報を失います。repo-map や --compress は関数本体を削除し、要約ツールや圧縮モデルは言い換えます。最も近い類似ツールも、コードのみを対象とするか、モデルに 変換後 のビューを見せ、元の内容をサイドキャッシュに保持します。skim の方針はより厳格です。コンテキストに含まれる内容はすべて原文のままであり、表示されない内容もアンカーを指定すれば 1 回の展開で取得できます。そのため、エージェントは読み直さずに、読んだ内容に基づいてコードを編集できます。これは次のすべてで成り立ちます。

• ファイル — Python（ast）と約 17 言語（tree-sitter）に対応。関数本体は折りたたまれ、1 回の expand で取得できます。
• リポジトリ全体 — skim_repo が順位付けされた、トークン予算内のマップを作成します。任意のファイルから正確なコードを展開できます。
• コマンド出力 — skim_run が冗長なテスト／ビルド／ログ出力を圧縮し、完全に復元可能な状態にします。
• データとログ — 保持保証付きの汎用パスです（ID、数値、エラーコード、否定表現は骨格に昇格され、黙って削除されることはありません）。また、繰り返されるブロックを重複排除します。

アーキテクチャと、検証済みの先行事例との位置付けについては、DESIGN.mdをご覧ください。

検証可能であり、単に主張するだけではありません

削減率は、確認できなければマーケティングにすぎません。skim には検証ツールが付属しています。

uv run skim-verify path/to/your/gnarliest_file.py     # any file at all; exit code tells CI

5 つの不変条件を、お使いのファイルでローカルに検証します。空行以外のすべての行を復元できること、展開結果がバイト単位で完全一致すること、アンカーが範囲内にあること、再構成結果がデコード済みファイルと一致すること、出力が決定的であることです。テストスイートでは、すべてのパスに対する Hypothesis ファジングで同じ契約を確認しています。読み取り可能なファイルで再現可能な FAIL が発生した場合はバグです。ぜひ報告してください。要約優先のツールでは、同等のチェックが設計上失敗するため、このコマンドを提供できません。

コストと正確性のトレードオフを評価するため、独立して参照できる基準も用意しています。eval/ACCURACY.mdでは、すべての評価問題について、全文読み込みと skim のコストを算出しています（skim が 劣る 行も含みます）。ほかのコンテキストツールも、同じプロトコルで評価できます。

監査しやすい設計

• パッケージ全体で標準ライブラリの Python が 2,000 行未満（読み取りエンジンは約 1,200 行）です。ダウンロードが必要な ML モデルも、フレームワークも、テレメトリーもありません。依存関係は 1 つ（mcp。tiktoken／tree-sitter の追加依存関係は任意）だけです。すべてを半日でセキュリティレビューできます。SECURITY.md に脅威モデルを記載しています。
• 読み取り専用でないすべての機能にキルスイッチを用意しています。 SKIM_RUN_DISABLED=1 でシェルツールを無効化し、SKIM_PATCH_DISABLED=1 でファイルエディターを無効化できます。読み取り機能は引き続き動作します。
• Windows を移植先ではなく、第一級のプラットフォームとしてサポートしています。 コマンド出力は UTF-8 でデコードし（cp1252 による文字化けを防止）、タイムアウト時にはプロセスツリーを実際に終了し（taskkill /F /T）、skim_patch では CRLF を保持します。また、CI では Ubuntu と並行して windows-latest でも全テストスイートを実行します。

コア機能を試す（インストール不要）

python demo.py path/to/file.py            # measured before/after token counts
python demo.py                            # demo on examples/sample.log (retention + dedup)

結果（実測データ）

以下の数値はすべて uv run python benchmarks.py によって実行時に生成されます。再現可能な全表は BENCHMARKS.md にあります。稼働中のインタープリターの標準ライブラリを使って測定しています（実際のコード）。トークン数は tiktoken の cl100k_base で計測しています（Claude のトークナイザーの代替指標であり、比率はトークナイザーに左右されません）。

実際のコードでのトークン削減 — Python 標準ライブラリの 60 ファイルで、387,911 → 122,660 トークン（68%削減、3.16 倍）。 ファイルごとに 1.5～11 倍、100% ロスレスで決定的に動作します。実行時間はほぼ線形（1,000 行あたり約 4 ミリ秒）です。CPU のみで動作し、GPU、ネットワーク、モデル呼び出しは不要です。

マルチ言語（tree-sitter、[lang] 追加依存関係） — JS／TS／Go／Rust／Java／C／C++／Ruby／PHP／C# などで、同じロスレスエンジンを使用できます。例：481 行の JavaScript モジュールで 6.6 倍／85%削減、ロスレスです。

実際のタスクにおける 1 対 1 の前後比較（分布全体） — 「このモジュール内で最も大きな関数を読む」。 モデルがファイルを開いてスケルトンを読み、必要な関数だけを展開します。同じ答えを得るための、スキムの全コスト（スケルトン＋展開）を計上した結果です。24 個の大規模モジュールで測定しています。

file	lines	function read	full read	skim (skeleton+expand)	saved
tarfile.py	3,032	_proc_pax（119 行）	25,180	8,906	65%
optparse.py	1,682	parse_args（37）	12,830	5,610	56%
pathlib.py	1,436	walk（43）	11,242	5,421	52%
bdb.py	921	effective（48）	7,279	3,243	55%
socketserver.py	864	serve_forever（27）	5,824	3,615	38%
24-file total			176,897	71,877	59%

タスクごとの削減率は、24 タスクで**中央値 51%、平均 51%、範囲 30～91%**です。都合のよいベストケースではなく、実際の分布を示しています。ファイルの大部分を読む必要がある場合、効果は小さくなります。

直接比較 — 同じ 30 ファイル（compare.py ＋ npx で実行した実際の Repomix）：

approach	tokens	% of full	lossless?
全文読み取り（Claude Read）	184,277	100%	はい
skim	64,043	34.8%	はい（遅延展開）
Repomix --compress	105,963	57.5%	いいえ（本文を削除）
シグネチャのみ（Aider／Basemind の方式）	20,276	11.0%	いいえ

skim は唯一のロスレスな選択肢であり、Repomix の --compress よりトークン数を 40% 削減します。リポジトリマップ方式は約 3 分の 1 のサイズですが、本文／docstring／コメントを復元不能な形で破棄します。（Basemind は純粋な Rust 製で、インストールされていませんでした。その行はシグネチャのみの方式を再現したものです。COMPARISON.md を参照してください。）

正確性： 80 ファイルの空白でない 54,215 行のうち、復元不能な行は 0 行です。Hypothesis による両方の経路のプロパティベース・ファジングを含む 202 件のテストと、約 80% のカバレッジを達成しています。約 18,000 件の敵対的ケースを用いたテストキャンペーンを実施済みです（発見したバグはすべて修正し、回帰テストで検証しています）。再現するには、uv run python bench.py／pytest／benchmarks.py を実行してください。

MCP サーバーとして実行する

1 行で実行できます（初回実行時に PyPI からインストールされ、tree-sitter 言語も含まれます）。

claude mcp add skim -- uvx --from "skim-mcp[lang,tokens]" skim-mcp

または、ソースから実行します。

git clone https://github.com/helloderekg/skim-mcp.git && cd skim-mcp
uv sync --extra lang                       # MCP SDK + multi-language (tree-sitter); drop --extra lang for Python-only

Claude Code に登録します（リポジトリの絶対パスを使用してください。Windows ではスラッシュも使えます）。

claude mcp add skim -- uv run --directory /abs/path/to/skim-mcp skim-mcp

または Claude Desktop の場合は、claude_desktop_config.json に追加し（Windows では %APPDATA%\Claude\、macOS では ~/Library/Application Support/Claude/）、再起動します。

{
  "mcpServers": {
    "skim": {
      "command": "uv",
      "args": ["run", "--directory", "/abs/path/to/skim-mcp", "skim-mcp"]
    }
  }
}

（uv が見つからない場合は、where uv / which uv で確認できるフルパスを使用してください。）

ツール

• skim_open(path, query="") → 簡潔な骨格とアンカー ID（骨格を読みます。ID は expand("aN") マーカーに記載されています）。query を渡すと、同じ呼び出しで matches（行と該当範囲を含むアンカー）も取得でき、検索を別途行う必要がありません。
• skim_expand(handle, anchors=[...]) → 正確な原文の範囲を取得します。項目にはアンカー ID（"a7"）または、grep ですでに行番号がわかっている場合に使うリテラルの行範囲（"L120-180"）を指定します。
• skim_search(handle, query) → 文字列を含むアンカー／行を、内容を読まずに特定します。
• skim_run(command) → シェルコマンドを実行し、出力を展開可能な簡潔なビューで取得します（テスト／ビルド／ログ）。
• skim_repo(path, query) → リポジトリ全体の情報を、内容を損なわずに、順位付けし、トークン予算内で取得します。任意のファイルから正確なコードを展開できます。クエリを渡すとクエリとの一致度で順位付けされ、渡さない場合は インポートグラフの中心性（どのファイルがどのファイルをインポートするかに基づく PageRank）で順位付けされるため、基幹となるモジュールが最初に表示されます。
• skim_patch(handle, anchor, new_text) → 展開した範囲を ディスク上で 正確に 1 つ置き換えます。変更が安全に検出されるよう、skim_open 以降にファイルが変更されていた場合は拒否され、LF／CRLF は維持され、結果はディスクから再検証され、新しいハンドルが返されます。展開内容は原文そのままなので、それをもとにした編集は安全に適用できます。ファイルの 8% を読んで、残りを編集できます。 （SKIM_PATCH_DISABLED=1 で無効になります。）
• 範囲は MCP リソースとしても利用できます。@skim:skim://doc/<handle>/span/<anchor> を指定すると、参照先の範囲を取得できます。

実際の使用例

ほとんど読む必要のない大きなモジュールのバグを修正する。 タスクは「tarfile.py（3,032 行、25,180 トークン）で _proc_pax が pax ヘッダーを誤って処理するのはなぜか？」です。Claude は skim_open を呼び出し、すべてのシグネチャを含む骨格を読み、_proc_pax を見つけ、そのアンカー 1 つを展開して、正確な 119 行の本体をもとに回答します。測定コストは、骨格と展開を含めて 8,906 トークンです。同じ回答を、トークン数を 65% 削減して得られます（ベンチマーク表を参照してください。24 件の同様のタスクの中央値は 51% です）。

初めて見るリポジトリの全体像を把握する。 skim_repo(".", query="rate limit") は、最も関連性の高いファイルの骨格を順位付けし、1 つのトークン予算内で、それぞれ固有のハンドルとともに返します。Claude はマップを読み、異なる 2 つのファイルから重要な 2 つの関数を展開して編集を開始します。リポジトリの残りはまだ読んでいませんが、必要に応じて参照できます。

ノイズが 400 行ある赤い CI 実行結果。 skim_run("pytest -q") は終了コードと簡潔なビューを返します。繰り返しの定型文は「a3 と同一」というポインターにまとめられ、保持レイヤーは重要なリテラル（エラーコード、ファイルパス、件数）を表示するため、何も展開しなくても失敗内容がわかります。Claude が完全なトレースバックを必要とする場合は、そのブロックだけを展開します。

skim を使わないほうがよい場合（正直に言うと）。 40 行の設定ファイルや、まるごと書き換える予定のファイルなら、そのまま読みましょう。小さな入力では骨格のラッパーのほうが節約量より大きく、メーターにはそうした行が隠されず、マイナスとして表示されます。skim のメリットが得られるのは、2,000 行の中から必要な 40 行を探すような、日常的なケースです。

Claude に skim を使わせる

skim をマウントするとツールが利用可能になりますが、Claude がそれを使うようになるわけではありません。 Claude はタスクごとにツールを選び、「このファイルを読んでレビューして」という依頼には、skim_open ではなく組み込みの Read をデフォルトで使います。小型モデル（Haiku など）は、MCP ツールを自分から使う可能性が特に低くなります。そのため、skim がトークンを節約するのは、実際に呼び出されたときだけです。呼び出してもらう方法は 2 つあります。

1. タスクごとに依頼する：

skim を使って src/big_module.py をレビューしてください 作業を始める前に skim_repo でこのリポジトリの構成を把握してください skim_run を使ってテストを実行してください

2. 自動化する — CLAUDE.md にルールを追加する（プロジェクト用、またはグローバルの ~/.claude/CLAUDE.md）ことで、毎回リマインドしなくても Claude が skim を使うようにします。

When the skim MCP tools are available, prefer skim_open (files) and skim_repo (directories/repos) over
the built-in Read for anything larger than ~300 lines, and skim_run for verbose command output. Expand
only the spans you need — skim is lossless, so skimming first is never risky, only cheaper.

skim はモデル向けに「skim を優先する」という指示も提供しますが、モデルがサーバーレベルの指示に確実に従うとは限りません。特に小型モデルでは、しっかり効くのは CLAUDE.md のルールです。いつでも設定を確認できます。セッションで 「skim を使って<a big file>を開いて」 と伝え、メーターが動くか確認してください。

または、登録とルール設定の両方を、skim に 1 つの冪等なコマンドで実行させることもできます。

uv run skim-mcp install                              # from a source checkout (project ./CLAUDE.md rule)
uvx --from "skim-mcp[lang,tokens]" skim-mcp install  # from PyPI
skim-mcp install --rule global                       # write the rule to ~/.claude/CLAUDE.md instead
skim-mcp install --print-only                        # show what it would do, change nothing

再実行してもルールは重複しません。claude CLI が PATH にない場合は、手動で実行するための正確なコマンドと Claude Desktop 用の JSON が出力されます。

節約量をリアルタイムで確認する

skim をマウントし、2 つ目のターミナルでメーターを実行します。ローカルホスト上で動作する小さなダッシュボード（標準ライブラリのみを使用し、ネットワークも依存関係も不要）で、サーバーが書き込むものと同じ skim_calls.jsonl を読み込み、1 秒ごとに更新します。

uv run skim-meter                        # -> http://127.0.0.1:17321
uv run skim-meter --once                 # one-shot text snapshot instead of the web view
uv run skim-meter --price-per-mtok 3     # optional: also show ~dollars saved at YOUR rate

リアルタイムで表示される内容：入力トークン数（これらのファイルを読んだり、コマンドをそのまま実行したりした場合にかかったトークン数）、出力トークン数（skim が実際にコンテキストに加えたトークン数。スケルトンに加え、すべての展開・検索を含む）、節約率（1 - out/in）、セッション別の内訳です。実際の数値を正直に示します。展開によって節約率は下がり、小さな出力に対する skim_run では、差し引きで節約量がマイナスになることさえあります。

セッション別： skim サーバーの各プロセスは、すべての呼び出しにセッション ID を付与します。また、Claude Code はセッションごとに 1 つのプロセスを起動するため、ダッシュボードには skim をまだ使っていないセッションも含め、すべてのセッションが最終アクティビティ順に表示されます。各行には、SKIM_SESSION_LABEL を設定している場合はその値、設定していない場合はそのセッションが最初に触れたファイル／リポジトリ（それもない場合は idle）が表示され、さらに開始時刻と短縮 ID も表示されるため、セッションを区別できます。Clear ボタン（または skim-meter --clear）を押すと、ログがタイムスタンプ付きの ghost ファイルにアーカイブされ、メーターがゼロにリセットされます。データは失われません。（MCP は、呼び出しを発行したサブエージェントをサーバーに伝えないため、サーバー側で可能な最も細かな区分は、接続／セッション単位です。）

テスト

uv sync --extra dev
uv run pytest                  # unit + property-based fuzzing of the invariants (202 tests, ~80% coverage)
uv run python bench.py         # invariant sweep + compression over the standard library
uv run python check_invariant.py <file>   # check one file against the invariants

このテストスイートは、手書きのエッジケース、実際の標準ライブラリ、コードと汎用パスの両方に対する Hypothesis のファジングを通じて、どのような入力に対しても 6 つの不変条件を検証します。すなわち、情報の欠落がないこと、ラウンドトリップで完全に一致すること、復元結果が完全に一致すること（full_text がデコードされたファイルとバイト単位で一致すること）、範囲内であること、決定論的であること、クラッシュしないことです。

展開ループを自分で測定してみましょう： eval/QUESTIONS.md は、取得不足を評価する 7 つの質問で構成されています（すべての回答はアンカーの背後に隠され、テストで固定されています）。uv run python eval/score_expand_loop.py を実行すると、実際のセッションのログを基に採点できます。また、eval/ACCURACY.md では各質問のコスト（全体を読む場合と skim を使う場合。マイナス分も含む）を算出します。これは、ほかのコンテキストツールにも実行を呼びかけている、精度とコストを比較するための基準です。

制限事項（正直に）

• コードスケルトンは Python（ast）と、tree-sitter 経由の約 17 言語に対応しています — JS、TS、Go、Rust、Java、C、 C++、Ruby、PHP、C#、Kotlin、Swift、Scala、Bash、Lua、R です。省略可能な [lang] エクストラをインストールしてください。それ以外のテキストは、 汎用（ロスレス）ブロックパスにフォールバックします。残り約 300 の tree-sitter 文法への対応は段階的に進めます（各言語の折りたたみは、 リリース前に実際のパース結果で検証します）。
• 密度の高い反復ログには Drain 形式のテンプレートを適用します（~412x GET /api/<*> took <*>ms）。これにより、スケルトンから何が繰り返されているかが分かります。構造化 JSON／CSV のスケルトンはまだロードマップ上のため、これらの圧縮効果は控えめです。
• モデルが expand を呼び出すことに依存します。 折りたたまれた本文が必要な場面でモデルがスケルトンだけを見て回答すると、誤りになることがあります。誘導ヒントで軽減できます。また、skim_calls.jsonl でその状況を測定できます。
• if／try ブロック内で定義された関数は、シグネチャとして表示されません（それでもロスレスで、展開可能です）。
• skim_run は出力を取得して圧縮するため、マシン上でシェルコマンドを実行します。権限はサーバープロセスと同じで、エージェントの Bash ツールと同じ種類の機能です。エージェントにコマンドを実行させてもよい場所でのみ skim をマウントしてください。プロンプトインジェクションを受けたモデルが破壊的なコマンドを実行する可能性があります。 SKIM_RUN_DISABLED=1 を設定すると、skim は読み取り専用でマウントされます（シェルツールは実行を拒否しますが、リーダーは引き続き動作します）。 詳細な脅威モデルは SECURITY.md をご覧ください。
• ハンドルはサーバープロセスのメモリ上に保持されます。 セッション中は維持されます（Claude Code はセッションごとに skim プロセスを 1 つ実行します）。再起動後に古いハンドルを使うと、明確な unknown handle エラーが返されます。再度開いてください。 ハンドルはコンテンツのハッシュに基づくため、再度開いたファイルの内容が変わっている場合は新しいハンドルが割り当てられ、古いアンカー ID が別の行を指すことはありません。
• 削減効果は使い方によって異なります。 一部だけ読む大きなファイルでは大きく、小さなファイルやファイルの大部分が必要な場合はほとんどありません。トークン数は tiktoken を使用して計測します（Claude のトークナイザーの代替指標です）。比率は安定しています。

ステータスとロードマップ

リリース済み： Python ast と、実際のパース結果で検証済みの多言語 tree-sitter コードスケルトン（約 17 言語）、保持機能と重複排除、密度の高いログ向けの Drain 形式テンプレートを備えた汎用ブロックパス、skim_run（プロセスツリーに安全なタイムアウトを備えた、コマンド／テスト出力のロスレス圧縮）、skim_repo（クエリとの一致度またはインポートグラフの PageRank による順位付けを備えた、リポジトリ全体のロスレスマップ）、MCP リソースとしてのスパン、過少取得評価ハーネス、skim-meter（トークン削減効果をリアルタイムで確認できるダッシュボード） — すべて、厳格なテストスイートで検証されています。

ロードマップ： JSON／CSV 向けの構造化データスケルトン（スキーマ＋値の統計情報）、残りの tree-sitter 言語への対応、過少取得評価によってモデルが回答の質を高める機会を逃していると分かった場合のハイブリッドプッシュモード（関連度ランキング上位のアンカーを自動展開）、および他のコンテキストツールを精度とコストの評価基準で評価するためのランナーアダプターです。

貢献、セキュリティ、変更履歴

CONTRIBUTING.md には、すべての変更で守るべき 5 つの不変条件（ロスレス、完全なラウンドトリップ、範囲内、決定的、クラッシュしない）と、言語を追加する方法が記載されています。 SECURITY.md には脅威モデルと、非公開で報告する方法が記載されています。 CHANGELOG.md にはリリース履歴が記録されています。RELEASING.md にはリリース手順が記載されています。

商標、プライバシー、ライセンス

独立したプロジェクトです。 skim はコミュニティによるオープンソースプロジェクトであり、Anthropic PBC、OpenAI、その他いかなる企業とも提携、承認、支援関係にありません。 「Claude」、「Claude Code」、「Anthropic」は Anthropic, PBC の商標です。「Model Context Protocol」／「MCP」はプロトコルとの互換性を示す記述として使用しています。「Aider」、「Basemind」、「Repomix」はそれぞれの所有者の商標です。これらの標章は識別と比較のみを目的として商標名として使用しており、推奨を意味するものではありません。第三者のロゴは使用していません。

ベンチマーク。 このリポジトリの数値は、文書化された条件（ツールのバージョン、フラグ、コーパス、トークンカウンター、日付）での測定結果であり、公開済みのスクリプトで再現できます。他の条件での結果を保証するものではありません。Aider、Basemind、Repomixとの比較数値は、それぞれの当時の最新公開リリースを使用して算出しました。修正が必要な場合は、issue でお知らせください。

プライバシーとテレメトリー。 skim はすべてお使いのマシン上で動作します。ネットワークリクエストは一切行わず、データの収集、送信、販売も一切ありません。書き込まれるデータは、ローカルの skim_calls.jsonl ログ（skim のツール呼び出し——ファイルパスと範囲アンカー。デバッグ用）だけで、お使いのコンピューターの外に出ることはありません。いつでも削除するか、SKIM_LOG_FILE を設定して保存先を変更できます。ご自身のファイルのパスや抜粋が含まれる場合があるため、ローカルログと同様に取り扱ってください。

ライセンス。 MIT。実行時依存関係の mcp（MIT、© Anthropic PBC）と tiktoken（MIT、© OpenAI）については、NOTICE をご覧ください。開発時のみ使用するテスト依存関係の hypothesis は MPL-2.0 で、変更せずに使用しており、バンドルされることはありません。

mcp-name: io.github.helloderekg/skim-mcp