CodeWhale is a terminal-native, agentic IDE designed for open-source and open-weight models, with a primary focus on the DeepSeek V4 family. It enables LLMs to interact directly with your local workspace to read and edit files, execute shell commands, manage git state, and coordinate complex sub-agent workflows.
The system is built as a high-performance Rust workspace consisting of 17 crates, providing a robust, keyboard-driven Terminal User Interface (TUI) alongside a headless runtime API. Cargo.toml1-18
CodeWhale utilizes a dual-binary architecture to separate CLI dispatching from the interactive TUI runtime. This separation ensures that the interactive UI remains responsive while the CLI handles lifecycle tasks like updates and environment validation. README.md10-18
codewhale (Dispatcher): The entry point binary (defined in codewhale-cli) that handles command-line arguments, environment resolution, and session management. It dispatches to the TUI or the background server as needed. Cargo.toml5 README.md27codewhale-tui (Runtime): The companion binary (defined in codewhale-tui) that hosts the ratatui-based interface and the core async engine. Cargo.toml16 README.md28The CLI crate also provides short-form and legacy shims to support user muscle memory:
codew: A short-form alias for codewhale. README.md12-13deepseek: A legacy shim for backward compatibility (referencing the project's origin as deepseek-tui). README.md30-34Sources: README.md10-49 Cargo.toml1-20
CodeWhale bridges the gap between high-level reasoning and low-level system execution through several integrated subsystems:
| Capability | Description |
| :--- | : :--- |
| Model Auto-Routing | The Fin router dynamically selects between deepseek-v4-flash and deepseek-v4-pro based on turn complexity. README.md137-141 |
| Thinking Stream | Real-time streaming of model reasoning blocks (CoT) directly in the TUI. README.md3 |
| 1M-Token Context | Advanced context management with prefix-cache stability tracking (FrozenPrefix) and automated compaction. CHANGELOG.md26-28 README.zh-CN.md3 |
| Tool Suite | Native support for file operations, shell execution (PTY), web search, and MCP servers. README.md148-153 |
| Side-Git Rollback | Automatic pre/post-turn snapshots allowing /restore without polluting the project's .git. README.md140-141 |
| Sub-Agents | Parallel execution of up to 20 specialized agents for exploration, planning, and verification. README.md142-146 |
Sources: README.md3-153 CHANGELOG.md26-34 README.zh-CN.md3-130
The following diagram illustrates how the CLI, Engine, and UI components interact with the local filesystem and remote LLM providers.
Sources: README.md150-153 Cargo.toml1-18 docs/ARCHITECTURE.md13-64
To help developers navigate the codebase, these diagrams map conceptual system features to their specific Rust implementations.
Sources: README.md114-119 CHANGELOG.md31-35 docs/ARCHITECTURE.md74-82
Sources: README.md126-130 CHANGELOG.md86-89 docs/ARCHITECTURE.md121-132
For deeper dives into specific areas of CodeWhale, refer to the following child pages:
codewhale doctor health check. README.md10-49 CHANGELOG.md14-17config.toml, environment variables (e.g., DEEPSEEK_API_KEY), and per-project overlays like AGENTS.md. README.md143-153 CHANGELOG.md108-109SandboxPolicy. README.md132-136 docs/ARCHITECTURE.md95Sources: README.md10-153 CHANGELOG.md14-114 docs/ARCHITECTURE.md88-102