v0.8.62

CodeWhale is the canonical project, command, npm package, and
release-asset name. The legacy npm package deepseek-tui is
deprecated and receives no further releases. Users coming from
v0.8.x legacy deepseek / deepseek-tui names should migrate
with docs/REBRAND.md.

Install

Recommended — npm (one command, both binaries)

npm install -g codewhale

The wrapper downloads both binaries from this Release and places them in the same directory.

Docker / GHCR

docker run --rm -it \
  -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \
  -v ~/.deepseek:/home/codewhale/.deepseek \
  ghcr.io/hmbown/codewhale:v0.8.62

The image ships the codewhale dispatcher and codewhale-tui runtime. The latest tag is also updated on release.

Cargo (Linux / macOS)

cargo install codewhale-cli codewhale-tui --locked

Both crates are required — codewhale-cli produces the codewhale dispatcher and codewhale-tui produces the interactive runtime that the dispatcher delegates to. Installing only one binary will fail at runtime with a MISSING_COMPANION_BINARY error.

Manual download — platform archives (recommended)

Each archive below contains both the codewhale dispatcher and codewhale-tui runtime, plus an install script:

Platform	Archive	Install script
Linux x64	codewhale-linux-x64.tar.gz	install.sh
Linux ARM64	codewhale-linux-arm64.tar.gz	install.sh
Linux RISC-V	codewhale-linux-riscv64.tar.gz	install.sh
macOS x64	codewhale-macos-x64.tar.gz	install.sh
macOS ARM	codewhale-macos-arm64.tar.gz	install.sh
Windows x64 (installer)	CodeWhaleSetup.exe	NSIS setup
Windows x64	codewhale-windows-x64.zip	install.bat
Windows x64 (portable)	codewhale-windows-x64-portable.zip	—

Unix (Linux / macOS):

tar xzf codewhale-<platform>.tar.gz
cd codewhale-<platform>
./install.sh

Windows:

• For the installer path, run CodeWhaleSetup.exe; it installs both binaries under %LOCALAPPDATA%\Programs\CodeWhale\bin and adds that directory to the current-user PATH.
• Extract codewhale-windows-x64.zip
• Run install.bat (copies to %USERPROFILE%\bin)
• Add %USERPROFILE%\bin to your PATH

The portable Windows archive skips the install script — extract and run from any directory. The NSIS installer is currently unsigned and may trigger Windows SmartScreen until a signing certificate is wired into the release pipeline.

Each platform also has bare, unarchived binaries attached below (codewhale-<platform> and codewhale-tui-<platform>) — these are what the npm wrapper and the in-app codewhale update download, whereas the .tar.gz / .zip archives above are the recommended manual download and additionally bundle an install script. The legacy npm package deepseek-tui is deprecated and is not republished. For migration from v0.8.x legacy binary names, see docs/REBRAND.md.

Verify (recommended)

Download the checksum manifests from this Release and verify:

# Linux — archive bundles
sha256sum -c codewhale-bundles-sha256.txt

# Linux — individual binaries
sha256sum -c codewhale-artifacts-sha256.txt

# macOS
shasum -a 256 -c codewhale-bundles-sha256.txt
shasum -a 256 -c codewhale-artifacts-sha256.txt

What's in v0.8.62

Changed

• GLM-5.2 is now the default direct Z.AI model. DEFAULT_ZAI_MODEL resolves
  to GLM-5.2 in both codewhale-tui and codewhale-config; the glm-5.1
  alias still resolves to GLM-5.1 (the defaulting was decoupled from the alias
  arm so it no longer tracks the default). Docs and config.example.toml no
  longer describe GLM-5.2 as an opt-in preview.
• GLM-5-Turbo registered as a real model and wired as the faster/explore
  sub-agent sibling for the GLM family: a GLM-5.2 parent routes
  faster/explore children to GLM-5-Turbo (direct Z.ai) and z-ai/glm-5-turbo
  (OpenRouter), instead of down to GLM-5.1. GLM-5.1 and GLM-5-Turbo themselves
  have no cheaper tier and keep children on the parent.
