Issue 2026-08-12
v0.9.5
Codewhaleany model, on your machine
★ 40.7k
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.6Current source v0.9.640 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#5337Web: finish the #4934 dictionary spine — retire every isZh branch and …by @Lstarsky04h agoclosed#5320fix(session): separate snapshot reads from crash recoveryby @h3c-hexin4h agomerged#5330fix(session): separate snapshot reads from crash recoveryby @Hmbown4h agoopened#5336fix(mcp): omit nextCursor when there are no further pagesby @xiaoray-blip4h agoopened#5335serve --mcp responds to tools/list and resources/list with "nextCursor…by @xiaoray-blip4h agoopened#5334docs(i18n): retire the stale zh-Hant partial-pack declarationby @Lstarsky05h agoclosed#5321feat: register OrcaRouter as a named providerby @XiaoHuo888-hue5h agomerged#5332feat(config): register OrcaRouter as a named providerby @Hmbown5h agoclosed#5314Copy message from context menu includes rail decorations (● ▏) — make …by @maimik6h agoclosed#5319fix(tui): copy messages without visual railsby @XhesicaFrost6h agomerged#5331fix(tui): copy messages without visual railsby @Hmbown6h agoclosed#5267v0.9.5: turn-stop honesty (status that says ending must end)by @Hmbown7h agoopened#5333feat(tui): pin host terminal window as an always-on-top mini windowby @Hmbown7h agoreleasedv0.9.69h agoopened#5323**Regression in v0.9.5: Auto-Review mode silently blocks every Bash ca…by @USTHzhanglu16h agoopened#5322Regression: output area doesn't fill wide terminals (worked in v0.8.65…by @M-Maciej22h agoopened#5316EPIC-005: CodeWhale TUI Crate Decomposition (Umbrella)by @aboimpinto2d agoopened#4949Discussion: The Chinese Translation of "Constitution" — "宪法", "协作准则", …by @SparkofSpike16d ago

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

Bring the model you already use — hosted, gateway, or local. Plan / Act / 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 → first Fleet workflow. 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. Run a first Fleet workflow

    For durable workers, ordered phases, or receipts, author a reusable agent-team profile and launch a run. Fleet state lives in the workspace ledger; ordinary single tasks need none of this.

    codewhale fleet init
codewhale fleet run tasks.json --max-workers 4
    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.

40 provider routes
Hosted, gateway, and local models
Plan · Act · 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.