JuliusBrussee/caveman

Caveman – AIコーディングアシスタント向けトークン節約ラッパー

概要 – Cavemanは、AIコーディングアシスタント（Claude Code、Codex、Gemini、Cursorなど）と基盤となるLLMプロバイダーの間に配置される軽量な「スキル」（ルールファイル）と、オプションのローカルプロキシです。その唯一の目的は、モデルが読み書きするテキスト量を削減し、課金されるトークン数を減らすことです。

仕組み

• スキル（小さな岩） – モデルの応答の散文部分を簡潔な「原始人」スタイルに書き換える、シンプルなプロンプトスタイルのルールです（例：69トークンの説明を19トークンに）。コードスニペット、ファイルパス、正確なエラーメッセージは変更されません。
• プロキシ（大きな岩） – エージェントからLLMプロバイダーへのすべてのリクエストをインターセプトするローカルNode.jsプロセスです。ペイロードタイプ（JSON、ログ、コード、検索結果など）を検出し、カスタム圧縮機で重要な情報（キー、エラー行、関数シグネチャなど）を保持しながら、反復的またはノイズの多い部分を破棄します。元のペイロードはSQLiteキャッシュに保存され、必要に応じて全文を取得できます。
• ラップ・エニー・エージェント – プロキシを有効にしてターゲットエージェントを起動する薄いラッパーで、エージェントの設定ファイルを変更する必要はありません。対応エージェント：Claude Code、OpenAI Codex CLI、Gemini CLI、Aider、Kilo Code、Qwen Code、opencode、Hermes、OpenClaw、Pi。

主な数値（READMEより）

• 書き込み側の節約 – 10の典型的なプロンプトで、スキルにより出力トークンが平均1,214から294に削減され、**65%**削減。
• 読み取り側の節約 – 54回のClaude Codeベンチマークで、プロキシにより入力トークンが885,793から591,673に削減され、全体で**33%**削減（純粋なHTMLページなど一部のケースではわずかに増加）。
• 圧縮率 – JSONペイロードは70〜90%、ログは85〜95%、コードは40〜70%、差分は60〜80%縮小。

インストール

1. スキルのみ – スキルCLIによるワンライナー：

   npx skills add JuliusBrussee/caveman
   

   その後、エージェント内で/cavemanを呼び出します（エージェントが自動ロードしない場合は/cavemanと入力）。
2. プロキシ – グローバルnpmインストールとセットアップ：

   npm install -g @caveman-ai/cli && caveman setup --install
   caveman claude   # または codex、gemini など
   

   macOS/Linux用の完全なインストーラースクリプト（install.sh）とWindows PowerShell用（install.ps1）も提供されています。

典型的なワークフロー

1. caveman <agent>（またはcaveman wrap <agent>）を実行して、プロキシを有効にした状態で選択したコーディングアシスタントを起動します。
2. エージェントがLLMに支援を求めると、プロキシが大きなコンテキスト（ログ、差分、JSON）を上流に送信する前に圧縮します。
3. LLMの応答はスキルによって後処理され、冗長な説明が簡潔な文章に変換されます（コードはそのまま）。
4. 以下のようなヘルパーコマンドを使用します：
   • /caveman-commit – 簡潔なConventional Commitメッセージを生成
   • /caveman-review – ワンライナーのコードレビューコメントを生成
   • caveman compress <file> – 大きなMarkdownファイルをローカルで圧縮
   • caveman stats – 現在のセッションのトークン使用統計を表示
   • caveman learn – ディスク上の過去のセッションを分析し、トークン浪費が発生している箇所を提案

なぜ使うのか

• コスト削減 – トークン単位で課金される場合（例：Anthropic、OpenAI）、入力と出力の両方を削減することで、特に大規模なログや差分を扱う長時間のデバッグセッションで、請求額を大幅に削減できます。
• 速度 – ペイロードが小さくなると、転送データ量が減り、応答時間が短縮されます。
• プライバシー – プロキシは元のデータをローカルに保存します。圧縮版のみがプロバイダーに送信されます。

注意点と制限

• スキルは散文のみを短縮します。モデルの推論や、プロキシが圧縮できない入力コンテキストに費やされるトークンは削減されません。
• 圧縮には独自のオーバーヘッド（ターンあたり約1〜1.5k入力トークン）が追加され、既に簡潔なやり取りでは節約効果が相殺される可能性があります。
• 一部のペイロードタイプ（例：純粋なHTML）では、圧縮機が削減できる部分が少ないため、正味の増加が見られる場合があります。
• このツールは「ラッパー」であり、基盤となるエージェントのコードを変更しませんが、各対応エージェントにはNode.js 22+と互換性のあるCLIが必要です。
• READMEには、トークン節約の主張はベンチマークに基づくものであり、実際の節約額は異なる場合があると記載されています。caveman statsまたはカスタムA/Bテストで測定することをお勧めします。

ライセンス – スキルコンポーネントはMITライセンスで、永久に無料です。プロキシランタイムはデュアルライセンス（MIT + BSL-1.1）です。

---

上記の詳細はすべて、リポジトリのREADMEから直接引用しています。追加の機能は推定されていません。