Issue 2026-08-26
v0.9.11
Codewhaleany model, on your machine
★ 40.9k
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 the checks, and stops when the job is done or it needs you. Use any model, or a different one for each role.

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

cwLatest release v0.9.11Source v0.9.1145 providersMIT

Codewhale TUISession
Codewhale terminal session in Operate mode: the whale, the composer, and the status footer
Codewhale session · Operate mode · permissions: Ask
实 时LIVE
opened#5630Bug 0.9.12 integration: runtime store owner lockby @M-Maciej11m agoopened#5629fix(tui): persist context pressure warningsby @wuisabel-gif12m agoclosed#5533Feature: the control surface for supervised operationby @M-Maciej1h agoopened#5627Add Xquik to the reviewed MCP recommendationsby @kriptoburak3h agomerged#5623feat(tui): report post-compaction input tokensby @h3c-hexin3h agomerged#5622feat(tui): support Kimi Code k3-256kby @h3c-hexin3h agomerged#5624feat(tui): show live session token totalsby @wuisabel-gif3h agomerged#5619chore(contrib): grant @wuisabel-gif recurring PR accessby @Hmbown4h agomerged#5621fix(tui): make edit-last-turn boundaries authoritativeby @h3c-hexin4h agoopened#5626feat(runtime-api): add per-thread usage endpoint and persist session c…by @gaord9h agoopened#5625Enhancement: non-blocking "pending user input" peek tool for mid-turn …by @ronohara15h agoopened#5620Context pressure warning is transient and the agent does not proactive…by @ronohara19h agoclosed#5608feat(tui): add focused transcript actionsby @wuisabel-gifyesterdayopened#5586Decompose the mega files: lib.rs (18.7k), config.rs (12.3k), client.rs…by @Hmbown3d agoreleasedv0.9.113d agoopened#4956provider Network error: Connection failed: error sending request for u…by @RelicOfTesla29d agoopened#4568新版斜杠指令(/xxx)响应迟缓,性能不如上一版本by @whp233last mo.opened#4564codewhale exec --auto: --model and --toolsets flags consumed as single…by @alozano978-speclast mo.

A coding agent in your terminal. Any model. On your machine.

Use the model you already have — hosted, through a gateway, or local. Pick a mode: Plan, Work, or Operate. Pick how much it does without asking: Ask, Auto-Review, or Full Access.

How it decides

The reasoning, in its own words

Session excerpts. Each shows the project rule the model applied and what it did next.

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, asking first where you told it to.

  3. 03

    Verify

    Run the checks and read the result.

  4. 04

    Report

    Say what changed and what passed.

$ codewhale exec "fix the failing test"inspect   repository and instructionsact       edit files under the permissions you setverify    cargo test --lockedreport    checks passed · summary saved

New here? Four steps.

Install → first session, no key → connect a provider → set up a fleet.

  1. Install Codewhale

    One npm command installs the terminal runtime. Cargo, prebuilt archives, Docker, Nix, and China mirrors also work. All of them install published releases.

    npm install -g codewhale
codewhale doctor
    Full install guide →

  2. Open a first session — no key needed

    Starts without any API key. A short setup, then the full interface. Look around in Plan mode, which is read-only. Model replies need a provider — that's the next step.

    codewhale
    Learn the product nouns first →

  3. Connect a provider

    Use a hosted API key, a gateway, or a local runtime with no key (Ollama, vLLM, SGLang). You pick the provider and the model. A model name never switches the provider for you.

    codewhale auth set --provider deepseek
    Providers and models →

  4. Set up your ideal fleet

    Add each provider you use with one auth set (local runtimes need none). Then run /fleet setup. It goes one member at a time — a semantic role, a model from any configured provider, a thinking tier, then an exact identity/route review — and saves the roster profile for this repo or for every repo on this machine. Runtime permissions stay separate. A single task needs none of this.

    /fleet setup
codewhale fleet status
    Fleet and Workflow docs →
Read the getting-started guide →Look up a term →

Your model.
Your boundaries.

You choose the model, the mode, and how much it may do without asking. The provider and model never change unless you change them. Preview features are marked preview.

45 providers
Hosted, gateway, and local models
Plan · Work · Operate
From read-only planning to autonomous operation
Ask · Auto-Review · Full Access
How much it does before asking you
TUI · exec · web · API
Interactive or scripted

Use it where the work happens.

TUIInteractive terminal work
codewhale execScripts and CI
Web clientBrowser client, localhost only
Runtime API + MCPLocal integrations
FleetSeveral agents on one job
Runtime surfaces and what is stable →

Start with one command.

npm install -g codewhale

CargoBinariesDockerNixWindowsAndroid / TermuxChina mirrors

Read the install guide →

Built in public

MIT license. Contributors work on the runtime, providers, platforms, docs, and tests.