CodeWhale is an open-source terminal coding agent — a TUI and a CLI — for any model, with DeepSeek and open weights first-class. Instructions pile up and conflict: the old spec, a stale handoff, your request, fresh test output. Most agents resolve that by guess. CodeWhale resolves it by rank — a nested constitution: bundled base law, your standing rules, your repo's own law. Enforced in the harness, intact when you swap models.
npm install -g codewhale
Faithful excerpts from a real session — the constitution is observable in the model's reasoning, not a claim on a landing page.
The base law. Its priority article fixes the authority order for any conflict.
Your standing law — drafted at first launch with your model's help, ratified by you, carried across projects.
Protected invariants, branch policy, verification, escalation — above project instructions, memory, and handoffs.
Approval, sandbox, network, and trust controls are enforced in code — constitution text never overrides them.
Why law →Three steps: install it, point it at a model key, and run it in a project. The install guide walks through each one.
One npm line, or Cargo / Homebrew / a direct binary. On mainland China networks, the CNB and Tsinghua Tuna mirrors route around GitHub.
Install guide →codewhale auth set --provider deepseek (or openrouter, anthropic, zai, …). A local vLLM or Ollama box needs no key at all.
Provider list →Type codewhale in a project. Plan mode is read-only by default; press Tab for Agent mode.
Docs →30 providers, one runtime. Bring your own key, no inference markup, no silent model switching. Where things stand right now:
This dispatch is regenerated by DeepSeek V4-Flash on a six-hour cron. Until the cron fills in fresh repo activity, the static links below are the best starting points.
npm, Cargo, Homebrew, or a direct download.
Start with anything labelled good first issue.
What is confirmed, what is being weighed, what is ruled out.
Every install path, key setup, sandboxing, the CNB / Tsinghua Tuna mirrors for mainland China, and troubleshooting.
Install guide →High-frequency questions on models, providers, modes, MCP, skills, and where config lives.
FAQ →Hit a bug or have an idea? Open an issue or pull request on GitHub — the maintainer reads everything personally.
Contribute →This release merged and harvested a large community tranche. The full notes live in the changelog; this keeps the latest public credit surface easy to find.
Some boundaries are worth stating outright. Each line below is true of this codebase and checkable in the source — not a marketing turn of phrase.
It runs locally on your machine — no CodeWhale account, no sign-up. A local vLLM or Ollama model needs no key at all.
Your code and usage stay on your machine; nothing is sent for analytics. The only call it makes on its own is an opt-out check for a newer release, which sends no code.
Bring your own key. Requests go straight to the provider you configured, at the provider's price. No proxy, no margin.
Contributing is MIT in, MIT out. There is no contributor license agreement and no copyright assignment to sign.
The model you pick is the model that runs. Switching is an explicit command; automatic routing is opt-in and shown.
Approval, sandbox, network, and trust are enforced in code. No constitution text — bundled, yours, or a repo's — can loosen them.
The last one is load-bearing and verifiable — enforced in the harness code, not the prose. Read the constitution →
CodeWhale started as one person's DeepSeek side project, and contributors from many countries have shaped it into what it is — the contributor list on every release is the proof. No CLA, no sponsor lockouts, issues triaged in the open, releases cut from main.
“All feedback is a gift.” Something I learned early in teaching, and the way I maintain CodeWhale. Every issue, PR, bug report, or idea is how I understand real use cases and make better decisions.
If you hit something that doesn't work, or want a model that isn't listed — that's the most useful thing you can tell the project.