Codewhale: The Terminal Coding Agent That Admits What It Does Not Know

There is no shortage of terminal coding agents now. What separates them, once you have used a few, is rarely the model — it is what the tool does when it is uncertain, and how much it is willing to admit it does not know.

Codewhale is an open-source coding agent written in Rust, MIT licensed, that you point at a provider and a model of your choosing. It reads your code, edits files, runs commands, and checks its own work, then stops when the job is done or when it needs you. That description fits a dozen tools. What makes this one worth a look is a set of small, unglamorous decisions about honesty that most agents get wrong.

An unknown token price shows as unknown, not $0. The agent claims a command is sandboxed only when an OS sandbox is genuinely wrapping it. And a repository can declare write holds that even the most permissive mode cannot step over. None of that demos well. All of it matters at 2am when the agent is three commands into something you did not fully read.

Where it came from

Codewhale started life as a native terminal experience for DeepSeek. It has since become a community-driven project with a broader remit: one coding harness that fits a growing international community and supports as many models and providers as possible — open models first, hosted or local, none privileged over the rest.

That last clause is a governance statement more than a technical one, and the project backs it up in the licence footer: MIT, "an independent community project, not affiliated with any model provider." A tool that began inside one vendor's orbit and explicitly refuses to keep that vendor's models in a privileged slot is doing something slightly unusual, and it is the reason the provider list is as long as it is.

The internationalisation effort tells the same story. The README exists in Simplified Chinese, Japanese, Vietnamese, Indonesian, Korean, Spanish, Portuguese, Russian and Ukrainian alongside English — not machine-dumped once, but maintained, with a full Indonesian documentation suite landing recently. There is also a CNB mirror for install, specifically for people who cannot reach GitHub. Most projects treat that as somebody else's problem.

If you used its predecessor: coming from deepseek-tui, your config and sessions carry over. The project keeps a docs/REBRAND.md for exactly that migration. We looked at what that DeepSeek-native release line actually did separately — some of its sharper ideas, like compaction that respects the provider's prefix cache, only work when you know exactly which model you are talking to.

Installing it

The headline route is npm, which is a slightly odd fit for a Rust binary and entirely sensible for reach:

npm install -g codewhale

Everything else is documented in docs/INSTALL.md: Cargo, Docker, Nix, Scoop for Windows, prebuilt archives, Android and Termux, and the CNB mirror mentioned above. The Termux entry is worth pausing on — a coding agent that runs on a phone is a genuinely different product from one that assumes a workstation.

The first five minutes

Four commands cover the whole surface area:

codewhale auth set --provider deepseek   # or export ANTHROPIC_API_KEY, etc.
codewhale                                # open the TUI
codewhale exec "fix the failing test"    # headless
codewhale web                            # local browser client on 127.0.0.1

Credentials go through codewhale auth set, or through the environment variable the provider already expects — so if you have ANTHROPIC_API_KEY exported for something else, it is already configured.

Living in the TUI

The interactive terminal UI is where the design decisions show. Four things are worth knowing before you start:

• /model switches provider and model together. That pairing matters: most agents make you reconfigure a provider and then pick a model from it, which is two steps and one opportunity to end up pointed somewhere you did not intend. Doing it mid-task means you can plan on a strong model and execute on a cheap one, or escalate when a task turns out to be harder than it looked.
• /fleet runs a team of workers rather than a single agent.
• /restore undoes a turn. Not a git operation you have to reason about afterwards — a first-class undo for the thing the agent just did.
• ! runs a shell command, and it goes through the normal approval path rather than around it. That is the correct decision and not the obvious one; an escape hatch that skips your own safety checks is how tools end up with a "how did it delete that?" issue thread.

Two keys carry the safety model, and both only act when the composer is idle, so they never fire mid-typing:

Splitting these into two independent axes is the sharper idea in the whole interface. Most agents collapse "what can it do" and "how much do I trust it right now" into a single mode selector, which forces false choices — you want an agent that can only read, but that does not stop to ask permission for each read. Two dials solve that cleanly.

Any model, any provider

The README names DeepSeek, Claude, GPT, Kimi and GLM, and puts the total at 30+ providers. Beyond hosted routes, you can point it at your own vLLM, SGLang or Ollama server with no key at all. One runtime, one toolset, regardless of which of those is behind it.

The detail I find most telling is about cost accounting:

Context limits and prices come from the real route, and an unknown price shows as unknown rather than $0.

Anyone who has run an agent against a gateway or a self-hosted model has seen the alternative: a cost readout that confidently displays $0.00 because the tool has no pricing data for that route, quietly training you to ignore the number entirely. Showing unknown is worse UI and better engineering. The same applies to context limits — taking them from the real route rather than a hardcoded table is the difference between an agent that knows it is about to overflow and one that finds out from an API error.

Full routing details for hosted, gateway and local providers live in docs/PROVIDERS.md.

The permission model

This is the part of Codewhale that has clearly received the most thought, and it is worth being precise about what is and is not promised.

Plan mode cannot change files. Not "is instructed not to" — cannot. That distinction is the whole game with agent safety, because a prompt-level instruction is a suggestion to a language model and a runtime-level restriction is not.

Approvals gate risky commands. Combined with the posture dial above, that gives you a spectrum from "ask me about everything" to "go", without leaving the session.

Sandboxing is claimed only when it is real. Here is the exact position: when an OS sandbox actually wraps a command, Codewhale says so — Seatbelt on macOS where available, opt-in bubblewrap on Linux.

