Issue 2026-08-13
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#5347fix(release): preserve asset auth for npm publishby @Hmbown39m agoopened#5346Release: npm publish loses GH_TOKEN during prepublish asset guardby @Hmbown39m agoreleasedv0.9.71h agoopened#5345[FR] 增加多行模式或者是允许自定义”发送“快捷键by @AiurArtanis1h agoopened#5344v0.9.7 release parity test times out under shared-runner loadby @Hmbown2h agoopened#5343test(release): tolerate shared-runner route latencyby @Hmbown2h agomerged#5341chore(release): prepare v0.9.7by @Hmbown3h agoopened#5342fix(tui): restore bounded Auto-Review executionby @Hmbown3h agoopened#5328FEAT-014: Command contract crate boundary (facets + shared types) for …by @aboimpintoyesterdayopened#5324agent tool: simplify the 32-field schema so models stop erroring on itby @Hmbownyesterdayopened#5312Replace hardcoded archive timestamps with SOURCE_DATE_EPOCHby @LmeSzinc4d agoopened#5299release: move npm publication to trusted publishingby @Hmbown5d agoopened#5290fix(web): restore clickable controls on non-English routesby @Hmbown5d agoopened#5288Website: retire fully-merged codex/website-polish + close the manual-d…by @Hmbown5d agoopened#5087Bound diff rendering by view context without materializing the full wr…by @Hmbown11d agoopened#5060Workflow experimental search re-hardcodes a 16-worker ceiling instead …by @Hmbown11d agoopened#5055DeepSeek Pro effort mapping is hardcoded inline with no date-annotated…by @Hmbown11d agoopened#5053TUI never tells the user an update exists; add update notice + one-cho…by @Hmbown11d agoopened#4949Discussion: The Chinese Translation of "Constitution" — "宪法", "协作准则", …by @SparkofSpike16d agoopened#4669Stabilize coalesced raw-read working-set test under full parallel CIby @Hmbown23d 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.