Install 安装
curl -fsSL https://codewhale.net/install.sh | sh
codewhale
The macOS / Linux installer downloads SHA-256-verified binaries from GitHub Releases, installs to ~/.local/bin by default, and exposes codewhale and codew as two names for the same compiled runtime. To inspect it first, run curl -fsSL https://codewhale.net/install.sh. See Other ways to install below for npm, cargo, GitHub Releases, CNB, Homebrew, prebuilt binaries, Docker, or mainland China mirrors.
codewhale --version # latest published: 0.9.8 codewhale doctor
codewhale doctor checks your API key, network, sandbox availability, and MCP servers, then prints remediation guidance. Add --json when you need structured output.
codewhale update
curl -fsSL https://codewhale.net/install.sh | sh
Checks GitHub Releases for a newer version and replaces the binary in place. If you installed with install.sh, re-run the same curl command to overwrite the binaries. If you installed via a package manager, prefer it instead: npm users run npm update -g codewhale; Cargo users re-run the one codewhale-cli install command with --force. Cargo installs only codewhale; define your own codew shell alias if you want the shorter name; Homebrew updates with brew upgrade codewhale.
- ① Open a first session — no key needed
Launches without any API key: short constitution-first setup, then the full interface. Explore in Plan mode — always read-only. Model replies need a provider; that's the next step.
codewhale
- ② Connect a provider
Pick a supported route — hosted key, gateway, or keyless local runtime (Ollama, vLLM, SGLang). Provider and model stay explicit; reasoning and routing provenance stay separate, and unavailable values stay unavailable.
Providers and models →codewhale auth set --provider deepseek
- ③ Run it in a project
cd path/to/project codewhale
New sessions use your selected default mode (Act unless you changed it). When the composer is idle, press Tab to cycle Plan → Act → Operate; press Shift+Tab to cycle Ask → Auto-Review → Full Access permission postures. You can also run
/modeto choose a mode or/configto inspect permissions. Plan stays read-only; use Full Access only in a workspace you trust.
Other ways to install
If the script above doesn't fit your setup, choose the channel that matches your environment. Command availability and packaging differ by channel, and each description states exactly what it installs.
Release-backed commands below use v0.9.8, the latest version published on GitHub. The current source candidate is v0.9.9; install commands do not advertise it before publication.
npm install -g codewhale
The npm wrapper downloads SHA-256-verified binaries from GitHub Releases and installs codewhale and codew as two names for the same runtime.
cargo install codewhale-cli --locked
The one codewhale-cli Cargo package installs only codewhale to ~/.cargo/bin. Define your own codew shell alias if you want the shorter name. Requires Rust 1.88+; install via rustup.rs if you don't have it. On Linux, install build dependencies such as pkg-config and libdbus-1-dev first.
# Download your platform archive: https://github.com/Hmbown/CodeWhale/releases/latest
cargo install --git https://cnb.cool/codewhale.net/codewhale --tag v0.9.8 codewhale-cli --locked --force
Official source: GitHub Releases is the sole canonical release source. Cargo via Tsinghua Tuna mirror — add to ~/.cargo/config.toml:
# ~/.cargo/config.toml [source.crates-io] replace-with = "tuna" [source.tuna] registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"
cargo install codewhale-cli --locked
For the npm path, set CODEWHALE_USE_CNB_MIRROR=1 and the wrapper downloads binaries from the CNB mirror instead of GitHub. Cargo + Tuna or the CNB path also routes around GitHub download bottlenecks. The DeepSeek API at api.deepseek.com is reachable from mainland China without a proxy.
brew tap Hmbown/deepseek-tui brew install codewhale
The formula is codewhale. The tap repo is still Hmbown/homebrew-deepseek-tui until it is renamed; brew tap Hmbown/deepseek-tui keeps working. The legacy deepseek-tui formula remains a deprecated alias for one overlap release.
curl -fsSL -O https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-artifacts-sha256.txt curl -fsSL -O \ https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-macos-arm64 curl -fsSL -O \ https://github.com/Hmbown/CodeWhale/releases/latest/download/codew-macos-arm64 grep -E ' (codewhale|codew)-macos-arm64$' codewhale-artifacts-sha256.txt | shasum -a 256 -c - chmod +x codewhale-macos-arm64 codew-macos-arm64 xattr -d com.apple.quarantine codewhale-macos-arm64 codew-macos-arm64 2>/dev/null || true sudo mv codewhale-macos-arm64 /usr/local/bin/codewhale sudo mv codew-macos-arm64 /usr/local/bin/codew
curl -fsSL -O https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-artifacts-sha256.txt
verify_binary() {
asset="$1"
installed="$2"
expected=$(awk -v asset="$asset" '$2 == asset { print $1 }' codewhale-artifacts-sha256.txt)
actual=$(shasum -a 256 "$installed" | awk '{ print $1 }')
if [ -z "$expected" ] || [ "$actual" != "$expected" ]; then
echo "$installed checksum mismatch" >&2
return 1
fi
}
verify_binary codewhale-macos-arm64 /usr/local/bin/codewhale
verify_binary codew-macos-arm64 /usr/local/bin/codewdocker volume create codewhale-home docker run --rm -it \ -e DEEPSEEK_API_KEY=$DEEPSEEK_API_KEY \ -v codewhale-home:/home/codewhale/.codewhale \ -v "$PWD:/workspace" -w /workspace \ ghcr.io/hmbown/codewhale:latest
The release image is published to GHCR. Replace latest with a release tag when you need a pinned version.
git clone https://github.com/Hmbown/CodeWhale cd CodeWhale cargo build --release --locked # Install the compiled runtime as codewhale cargo install --path crates/cli --locked
Useful for working on the workspace itself or contributing patches.
$CODEWHALE_HOME/ (default: ~/.codewhale/) ├── config.toml api keys, model, hooks, profiles ├── mcp.json MCP server definitions ├── skills/ user skills (each with SKILL.md) ├── sessions/ checkpoints + offline queue ├── tasks/ background task store └── audit.log best-effort credential / approval / elevation events ./.codewhale/ project-scoped config (optional, per-repo)
The project-scoped ./.codewhale/ directory is optional — each repo can carry its own MCP servers, hooks, skills, and config overrides (e.g. provider keys). On first run the app asks whether to interactively create a config file if one is missing. Legacy ~/.deepseek and ./.deepseek paths are still read as compatibility fallbacks.
codewhale.net and www.codewhale.net are the official Codewhale sites, deployed on Cloudflare. The website source lives under web/ in the Hmbown/CodeWhale repository — anyone can self-deploy it as a mirror.
All official releases and SHA-256 checksums are distributed exclusively through GitHub Releases. The npm package downloads verified binaries from GitHub Releases.
A CNB mirror is available for users who cannot reliably reach GitHub (docs/CNB_MIRROR.md). The mirror is maintained by community members; release latency may be a few hours.
Cargo users can accelerate downloads via TUNA (Tsinghua University Open Source Mirror). These mirrors are maintained by third parties; the Codewhale project does not control mirror content.
Self-deployed website copies, mirror sites, and third-party packages are not controlled by the Codewhale project. Verify download sources and checksums.