CodeWhale

CodeWhale is an MIT-licensed, open-source terminal coding agent built primarily in Rust, maintained by Hmbown on GitHub. It wraps DeepSeek V4 (and other OpenAI-compatible models) in a structured harness that defines authority ordering, live evidence feedback, and approval-gated tool use — all from the command line. As of June 2026, the project reports over 37,000 GitHub stars and is actively developed with frequent releases.

What It Is

CodeWhale is a CLI-based agent harness — not just a chat wrapper — designed to keep a language model oriented through long, multi-step coding sessions. The core idea is that most coding agents fail not from lack of capability but from lack of structure: competing instructions, stale memory, and no clear hierarchy of authority. CodeWhale addresses this with a written "Constitution" that explicitly ranks nine sources of authority (current user message, live tool output, project rules, safety policy, etc.) and uses DeepSeek V4's prefix cache to make that Constitution cheap to reference recursively across turns.

How the Constitution and Feedback Loop Work

Every agent turn, CodeWhale arbitrates between the user's intent, the project's .codewhale/constitution.json, system defaults, live tool output, and stale memory. The Constitution ranks these sources explicitly so the model doesn't have to guess. The feedback half of the loop is equally concrete: non-zero exit codes, type errors from language servers (e.g., rust-analyzer), and sandbox denials are fed back into context as correction vectors, letting the model use its own drift to self-correct rather than silently proceeding.

When running with --model auto, a lightweight routing call at the start of each turn decides whether to use a cheaper Flash model or escalate to a deeper Pro model — keeping short conversations economical and complex coding or architecture work at higher thinking depth.

Autonomy Modes and Tool Surface

CodeWhale ships three operating modes:

• Plan (read-only): the agent can read and reason but not modify files or run commands.
• Agent with approval: every file edit, shell command, git operation, web fetch, MCP call, or sub-agent spawn requires explicit user approval.
• YOLO (auto-approve): all tool calls proceed without interruption.

The tool surface includes file editing, shell execution, git operations, web search (with multiple configurable backends including Bocha, Baidu AI Search, Metaso, and Sofya), MCP (Model Context Protocol) integration, sub-agent spawning for parallel investigation, side-git snapshots with /restore rollback, and a runtime HTTP/SSE API for editor and GUI integration.

Model and Provider Support

DeepSeek V4 is the primary and first-class model, but CodeWhale maintains explicit provider paths for OpenRouter, NVIDIA NIM, Xiaomi MiMo, Arcee, SiliconFlow, Fireworks, Novita, Together AI, Volcengine, self-hosted SGLang/vLLM, Ollama, and generic OpenAI-compatible gateways. The v0.8.55 release added dedicated Together AI support and expanded the OpenRouter model catalog with Qwen 3.7 Max and Qwen 3.6 Plus entries.

Update: v0.8.55 — Together AI, OpenAI Codex, Model Catalog

The latest release, v0.8.55 (published June 9, 2026), is titled "Together AI, OpenAI Codex, Model Catalog." Active development on the v0.9.0 track is ongoing, gathering work around stronger relay and handoff surfaces, calmer transcripts for dense tool runs, runtime APIs for VS Code and GUI clients, typed HarnessProfile posture and model routing, and WhaleFlow branch/leaf workflow orchestration. The project lists 147 contributors and ships with a multi-language README (English, Simplified Chinese, Japanese, Vietnamese).

Installation and Setup Path

CodeWhale is installable via Cargo (cargo install codewhale-cli --locked), npm (npm install -g codewhale), Homebrew, GitHub Releases binary archives, a CNB mirror for users in China, Windows Scoop, Nix, and Docker. On first launch it prompts for a DeepSeek API key stored at ~/.codewhale/config.toml. The codewhale doctor command verifies the setup. Config lives at ~/.codewhale/ and repositories can add .codewhale/constitution.json for durable project-level authority rules.