# CtxPack **AI エージェント向けトークン節約型コンテキスト抽出ツール。** CtxPack は、ノイズの多い Web ページ・HTML・Markdown をエージェントが安全に消費できるコンパクトなコンテキストに変換します。不要なページ要素を除去し、有用な構造を保持しながら、トークン削減量を累積で記録します。 ```bash ctxpack https://example.com/article ctxpack https://example.com/article --query "価格と制限" --json ctxpack stats ctxpack reset --yes ``` ## なぜ CtxPack か AI エージェントはしばしば、ナビゲーション・スクリプト・スタイル・Cookie バナー・フッター・関連リンク・繰り返しの定型文でコンテキストを無駄に消費します。既存の Web-to-Markdown ツールは有用ですが、エージェントにはもう一歩が必要です。**トークンを意識したパッキングと、測定可能な節約量の記録**です。 CtxPack はエージェントが URL を読む前に呼び出すツールとして設計されています。 ```text URL / HTML / Markdown -> ページの不要要素を除去 -> 読みやすいテキストを抽出 -> タスクに関連するセクションを先頭に移動 -> コンパクトな Markdown または構造化 JSON で返却 -> 節約したトークン数を記録 ``` ## 使用例 ```bash ctxpack https://example.com/docs --stats ``` Markdown 出力にはソースのメタデータと、オプションで実行ごとの節約量が含まれます。 ```text Raw input: 42,100 tokens Clean text: 7,800 tokens Final: 7,800 tokens Saved: 34,300 tokens Reduction: 81.5% ``` エージェントからは JSON で使います。 ```bash 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` にローカル記録されます。 ```bash ctxpack stats ``` ```text Runs: 24 Raw input: 1,024,000 tokens Clean text: 181,200 tokens Final: 181,200 tokens Saved: 842,800 tokens Reduction: 82.3% ``` 履歴をリセットする場合。 ```bash ctxpack reset --yes ``` 1 回の実行だけ記録をスキップする場合。 ```bash ctxpack https://example.com --no-record ``` ## インストール ### Homebrew（推奨） ```bash brew install atani/tap/ctxpack ``` ### Windows / winget ```powershell winget install atani.ctxpack ``` Windows 向けの x64/arm64 ZIP 成果物と winget マニフェストはリリースに含まれます。投稿フローと自動更新ジョブは [`packaging/winget/`](packaging/winget/README.md) を参照してください。 ### ソースから ```bash git clone https://github.com/atani/ctxpack.git cd ctxpack go install ./cmd/ctxpack ``` 開発中に実行する場合。 ```bash go run ./cmd/ctxpack https://example.com --stats ``` ### Python 版からの移行 v0.2.x までの ctxpack は Python パッケージでした。CLI（フラグ・サブコマンド・終了コード・JSON スキーマ）と `~/.ctxpack/stats.jsonl` の履歴形式は変わらないため、既存のスクリプトと履歴はそのまま動きます。Python ライブラリ API（`from ctxpack import pack`）は廃止されたので、`pip` / `uv tool install` でインストールしていた場合は上記のいずれかの方法に切り替えてください。 ## CLI リファレンス ```bash ctxpack SOURCE [--query TEXT] [--json] [--stats] [--no-record] [-o FILE] ctxpack run SOURCE [--query TEXT] [--json] [--stats] [--no-record] [-o FILE] ctxpack stats [--json] [--reset] ctxpack reset --yes ``` `SOURCE` に指定できるもの： - `https://...` または `http://...` - ローカルの HTML / Markdown ファイル - 標準入力（`-`） オプション： - `--query TEXT` — タスクに関連するセクションを先頭に移動します。 - `--json` — エージェントの tool call 向けの構造化出力。 - `--stats` — Markdown 出力に実行ごとのトークン削減表を含めます。JSON 出力は常に `stats` を含むため、このフラグは Markdown 出力にのみ影響します。 - `--no-record` — この実行を累積削減量に記録しません。 - `-o FILE` — 出力をファイルに書き込みます。 終了コード： - `0` — 成功。 - `1` — ネットワーク障害やレスポンスサイズ超過などの実行時エラー（リトライ可能）。 - `2` — 使い方エラーや入力ファイルが存在しない（リトライ不可）。 - `3` — 取得したページが JavaScript レンダリングを必要としている（ctxpack 単体ではリトライ不可。[JavaScript レンダリングが必要なページ](#javascript-レンダリングが必要なページ)を参照）。 ## 仕組み ### コンテンツフィルタリング テキスト抽出の前に CtxPack が除去するもの。 - `