skimread

skimread — 読む前にざっと確認

AI コーディングエージェント向けのロスレスなコンテキストガードです。 依存関係ゼロで、すべてローカルマシン上で動作し、MIT ライセンスです。Claude Code ではすぐに利用でき、CLI と MCP サーバーを通じて、ほかのエージェント（Codex、Cursor、Aider、Copilot、自作のもの）でも利用できます。

これは何ですか？

AI コーディングエージェントを使うと、エージェントが読み取るトークンのすべてに料金が発生します。その費用の大半は、エージェントが実際には必要としていない次の2つに使われています。

1. 大きなファイルを丸ごと読むこと。 エージェントは1つの関数を探すために、ファイルの2,000行すべてを読み込みます。次のセッションでも、また同じことを繰り返します。
2. ノイズの多いコマンド出力を読むこと。 pytest -v は2件の失敗を知らせるために、1,500行の PASSED を出力します。npm install は非推奨に関する警告を40件出力します。cargo build はコンパイルしたすべてのクレートを列挙します。

skimread はエージェントとこの2つの情報源の間に入り、まずエージェントに概要を渡します。

• ファイルの場合：ファイルの代わりにアウトラインを提示します。 エージェントが大きなファイルを読み込もうとすると、skimread はファイルのマップ（関数、クラス、見出し、キーと、それぞれの行範囲）を渡し、「必要な部分だけを読み込む」よう伝えます。これにより、エージェントが読むのは2,000行ではなく60行になります。
• コマンドの場合：出力全体の代わりにダイジェストを提示します。 ノイズの多いコマンドは skimread 経由で実行されます。エージェントにはエラー、失敗したテスト、自分のコード内のスタックフレーム、サマリー行が表示されます。1,500行の PASSED は、成功したことを示す1行にまとめられます。

重要なキーワードはロスレスです。何も破棄されません。すべてのコマンドの全出力がディスクに保存され、すべてのダイジェストの末尾には参照用のコマンド（skimread show 42、skimread show 42 120-180、skimread show 42 --grep TypeError）が付いています。すべてのアウトラインには、次に読み込むべき行範囲が正確に示されます。エージェントが行き詰まることはなく、見落とした内容を確認するためにビルドを再実行する必要もありません。

既存の出力圧縮ツールではだめなのですか？

シェル出力を圧縮するツールはすでに存在します（RTK、token-saver、condense）。これらには共通する制約が2つあります。エージェント自身のファイル読み込みツールには介入できませんが、ここがトークンを最も消費する部分です。また、ロスのある圧縮です。エージェントが必要とする1行を圧縮ツールが削除すると、エージェントはコマンドを再実行します。実際、独立したベンチマークでは、圧縮しない場合よりもコストが高くなることがあると報告されています。skimread はファイルの読み込みもガードし、すべての情報を後から取得できるように保持します。

対象ではないもの

• クラウドサービスではありません。ネットワーク通信、アカウント、テレメトリーはありません。状態はすべて ~/.skimread に保存されます。
• LLM ではありません。すべて決定論的な解析と折りたたみ処理なので、ミリ秒単位で動作し、費用もかかりません。
• 推測する要約ツールではありません。行を書き換えることはなく、名前と数を特定できる行を隠し、それらを取り戻す方法を伝えるだけです。

数値

実際のツール出力で測定しています（フィクスチャは tests/fixtures にあります。python bench/bench.py で再現できます）。トークン数は推定値です（文字数 ÷ 3.6）。

コマンド出力	行数	入力トークン数	出力トークン数	削減率
pytest -v（1,504 テスト、2 件失敗）	1546	33,876	473	99%
vitest --reporter=verbose（579 テスト、3 件失敗）	653	7,751	698	91%
pytest（65 テスト、3 件失敗、警告 60 件）	294	3,451	496	86%
npm install（649 パッケージ、非推奨警告 23 件）	41	1,048	204	81%
cargo build（37 クレート、警告 3 件）	61	559	254	55%
go test -v（1 件失敗、1 件パニック）	35	301	137	54%
tsc（8 ファイルでエラー 48 件）	48	1,087	628	42%
cargo test（1 件失敗、バックトレースあり）	68	713	487	32%
cargo build（エラー 2 件）	39	408	411	-1%
vitest（13 ファイル、3 件失敗）	76	613	628	-2%

最後の 2 行が重要です。出力がすでに情報だけ（エラー 2 件の短いビルド）なら、skimread は手を加えません。削減されるのはノイズであり、失敗を隠すことはありません。

読み取ったファイル	行数	全体を読み取る場合（トークン数）	アウトライン（トークン数）	エージェントがその後 60 行分を読む場合の削減率
skimread/outline.py	598	7,648	477	84%
skimread/formats.py	463	4,961	569	76%
skimread/cli.py	368	4,086	357	75%

