README

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.







Website · Documentation · Changelog · Contributing

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



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.




  
    
  


View the Codewhale × OrcaRouter offer. Codewhale earns a referral fee from OrcaRouter.

 Install

macOS and Linux:

bash
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

bash
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:

text
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