ReleaseLatest release v0.10.2 · 24. Okt. 2026These pages describe v0.10.2, the published release.Changelog →

Fix a problem

Start with one diagnostic command, then find your symptom below. Each fix names the exact message you will see.

Run the diagnostics

Terminal

codewhale --version
codewhale doctor
codewhale doctor --probe-api                  # one real test call to your provider
codewhale auth status --provider deepseek     # which key is in use

codewhale doctor --json produces a diagnostics bundle without secrets, ready to attach to an issue. Plain doctor does not tell you which key is active and exits successfully even with no key; use auth status for that.

Install and update

codewhale: command not found
~/.local/bin is not on your PATH in this terminal. Add export PATH="$HOME/.local/bin:$PATH" to your shell profile and open a new terminal.
npm error code EACCES
Your Node install is owned by the system. Do not use sudo: point npm at a folder you own with npm config set prefix "$HOME/.npm-global", add its bin to your PATH, and install again.
refusing to replace existing ~/.local/bin/codewhale
A different version is already there. Run codewhale update, or remove the old binaries first.
checksum mismatch
The download was corrupted or altered, and nothing was installed. Try again; if it repeats, do not use a mirror.
The package-managed executable was not changed.
You installed with npm, Cargo, or Homebrew. Update with that tool, for example npm install -g codewhale.

No reply, or the key is rejected

No answer arrives
Check codewhale --version: in v0.10.2, a missing model keeps your message in the composer and opens provider setup, so connect a model and send it again. If setup is complete, check codewhale auth status --provider <name>, then run codewhale doctor --probe-api for your selected hosted route or codewhale doctor --probe-local for a local model; these probes contact the service.
API key not found
No key anywhere. Save one with codewhale auth set --provider <name>.
Authentication Fails … is invalid
The key is wrong or revoked. Run auth status to see which source is used — a saved key beats an environment variable — then save the right key or codewhale auth clear --provider <name>.
Network error: SSE stream request failed …
Usually no connection to the provider. Check with curl -sI https://api.deepseek.com (a 401 means it is reachable). Behind a proxy, export HTTPS_PROXY. On Windows or strict proxies, try CODEWHALE_FORCE_HTTP1=1.

A turn is stuck

  • Press Esc to cancel the turn. Esc also closes menus first, so press it again if a menu was open.
  • If a long shell command is holding the turn, press Ctrl-B to move it into the background. The turn continues, and /jobs shows the command.
  • /retry sends the last request again.

For a detailed record, start Codewhale with RUST_LOG=codewhale_tui=debug (or RUST_LOG=codewhale_tui::client=debug for connection retries). Logs are written to ~/.codewhale/logs/.

Resume a session

Terminal

codewhale sessions            # list saved sessions
codewhale resume <id>         # an id or a unique prefix
codewhale -c                  # the latest session in this folder

Inside Codewhale, Ctrl-R opens the session picker. No saved sessions found for workspace after codewhale exec --continue means the earlier run was a plain exec, which is not saved; use --output-format stream-json for runs you want to continue.

Messages you send while offline wait in a queue, saved with the session. /queue list shows them. When the connection is back, open one with /queue edit <n> and press Enter to send it.

MCP tools are missing

  • After changing mcp.json or a server's credentials, run /mcp reload. /mcp validate only refreshes what you see.
  • Run the server's command yourself in a shell to confirm it starts.
  • If mcp.json is missing, codewhale mcp init can create it. Back up an existing file before repair; --force replaces its configuration.

Run in Docker

Terminal

docker 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:v0.10.0

This uses the image and v0.10.0 tag documented in the Docker guide. It runs as a non-root user; keep settings in the named volume, use one volume per project and never bake keys into the image.

Next

Connect a provider

Save a key, check which one is used, or switch to a local model.

Install Codewhale

Every install method, with the output each step should print.

Review what changed

Roll files back to the snapshot before a turn went wrong.