Terminal coding agents have been popping up left and right. Most of them either lock you into a single cloud vendor or bury the approval logic in a black box. CodeWhale takes a different angle: model-agnostic by design, with observable approvals. The target audience is clear—developers who want to run open-source models locally and still see what the agent is doing.
GitHub repo: https://github.com/Hmbown/CodeWhale, currently at 40,828 stars, with the README translated into 18 languages.
What problem it solves
Most terminal coding agents fall into one of two traps: they tie you to a single cloud provider, or they hide the approval process in a black box—you hit Enter and have no idea which files the agent is about to touch.
CodeWhale's pitch comes down to two things:
- Model-agnostic. Local Ollama, vLLM, SGLang; hosted OpenAI-compatible endpoints, Anthropic—they all work, and you can switch at runtime.
- Observable approvals. What the agent can do and how far it's gotten are exposed as user-visible tiers (Plan / Ask / Auto-Review / Full Access), paired with rollback-capable snapshot logs.
The target user is anyone who wants to run a coding agent on open-source local models but doesn't trust the agent to modify files unsupervised.
How to use it
Three commands to get going:
# Three-step quickstart
npm install -g codewhale # Also available via cargo / docker / nix
codewhale # Launches the TUI; first run guides you through provider setup or stays offline
# Run a task without entering the TUI
codewhale exec "fix the failing tests and explain what changed"
# Common TUI commands
# /model Switch provider and model
# /undo Undo the last action
# /restore Roll back to a workspace snapshot
# /goal Set a persistent goal
# /help List all shortcuts
# Want a local model? Spin up Ollama, then pick it via /model
# Same applies to vLLM and SGLang (OpenAI-compatible protocol)
The install chain covers npm, Cargo, Docker, Nix, Scoop, Termux, and a CNB mirror—plenty of options for users in mainland China.
How it works (architecture)
CodeWhale splits the system into four layers, each with its own entry point in the docs so you can read what you need.
- Entry layer: TUI (default) +
codewhale exec(headless, for single tasks) + a local web client (docs/WEB.md). All three share the same agent runtime. - Provider abstraction: OpenAI-compatible, Anthropic, Ollama, vLLM, and SGLang are unified behind an internal
Modeltrait. When the price for an unknown model is missing, it stays blank rather than showing up as $0, so users maintain their own cost table. - Approval policy stack: Four tiers—Plan (read-only, no file changes) / Ask (prompt each step) / Auto-Review (autonomous but rollbackable) / Full Access. Combined with
/undoand/restore, this forms an observable safety boundary. Full policy definition lives indocs/AUTHORIZATION_ORDER.md. - Extension layer: MCP server, skill files, hooks, agent role files (project-level or global settings). In multi-agent collaboration (
docs/FLEET.md), internal prompts never leak into the user's transcript.
The core loop is short: user input → parse into goal/turn → load MCP + skills + hooks → call Model → apply the current approval tier before any tool call → write a session snapshot → render the result.
Where it shines
- Model-agnostic means model-agnostic. Not just a claim—Ollama, vLLM, and SGLang are all supported, and
/modelswitches between them on the fly. No code changes or redeploys needed. - Tiered approvals aren't marketing fluff. The full
AUTHORIZATION_ORDERpolicy stack is documented, and every operation has a rollback-capable snapshot. The move from Plan to Full Access is a continuous dial, not an on/off switch. - Multi-agent collaboration keeps transcripts clean. The collaboration mode in
docs/FLEET.mdensures sub-agent prompts don't pollute the user's conversation log—a real plus for debugging. - Rust single-binary, multi-channel distribution. Whether you install via Cargo, npm, or Docker, it's the same binary with consistent behavior.
- Active community. 40,828 stars, an 18-language README, and reasonably responsive issue triage.
Where it falls short
- The name invites confusion with Claude Code. "CodeWhale" requires context in community discussions, and searches get drowned in noise.
- Documentation outweighs code. For users who just want to install and go, the learning curve is steep.
docs/AUTHORIZATION_ORDER.md,docs/FLEET.md, anddocs/WEB.mdadd up. - Unknown model prices are left blank. Cost-sensitive teams have to maintain their own pricing tables—the tool won't estimate for you.
- It was renamed from
deepseek-tui. Compatibility with old configs and sessions is a hidden cost; migration may require manual tweaks.
I didn't run it—but here's how I'd verify
This is a static analysis based on the README and repo structure; I haven't actually run it. If you want to validate the claims, go in this order:
- Install
codewhaleand connect it to a local Ollama instance runningqwen2.5-coder. - In a toy repo, run
codewhale exec "add unit tests for src/foo.py"and compare the output between Plan and Full Access tiers (Plan should barely touch files). - Use
/restoreto roll back and check whether the snapshot is complete and can pinpoint a specific turn. - Spin up two agent roles using the example in
docs/FLEET.mdand verify the transcript stays clean (sub-agent reasoning should stay invisible).
Drop the numbers in the comments—tokens/sec on local models, approval latency, snapshot size—and let's compare notes.
Who should use it
Good fit for:
- Developers who want to run a coding agent on open-source local models (Ollama/vLLM) but don't trust the agent to modify files unsupervised.
- Engineering teams that need to audit agent operations and want the approval flow to be observable rather than a black box.
- Rust ecosystem contributors curious what a 40K-star Rust agent project looks like—the directory structure and module breakdown are worth a look.
Not a fit for:
- Users who just want to install an IDE plugin and skip reading five docs.
- Anyone hooked on the "best out-of-the-box model" experience of Claude Code or Cursor and unbothered by lock-in. CodeWhale won't pick a model for you—the switching overhead is yours to manage.
- Teams allergic to terminal UIs who need a full GUI. CodeWhale ships a local web client (
docs/WEB.md), but the TUI is still the main act.
Reference: CodeWhale repo at https://github.com/Hmbown/CodeWhale; docs/AUTHORIZATION_ORDER.md, docs/FLEET.md, and docs/WEB.md cover approval policies, multi-agent collaboration, and the web client respectively.