CodeWhale とは?Rust 製のターミナル型コーディング Agent を読み解く
ここ数年、ターミナル型のコーディング Agent が一気に増えた。大半は特定のクラウドベンダーと深く結びついているか、承認ロジックをブラックボックス化したまま動かしている。CodeWhale の立ち位置はやや異なる。モデルに依存しない設計と、承認プロセスの可視化を両立させている点が特徴だ。想定ユーザーは明確で、オープンソースのローカルモデルを使いながら、Agent の挙動範囲をきちんと見届けたい開発者に向けて作られている。
GitHub リポジトリ:https://github.com/Hmbown/CodeWhale。Star 数は現在 40,828 で、README は 18 言語に翻訳されている。
何の課題を解決するのか
ターミナル型コーディング Agent はここ数年で一気に増えた。しかし多くは、特定クラウドベンダーへのロックインがあるか、承認ロジックがブラックボックス化されている——Enter を押すまで、次にどのファイルに触れるのかが分からない。
CodeWhale のアプローチは次の二点に集約される。
- モデル非依存。ローカルの Ollama、vLLM、SGLang から、OpenAI 互換プロトコルや Anthropic のホスト API まで接続でき、実行時にモデルを自由に切り替えられる。
- 承認プロセスの可視化。Agent に許可する操作の範囲を 4 段階(Plan / Ask / Auto-Review / Full Access)として明示し、各操作をロールバック可能なスナップショットログとして記録する。
ターゲットは、ローカルのオープンソースモデルでコーディング Agent を動かしたい一方、ファイルへの無秩序な変更を許容できないユーザー層だ。
使い方
導入は次の 3 コマンドで完結する。
# 三步起步
npm install -g codewhale # 也可用 cargo / docker / nix
codewhale # 启动 TUI,首次运行引导接 provider 或保持离线
# 不开 TUI 直接跑任务
codewhale exec "fix the failing tests and explain what changed"
# TUI 内常用命令
# /model 切换 provider 和模型
# /undo 撤回上一轮操作
# /restore 回滚到某个 workspace snapshot
# /goal 设置持久目标
# /help 查看所有快捷键
# 想用本地模型?起一个 Ollama 后 /model 选 Ollama 即可,
# vLLM、SGLang 同理(OpenAI 兼容协议)
インストール経路も豊富に用意されている。npm、Cargo、Docker、Nix に加え、Scoop、Termux、CNB ミラーも利用可能で、国内からの導入もしやすい。
アーキテクチャの全体像
CodeWhale はシステムを 4 層に分割しており、それぞれに README 内のドキュメントエントリが対応しているため、興味がある層から読み進められる。
- エントリ層:TUI(デフォルト)+
codewhale exec(ヘッドレス、単発タスク向け)+ ローカル Web クライアント(docs/WEB.md)。3 つのエントリは同一の agent runtime を共有する。 - Provider 抽象:OpenAI 互換プロトコル、Anthropic、Ollama、vLLM、SGLang を内部の Model trait に統一する。未知モデルの価格は 0 円と誤表示せず空欄のままにし、ユーザー自身がコスト表を管理する設計。
- 承認ポリシースタック:4 段階のレベル——Plan(読み取り専用、ファイル変更なし)/ Ask(各ステップで確認)/ Auto-Review(自動実行、ただしロールバック可能)/ Full Access。`/undo` と `/restore` を組み合わせることで、可観測なセーフティ境界を構成する。完全なポリシー定義は docs/AUTHORIZATION_ORDER.md に記載。
- 拡張層:MCP server、スキルファイル、hooks、agent role ファイル(プロジェクト内またはグローバル settings に配置)。複数 agent の協調動作時(docs/FLEET.md)でも、内部プロンプトがユーザーの transcript に混入することはない。
主要な処理フローは短い。ユーザー入力 → goal/turn に分解 → MCP + skills + hooks をロード → Model 呼び出し → 現在の承認レベルに応じてツール呼び出しを判定 → session snapshot に記録 → 結果をレンダリング、という流れだ。
優れている点
- モデル非依存は本物。Ollama、vLLM、SGLang まで対応し、`/model` コマンド一発で切り替えられる。Provider を変更するためにコード改修や再デプロイは不要。
- 承認レベルの細分化は単なる marketing 表現ではない。ドキュメントには AUTHORIZATION_ORDER の完全なポリシースタックが記載され、各操作に snapshot が残るためロールバック可能。Plan から Full Access までは連続的に調整可能で、on/off の二者択一ではない。
- 複数 agent 協調でも transcript が汚れない。docs/FLEET.md の協調モードでは、内部 sub-agent のプロンプトがユーザーの対話ログを汚染しないため、デバッグが容易。
- Rust の単一バイナリ + 多チャネル配布。Cargo、npm、Docker のいずれで導入しても同一バイナリが配布され、挙動が一貫している。
- コミュニティが活発。Star 数は 40,828、README は 18 言語に翻訳済み、issue へのレスポンスも迅速。
物足りない点
- 名称が Claude Code と混同されやすい。「CodeWhale」という名前だけでは文脈が不足し、検索時にノイズに埋もれやすい。
- ドキュメント量がコード量を上回る。導入してすぐ使いたいユーザーにはやや取っつきにくい。docs/AUTHORIZATION_ORDER.md、docs/FLEET.md、docs/WEB.md の三つだけでもそれなりのボリュームがある。
- 未知モデルの価格は空欄のまま。コスト管理を重視するチームでは、自ら価格表を維持する必要がある。自動算出はされない。
- `deepseek-tui` からのリネームプロジェクト。古い設定ファイルやセッションとの互換性は隠れたコストになり、移行時に手動調整が必要になる可能性がある。
動作未検証——ただし、以下の手順で確認することを推奨
本記事は README とリポジトリ構成に基づく静的分析であり、実機での動作検証は行っていない。次の手順で検証することを勧める。
codewhaleをインストールし、ローカルの Ollama 上でqwen2.5-coderを起動して接続する。- 適当な toy リポジトリで
codewhale exec "给 src/foo.py 补单元测试"を実行し、Plan レベルと Full Access レベルでの出力差異を比較する(Plan ではファイル変更がほぼ発生しないはず)。 - `/restore` でロールバックし、snapshot が完全か、特定ターンに正確に復元できるかを確認する。
- 二つの agent ロールで docs/FLEET.md のサンプルを実行し、transcript が実際にクリーンか検証する(内部 sub-agent の思考は可視化されないはず)。
検証結果(ローカルモデルでの token/s、承認応答遅延、snapshot サイズなど)をコメントで共有してもらえると、数値合わせができる。
どんな人に向くか
向いているケース:
- オープンソースのローカルモデル(Ollama / vLLM)でコーディング Agent を動かしたい一方、ファイル変更を Agent に任せきれないユーザー。
- チーム内で Agent の操作ログを監査し、承認フローをブラックボックスではなく可視化されたプロセスとして運用したいエンジニア組織。
- Rust エコシステムの貢献者で、4 万 Star の Rust 製 Agent プロジェクトの構成を学びたい人。ディレクトリ構造とモジュール分割は見どころ。
向かないケース:
- IDE プラグインを手軽に導入したい、5 本のドキュメントを読むのが面倒というユーザー。
- Claude Code や Cursor のような「最強モデルを開封即利用」体験に依存しており、ベンダーロックインを許容する層。CodeWhale はモデルの選定を代行しないため、切り替えの判断コストはユーザー側に残る。
- ターミナル UI に抵抗があり、GUI が必須なチーム。CodeWhale にはローカル Web クライアント(docs/WEB.md)もあるが、主戦場は TUI。
参考:CodeWhale リポジトリ https://github.com/Hmbown/CodeWhale、docs/AUTHORIZATION_ORDER.md、docs/FLEET.md、docs/WEB.md はそれぞれ承認戦略、複数 agent 協調、Web クライアントの 3 領域をカバーしている。