codewhale

The installer puts checksum-verified codewhale and its short alias codew in ~/.local/bin. If your shell then says command not found, run the PATH line the installer prints (details). codewhale update upgrades it. These commands install the latest release. This page follows main, so a feature marked with a version arrives in that release; the changelog lists what each release adds.

Windows, npm, Cargo, and other ways to install

winget install HunterBown.CodeWhale  # Windows x64 (or Scoop, or the installer from GitHub Releases)
npm install -g codewhale            # wraps the same release binaries
cargo install codewhale-cli --locked  # crates.io; can trail GitHub Releases

Prebuilt binaries cover Linux, macOS, and Windows on x64 and arm64. Nix, Homebrew on Linux, Android/Termux (preview), and manual downloads are in the installation guide, and containers in Docker. Stick to one install method per machine; otherwise two copies end up on PATH and whichever comes first wins.

Quickstart

1. Commit or stash your work, then run codewhale from the root of a git repository. By default it asks before each file edit and command; press Shift+Tab once for Accept Edits to let it edit files in the repository without asking.
2. Run /provider (or press F3), pick a provider, paste its API key, and choose a model. DeepSeek is the default provider. With no key, pick a local runtime instead. If no provider is configured and Ollama is already serving a chat model, Codewhale uses it automatically; from 0.10.2 it offers it when you send your first message.
3. Type a task:

Fix the failing tests and explain what changed.

Read-only commands run straight away. For any other shell command Codewhale asks first: y runs it once, a allows commands like it for the rest of the conversation, n refuses. /undo takes back your last request and its file changes. /help lists commands and keys.

For scripts and CI, codewhale exec runs one task without the interface. By default, --auto uses Full Access: tools run without asking, shell commands have no Codewhale sandbox, and trust mode lets file tools write outside the workspace. Add --sandbox workspace-write to keep the shell sandbox and file-tool workspace restrictions, with trust mode off:

codewhale exec --auto --sandbox workspace-write "fix the failing tests and explain what changed"

Modes and permissions

A fresh install starts in Work mode with the Ask permission.

See the modes and permissions guide for the details.

What it does

New in 0.10.2

• /pet on turns your terminal into an animated whale that shows what the agent is doing, while the message box stays live. Its 980 particles spell the current step in English, Chinese or Japanese.
• /workbar terminal shows the shells the agent is running as they run. Type into one, or press Ctrl+N for a shell of your own (macOS and Linux).
• /undo takes back your whole last request in one step, including every file it changed, and /diff works in folders without Git.
• When a plan is ready, Codewhale asks whether to start Work with Ask or Auto-Review, or keep planning.
• /color gives each chat its own composer color, saved with the session.
• web_search can use DeepSeek's new Search API: set [search] provider = "deepseek" with a DeepSeek key.
• Outside Full Access, a curl or wget that would upload a credential never runs without your approval, and a command that hides invisible Unicode is refused. write no longer replaces a file the agent has not read, or one that changed after it read it.

Models

More than 40 providers are built in, including Anthropic, OpenAI, DeepSeek, Google, Mistral, Moonshot, OpenRouter, and xAI. Any OpenAI-compatible endpoint works, and so do local models through Ollama, vLLM, or SGLang. The default is DeepSeek's deepseek-flash, which DeepSeek moved to DeepSeek-V4.1-Flash-1017 on 2026-10-17; 0.10.1 runs it without an update (details).

/model switches models between turns, and /model auto picks one for each turn (/router sets up how). /turn inspect shows which model a turn used, what it cost and how long it took. codewhale auth chatgpt lets you use a ChatGPT plan instead of an API key (experimental). See Providers.

Receipts and undo

/receipts, or codewhale receipts --last after you quit, lists the files changed, commands run, web and MCP calls, agents started, approvals and who gave them, and failures. /undo takes back your last request and the files it changed, in one step and without trust mode. /restore rolls the whole workspace back to an earlier snapshot; because that overwrites later edits, it needs /trust on or Full Access. See Receipts.

Exec runs that offer tools are saved in every output format, so codewhale receipts --last works after exec --auto, including --json. Answer-only text and --json runs are saved only when resuming or when conversation compaction starts; use --output-format stream-json to always save them for receipts or exec --continue.

Longer work

/goal sets an objective that carries across turns. Codewhale can split work across sub-agents, run a fleet of agents, or follow a workflow checked into the repository.

Coming from another agent

Codewhale reads AGENTS.md on its own. Instruction files written for other tools, such as CLAUDE.md, .cursorrules, or .github/copilot-instructions.md, load only when you opt in with project_instruction_imports = ["claude"] (or "cursor", "cline", "windsurf", "copilot", "all") in your config; see config.example.toml. Codewhale warns when it finds one it did not load.

/import-claude prepares an import of your Claude Code settings and MCP servers for you to review. /plugin install accepts Claude Code plugins containing skills, commands, agent profiles, and MCP servers, and refuses plugins that need hooks or LSP servers (details).

Extensions

Connect MCP servers, add skills and plugins, and run hooks on session and tool events. Code mode (experimental, on by default) lets the model write one execute_tools program that calls several MCP and plugin tools; each call still meets your approval rules and keeps its receipt. The independently installed Computer Use plugin (experimental, macOS only) can observe and operate other apps. It stays off until you review its access and enable it (guide).

Ways to run it

The terminal app, exec, web, and the Runtime API share one engine (architecture). A community-maintained VS Code extension connects to it from the sidebar (source). A native desktop app built on the Runtime API is in development; it has no public download yet.

Cost and accounts

Codewhale is free and MIT licensed. With your own API key you pay the provider directly; local models need no key. The footer and /cost show what a session has cost when the price is known, and an unknown price is shown as unknown, never as free.

You don't need an account. Keys you add with /provider stay on your machine.

Safety and privacy

In Ask and Auto-Review, commands run in an OS sandbox where the system has one: Seatbelt on macOS, and bubblewrap on Linux when it is installed. Windows has no OS sandbox yet, and Full Access turns the sandbox off. Inside the sandbox, shell commands cannot read credential stores such as ~/.ssh, ~/.aws and .env files; from 0.10.2 the same rule covers terminal sessions and more file tools. /preview-request shows a redacted preview of the next request without sending it.

Telemetry is on by default. It sends aggregate counts (version and platform, session length and outcome, which built-in providers you used, feature and error counts) with a random install ID that rotates every 90 days, and never conversations, code, prompts, model names, file or repository names, or credentials. codewhale config set telemetry false turns it off. At startup Codewhale also checks GitHub for a new release; set CODEWHALE_NO_UPDATE_CHECK=1 to skip that. More in authorization order, sandboxing, and telemetry.

Documentation

Community

If a provider is missing or a workflow is awkward, open an issue or send a pull request. Contributors keep credit for the work that lands, and the repository layout shows where things live.

Chat on Discord, or add the maintainer, Hunter, on WeChat (hunterbown) and ask to join the Whale Brothers group.

History and license

Codewhale started as deepseek-tui and still reads that project's configuration and sessions. It is independently maintained and not affiliated with DeepSeek or any other model provider. Thanks to everyone who has contributed.

MIT. Code adapted from other open-source projects is listed in the third-party notices.