はじめに
Claude Code などの AI エージェントに URL を読ませると、ページのナビゲーション・広告・フッター・スクリプトタグといった「読んでも意味のないノイズ」がコンテキストを大量に消費します。
「docs ページを 1 つ読ませるだけで 40,000 トークン消えた」といった体験が続いたため、AIエージェントが URL を読む前に呼ぶ前処理 CLI「ctxpack」 を作りました。
– ctxpack が何をするツールか（機能・デモ・インストール方法）
– ノイズ除去の仕組み（コンテンツフィルタリング・クエリマッチング）
– Claude Code の CLAUDE.md での実際の活用パターン
作ったもの
ctxpack は、Web ページや HTML/Markdown を受け取り、ノイズを取り除いたコンパクトな Markdown または JSON を返す CLI です。
ctxpack https://example.com/docs
ctxpack https://example.com/docs --query "pricing and limits" --json
ctxpack stats以下のような変換をパイプラインで行います。
URL / HTML / Markdown
→ ページのクロームを除去
→ 読めるテキストを抽出
→ タスク関連セクションを先頭に移動（--query 指定時）
→ コンパクトな Markdown または JSON を返す
→ 節約したトークン数を記録インストール
brew install atani/tap/ctxpackソースからビルドする場合は以下の手順です。
git clone https://github.com/atani/ctxpack.git
cd ctxpack
uv tool install .基本的な使い方
URL を渡す
ctxpack https://example.com/docs --stats--stats を付けると、Markdown 出力の末尾にトークン節約量が表示されます。
Raw input: 42,100 tokens
Clean text: 7,800 tokens
Final: 7,800 tokens
Saved: 34,300 tokens
Reduction: 81.5%ローカルファイルや stdin も使える
ctxpack ./page.html
cat page.md | ctxpack -SOURCE には URL のほか、ローカルの HTML/Markdown ファイルパスや -（stdin）が使えます。
–query でタスク関連セクションを先頭に
ctxpack https://example.com/docs --query "pricing and limits"キーワードが本文・見出しに含まれるセクションを先頭に並べ替えます。全コンテンツを捨てずに「最も関係するところから読む」形になるため、LLM の読み取り精度も上がります。
エージェント向けの JSON 出力
ctxpack https://example.com/docs --jsonツール呼び出し結果として使いやすい構造化 JSON を返します。
{
"ok": true,
"source": { "url": "https://example.com/docs", "fetched_at": "..." },
"title": "Example Docs",
"content": { "format": "markdown", "text": "..." },
"stats": {
"raw_html_tokens": 42100,
"clean_text_tokens": 7800,
"final_tokens": 7800,
"saved_tokens": 34300,
"reduction_percent": 81.5
}
}累計節約量を確認する
すべての通常実行は ~/.ctxpack/stats.jsonl に記録されます。
ctxpack statsRuns: 24
Raw input: 1,024,000 tokens
Clean text: 181,200 tokens
Final: 181,200 tokens
Saved: 842,800 tokens
Reduction: 82.3%ctxpack reset --yes で履歴をリセット、--no-record で 1 回の実行を記録対象から除外できます。
仕組み
ノイズ除去
ctxpack は HTML を受け取ると、以下の要素をテキスト抽出の前に除去します。
- タグごと削除:
<script>、<style>、<noscript>、<svg>、<canvas>、<iframe> - 構造要素を削除:
<nav>、<footer>、<aside> - クラス/ID/role でキーワードマッチ:
ad、banner、breadcrumb、cookie、header、menu、modal、nav、sidebar、socialなど
マッチングはキーワード単位で行われます。site-nav-primary は nav としてノイズ扱いになりますが、navigation はそのままです。
トークン推定
トークン数は高速なモデル非依存の近似値で計算します。
- CJK 文字（ひらがな・カタカナ・CJK 統合漢字）: 1 文字 ≒ 0.8 トークン
- その他の文字: 4 文字 ≒ 1 トークン
特定モデルの正確なトークン数とは異なりますが、節約効果の相対比較には十分な精度です。
クエリマッチング
--query を指定すると、セクションごとにスコアを計算してソートします。
- 本文中のマッチ: +2 点
- セクションの見出しにマッチ: +3 点追加
- スコア降順でソート、同点は元の順番を維持
Claude Code での使い方
自分の Claude Code グローバル設定（CLAUDE.md）に以下を書いています。
## URL 読み込み（ctxpack）
WebFetch / curl で URL 本文を読む前に `ctxpack <url> --json` でパックしてトークンを節約する。
ctxpack はページの chrome を除去し、`--query "<タスク>"` で関連セクションを先頭に寄せる。
記事 / docs 系ページで 7 割前後のトークン削減が見込める。この一文を入れておくだけで、Claude Code はドキュメントや記事 URL に対して ctxpack 経由の読み取りを選ぶようになります。
制限事項
ctxpack 0.1 は静的 HTML/Markdown を対象としています。現時点では以下は対象外です。
- JavaScript レンダリングが必要なページ（SPA・遅延ロードコンテンツ）
- 強力なボット対策・CAPTCHA 付きページ
- ログイン必須コンテンツ
- PDF・DOCX 等のバイナリフォーマット（あらかじめ HTML/Markdown に変換してから使う）
おわりに
ctxpack は「エージェントが URL を読む前にかます前処理」として作ったツールです。
80% 前後のトークン削減は体感でも大きく、長い docs ページを複数読ませるセッションでは特に効きます。Claude Code のような対話型エージェントだけでなく、ツール呼び出しの JSON レスポンスとしても使えるため、カスタムエージェントの実装にも組み込めます。
フィードバックや PR はリポジトリまでどうぞ。
コメント