Reading the repo
Opening the box…
Reading the repo
Opening the box…
How to install on Windows
Coding agent for DeepSeek models that runs in your terminal
Saved setup from 10 h ago
Will it work on Windows?
Also: In the browser ↗
Heads-upBuilding it yourself? It also needs 51 settings in .env (5 secret).
docs/INSTALL.md阅读简体中文版:zh_hans/INSTALL.md
Codewhale is an open-source coding agent that runs in your terminal. You give it a task ("fix the failing test", "add a CLI flag"). It reads your repository, edits files and runs commands. In the default Ask posture it applies file edits inside the workspace immediately (and shows you the diff), but asks before running shell commands, so commit or stash anything you care about first. It works with many model providers. DeepSeek is the default.
The command is codewhale. codew is a shorter alias for the same program.
The installation paths were first checked with v0.10.0 (released 2026-09-22) on a fresh Ubuntu 24.04 x86_64 machine. The dated install receipts record the commands and output checked at that time. Steps that could not be run on that machine are marked (untested on this VM: reason). macOS, Windows and Android are out of scope, apart from a few notes. A second pass re-ran the installer, manual-download, archive and npm paths, the no-key checks and zsh completion on macOS 26.1 (Apple silicon); see macOS notes. Steps that need a model call were not re-run there.
Install commands that use latest resolve to the latest published GitHub
Release or package. Between releases, main may already describe the next
version (for example a v0.10.3 source candidate before its tag). A
prebuilt candidate is available through the official installer only after its
tag, checksums and release assets exist. Contributors can build main now.
Codewhale needs no account. Keys you save with /provider or
codewhale auth set stay on your machine; see
API keys and providers. New Codewhale accounts
are not open, so this guide does not cover account key storage.
latest selects the latest published release. To test unreleased repairs,
build canonical GitHub main, or CNB main after verifying its commit matches.
The source version number alone does not establish a published package.
git clone --branch main https://github.com/codewhale-hq/CodeWhale.git
cd CodeWhale
cargo build --release --locked -p codewhale-cli
target/release/codewhale --version
See the Cargo section for build prerequisites; use the repository's stable Rust
selection (declared minimum 1.89). Windows uses target/release/codewhale.exe
and needs MSVC. A development build is separate from a signed release package.
For mainland-China downloads and source validation, see CNB mirror.
The Tencent Lighthouse bootstrap is
bilingual. An npm registry mirror serves the wrapper; native binary downloads
still need an available release asset source.
# 1. Install. Downloads two checksum-verified binaries into ~/.local/bin (no sudo).
curl -fsSL https://codewhale.net/install.sh | sh
# 2. Make sure ~/.local/bin is on your PATH, now and in future terminals.
printf '%s\n' '# >>> codewhale PATH >>>' 'export PATH="$HOME/.local/bin:$PATH"' '# <<< codewhale PATH <<<' >> ~/.bashrc # zsh: use ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"
codewhale --version # -> codewhale 0.10.0 (1be1a703b975)
# 3. Give it a DeepSeek API key (from https://platform.deepseek.com/api_keys).
codewhale auth set --provider deepseek # prompts for the key; nothing is echoed
codewhale auth status --provider deepseek # "active source: secret store"
# 4. Run your first task inside a git repository.
cd ~/your-project
codewhale
In the TUI, type something concrete:
create a Python file primes.py that prints the first 10 primes, run it, and show me the output
Codewhale writes the file, shows you a diff, then asks APPROVAL: bash
python3 primes.py – Do you want to proceed? Press y to allow it once. It
runs the command and reports the output. Press Ctrl-D (with an empty input
box) to quit. It prints the command to resume the session later.
If nothing happens after you send your first message, you have no key configured. v0.10.0 doesn't warn you in that case. Press F3. If DeepSeek shows
missing key, press Enter, paste the key, then pick a model and confirm.
| You need | Why |
|---|---|
| Linux x86_64 or arm64, or macOS | Prebuilt binaries exist for these. The Linux binaries are static (musl), so they have no glibc or libdbus dependency and run on any distro. |
| HarmonyOS PC | Run the Linux ARM64 build inside the Linux subsystem (融合开发引擎), or build natively for aarch64-unknown-linux-ohos and sign it; see HarmonyOS and OpenHarmony. |
| curl (or wget) and sha256sum (or shasum) | The installer uses them to download and verify. |
| A model provider key, e.g. DeepSeek | Codewhale does nothing useful without a model. |
| git (recommended) | Codewhale works best inside a git repository. |
| Optional: Python 3, Node.js 20+ | If present, Codewhale enables its Python and JS execution tools (codewhale doctor lists them). |
Which install path?
codewhale update.Pick one. Several installs on one machine end up fighting over PATH (see Troubleshooting).
Privacy note: Codewhale sends aggregate usage counts (PostHog) by
default. To turn this off permanently:
codewhale config set telemetry false, or export CODEWHALE_TELEMETRY=0,
which always wins. The TUI also checks GitHub for updates at startup
([update] check_for_updates in ~/.codewhale/config.toml).
<a id="recommended-official-github-releases"></a>
curl | sh)Prerequisites: curl, sha256sum (Linux) or the built-in shasum (macOS),
a writable home directory. No sudo, no Node, no Rust.
curl -fsSL https://codewhale.net/install.sh | sh
What it does (verified):
linux-x64, linux-arm64, macos-x64,
macos-arm64). It refuses Android/Termux and riscv64 with a clear message.codewhale-<platform> and codewhale-artifacts-sha256.txt from
the latest GitHub Release. When the codewhale and codew manifest entries
have the same digest, it reuses that verified download for both command names;
otherwise it downloads and verifies codew-<platform> separately. If either
entry doesn't match, it stops before installing anything (codewhale install: checksum mismatch for …).~/.local/bin/codewhale and ~/.local/bin/codew from the
verified release bytes as two separately managed files. When both manifest
entries match, the download staging step uses a hard link when possible and
a temporary copy otherwise./usr/bin,
~/.cargo/bin, Homebrew and MacPorts bin directories, node_modules,
/nix/store…), into your home directory or /, or into a directory that
other users or groups can write (chmod go-w <dir> fixes one you own). It
also refuses to overwrite a different existing codewhale unless you ask
for it with CODEWHALE_FORCE_REINSTALL=1 (see re-running the
installer).Expected output:
Installing Codewhale for linux-x64
Release assets: https://github.com/codewhale-hq/CodeWhale/releases/latest/download
Install dir: /home/you/.local/bin
Checksums verified
Installed checksummed release commands:
/home/you/.local/bin/codewhale
/home/you/.local/bin/codew
…
PATH selects no codewhale command; this install is /home/you/.local/bin/codewhale
…
Put /home/you/.local/bin first on PATH in future shells (run once; this installer does not edit shell profiles):
printf '%s\n' '# >>> codewhale PATH >>>' 'export PATH="$HOME/.local/bin:$PATH"' '# <<< codewhale PATH <<<' >> ~/.bashrc
The marker lines let codewhale uninstall remove exactly this block; a bare export line is yours and is never touched.
Then run: . ~/.bashrc (or open a new terminal)
…
Re-checked on macOS 26.1, Apple silicon (macos-arm64), with a fresh HOME:
Installing Codewhale for macos-arm64, verified
checksums with the system tools, and installed codewhale and codew
(64 MiB each, Mach-O arm64) in 4.3 s. Both report
codewhale 0.10.0 (1be1a703b975). They ran without a Gatekeeper prompt.PATH, it also prints Computer Use is included and needs Node.js 20 or newer on PATH. The core TUI works without Node, but Computer Use
and the JavaScript execution tool (js_execution) stay unavailable until Node
is on PATH.codewhale doctor behaves as on Linux (exit 0, All checks complete! with no
key, file-based secret store under ~/.codewhale/secrets/), except that it
reports ✓ sandbox available: macos-seatbelt.If the installer says PATH selects no codewhale command, ~/.local/bin isn't
on your PATH in this shell. The codewhale.net/install.sh installer then
prints the matching line from the block below for your $SHELL (zsh, bash,
fish, or a POSIX sh; for any other shell, or a directory name with quotes,
$, backticks or backslashes, it tells you to add the directory yourself). It
never edits a shell profile itself. The install.sh inside a release archive
prints only the current-shell export line. On Ubuntu and Debian, ~/.profile adds
~/.local/bin, but only if the directory existed when you logged in. So:
bash: codewhale: command not found in Ghostty right after installing.Fix it once:
printf '%s\n' '# >>> codewhale PATH >>>' 'export PATH="$HOME/.local/bin:$PATH"' '# <<< codewhale PATH <<<' >> ~/.bashrc # bash (macOS login bash: ~/.bash_profile, or ~/.profile if only that exists)
# printf '%s\n' '# >>> codewhale PATH >>>' 'export PATH="$HOME/.local/bin:$PATH"' '# <<< codewhale PATH <<<' >> ~/.zshrc # zsh
# fish_add_path ~/.local/bin # fish (untested on this VM)
export PATH="$HOME/.local/bin:$PATH"; hash -r
command -v codewhale codew
The three-line block is marked so codewhale uninstall can remove exactly it later. A bare
export PATH=… line is yours: uninstall never touches it, because other tools share ~/.local/bin.
# Choose the directory (must be absolute; created if missing)
curl -fsSL https://codewhale.net/install.sh | CODEWHALE_INSTALL_DIR="$HOME/.local/codewhale/bin" sh
# Install a specific release
curl -fsSL https://codewhale.net/install.sh | CODEWHALE_VERSION=v0.9.13 sh
# Show help
curl -fsSL https://codewhale.net/install.sh | sh -s -- --help
codewhale --version # codewhale 0.10.0 (1be1a703b975)
codew --version # same
codewhale doctor # diagnostics; see the note in §8 about what it does NOT check
Already installed: … and exits 0.codewhale, codew and receipt move to
~/.codewhale/recovery/<UTC stamp>/ (kept 30 days, never left beside the
commands on PATH), the new release is installed with a fresh receipt, and the
last lines print the undo command
(codewhale doctor --restore <stamp>) and a short report of any other copies
on the machine (codewhale doctor --installs --brief).CODEWHALE_FORCE_REINSTALL=1 to move a regular file
you own to the recovery folder and install anyway. A managed directory
(npm, Cargo, Homebrew, system paths) is always refused.cargo build reports
0.10.2 (dev)): codewhale update still reinstalls the release artifact
over it, because that build has no release provenance to preserve.codewhale update now.~/.local/bin/codewhale uninstall previews the receipt-owned
files; add --yes to remove them. See §12 for data.Use this when you want to see and verify every byte yourself. Releases:
https://github.com/codewhale-hq/CodeWhale/releases. Each platform has bare
binaries (codewhale-linux-x64, codew-linux-x64, …) and an archive
(codewhale-linux-x64.tar.gz) that holds the same two binaries plus an
install.sh.
mkdir -p ~/codewhale-dl && cd ~/codewhale-dl
base=https://github.com/codewhale-hq/CodeWhale/releases/latest/download
curl -fsSLO "$base/codewhale-linux-x64" # use linux-arm64 on ARM
curl -fsSLO "$base/codew-linux-x64"
curl -fsSLO "$base/codewhale-artifacts-sha256.txt"
sha256sum -c codewhale-artifacts-sha256.txt --ignore-missing
# codew-linux-x64: OK
# codewhale-linux-x64: OK
mkdir -p ~/.local/bin
install -m 755 codewhale-linux-x64 ~/.local/bin/codewhale
install -m 755 codew-linux-x64 ~/.local/bin/codew
Then put ~/.local/bin on PATH and run
codewhale --version. On macOS the assets are codewhale-macos-arm64 and
codew-macos-arm64 (-macos-x64 on Intel), and the built-in shasum verifies
them (tested on macOS 26.1, Apple silicon):
/usr/bin/shasum -a 256 -c codewhale-artifacts-sha256.txt --ignore-missing
# codew-macos-arm64: OK
# codewhale-macos-arm64: OK
The codewhale-macos-arm64.tar.gz archive verifies the same way against
codewhale-bundles-sha256.txt, and its ./install.sh installs into
~/.local/bin (tested).
To pin a release, replace latest/download with download/vX.Y.Z, and take
the manifest from the same tag.
cd "$(mktemp -d)"
base=https://github.com/codewhale-hq/CodeWhale/releases/latest/download
curl -fsSLO "$base/codewhale-linux-x64.tar.gz"
curl -fsSLO "$base/codewhale-bundles-sha256.txt" # note: *bundles*, not *artifacts*
sha256sum -c codewhale-bundles-sha256.txt --ignore-missing
# codewhale-linux-x64.tar.gz: OK
tar -xzf codewhale-linux-x64.tar.gz
cd codewhale-linux-x64 && ./install.sh # -> ~/.local/bin; PREFIX=/some/dir ./install.sh -> /some/dir/bin
The archive's install.sh never uses sudo, leaves differing existing files
alone, never edits a shell profile, and asks nothing; it prints only the
current-shell export line.
Upgrade: codewhale update works for both 3a and 3b, because they're
"direct binary" installs. Uninstall: delete the two files (see §12).
Prerequisites: Node.js 18+ and npm, with a global prefix you can write to. npm installs the registry's latest published version, never an unpublished source candidate.
npm install -g codewhale
codewhale --version
The package is a small wrapper. Its postinstall step downloads the same
codewhale/codew release binaries, checks them against the release's SHA-256
manifest, and links codewhale and codew into npm's global bin. The whole
thing took 6 s here.
Windows npm sessions: Node remains the native program's launcher for the
whole session. A process-name kill such as taskkill /IM node.exe or
Get-Process node | Stop-Process -Force can interrupt this and other npm
Codewhale sessions and prevent normal terminal cleanup. Stop only the server
PID you started or the process owning its port, or use Codewhale's task
cancellation. The Windows
native archive/installer avoids this npm-parent dependency; this does not
remove Node requirements for optional JavaScript tools. Codewhale's Windows
shell safety floor holds recognized image-wide Node kills even in Full Access.
An external hard kill or an arbitrary program that terminates the launcher
cannot be made graceful by this shell-command check.
EACCES: permission deniedThat means Node is installed system-wide (apt, /usr/local, /opt), and your
user can't write to its global prefix:
npm error code EACCES
npm error Error: EACCES: permission denied, mkdir '/opt/node22/lib/node_modules/codewhale'
Don't use sudo npm. Either use a per-user Node (nvm, fnm, volta), or
point npm at a directory you own. I tested the second option:
npm config set prefix "$HOME/.npm-global"
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
export PATH="$HOME/.npm-global/bin:$PATH"
npm install -g codewhale
command -v codewhale codew # ~/.npm-global/bin/codewhale, ~/.npm-global/bin/codew
--foreground-scripts to see it
(codewhale: selected GitHub Releases for v0.10.0 … done.). The chosen
source is also written to
$(npm prefix -g)/lib/node_modules/codewhale/bin/downloads/codewhale.source.npm install -g --prefix <dir> codewhale) took 3 s and linked
codewhale and codew, both codewhale 0.10.0 (1be1a703b975).npm install -g codewhale@latest. codewhale update refuses
on npm installs. It prints migration instructions and exits 1 with
error: The package-managed executable was not changed.npm install -g codewhale@0.9.13.npm uninstall -g codewhale. This removes only the program,
not your data (§12).<a id="4-install-via-cargo-any-tier-1-rust-target"></a><a id="7-build-from-source"></a>
Use this if there's no prebuilt binary for your platform, or you want to
compile it yourself. One Cargo package is required:
codewhale-cli installs the codewhale command. npm and prebuilt releases also
expose codew as a convenience name for the same compiled runtime; Cargo does
not create that alias, so add alias codew=codewhale to your shell rc if you
want the short
Then run powershell -ExecutionPolicy Bypass -File .\setup.ps1. It stops at the first error and is safe to run again. Servers and tests aren't started; it lists them at the end. Read it first.
Needs Git: winget install Git.Git
git clone https://github.com/rjaysolamo/DeepSeek-TUI.git cd DeepSeek-TUI
Node.js 22, Rust stable
winget install CoreyButler.NVMforWindows nvm install 22 nvm use 22 winget install Rustlang.Rustup rustup show # installs the pinned toolchain
Fill in secrets: FEISHU_APP_SECRET, CODEWHALE_RUNTIME_TOKEN, DINGTALK_CLIENT_SECRET, TELEGRAM_BOT_TOKEN, WECOM_BOT_SECRET
Copy-Item .env.example .env
npm ci cargo build
npm test cargo test
codewhale from the root of a git
repository. By default it applies file edits there without asking and
shows you the diff./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.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"
No reports for Windows yet.
GitManual AI Agent reads the 20 key files and writes a step-by-step guide for Windows. Once written, it's saved for everyone.