A 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 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.

Website · Documentation · Changelog · Contributing

简体中文 · 日本語 · Tiếng Việt · Bahasa Indonesia · 한국어 · Español · Português · Русский · Українська · Français · Deutsch · 繁體中文 · हिन्दी · Türkçe · Italiano · Polski · العربية · Català

_{Captured from a local demo session.}

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.

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  # build from crates.io

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 applies file edits there without asking and shows you the diff.
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.
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 reverts your last request and its file changes. /help lists commands and keys.

For scripts and CI, codewhale exec runs one task without the interface. With --auto it edits files and runs shell commands without asking, so give it a container or a throwaway checkout:

codewhale exec --auto "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.

See the modes and permissions guide for the details.

What it does

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. /model switches models between turns. 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 reverts your last request. /restore rolls the whole workspace back to an earlier snapshot; because that overwrites later edits, it needs /trust on or Full Access. See Receipts.

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. 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 lets it edit files and run commands, and --output-format stream-json streams events as JSON
codewhale web	A local web UI on 127.0.0.1 (guide)
codewhale review --pr N	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, and approvals
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 desktop app is in development; see the product page.

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. With one (codewhale login), you can keep provider keys in your Codewhale account; on another device, sign in and choose Codewhale in /provider to use them. Signing in does not upload keys already 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. /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, feature and error counts) with a random install ID that rotates every 90 days, and never conversations, code, prompts, 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

Start here	Reference
Installation	Configuration
Providers and local models	Architecture
Modes and permissions	Runtime API
Keybindings	Plugin authoring
GitHub PR review	All 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.