Issue 2026-08-14
v0.9.7
Codewhaleany model, on your machine
★ 40.8k
Open source · Bring your own model · Runs in your terminal

Codewhale dives into the deep
so you don't have to.

Codewhale is an open-source coding agent for your terminal. Give it a model and a task — it reads your code, edits files, runs its own checks, and stops when the job's done or it needs you. Bring any model, or mix them: pin a different model to each role.

Install Docs GitHub
one-line install
npm install -g codewhale
needs Node 18+ — no Rust toolchainother ways →

cwLatest release v0.9.7Current source v0.9.742 provider routesMIT

Codewhale TUICurrent session
Current Codewhale terminal session showing Operate mode, the whale, composer, and footer
Current Codewhale session · Operate mode · Ask permission posture
实 时LIVE
opened#5377main is red on macOS and Windows: nine reasoning-effort tests still as…by @Lstarsky03h agoclosed#5053TUI never tells the user an update exists; add update notice + one-cho…by @Hmbown4h agoclosed#5287TUI/Fleet: sub-agent display identity should be the fleet/session name…by @Hmbown4h agoclosed#5373Output-token ceiling clamped below the documented catalogue limit; tru…by @Hmbown4h agoclosed#5372Stale write-claims from closed sessions block new sub-agents (dead own…by @Hmbown4h agoclosed#5371Sub-agents not inspectable: model, fleet role, and type invisible (eve…by @Hmbown4h agoclosed#5293TUI: make deny-by-default approval selection configurable and clearly …by @JayBeest4h agoclosed#5340[0.9.6] doctor: `first-run` / `update checkpoint` permanently stuck on…by @pnbob19884h agoopened#5370P0: web UI looks broken — audit and rebuild look/features against harn…by @Hmbown10h agoopened#5361v0.9.8: add keyless assembled-journey fixtures for model-visible chang…by @Hmbown20h agoopened#5355v0.9.8 Known issues: parallel-load and config-fixture flakes (from the…by @Hmbown23h agoopened#5350简化第三方模型配置，增加预制模板Simplify third-party model config with pre‑built templ…by @shadapangyesterdayreleasedv0.9.7yesterdayreleasedv0.9.62d agoopened#5324agent tool: simplify the 32-field schema so models stop erroring on itby @Hmbown2d agoopened#5322Regression: output area doesn't fill wide terminals (worked in v0.8.65…by @M-Maciej3d agoclosed#5266v0.9.5: milestone tracker — start here (pick order)by @Hmbown5d agoopened#5311v0.9.8: ship Kimi-level plugin system and federated marketplacesby @Hmbown5d agoopened#5290fix(web): restore clickable controls on non-English routesby @Hmbown6d agoopened#5288Website: retire fully-merged codex/website-polish + close the manual-d…by @Hmbown6d ago

An underwater terminal shell. Any model. On your machine.

Bring the model you already use — hosted, gateway, or local. Plan / Work / Operate and explicit permission postures keep the dive under your control.

See how it decides

Law you can watch in the trace

Real session excerpts — ranked project law visible in the model's reasoning, not just a landing-page claim.

codewhale — thinking
reasoning trace
# When the prior session's summary didn't match the repo…
› Per Article II (truth) and V (verification), I report what's actually in the tree — not what the previous agent claimed.
Article II · TruthArticle V · Verification
→ Reported the uncommitted work the summary left out, instead of repeating the claim.
›

From task to verified change.

  1. 01

    Inspect

    Read the repository, its instructions, and the task.

  2. 02

    Act

    Edit files through explicit approval boundaries.

  3. 03

    Verify

    Run checks and inspect the result.

  4. 04

    Report

    Leave a concise, durable receipt.

$ codewhale exec "fix the failing test"inspect   repository and instructionsact       edit through the selected permission postureverify    cargo test --lockedreport    checks passed · receipt saved

New to Codewhale? Four steps end to end.

Install → keyless first session → connect a provider → set up your fleet. Nouns defined on the vocabulary page.

  1. Install Codewhale

    One npm command installs the dispatcher and terminal runtime. Cargo, archives, Docker, Nix, and China mirrors are documented alternatives — published releases only.

    npm install -g codewhale
codewhale doctor
    Full install guide →

  2. Open a first session — no key needed

    Launches without any API key: short constitution-first setup, then the full interface. Explore in Plan mode — always read-only. Model replies need a provider; that's the next step.

    codewhale
    Learn the product nouns first →

  3. Connect a provider

    Pick a supported route — hosted key, gateway, or keyless local runtime (Ollama, vLLM, SGLang). Provider and model stay explicit; reasoning and routing provenance stay separate, and unavailable values stay unavailable.

    codewhale auth set --provider deepseek
    Providers and models →

  4. Set up your ideal fleet

    Add every provider you use — one auth set per hosted route; keyless local runtimes need nothing — then author the team: /fleet setup walks one role at a time (a model from any configured provider, a thinking tier, permissions) and saves a reusable profile for this repo or every repo on this machine. Fleet state lives in the workspace ledger; ordinary single tasks need none of this.

    /fleet setup
codewhale fleet status
    Fleet and Workflow docs →
Read the getting-started guide →See the product vocabulary →

Your model.
Your boundaries.

Choose the model, working mode, and permission posture explicitly. Unknown cost stays unknown, and preview surfaces stay labeled as such.

42 provider routes
Hosted, gateway, and local models
Plan · Work · Operate
Read-only planning through autonomous operation
Ask · Auto-Review · Full Access
Choose the permission posture for the work
TUI · exec · web · API
Interactive and headless runtime surfaces

Use the runtime where the work happens.

TUIInteractive terminal work
codewhale execScripts and CI
Web clientLoopback-only browser client
Runtime API + MCPLocal integrations
FleetDurable multi-agent work
See runtime surfaces and stability notes →

Start with one command.

npm install -g codewhale

CargoBinariesDockerNixWindowsAndroid / TermuxChina mirrors

Read the install guide →

Built in public

MIT-licensed and shaped by contributors across runtimes, providers, platforms, documentation, and tests.