All of these compose in a defined order, and the project publishes it. docs/AUTHORIZATION_ORDER.md documents how modes, hooks, permission rules, safety floors, repo law, approvals and sandboxing stack up against each other. Publishing a precedence order — and, per the commit history, locking it — is a maturity signal. Most agents leave you to discover by experiment which layer wins when two of them disagree.

Repo law: constitution.json

The single most interesting feature gets one sentence in the README:

A repo's constitution.json compiles into write holds that even Full Access can't skip.

Unpack that. The rules live in the repository, not in your personal config, so they travel with the code and apply to every contributor who points an agent at it. They compile into write holds rather than being read as prose the model may or may not honour. And they sit above the most permissive posture the user can select — Full Access is not a master key.

That inverts the usual arrangement, where the human's local settings are always the final authority. It is the right inversion for a shared codebase: the repository's rules about what must never be auto-edited — generated files, migrations, licence headers, a security-sensitive module — should not depend on each individual having configured their tool correctly. Configuration details are in docs/CONFIGURATION.md.

Fleets and the ledger

/fleet runs a team of workers on a task. The interesting half is what happens underneath:

A fleet records every step to an append-only ledger, so fleet resume picks up where you left off.

Multi-agent runs are exactly where crash recovery stops being a nice-to-have. A single-agent session that dies costs you one conversation. A fleet that dies forty minutes into coordinated work across a codebase costs you forty minutes of tokens and the mental model of what got done. An append-only ledger is also the right shape for the audit question — what did this thing actually do to my repository — which is the question you ask after the fact, when nobody is watching the screen. docs/FLEET.md has the detail.

Headless, CI, and the hooks caveat

codewhale exec "fix the failing test" runs a task without the TUI, which is what makes the tool usable from scripts and CI pipelines.

There is one caveat here that will bite somebody, and the project deserves credit for putting it in the README rather than burying it. Codewhale has eleven TUI lifecycle hook events, three of which can steer a turn — and:

codewhale exec and the CLI subcommands do not fire hooks.

If you build a policy layer out of hooks — a check that blocks certain edits, a notifier, a guard that inspects commands before they run — that layer is inactive in headless mode. Interactive sessions are governed by it; your CI job is not. Any policy that must hold everywhere belongs in constitution.json and permission rules, which apply regardless of entrypoint, not in a hook. The events and payloads are documented in docs/HOOKS.md.

The browser client

codewhale web starts a local browser client on 127.0.0.1. Two constraints are stated plainly: it is loopback-only, and it has a one-time authentication boundary, both documented in docs/WEB.md.

Loopback-only means the listener is not reachable from your network by default. Worth remembering if you are tempted to port-forward it to reach a session on a remote box — you would be taking a component that was designed to only ever talk to the machine it runs on and putting it somewhere it was not designed to be. Tunnel the connection instead of rebinding the listener.

The state of the project

Some numbers, because they change how you should read everything above. Codewhale has 40.4k stars, 3.5k forks, 207 contributors, 127 releases, and is at v0.9.3 — released two days before this was written. It is 94.3% Rust, with TypeScript, JavaScript, Python, Shell and CSS making up the rest. There are also 310 open issues.

Read those together and you get an accurate picture: a very popular, very active, pre-1.0 project moving fast. The release cadence and the issue count are two views of the same energy. Pin your version if you are putting it in CI.

The repository itself signals more care than the star count alone would predict. There is a SECURITY.md, RustSec auditing and cargo-deny wired into CI via audit.toml and deny.toml, a code of conduct, a VS Code extension, a devcontainer, a Nix flake, and an AGENTS.md — the project uses agents on itself, which is either reassuring or recursive depending on your mood.

One contributor policy deserves a mention because it is genuinely uncommon. When a pull request cannot merge as-is, maintainers harvest what works and keep the author credited — in the commit, in the changelog, and in docs/CONTRIBUTORS.md. The usual outcome for an imperfect PR is a polite close and a rewrite by a maintainer, with the original author's name nowhere. Deciding otherwise, and writing it down, is how a project ends up with 207 contributors.

Where it fits, and where it doesn't

Reach for it when you want one agent across several providers instead of a different tool per model; when you run local models and want first-class support rather than a compatibility shim; when you need an agent that works on a shared repository with rules that apply to everyone; or when you want the whole thing to be MIT-licensed, in Rust, and running on your machine.

Think twice when:

• You need a kernel-level sandbox on Linux by default. Bubblewrap is opt-in. Approvals and mode restrictions are enforcement inside the agent, and that is a different guarantee.
• Your safety policy lives in hooks and your work runs headless. codewhale exec does not fire them. Move that policy into repo law and permission rules.
• You want a stable API surface. This is a pre-1.0 project shipping releases weekly and carrying 310 open issues. That is a healthy sign for a young tool and a real cost if you build automation on top of it without pinning.
• You want published benchmarks. The README makes no claims about task success rates, speed, or comparisons with other agents, and this write-up does not invent any. Try it on your own repository.
• You prefer a GUI. There is a VS Code extension and a local web client, but the centre of gravity is the terminal.

The README is deliberately a doorway — nearly every section defers to docs/ for the real detail, and the material above stops where the README stops. If a specific behaviour matters to your decision, particularly around authorization order or sandboxing, read the corresponding doc rather than trusting a summary of a summary.

Frequently asked questions