CodeWhale

2. Cargo — no Node needed. Requires Rust 1.88+ (the crates use the

Install

codewhale is distributed as Rust binaries: the dispatcher command (codewhale) and the companion TUI runtime (codewhale-tui). Pick whichever install path you already use; they all put the same commands on your PATH. The npm package is an installer/wrapper for the release binaries, not the agent runtime itself.

```bash

5. Docker — prebuilt release image.

docker volume create codewhale-home docker run --rm -it \ -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \ -v codewhale-home:/home/codewhale/.deepseek \ -v "$PWD:/workspace" \ -w /workspace \ ghcr.io/hmbown/codewhale:latest

> In mainland China, speed up the npm path with
> `--registry=https://registry.npmmirror.com`, or use the
> [Cargo mirror](#china--mirror-friendly-installation) below.
>
> Download safety: official release binaries live under
> `https://github.com/Hmbown/CodeWhale/releases`. For manual downloads,
> verify the SHA-256 manifest and avoid look-alike repositories or search-result
> mirrors. See [download safety and checksums](docs/INSTALL.md#2-download-safety-and-checksums).

Already installed? Use the updater that matches the install path:

DeepWiki project index

---

China / Mirror-friendly Installation

If GitHub or npm downloads are slow from mainland China, use a Cargo registry mirror:

```toml

Linux build deps (Debian/Ubuntu/RHEL):

sudo apt-get install -y build-essential pkg-config libdbus-1-dev

sudo dnf install -y gcc make pkgconf-pkg-config dbus-devel

git clone https://github.com/Hmbown/CodeWhale.git cd CodeWhale

cargo install --path crates/cli --locked # requires Rust 1.88+; provides codewhale cargo install --path crates/tui --locked # provides codewhale-tui ```

Both binaries are required. Cross-compilation and platform-specific notes: docs/INSTALL.md.

</details>

Quickstart

npm install -g codewhale
codewhale --version
codewhale --model auto

Prebuilt binaries are published for Linux x64, Linux ARM64 (v0.8.8+), macOS x64, macOS ARM64, and Windows x64. For other targets (musl, riscv64, FreeBSD, etc.), see Install from source or docs/INSTALL.md.

On first launch you'll be prompted for your DeepSeek API key. The key is saved to ~/.deepseek/config.toml so it works from any directory without OS credential prompts.

You can also set it ahead of time:

codewhale auth set --provider deepseek   # saves to ~/.deepseek/config.toml
codewhale auth status                    # shows the active credential source

export DEEPSEEK_API_KEY="YOUR_KEY"      # env var alternative; use ~/.zshenv for non-interactive shells
codewhale

codewhale doctor                         # verify setup

If codewhale doctor says the rejected key came from DEEPSEEK_API_KEY, remove the stale export from your shell startup file, open a fresh shell, or run codewhale auth set --provider deepseek. Use codewhale auth status to see the config, keyring, and env-var source state without printing the key. Saved config keys take precedence over the keyring and environment and are easier to rotate.

To rotate or remove a saved key: codewhale auth clear --provider deepseek.

Usage

codewhale                                         # interactive TUI
codewhale "explain this function"                 # one-shot prompt
codewhale exec --auto --output-format stream-json "fix this bug"  # agentic exec with tool auto-approvals
codewhale exec --resume <SESSION_ID> "follow up"  # continue a non-interactive session
codewhale --model deepseek-v4-flash "summarize"   # model override
codewhale --model auto "fix this bug"             # auto-route model + thinking
codewhale --yolo                                  # auto-approve tools
codewhale auth set --provider deepseek            # save API key
codewhale doctor                                  # check setup & connectivity
codewhale doctor --json                           # machine-readable diagnostics
codewhale setup --status                          # read-only setup status
codewhale setup --tools --plugins                 # scaffold tool/plugin dirs
codewhale models                                  # list live API models
codewhale sessions                                # list saved sessions
codewhale resume --last                           # resume the most recent session in this workspace
codewhale resume <SESSION_ID>                     # resume a specific session by UUID
codewhale fork <SESSION_ID>                       # fork a saved session into a sibling path
codewhale serve --http                            # HTTP/SSE API server
codewhale serve --acp                             # ACP stdio adapter for Zed/custom agents
codewhale run pr <N>                              # fetch PR and pre-seed review prompt
codewhale mcp list                                # list configured MCP servers
codewhale mcp validate                            # validate MCP config/connectivity
codewhale mcp-server                              # run dispatcher MCP stdio server
codewhale update                                  # check for and apply binary updates

~/.cargo/config.toml

[source.crates-io] replace-with = "tuna"

[source.tuna] registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"

Then install both binaries (the dispatcher delegates to the TUI at runtime):

Prebuilt binaries can also be downloaded from GitHub Releases. Use DEEPSEEK_TUI_RELEASE_BASE_URL for mirrored release assets.

Configuration

User config: ~/.deepseek/config.toml. Project overlay: <workspace>/.deepseek/config.toml (denied: api_key, base_url, provider, mcp_config_path). config.example.toml has every option.

Key environment variables:

Set locale in settings.toml, use /config locale zh-Hans, or rely on LC_ALL/LANG to choose UI chrome and the fallback language sent to V4 models. The latest user message still wins for natural-language reasoning and replies, so Chinese user turns stay Chinese even on an English system locale. See docs/CONFIGURATION.md and docs/MCP.md.

---

Other API Providers

Official DeepSeek remains the default and first-class path. Other providers are additive, with OpenRouter starting from DeepSeek Pro/Flash before broader open-model catalogs are enabled.

```bash

Generic OpenAI-compatible endpoint

codewhale auth set --provider openai --api-key "YOUR_OPENAI_COMPATIBLE_API_KEY" OPENAI_BASE_URL="https://openai-compatible.example/v4" codewhale --provider openai --model glm-5

1. npm — easiest if you already use Node. The package downloads the

3. Homebrew — macOS package manager.

brew tap Hmbown/deepseek-tui brew install deepseek-tui

4. Direct download — no package manager or toolchain.

description: Use this when DeepSeek should follow my custom workflow.