Codewhale
DeepSeek + MiMo coding agent in terminal
Last verified:
What is Codewhale?
CodeWhale is a terminal-native coding agent designed for open-source and open-weight models, with DeepSeek V4 as its first-class model. It wraps the model in a written Constitution that ranks nine sources of authority explicitly, enabling the agent to arbitrate between user intent, project rules, system defaults, live tool output, and stale memory. The agent streams reasoning blocks, edits local workspaces with approval gates, and uses a tool-feedback loop where non-zero exit codes, type errors, and sandbox denials feed back as correction vectors for self-correction.
Key features include three running modes (Plan for read-only investigation, Agent as the default multi-step mode with approval gates, and YOLO for auto-approve/trust mode), model auto-routing that uses a fast Flash call to route turns to the appropriate model and thinking depth, prefix caching that makes the Constitution roughly 100× cheaper per turn, sandboxing via seatbelt on macOS, landlock on Linux, and restricted tokens on Windows, and bidirectional MCP client/server support. The tool supports DeepSeek native API, OpenRouter, OpenAI, NVIDIA NIM, Novita, Fireworks, sglang, vLLM, and Ollama providers.
CodeWhale is for developers who want an AI coding assistant that runs entirely from the terminal on their local machine, with no telemetry or cloud processing of their code. It is particularly suited for long coding sessions where model drift is a concern, debugging workflows, architecture work, and security reviews. The tool is open source under MIT license with 36.2k stars, 3.1k forks, and 141 contributors on GitHub.
The agent can be installed via npm (recommended, no Rust toolchain needed), Cargo (requires Rust 1.88+), Homebrew on macOS, or direct download from GitHub Releases. Configuration lives at ~/.codewhale/ and includes config.toml for API keys and provider settings. The current version is v0.8.48.
Codewhale pricing
Pricing model: Freemium
CodeWhale is completely free and open source under MIT license. There is no paid tier or subscription. The tool itself is free to download and use. However, users need to pay for API access to the language models they use (DeepSeek API, OpenRouter, OpenAI, etc.). The tool offers model auto-routing that uses deepseek-v4-flash (cheaper) for simple turns and deepseek-v4-pro (more expensive) for coding/debugging/architecture work to optimize costs.
Codewhale pros
- DeepSeek V4 native with reasoning streaming and cache metrics
- Written Constitution prevents model drift during long sessions
- Prefix caching makes Constitution roughly 100× cheaper per turn
- Tool-feedback loop enables self-correction from errors
- Three modes: Plan (read-only), Agent (default), YOLO (auto-approve)
- Model auto-routing with Fin for efficient model selection per turn
- Runs entirely locally with no telemetry or cloud code processing
- Sandboxing on all platforms: seatbelt, landlock, restricted tokens
- Supports multiple providers: DeepSeek, OpenRouter, OpenAI, Ollama, vLLM
- Open source under MIT license with active community (36.2k stars)
- npm installation requires no Rust toolchain
- Bidirectional MCP client and server support
- Approval mode configurable (suggest/auto/never) orthogonal to run mode
- Audit logging of all credential/approval/elevation events
- Works on Linux, macOS, and Windows
Codewhale cons
- DeepSeek V4 required for full feature set, other models on roadmap
- High token consumption if using Pro for simple queries
- Cache hit rate drops when modifying system prompt or switching models
- Cargo installation requires Rust 1.88+ toolchain
- YOLO mode removes workspace boundaries and should be used carefully
- Hugging Face Hub integration not fully implemented yet
- Some issues with glibc version requirements on FreeBSD
- TUI crashes can leak input to PowerShell terminal
Frequently asked questions about Codewhale
What is CodeWhale?
CodeWhale is a terminal-native coding agent for open-source and open-weight models. It runs from the codewhale command, streams reasoning blocks, edits local workspaces with approval gates, and can auto-route each turn to the right model and thinking level. DeepSeek V4 is the first-class model path, with OpenRouter ready. Hugging Face, self-hosted, and other open-model surfaces are on the roadmap.
How do I install CodeWhale?
Four installation paths are available: npm (recommended, no Rust toolchain needed) with 'npm install -g codewhale', Cargo (needs Rust 1.88+) with 'cargo install codewhale-cli --locked', Homebrew on macOS with 'brew tap Hmbown/deepseek-tui && brew install deepseek-tui', or direct download from GitHub Releases. Run 'codewhale' to start. First run creates ~/.codewhale/ automatically.
What's the difference between codewhale and codewhale-tui?
codewhale is the dispatcher CLI that manages config, auth, updates, and launches the TUI. codewhale-tui is the terminal UI binary that runs the agent loop. When you type 'codewhale', the dispatcher spawns codewhale-tui for you. Both are installed together and you rarely need to think about the split.
Is CodeWhale the same as DeepSeek TUI? What about the rename?
Yes. CodeWhale is the new name for what was previously called DeepSeek TUI. The canonical command is now codewhale. Legacy deepseek and deepseek-tui commands remain as compatibility shims that still work. Config lives at ~/.codewhale/ and DEEPSEEK_* env vars continue to work. The rename reflects CodeWhale's broader mission as the agentic terminal for open models across providers.
How do I set my API key?
Three methods are available: Method 1 uses environment variable 'export DEEPSEEK_API_KEY=sk-...', Method 2 uses saved config (recommended, survives shell restarts) with 'codewhale auth set --provider deepseek --api-key sk-...', and Method 3 adds api_key to ~/.codewhale/config.toml. Use 'codewhale auth status' to check what's active and 'codewhale doctor' for full connectivity check. Saved config keys take precedence over environment variables.
Which providers does CodeWhale support?
CodeWhale ships with these built-in providers: DeepSeek (first-class, native API with reasoning streaming, cache metrics, thinking effort control), OpenRouter (unified API for DeepSeek models and more), OpenAI, NVIDIA NIM, Novita, Fireworks, sglang, vLLM, and Ollama. Set the corresponding env var and provider in ~/.codewhale/config.toml. Hugging Face, ZenMux, and self-hosted OpenAI-compatible endpoints are on the roadmap.
What are Plan, Agent, and YOLO modes?
Plan is read-only investigation that can grep, read files, list directories, and fetch URLs but cannot write or execute shell. Agent is the default mode with multi-step tool calling where shell and side-effect tools require approval based on your approval_mode setting. YOLO auto-approves all operations and enables trust mode with workspace boundaries lifted. Press Tab to cycle modes. Approval mode (suggest/auto/never) is orthogonal to run mode.
What is model auto-routing? What is Fin?
Use 'codewhale --model auto' or '/model auto' to let CodeWhale decide how much model power each turn needs. Fin is the fast non-thinking path (deepseek-v4-flash with thinking off) used for routing decisions, summaries, RLM children, context maintenance, and coordination work. Before the real turn is sent, Fin makes a small routing call to pick the concrete model and thinking level. Short/simple turns stay on Flash, while coding, debugging, architecture, or security review move up to Pro and/or higher thinking.
Is my code safe? What sandboxing does CodeWhale use?
CodeWhale runs entirely on your machine with no telemetry and no cloud processing of your code. Sandbox backends include seatbelt on macOS, landlock on Linux, and restricted tokens on Windows. Workspace boundaries default to --workspace and /trust lifts them. Approval mode is configurable per session. All credential/approval/elevation events are written to ~/.codewhale/audit.log.
How do I update CodeWhale?
Four update methods are available: Release-binary updater works for npm/release-binary installs with 'codewhale update', npm users run 'npm install -g codewhale@latest', Cargo users run 'cargo install codewhale-cli --locked --force', and Homebrew users run 'brew update && brew upgrade deepseek-tui'. If installed via npm, 'codewhale update' downloads the latest release binaries. If a mirror is lagging, download directly from GitHub Releases.