Caveman: AIエージェント向けトークン圧縮ツール

1. プロジェクト概要

Cavemanはオープンソースのツールキットであり、Claude Codeスタイルのスキルとローカルプロキシで構成されています。AIコーディングエージェントが読み取るもの（入力）と出力するもの（出力）の両方を圧縮することで、正確なコード、エラー、重要なコンテキストを失うことなく、トークン消費量を削減します。

2. 背景とポジショニング

コアミッション: エージェントによるコーディングセッションが長引くにつれ、コンテキストウィンドウはすぐに埋まり、API料金もそれに伴って上昇します。Cavemanが掲げる「少数で済むのに多数のトークンを使う必要はない」という哲学は、冗長なツール出力、ログ、JSON、差分をオンザフライで縮小し、エージェントが同じ予算内でより多くの作業を行えるようにすると同時に、元のバイト列が常に復元可能であることを保証することです。
2つの補完的なプロダクト: 従来のCavemanスキルは、ターンごとのわずかなオーバーヘッドと引き換えに、エージェント自身の応答を簡潔にします（ベンチマークでは出力トークンが約65%削減されます）。新しいローカルプロキシであるCaveman 2は、プロバイダー宛てのトラフィックをインターセプトし、データがマシンから送信される前に入力を圧縮します（固定ベンチマークでは、プロバイダー報告の入力トークンが33.2%減少すると報告されています）。
類似プロジェクトとの違い: コンテンツの要約や言い換えを試みる（これにより正確なコードやスタックトレースが失われるリスクがあります）のではなく、Cavemanはコンテンツタイプを認識する無損失安全な圧縮を適用します。サイズが厳密に小さくなることが測定された場合にのみ変換を送信し、バイト単位の正確な復元のためにコンテンツアドレス指定されたオリジナルを保持します。また、独自のドキュメント（「Honest Numbers」）において、どの節約効果がローカルで推論されたもので、どれが独立してベンチマークされたものかを明示しています。

3. 機能カテゴリ

🗜️ 圧縮エンジン
エージェントが最も頻繁に扱うコンテンツに対するタイプ対応の圧縮機能：

JSON構造圧縮（キー/構造/エラーツリー） — 典型的には70〜90%の削減
ログ圧縮（エラー、トレース、境界） — 85〜95%
コード圧縮（インポート、シグネチャ、型） — 40〜70%
差分圧縮（ヘッダー、変更行） — 60〜80%
検索結果およびテキスト/HTML圧縮 — 50〜95%
目的：コンテキストトークンを消費する前に、最もノイズが多く反復的なコンテンツタイプを縮小すること。

🖼️ ピクセルモード
高密度のテキスト（バンドルされたツールカタログ、長いログなど）を視覚対応モデル向けにPNG画像としてレンダリングします。文書化された事例の一つでは、約55kのテキストトークンから約11kの画像トークンへと移行し、79%の削減を達成しました。
目的：モデルが生のテキストよりも低コストで画像を読み取れる場合に、テキストトークンを画像トークンに置き換えること。

🧠 学習と分析
caveman learnコマンドはエージェントのローカル履歴をスキャンし、トークンの浪費箇所を特定して修正方法を分類します。
目的：データを外部に送信したりユーザーに課金したりすることなく、具体的かつ定量化された節約の機会を提示すること。

🔌 エージェントラッピング
Claude Code、OpenAI Codex CLI、Gemini CLI、Aider、opencode、Hermes Agent、OpenClawに対するネイティブラッピングに加え、Vercel AI SDK、LangChain、LiteLLM、CrewAI、PydanticAIなどのフレームワークとのbaseURLレベルでの互換性を備えており、合計30以上のエージェントに対応しています。
目的：既存のあらゆるエージェント設定が、コードの変更を最小限に抑えるか、あるいは全く変更せずに圧縮プロキシ経由でルーティングできるようにすること。

🧰 CLIユーティリティ
caveman shrink、caveman browse、caveman mem remember|recall、caveman toon encode|decodeなどのスタンドアロンコマンド。
目的：開発者がエージェントセッション外でも同じ圧縮プリミティブに直接アクセスし、スクリプト化できるようにすること。

