An open-source coding agent for your terminal that works with any model.
Give Codewhale a task and it reads the repository, edits files, and runs
commands until the task is done or it needs input from you. It works with more
than 40 built-in providers, DeepSeek V4.1 Flash by default, and with models running on
your own machine. /receipts lists the files it changed, the commands it ran,
and the web and MCP calls it made.
A 0.10.2 development build with a scripted test model, in Full Access inside a throwaway workspace. The edit, three tests and a sub-agent review ran for real.
Install
macOS and Linux:
curl -fsSL https://codewhale.net/install.sh | sh
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
Commit or stash your work, then run codewhale from the root of a git
repository. By default it applies file edits there without asking and
shows you the diff.
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.
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 (in 0.10.1, run /trust on first). /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.
Switch with
Options
Mode
Tab (when the input is empty) or /mode
Plan reads and searches but changes nothing. Work edits files and runs commands. Operate has the same access as Work, treats your request as a goal, and keeps going until the goal is verified or it needs input from you.
Permission
Shift+Tab
Ask applies file edits in your repository without asking and asks before shell commands that are not read-only. Auto-Review lets rules and a reviewer model approve routine calls and refuses high-risk ones; switch to Ask to approve those yourself. Full Access never asks and turns off Codewhale's sandbox; repository rules and managed policy still apply.
These are merged on main and not in a published release yet;
build main to try
them now.
/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 ends with open steps, 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; in 0.10.1 it
needs /trust on for files and steps back one tool call at a time. /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 bundled 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
Command
What it does
codewhale
The interactive terminal app
codewhale exec "…"
One task without the interface. On its own it answers without using tools; --auto enables tools with Full Access by default, --sandbox workspace-write restricts them, and --output-format stream-json streams events as JSON
An advisory review of a GitHub pull request. It posts nothing unless you add --post; the GitHub Action runs the same review in CI
codewhale app-server --http
The Runtime API, a local HTTP API for threads, events, approvals, and each turn's file changes
codewhale serve --acp
The Agent Client Protocol over stdio, for editors such as Zed
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.
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.
