CodeWhale is an open-source terminal coding agent written in Rust that enables users to point a language model at a software project and have it autonomously read code, make edits, run commands, check results, plan multi-step tasks, and correct itself when failures occur. The project began as deepseek-tui, a coding harness built specifically around DeepSeek workflows, but evolved into a multi-provider platform after the developer community, particularly in China, adopted it and contributed fixes that revealed the harness's broader potential. The repository is classified across multiple domains including terminal interface, chatbot, AI assistant, DeepSeek integration, natural language processing, command line tool, interactive chat, text-based UI, language model, and user prompt handling.
CodeWhale operates as both a TUI (terminal user interface) and CLI tool, with installation available through npm for Node 18 and above, cargo for Rust 1.88 and above, or prebuilt archives for every platform including Linux riscv64.
The platform supports an extensive roster of language model providers, treating DeepSeek and open-weight models as first-class citizens while also offering full support for Claude, GPT, Kimi, and GLM through the same unified runtime. Users can point local vLLM, SGLang, or Ollama instances at their LAN without requiring API keys. CodeWhale resolves a real route—a concrete endpoint, wire protocol, model ID, context limit, and price—rather than simply swapping base URLs, enabling route-aware context budgets, honest cost display, and explicit wire protocol handling. The provider registry is documented in docs/PROVIDERS.md and includes hosted open models from deepseek, openrouter, huggingface, moonshot, and numerous others, plus self-hosted options and native adapters for anthropic and openai-codex.
Fleet is CodeWhale's durable control plane for multi-worker runs, recording work in an append-only ledger at .codewhale/fleet.jsonl so tasks survive manager exits, laptop sleep, or runtime restarts. Workers are shaped by roles, profiles, loadouts, and slots, with loadouts expressing model intent as strong, balanced, or fast classes that the route resolver translates into concrete provider and model selections.
Safety is architected into the product through three operational modes—Plan for read-only investigation, Agent for execution with per-action approval, and YOLO for auto-approval—switchable via Tab or /mode command. A .codewhale/hooks.toml hook system gates tool calls, and OS-level sandboxing via Seatbelt on macOS, Landlock plus seccomp on Linux, and bubblewrap where available prevents unintended system modifications. Side-git snapshots enable rollback of agent actions without touching the repository's real git history.
The agent maintains a persistent goal loop where users set objectives with /goal and the agent continues working across turns until completion, blockage, or user intervention. Sessions persist across restarts and system sleep, supporting tasks requiring dozens of tool calls. Headless mode via codewhale exec supports scripts and CI with configurable tool allowlists, denylists, turn limits, and system prompt appending. The project supports MCP bidirectionally, consuming tools from external MCP servers or exposing CodeWhale itself as an MCP server. Reusable workflows called Skills can be loaded from ~/.codewhale/skills/, and the platform is embedded across HTTP/SSE and ACP runtime APIs, VS Code extensions, and Telegram and Feishu bridges.
