Tools

CodeWhale: A 40K-Star Rust Terminal Coding Agent That Sidesteps Claude Code

CodeWhale differentiates itself from other TUI coding agents through tiered approvals and reviewable workflows, backed by a Rust single-binary build and a model-agnostic architecture.

Font size

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:

  1. Model-agnostic. Local Ollama, vLLM, SGLang; hosted OpenAI-compatible endpoints, Anthropic—they all work, and you can switch at runtime.
  2. 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 Model trait. 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 /undo and /restore, this forms an observable safety boundary. Full policy definition lives in docs/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 /model switches between them on the fly. No code changes or redeploys needed.
  • Tiered approvals aren't marketing fluff. The full AUTHORIZATION_ORDER policy 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.md ensures 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, and docs/WEB.md add 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:

  1. Install codewhale and connect it to a local Ollama instance running qwen2.5-coder.
  2. 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).
  3. Use /restore to roll back and check whether the snapshot is complete and can pinpoint a specific turn.
  4. Spin up two agent roles using the example in docs/FLEET.md and 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.

Source: https://github.com/Hmbown/CodeWhale