4,063 行の Go ファイル（net/http/server.go、約 36k トークン）は、構造体とメソッドを行範囲とともに示す約 600 トークンのマップになります。skimread stats を実行すると、これまでに節約できた量をトークン数と金額で確認できます。

使い方

1. インストール（30 秒）

Python 3.9 以降が必要です。それ以外は不要です。

pipx install skimread          # recommended: isolated, on your PATH
# or: uv tool install skimread
# or, inside any Python environment: pip install skimread
skimread --version

GitHub から最新の開発版を直接インストールする場合：pipx install git+https://github.com/avikchakraborty060-create/The-top-innovation。

skimread が保存するデータはすべて ~/.skimread に、所有者のみがアクセスできる権限で保存され、7 日後または 300 回実行後に削除されます。

2. Claude Code：コマンド 1 つ

skimread setup claude            # global: ~/.claude/settings.json
skimread setup claude --project  # or per project: .claude/settings.json

Claude Code を再起動します。これで完了です。以降は次のようになります。

• Claude が行範囲を指定せずに 400 行超（または 16 KB 超）のファイルを Read しようとすると、アウトラインと、代わりに範囲を指定して読むよう指示する内容が返されます。範囲を指定した読み取りは常に許可されます。Claude がセッション中に同じファイル全体を再度要求した場合はファイルが返されるため、行き詰まることはありません。
• Claude がノイズの多いことで知られるコマンド（npm、pytest、cargo、go、tsc、docker、git diff、find など約 100 種類）を実行すると、そのコマンドは skimread run 経由で実行されるように書き換えられます。Claude に表示されるのは要約とハンドルです。権限ルール Bash(<path-to-skimread>:*) が追加されるため、確認プロンプトが増えることはありません。

2,014 行のファイルの代わりに Claude に表示される内容は次のとおりです。

skimread: src/server.py is 2,014 lines (~20k tokens). Read only the part you need: call Read again
with offset and limit chosen from this outline. Any Read that sets offset or limit is allowed; ...
Outline: 2,014 lines, ~20k tokens (python)
      1-38  imports 12 import statements
    41-118  class Config
    44-58     def __init__(self, path: str) -> None
    61-90     def load(self) -> dict
   121-410  class Server(Base)
   123-140    def __init__(self, cfg: Config)
   142-229    def handle_request(self, req: Request) -> Response
   ...

1,504 件のテストスイートで pytest -v を実行した後、Claude に表示される内容は次のとおりです。

$ pytest -v test_many.py  ·  exit 1 in 1.2s
============================= test session starts ==============================
  (1502 passing/skipped tests hidden)
