Issue 2026-08-19
v0.9.9
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 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.9Source v0.9.945 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#5518Emergency compaction triggers around ~85K--105K tokens on DeepSeek V4 …by @hxfhd5h agoopened#5517feat(web): move docs/constitution and docs/runtime-api onto the dictio…by @Lstarsky05h agoopened#5516HTTP 400 max_tokens=384000 exceeds model limit after upgrading to v0.9…by @sfdzhmr5h agoopened#5514refactor(tui): extract stream processing from turn loopby @bistack7h agoclosed#894执行过程中出现了图片的的混乱。by @bdbox112h agoclosed#1651VS Code crashes or exits unexpectedly when YOLO Agent is running test …by @HubgitCCL12h agoclosed#1732合并分析报告保存文档巨慢by @yuhg9212h agoclosed#1829SSH 连接失败：exit code 255（疑似 DeepSeek TUI shell 沙箱 TCP 22 出站阻断）by @fodudu122612h agoclosed#1425执行大文本处理工程后会话中断卡死by @AiurArtanis12h agoclosed#1675QUESTION: Chinese garbled characters in Agent real-time outputby @AiurArtanis12h agoclosed#5056Test reliability: flaky verifier background tests, /workspace-sensitiv…by @Hmbown12h agoclosed#5403main is red on both platforms across all four completed runs: plugin_e…by @Lstarsky012h agoclosed#5510docs(readme): restore the star history chartby @OctoBored13h agoopened#5513release: Codewhale v0.9.10 — retention, identity, and durable approval…by @Hmbown13h agomerged#5507docs(i18n): complete Tier 1 of Chinese docs localization (#5482)by @SparkofSpike13h agoopened#5509fix(tui): restore /title as an independent terminal window title (#543…by @SparkofSpikeyesterdayreleasedv0.9.9yesterdayopened#5482EPIC(docs): review, partially restructure, and fully localize document…by @SparkofSpike2d agoopened#5337Web: finish the #4934 dictionary spine — retire every isZh branch and …by @Lstarsky07d ago

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 role at a time — a model from any configured provider, a thinking tier, permissions — and saves a profile for this repo or for every repo on this machine. 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.