• type: "explore" sub-agents default to model_strength: "faster". Bounded
  read-only lookup/search/status work now uses the cheaper same-family sibling
  automatically, unless an explicit model or model_strength: "same" is
  supplied. Non-explore roles keep the conservative same default.
• GPT-5.5 / OpenAI Codex faster route stays on GPT-5.5 with reasoning
  resolved to low (the Codex Responses API has no true off, so the resolved
  effort is now honest low rather than off silently rewritten). No
  DeepSeek/GLM fallback is fabricated when no cheaper same-provider sibling
  exists. DeepSeek Pro→Flash routing and its no-thinking faster lane are
  unchanged.
• Base prompt / delegate skill guidance updated to encourage parallel
  read-only exploration (2-4 type: "explore" sub-agents) for broad repo,
  version, branch, benchmark, and API-surface investigations, while keeping
  architecture, integration, and final verification in the parent. The
  delegate skill examples now use provider-neutral model_strength instead of
  hardcoded DeepSeek model ids.
• Agent synthesis guardrails. The base constitution now frames tools around
  sufficient evidence rather than open-ended persistence: extra reads, searches,
  and delegation must target a missing fact, and agents should answer with
  limits instead of broadening searches indefinitely. The runtime loop guard
  now blocks duplicate read-only/delegated calls earlier and caps repeated
  broad lookup/delegation loops in a single turn with a synthesis-forcing tool
  error. Guard metadata distinguishes exact duplicates
  (identical_tool_call) from no-progress loops (no_progress_tool_loop).
• Sub-agent handoff and visibility. Direct sub-agent completions are drained
  before the next parent model request, so finished children can wake the main
  model promptly instead of waiting for an empty-tool-use branch or idle engine
  path. Nested sub-agents now report completions to their immediate parent
  inbox; the main model still receives only direct-child completions, avoiding
  grandchild floods while preserving nested evidence flow. Sub-agent output
  guidance now requires child-agent provenance when a sub-agent relies on a
  child report: cite the child agent_id and the child's EVIDENCE line(s), and
  do not present child findings as directly verified facts. The sidebar orders
  sub-agents as a parent/child tree and annotates nested rows with parent and
  depth information in hover text.