4. 主なハイライト

バイト単位の正確な復元: すべての圧縮ペイロードは、圧縮が送信される前にコンテンツアドレス指定ストレージに元のバイト列を保存するため、何も失われません。
小さい場合にのみ圧縮する保証: サイズが測定可能なほど削減される場合にのみ変換を実行します。削減できない場合は、コンテンツを黙って劣化させるのではなく、理由とともに拒否がログに記録されます。
入力/出力圧縮の分離: スキル（出力）とプロキシ（入力）は独立して導入できるため、チームはより価値の高い方から開始できます。
透明性のあるベンチマーク: 「Honest Numbers」ドキュメントは、ローカルで推論された節約効果と独立して測定されたベンチマーク結果を区別しており、誇張された主張を避けています。
選択可能な強度レベル: エージェント内の/cavemanスキルは、異なる詳細度のニーズに合わせて複数の圧縮強度（lite、full、ultra、および「wenyan」バリアント）をサポートしています。
幅広いエージェントカバレッジ: ユーザーを単一のエージェント製品にロックインするのではなく、ネイティブラッピングまたはシンプルなbaseURL設定を通じて、30以上のエージェントおよびフレームワークで動作します。

5. 役割別のユースケース

一般開発者: プロンプトの方法を変更することなく、日常のエージェントコーディングセッション（Claude Code、Codex、Gemini CLI、Aiderなど）中のトークン支出とコンテキストの肥大化を削減します。
DevOps/SRE: 冗長なCIログ、コマンド出力、診断情報を圧縮（caveman shrink -- [command]）し、エージェントがより小さなコンテキストウィンドウ内でインシデントのトリアージを行えるようにします。
データ/リサーチサイエンティスト: caveman learnを使用してエージェントセッション履歴を分析し、トークン、ひいてはコストが実際にどこで消費されているかを定量化して、ワークフローの変更を検討します。
プロジェクトマネージャー: チーム全体にCavemanを展開する前に、ベンチマークと「Honest Numbers」ドキュメントを参照して、現実的なコスト削減期待値を評価します。

6. はじめに

必要な情報を見つける
アーキテクチャ、CLIリファレンス、セキュリティ/プライバシーに関する注意事項、ベンチマーク手法については、docsのREADME.mdから始めてdocs/ディレクトリを参照してください。

インストール / 統合

# プロキシ (Caveman 2) — 入力を圧縮
npm install -g @caveman-ai/cli && caveman setup --install
caveman claude   # または: codex, gemini, aider, hermes, openclaw

# スキル — 出力を圧縮、エージェントのスキルディレクトリにインストール
npx skills add JuliusBrussee/caveman

貢献

git commit -s -m "your message"   # すべてのコミットでDCO署名が必要です

変更したパッケージに関連するテストスイート（go test ./...、pnpm test、またはpytest）を実行し、PRは小さく焦点を絞った状態に保ち、メインリポジトリに対してオープンしてください。質問は[email protected]またはGitHubディスカッションにお寄せください。

7. プロジェクト構造

caveman/
├── agents/profiles/       # エージェントラッピング定義 (Claude Code, Codex, Gemini CLI, ...)
├── integrations/recipes/  # プロバイダーSDK統合例 (LangChain, LiteLLM, ...)
├── engine/                # 圧縮エンジンおよびピクセルモードレンダリング
├── browse/                # ブラウザコンテンツ圧縮実装
└── docs/                  # アーキテクチャ、CLIリファレンス、ベンチマーク、セキュリティドキュメント

8. 関連エコシステム

アップストリームエージェント/プラットフォーム: Claude Code (Anthropic)、OpenAI Codex CLI、Gemini CLI (Google)、Aider、opencode、Hermes Agent (Nous Research)、OpenClaw — Cavemanはこれらを置き換えるのではなくラップします。
補完的なフレームワーク: Vercel AI SDK、LangChain、LiteLLM、CrewAI、PydanticAIは、標準のbaseURL設定を通じてCavemanプロキシを指すことができます。
バンドルされたサードパーティコンポーネント: pxpipe (MIT)、Spleenフォント (BSD-2-Clause)、GNU Unifont (OFL-1.1 / GPLv2-with-font-exception) が内部的に使用されており、特にピクセルモードレンダリングに利用されます。

