Claude Code / Codex CLI の重いコード生成をローカルLLMに委譲するプラグイン（tunaLlama）

バイブコーディング中に Claude Code や Codex CLI の定額利用枠がすぐ減ってしまう人向けに作られた委譲ツールです。

https://github.com/hang-in/tunaLlama

Claude Code でコーディングしていると、出力が長い段階（コード生成、ファイルレビュー、リファクタ）が最も多くのトークンを消費します。しかし、この段階はたいてい決定的で、モデル品質の差が小さいです。逆に、分解（要件 → 作業一覧）と検証（返ってきた結果が要件を満たしているか）は短い入出力ですが、モデル品質の差が大きいです。

tunaLlama はこの非対称性をそのままコードフローとして固定したバックエンド + プラグインです。

役割	モデル	責任
Architect	Claude / Codex（定額制）	分解 / 仕様 / 検証 / 統合
Developer	ローカル LLM（Ollama / Cloud / LM Studio）	コード生成 / 自己レビュー / 自己修正
Reviewer	Architect と同じセッション	最終判定

トークン消費の重い段階だけがローカルに逃がされ、短い分解・検証段階はそのまま Claude / Codex に残ります。

Claude Code と Codex CLI はどちらもプラグイン経由で外部ツールを使えます。
一度インストールしておけば、エージェントが作業中に必要だと判断した時点で自動的に呼び出す構造です。
ユーザーが毎回「このツールを使って」と指示する必要はありません。tunaLlama はそうしたプラグインの一種で、MCP (Model Context Protocol) サーバー経由で 13 個のツールを公開します。
1 つのリポジトリで Claude Code と Codex CLI の両方が動作します。
（claude-plugin/marketplace.json ファイルを両クライアントが認識します。）

ユーザーが作業を依頼すると（日本語 / 英語）

1. Architect が作業を分解 - 短ければ tuna_dev_review、長ければ spec 文書を作成してから tuna_dev_review_from_spec
2. バックエンドが generate → review → fix ループを繰り返す（bounded delegation - 終了条件は review pass または max iter）
   すべての呼び出しは SQLite に記録され、韓国語形態素解析器（Kiwi）でインデックス化されます
3. Architect が結果を検証してユーザーに返します

mid-size ローカル LLM 単独で回した場合と、Architect がコンテキストを整理して渡した後を比較すると、+0.58 ～ +0.64（3 モデルで検証、Phase 7-2）でした。つまり、同じローカル LLM でもコンテキストをうまく整理して渡せば結果が有意に改善するという意味です。
ただし、この測定は合成シードに基づいています。現実でよく出る作業シナリオをあらかじめ作ったテストセット上で測定したものなので、実際のユーザーワークフローでも同じ結果になるかは別問題です。organic dogfooding metric は v0.5.7+ から 4 種（standalone_toy_rate / convention_adherence_rate / ast_excess_score / syntactically_valid）を ~/.tunallama/metrics.db に自動保存しており、累積ベースラインまで含めた外部ユーザー再現性の収集を継続中です。

利用枠の節約については Anthropic / OpenAI の上限計算式が非公開のため、「X% 節約」のような定量結果はありません。結論としては「普通に使うよりはまし」です。

韓国語サポート

Kiwi 形態素解析器を組み込んでおり、韓国語の検索インデックス化が可能です。이메일검증 のようにスペースのない入力でも、이메일 で検索すればマッチします。FTS5 の unicode61 トークナイザーが韓国語を音節 / 字母単位にしか分割できない限界を補う構成です。ただし、Kiwi が処理できない新語 / 専門用語は検索品質に影響する可能性があります。

5 分インストール

セッションで一行投げれば完了です:

"https://github.com/hang-in/tunaLlama の INSTALL.md に従ってインストールして"

エージェントが依存関係の導入、.env 設定、プラグイン登録、検証までを段階的に自動で進めます。
手動インストールを希望する場合は README を参照してください。

両環境の動作マトリクス

Claude Code と Codex CLI は同じリポジトリで動作しますが、一部機能は片方でしか検証されていません（v0.5.6 実測、Claude Code 2.1.138 + Codex CLI 0.128.0）:

項目	Claude Code	Codex CLI
MCP tools 13 個呼び出し	✓	✓
DB 共有 (~/.tunallama/memory.db)	✓	✓
state.md 共有	✓	✓
tuna_load_memory / tuna_recall 明示呼び出し	✓	✓
Agents auto-discovery	✓
SessionStart hook + state.md auto-prepend	✓ (v0.5.5+)	✗
MCP resource auto-attach	✗	✗

Claude Code では state.md auto-prepend が自動で動作し、
Codex CLI ではユーザーが最初のターンで tuna_load_memory を明示呼び出しするか、docs を直接 fetch することが推奨されます。
MCP ツール 13 個の呼び出しは両方で正常動作するため、委譲自体はツールレベルで可能です。

制限事項

利用枠の節約は体感データに基づくものです（前述）
MCP ツールの system prompt コストは意図されたトレードオフです - 13 個のツール description + schema が各 conversation の system prompt に約 1.6k tokens prepend されます。これは偶発的なコンテキスト肥大化ではなく、Architect が適切な委譲ツールを選ぶための affordance コストとして設計されています

ローカル LLM 環境（Ollama など、Ollama Cloud も正常動作）が必須 - ないと動きません
検索の測定値は合成シードベースです（前述）
Codex CLI の一部機能は未動作です（前述のマトリクス）
韓国語の新語 / 専門用語は検索品質に影響する可能性があります

なぜプロンプトシード / AGENTS.md ではないのか

エージェントにさらに多くの文書を読ませることでコンテキスト限界を解決しようとはしていません。
その代わり、作業単位を小さく切り出して MCP ツールでローカル / 低コスト LLM に渡し、上位の Architect モデルは短い spec、review 結果、最終 diff 判断に集中します。
文書ベースの運用ルールは時間が経つと stale state、drift、lost-in-the-middle 問題を生みかねません。
tunaLlama はこれを避けるため、delegation call を SQLite に記録し、必要なときに検索 / リコールする実行レイヤーを置いています。

どんな人に向いているか

Claude Code Pro/Max 定額ユーザー（上限管理の動機がある人）
Codex CLI ユーザー（OpenAI 定額制 / API quota 管理）
Ollama ローカル / Ollama Cloud / LM Studio 環境がすでにある人
韓国語の作業を扱う人（Kiwi 統合）

テスト / ライセンス

v0.5.x の実用 dogfooding release。507 unit/plugin tests + 27 integration/search_quality tests、カバレッジ 90%。
測定コマンドは README に記載（pytest --no-cov -q -m "not search_quality and not integration"）。
ライセンスは MIT。英語 README（README.en.md）は同期維持中です。フィードバック / issue / PR を歓迎します。
他の AI CLI との互換提案も歓迎します。