test_many.py::test_some_fail[1] FAILED                                   [ 99%]
test_many.py::test_some_fail[3] FAILED                                   [100%]
=================================== FAILURES ===================================
______________________________ test_some_fail[1] _______________________________
...
E       AssertionError: role mismatch for user 1
E       assert 'dev' == 'ops'
test_many.py:10: AssertionError
=========================== short test summary info ============================
FAILED test_many.py::test_some_fail[1] - AssertionError: role mismatch for user 1
FAILED test_many.py::test_some_fail[3] - AssertionError: role mismatch for user 3
======================== 2 failed, 1502 passed in 0.98s ========================
[skimread #42: 1546 lines, ~34k tok → 473. Full/slice/search: skimread show 42 [A-B | --grep RE]]

調整方法：

skimread setup claude --wrap all     # route every safe Bash command through skimread
skimread setup claude --wrap off     # Read guard only, leave Bash alone
skimread setup claude --uninstall    # remove the hook and the permission rule
skimread config read_threshold_lines 600   # guard only files longer than this (default 400)
skimread config budget 4000                # digest size in characters (default 6000)
skimread setup print                       # just print the settings.json snippet to paste yourself

安全性：Bash ラッパーは、シェルの状態を変更するコマンド（最後の cd、export、source）、ファイルへのリダイレクト、バックグラウンド実行、対話的に見えるコマンド、破壊的または特権を要するコマンド（rm、sudo、git push、git commit、curl | sh など）には一切触れません。これらは、通常の権限ルールのもと、Claude が記述したとおりに実行されます。先頭の cd dir && … は作業ディレクトリが変わるよう、ラッパーの外に維持されます。

3. Codex、Cursor、Aider、Copilot、または独自のエージェント

シェルコマンドを実行できるエージェントなら、CLI 経由で skimread を利用できます。エージェントのルールファイル（AGENTS.md、.cursorrules、システムプロンプト）に次の内容を追加してください。skimread setup agents を実行すると、そのまま使えるスニペットが出力されます。

skimread outline src/server.py           # map of the file with line ranges
skimread read src/server.py 142-229      # numbered slice
skimread run -c "npm test"               # digest + handle   (shorthand: skimread npm test)
skimread show 42                         # full stored output
skimread show 42 300-360                 # slice
skimread show 42 --grep "Error" -C 3     # search with context
skimread list                            # recent runs

MCP を話すエージェントは、代わりにサーバーとして利用できます。skimread mcp は run、show、outline、read、list ツールを備えた stdio MCP サーバーです。skimread setup mcp を実行すると、mcpServers 用の設定ブロックが出力されます。標準入力からの入力も利用できます：cmd 2>&1 | skimread pipe --cmd "cmd"。

4. 節約できた量を確認する

skimread stats                 # tokens and dollars saved, all time, by format
skimread stats --price 15      # use your model's input price per million tokens
skimread stats --json

仕組み

1. 正規化。 ANSI カラーとカーソルコードを取り除き、\r の進捗バーは最終状態に解決し、バックスペースを適用します。
2. 形式に応じた削減。 pytest、jest/vitest/mocha、cargo、go、npm/yarn/pnpm/bun、pip/uv/poetry、docker、tsc、git diff、ファイル／一覧表示コマンド用のリデューサーは、判断材料にならない部分だけを削除します。具体的には、PASSED の行、Compiling の行、非推奨警告（件数は記録）、標準ライブラリのスタックフレームです。それ以外はすべて残します。不明なツールには汎用処理を適用し、進捗のノイズを取り除き、完全一致する重複をカウントし（line (x5)）、類似した行が続く場合はまとめます（… 847 similar lines (159-1005) …）。
3. スコア付けと予算。 行にスコアを付けます（エラーとスタックフレームは高く、概要は中程度）。削減後も出力が予算を超える場合は、先頭、末尾、最も高いスコアの行の周辺を残し、削除箇所ごとに … [768 lines omitted (45-812) — skimread show 42 45-812] … に置き換えます。
4. スプール。 ダイジェストを生成する前に、正規化した出力全体を ~/.skimread/out/<id>.txt に書き込みます。これにより、フッターのハンドルが常に機能します。
5. アウトライン。 Python は ast モジュールを使用します（正確なシグネチャと範囲）。JS/TS、Go、Rust、Java/Kotlin/C#/Swift、C/C++、PHP、CSS は宣言用正規表現と波括弧の対応付け、Ruby/Elixir/Lua はインデントを使用します。Markdown の見出し、JSON/YAML/TOML のキー、CSV の構造、ログファイル（時間範囲、エラー行番号）、Makefile、シェル関数、SQL 文にも対応します。巨大なファイルでは、メンバーを親にまとめ、不完全な内容を完全であるかのように見せるのではなく、注記を付けて切り詰めます。

正直な制限事項

• トークン数はトークナイザーの出力ではなく、文字数を 3.6 で割った推定値です。重要なのは比率であり、比率には影響しません。
• 波括弧を使う言語のアウトラインは正規表現ベースです。正確さではなく、ナビゲーションを目的としています。特殊な書式ではシンボルを検出できないことがあります。Grep は引き続き使用できます。
• 閾値を少し超えるファイルでは、Read ガードによってツールの往復が 1 回増えます。デフォルト値（400 行）は、アウトラインと一部の内容を合わせてもファイル全体より大幅に軽くなるように設定されています。エージェントがファイル全体を必要とすることが多い場合は、値を引き上げてください。
• Bash ラッパーは、子プロセス内で bash -c を使ってコマンドを実行します。Claude Code の永続シェルで定義されたシェル関数とエイリアスは認識されません（環境変数と作業ディレクトリは引き継がれます）。
• エージェントのネイティブな Read をインターセプトするフックを備えているのは Claude Code だけです。それ以外のエージェントも、CLI/MCP ツールとルールファイル内の指示を通じて同じ機能を利用できます。

開発

git clone https://github.com/avikchakraborty060-create/The-top-innovation && cd The-top-innovation
pip install -e ".[dev]"
python -m pytest -q          # 68 tests, < 1 s
python bench/bench.py        # the tables above

形式を追加するには、skimread/formats.py にノイズ行を削除またはまとめてスコアを設定する reduce_<tool>() を記述し、detect() に登録して、実際の出力サンプルを tests/fixtures に追加し、残すべき内容を示す行を tests/test_formats.py に追加します。言語を追加するには、skimread/outline.py にパターンリストを追加します。

実際の環境で得られたフィクスチャの提供が、最も価値のある貢献です。リデューサーの品質は、これまでに参照した出力の質に左右されます。

ライセンス

MIT。