Faites de votre agent le vôtre dès aujourd’hui.

Installez Codewhale et lancez-le dans un dépôt avec une clé de modèle que vous avez déjà ou un modèle sur votre propre ordinateur. Vous n’avez besoin d’aucun compte, et codewhale update le tient à jour.

curl -fsSL https://codewhale.net/install.sh | sh

View install script

This installs the latest published release, v0.10.2.

New to the terminal?

You install Codewhale by pasting one command into a terminal. These steps show how to open one and how to check that it worked.

macOS

  1. Press Cmd+Space, type Terminal and press Return.
  2. Paste this command with Cmd+V and press Return:
    curl -fsSL https://codewhale.net/install.sh | sh
  3. When it finishes, open a new window with Cmd+N, type codewhale --version and press Return. A version number means it worked.

Windows

  1. Open the Start menu, type PowerShell and press Enter.
  2. Paste this command with Ctrl+V and press Enter:
    winget install --id HunterBown.CodeWhale --exact --source winget
  3. When it finishes, close the window, open PowerShell again, type codewhale --version and press Enter. A version number means it worked.

Read the first-time guide: which folder to work in, your first task, and how to undo

What the installer does to your PATH

The installer puts codewhale and codew in ~/.local/bin. When that folder is not on your PATH, it adds three marked lines to the startup file for your shell:

  • zsh: ~/.zshrc, or .zshrc in $ZDOTDIR when you set it.
  • bash on Linux: ~/.bashrc.
  • bash on macOS: ~/.bash_profile, or ~/.bash_login or ~/.profile when one of those exists and ~/.bash_profile does not.
  • sh, dash, ksh and other POSIX shells: ~/.profile.
  • fish: nothing is edited. The installer prints fish_add_path for you to run.

The three lines are:

# >>> codewhale PATH >>>
export PATH="$HOME/.local/bin:$PATH"
# <<< codewhale PATH <<<

The installer prints them and a command that removes them, and changes nothing else in the file. It does not edit your profile when the folder is already on your PATH. Shells that are already open do not reread the profile, so run this line in the shell you installed from, or open a new terminal:

export PATH="$HOME/.local/bin:$PATH"; hash -r

To leave your startup file alone, run the installer with --no-modify-path, or set CODEWHALE_NO_MODIFY_PATH=1:

curl -fsSL https://codewhale.net/install.sh | sh -s -- --no-modify-path

Then add this line to your shell's startup file yourself. Use ~/.bashrc for bash. For fish, run fish_add_path ~/.local/bin.

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

Check that it worked

Run this in a shell that has the PATH line. It prints codewhale 0.10.2 followed by a short commit id in parentheses.

codewhale --version

Optional. Mark this only after the command prints a Codewhale version. This is your confirmation, not an automatic installation test.

Your first task

  1. Run codewhale in a git repository.
  2. Type /provider before your first message and choose a provider, or paste a Custom endpoint.
  3. Give it a small task. It asks before it runs a command. Then type /receipts to read what it did, and /cost to see what it cost or why the cost is unknown.

Read the quickstart

Usage counting

Usage counting is on by default. Run codewhale config set telemetry false to turn it off.

codewhale config set telemetry false

The installer runs codewhale when it finishes. To turn counting off for that run, set CODEWHALE_TELEMETRY=0 for the installer:

curl -fsSL https://codewhale.net/install.sh | CODEWHALE_TELEMETRY=0 sh

What is counted

Update

Run codewhale update. If you installed with npm, Cargo or Homebrew, update with that tool instead, as shown below.

codewhale update

Remove it

Removal for v0.10.2: delete the program files.

rm -f ~/.local/bin/codewhale ~/.local/bin/codew ~/.local/bin/.codewhale-install.sha256

Then delete the three lines from # >>> codewhale PATH >>> to # <<< codewhale PATH <<<, inclusive, from the startup file the installer named.

~/.codewhale holds your settings, sessions and any keys you saved. Delete it only if you want them gone:

rm -rf ~/.codewhale

The v0.10.2 guide also lists ~/.deepseek/snapshots and each repository's .codewhale folder as places Codewhale writes.

If something goes wrong

  • If your shell says codewhale: command not found, it has not picked up the PATH line yet. Run the line shown above in that shell, or open a new terminal.
  • If messages say they were saved for later after you connect, quit with Ctrl+D and run codewhale again.
  • A Custom (OpenAI-compatible) row in /provider may show "legacy ! provider admission failed" although the endpoint works.

More fixes

Other ways to install

Each channel updates and removes with its own tool. The steps here are the ones in the v0.10.2 guide.

Windows

winget install --id HunterBown.CodeWhale --exact --source winget

Open a new terminal and run codewhale --version.

The winget package is for Windows x64 and can lag behind GitHub releases. On Windows ARM64, use npm under native ARM64 Node.js.

Windows has no operating-system sandbox yet. In Ask, Codewhale asks before shell commands that are not read-only.

Update with winget upgrade HunterBown.CodeWhale, or with npm if you installed with npm. Remove it with winget or with npm, whichever installed it.

npm

npm install -g codewhale

npm needs Node.js 18 or newer and a global folder you can write to, and that folder's bin must be on your PATH. On Windows, Node stays the launcher for the whole session, so do not stop it by process name.

If npm stops with EACCES, do not use sudo. Point npm at a folder you own:

npm config set prefix "$HOME/.npm-global"
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
export PATH="$HOME/.npm-global/bin:$PATH"

Update with npm install -g codewhale@latest. Remove the program with npm uninstall -g codewhale; it leaves ~/.codewhale.

Cargo

cargo install codewhale-cli --locked

Cargo builds from source. It needs current stable Rust, and on Linux libdbus-1-dev and pkg-config. It installs codewhale only, with no codew. Install codewhale-cli: the Cargo package named codewhale is an older package.

Update with the command below. Remove it with cargo uninstall codewhale-cli.

cargo install codewhale-cli --locked --force

Homebrew on Linux

brew install Hmbown/deepseek-tui/codewhale

The full name taps and trusts in one step. The two-step form fails on Homebrew 7.

Update with brew upgrade codewhale. Remove it with:

brew uninstall codewhale && brew untap Hmbown/deepseek-tui

Mirrors for mainland China

npmmirror serves the npm package. The program it installs still downloads from a release asset source: GitHub, or the CNB mirror, which the npm package tries on Linux x64.

The CNB mirror carries the source of each release tag and, for tags it has built, Linux x64 binaries with a checksum manifest. A mirrored source tag is not a binary release, so confirm the version you want has binaries and a manifest, then verify the download:

sha256sum -c codewhale-artifacts-sha256.txt --ignore-missing

Read the mirror guide

Read the full installation guide on GitHub