• Sub-agent summary provenance (#2652). A sub-agent's free-text result is now
  explicitly treated as an unverified self-report rather than confirmed
  evidence. The completion sentinel carries summary_kind: complete | truncated
  so the parent model can branch on whether it saw the full report or a clipped
  excerpt. Short summaries (≤ 12,000 chars) get a soft "re-verify material
  claims" suffix; longer ones are head+tail truncated with an honest marker
  stating the elided middle is not retrievable via retrieve_tool_result.
  Every summary therefore carries exactly one boundary marker, never both.
• Provider metadata centralization. Provider env vars, config keys, aliases,
  and auth hints are now resolved through the shared ProviderMetadata registry
  across codewhale-config, codewhale-tui, and codewhale-cli, reducing drift
  between the provider picker, codewhale auth, doctor --json, and setup
  hints.

Added

• Agent clarification questions (#3102). Agents now have a first-class
  request_user_input tool to ask the user structured clarifying questions
  through a modal UI surface instead of only emitting a chat message and hoping
  the user notices. Mirrors the approval/secret-request flow the harness
  already used for permissions. The tool accepts 1-3 questions, each with a
  header, an id, 2-4 selectable options (label + description), and
  allow_free_text / multi_select flags (both default to false for
  back-compat). Input is validated up front with actionable errors. Wired
  across all layers: the request_user_input tool, engine handling
  (turn_loop → approval), an interactive TUI modal (UserInputView) with
  full keyboard navigation, and the runtime protocol
  (EventFrame::UserInputRequest + AppRequest::SubmitUserInput) so headless
  / app-server clients can answer programmatically. Parity tests cover the
  wire round-trip and the omitted-flags default.
• Transcript hyperlinks — out-of-band OSC 8 (#3029). Clickable file /
  file:line / URL links now reach the terminal through a column-drift-safe
  path. Link payloads are embedded in-band by the markdown renderer, then
  extracted out of the ratatui buffer cells and re-emitted out-of-band by
  ColorCompatBackend — so the ESC bytes never occupy display columns or
  corrupt selection. Supporting terminals get live hyperlinks; others see the
  label text unchanged. Clipboard/selection extraction strips residual codes as
  defense-in-depth.
• CodeWhale-only skill discovery gate (#3296). New
  [skills].scan_codewhale_only = true limits session-time skill discovery to
  CodeWhale-owned roots (<workspace>/.codewhale/skills, ~/.codewhale/skills,
  and any explicit skills_dir) while ignoring cross-tool directories such as
  .claude/skills, .opencode/skills, .cursor/skills, and ~/.agents/skills.
  The default remains the broad compatibility scan.
• Permission/ask runtime rules (#3295). Sibling permissions.toml ask-only
  rules are now loaded by the TUI engine and applied to exec_shell before
  Auto/session approval shortcuts. Matching ask rules force an approval prompt
  in otherwise auto-approved flows and are rejected under
  approval_mode = "never".
• Runtime API no-auth documentation. docs/RUNTIME_API.md now documents
  codewhale app-server --insecure-no-auth for loopback-only testing and warns
  against combining it with --mobile on 0.0.0.0.

Fixed

• TUI polish. The empty-startup welcome block is centered by the actual
  rendered text width, fixing the off-center layout left over from the old
  sidebar-oriented welcome composition. Streaming HTTP body read errors now
  explain whether CodeWhale can retry before output, or is surfacing a warning
  after partial output to avoid replaying and duplicating streamed text.
• Config comment preservation. Rewriting config.toml, settings.toml, or
  tui.toml now merges user comments and formatting back into the serialized
  document; if comment merge fails, the write falls back to plain serialized
  output rather than failing.
• Snapshot gate respected for per-tool snapshots (#3292). Per-tool snapshots
  now check [snapshots].enabled before writing, matching the existing
  session-level gate.
• Poppler pdftotext detection (#1667). The dependency resolver now probes
  pdftotext -v instead of --version, because Poppler treats --version as
  an input filename. Fixes detection on systems where only Poppler is installed.
• Plan confirmation checklist visibility. The Plan-mode confirmation modal
  now shows the active checklist under the plan details, so users can review the
  concrete checklist_write work breakdown before accepting or revising a plan.

Retroactive credits

A credit-reconciliation pass found shipped community fixes that were never
recorded in this changelog. Crediting them now, with the version they shipped in:

• Global ~/.deepseek/AGENTS.md fallback loading — thanks @manaskarra (fix) and @xfy6238 (report) (#1157, v0.8.27)
• CRLF SSE event parsing for MCP — thanks @reidliu41 (fix) and @djairjr (report) (#1309, v0.8.29)
• Reduce-motion default on VTE/flicker terminals — thanks @Geallier (report) (#1470, v0.8.34)
• portable-pty 0.9 upgrade for LoongArch64 — thanks @quentin-lian (fix) and @k0tran (report) (#1531, #1992, v0.8.46)
• DEEPSEEK_ALLOW_INSECURE_HTTP guard for LAN vLLM — thanks @F1LT3R (report) (#1656, v0.8.47)
• Hidden reasoning_content kept in English regardless of locale — thanks @cmyyy (report) (#1842, v0.8.47)
• ExternalTool abstraction layer — thanks @aboimpinto (#1794, #2294, v0.8.48)
• Ephemeral generated project context — thanks @Final527 (report) (#3058, v0.8.59)

Contributor credits for this release live in the changelog entry above —
thank you to everyone whose reports, PRs, reviews, and reproductions shaped it.

See CHANGELOG.md for full notes and docs/CHANGELOG_ARCHIVE.md for older releases.