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, codew, and codewhale-tui. 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.1 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 two package cargo install commands with --force (codewhale-cliprovides codewhale and codew;codewhale-tui provides the command of the same name); the legacy Homebrew tap updates with brew upgrade deepseek-tui.
- ① Get an API key
Sign up at platform.deepseek.com and create a key (format:
sk-...). - ② Set the key
export DEEPSEEK_API_KEY=sk-...
Or persist it to ~/.codewhale/config.toml:
codewhale auth set --provider deepseek --api-key sk-...
- ③ Run it in a project
cd path/to/project codewhale
New sessions open in Act mode by default. 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.1, the latest version published on GitHub. The current source matches that release.
npm install -g codewhale
The npm wrapper downloads SHA-256-verified binaries from GitHub Releases and installs codewhale, codew, and codewhale-tui.
cargo install codewhale-cli --locked cargo install codewhale-tui --locked
The two Cargo packages install three commands—codewhale, codew, and codewhale-tui—to ~/.cargo/bin. 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.1 codewhale-cli --locked --force cargo install --git https://cnb.cool/codewhale.net/codewhale --tag v0.9.1 codewhale-tui --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 cargo install codewhale-tui --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 deepseek-tui
This is the legacy deepseek-tui tap, kept for compatibility while the formula is renamed to codewhale. It installs the same current-release binaries.
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 curl -fsSL -O \ https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-tui-macos-arm64 grep -E ' (codewhale|codew|codewhale-tui)-macos-arm64$' codewhale-artifacts-sha256.txt | shasum -a 256 -c - chmod +x codewhale-macos-arm64 codew-macos-arm64 codewhale-tui-macos-arm64 xattr -d com.apple.quarantine codewhale-macos-arm64 codew-macos-arm64 codewhale-tui-macos-arm64 2>/dev/null || true sudo mv codewhale-macos-arm64 /usr/local/bin/codewhale sudo mv codew-macos-arm64 /usr/local/bin/codew sudo mv codewhale-tui-macos-arm64 /usr/local/bin/codewhale-tui
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/codew
verify_binary codewhale-tui-macos-arm64 /usr/local/bin/codewhale-tuidocker 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 two Cargo packages; together they provide three commands cargo install --path crates/cli --locked # codewhale + codew cargo install --path crates/tui --locked # codewhale-tui
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.