9. ライセンス

Cavemanはディレクトリごとに分割されたライセンスを採用しています。

✅ スキル、エージェントSDK、CLI、クライアントSDK、および導入支援ツールは、MITライセンスの下で自由に使用、修正、再配布できます。
✅ エンジン、プロキシ、キャッシュエンジン、リライター、ブラウズ機能、およびMCPサーバーを、BSL-1.1ライセンスの下で、自社のファーストパーティトラフィック用に無料でセルフホストできます。
❌ プロジェクトからの商用ライセンスなしに、BSL-1.1対象のコンポーネント（エンジン/プロキシ/MCPサーバー）をサードパーティ向けのホストまたは組み込みサービスとして提供することはできません。
ℹ️ BSL-1.1対象のコードは、2030年6月21日、または各バージョンのリリースから4年後のいずれか早い時点で、自動的にApache-2.0に移行します。
ℹ️ GitHub自身のメタデータではライセンスが「NOASSERTION」と表示されていますが、これは分割されたMIT/BSL-1.1モデルが単一のSPDX識別子にマッピングされないためです。実際に適用される条件については、各ディレクトリのLICENSEファイルを確認してください。

10. FAQ

Q: Cavemanがデータを黙って破損させたり失ったりすることはありますか？
A: いいえ。すべての圧縮ペイロードは元のバイト列のコンテンツアドレス指定されたコピーを保持しており、変換は入力よりも厳密に小さいことが測定された場合にのみ送信されます。それ以外の場合は、理由とともに拒否がログに記録されます。

Q: プロキシなしで出力圧縮スキルのみを使用したり、その逆を行うことはできますか？
A: はい。スキル（npx skills add JuliusBrussee/caveman）とプロキシ（npm install -g @caveman-ai/cli）は独立したプロダクトであり、個別に導入できます。

Q: Cavemanはどのコーディングエージェントをサポートしていますか？
A: ネイティブラッピングはClaude Code、OpenAI Codex CLI、Gemini CLI、Aider、opencode、Hermes Agent、OpenClawに対応しており、baseURLで設定可能なフレームワークを含め、合計30以上のエージェントにアクセスできます。

Q: 自分のチーム用にプロキシ/エンジンをセルフホストできますか？
A: はい。ファーストパーティトラフィック用のセルフホストはBSL-1.1の下で無料です。商用ライセンスが必要なのは、それをサードパーティ向けのホストまたは組み込みサービスとして提供する場合のみです。

Q: ベンチマーク数値（65%、33.2%）はどこから来ていますか？
A: docs/HONEST-NUMBERS.mdおよびdocs/WRAP-BENCHMARK.mdを参照してください。これらはローカルで推論された見積もりと独立して固定されたベンチマーク結果を区別しています。

11. クイックリンク

リポジトリ: https://github.com/JuliusBrussee/caveman
ドキュメント: https://github.com/JuliusBrussee/caveman/tree/main/docs
貢献ガイド: https://github.com/JuliusBrussee/caveman/blob/main/CONTRIBUTING.md
ディスカッション / お問い合わせ: リポジトリのGitHub Discussions、または [email protected]

12. まとめ

Cavemanは、AIコーディングエージェントに、重要な情報を失うことなく発言と読み取りを少なくするための実用的な方法を提供します。簡潔な出力スキルと入力圧縮ローカルプロキシを組み合わせ、両方ともバイト単位の正確な復元保証によって支えられています。Claude Code、Codex、Gemini CLI、または同様のツールを使って長いエージェントコーディングセッションを実行し、正確なコード、エラー、ログを犠牲にすることなくトークン支出を測定可能なレベルで削減したい開発者やチームにとって最も価値があります。