Document Work and To-do as the two product concepts, synchronize every shipped locale, publish the six-tool and typed-image contracts, and keep static web generation offline while live GitHub chrome refreshes after deployment.
Three v0.9.5 benchmark tasks could not launch Codewhale at all:
mteb-leaderboard, mteb-retrieve, and pytorch-model-recovery run older ARM64
images, and the aarch64-unknown-linux-gnu artifact built on ubuntu-24.04-arm
requires GLIBC_2.39.
Release and nightly now build aarch64-unknown-linux-musl on the native ARM
runner, alongside the x64 musl build that has shipped since v0.8.65. Both
gain a static check (no ELF INTERP) plus a launch smoke on the matching
native runner, so a dynamically linked or non-starting binary fails the
build rather than the user's install. docs/INSTALL.md drops the arm64 glibc
floor section and describes the v0.9.6 matrix.
Also reconciles the copy the earlier commits invalidated: setup ratification
text and all 15 locales stop attributing execution doctrine to "mode
prompts", docs/MODES.md states Auto-Review's actual deterministic
allow/deny behavior, and the source-structure, dead-code, and
runtime-contract budgets are re-measured — the last locking down 25
decreased ceilings and the new mode-agnostic prompt-stage digests.
2026-08-04 model-facing-text audit. Four user-facing claims contradicted the
code, three of them in the direction that costs the user:
- CONFIGURATION.md said max_subagents 'defaults to 20 and is clamped to
1..=20' in four places. Code: DEFAULT_MAX_SUBAGENTS = 64, MAX_SUBAGENTS =
128 (config/subagent_limits.rs:13,17). Out-of-box concurrency is 3.2x the
documented figure, and a user writing max_subagents = 40 to 'raise it to
the max' was told it would clamp to 20 when it is honored in full. Same
shape for max_admitted: documented ceiling 200, actual
MAX_SUBAGENT_ADMISSION = 1024.
- Usage: codewhale [OPTIONS] [PROMPT]
codewhale [OPTIONS] <COMMAND> [ARGS]
Commands:
run Run interactive/non-interactive flows via the TUI binary
doctor Run Codewhale diagnostics
models List live provider API models via the TUI binary
speech Generate speech audio with Xiaomi MiMo TTS models via the TUI binary [aliases: tts]
sessions List saved TUI sessions
resume Resume a saved TUI session
rc Launch an interactive session and hand it to the Codewhale web app
fork Fork a saved TUI session
init Create a default AGENTS.md in the current directory
setup Bootstrap MCP config and/or skills directories
remote-setup Generate a remote Codewhale agent deploy bundle (cloud + chat bridge)
exec Run a non-interactive prompt through the TUI runtime
fleet Manage durable Agent Fleet runs via the TUI runtime
workflow Run checked-in Workflows through a Lane Runtime backend
lane Manage running workflow instances (Lanes) and Runtime backends (#4176)
review Run a Codewhale-powered code review over a git diff
apply Apply a patch file or stdin to the working tree
eval Run the offline TUI evaluation harness
mcp Manage TUI MCP servers
features Inspect TUI feature flags
serve Run a local TUI server
web Open the first-class local browser client over the canonical Runtime API
completions Generate shell completions for the TUI binary
login Configure provider credentials
logout Remove saved authentication state
auth Manage authentication credentials and provider mode
account Sign in to your Codewhale account and manage account-scoped provider keys [aliases: cloud]
mcp-server Run MCP server mode over stdio
config Read/write/list config values
model Resolve or list available models across providers
thread Manage thread/session metadata and resume/fork flows
sandbox Evaluate sandbox/approval policy decisions
app-server Run the canonical runtime API / control plane (HTTP/SSE, mobile, stdio)
completion Generate shell completions
metrics Print a usage rollup from the audit log and session store
update Check for and apply updates to the `codewhale` binary
help Print this message or the help of the given subcommand(s)
Arguments:
[PROMPT]...
Options:
--config <CONFIG>
--profile <PROFILE>
--provider <PROVIDER>
Provider selector; exec/fleet also accept configured custom provider identifiers
--model <MODEL>
--output-mode <OUTPUT_MODE>
--verbosity <LEVEL>
Controls transcript and output verbosity (normal, concise)
--log-level <LOG_LEVEL>
--telemetry <BOOL>
Opt in to anonymous product telemetry for this run (default off; CODEWHALE_TELEMETRY=0 always wins) [possible values: true, false]
--approval-policy <APPROVAL_POLICY>
--sandbox-mode <SANDBOX_MODE>
--api-key <API_KEY>
--base-url <BASE_URL>
-C, --workspace <DIR>
Workspace directory for TUI file tools
--mouse-capture
--no-mouse-capture
--skip-onboarding
--no-project-config
Skip loading project-level config, including the workspace-specific `[workspace]`/`[projects]` overlay from user config. Must appear before the subcommand; it is forwarded to the TUI ahead of the subcommand
-c, --continue
Continue the most recent interactive session for this workspace
-p, --prompt <PROMPT>
-h, --help
Print help
-V, --version
Print version said '(1-20)' while main.rs clamps to 128. Here the doc
was right and the help was wrong; both now say 1-128, default 64.
- MODES.md gave bare as the enable command. config.rs:2278 maps
"" | "status" | "list" to trust_status — bare /trust only REPORTS. A user
reads the status block, believes trust is on, and escalates to Full Access
when the next out-of-workspace operation fails. Now documents /trust on
and says plainly that bare /trust does not enable anything.
- CONFIGURATION.md gave as the Ollama default; the
string appears nowhere in crates/. provider_defaults.rs:109 is
deepseek-v4-flash. Self-hosted is where a bad default bites hardest.
Verified: limits read from config/subagent_limits.rs, /trust dispatch read
from config.rs:2278, Ollama default from provider_defaults.rs:109; tui
builds clean. Authored with agent assistance (Claude).
Terminal-Bench 2.1 (89 tasks, codewhale 0.9.4, deepseek-v4-flash):
5 of 7 NonZeroAgentExitCodeError forfeits were the identical failure —
the provider stream dropped mid-response ("error decoding response
body" after partial content), the #103 policy surfaced the warning and
failed the turn, and `codewhale exec` exited 1. regex-log passed the
smoke run and crashed in the full run: a nondeterministic transport
drop, not a task failure. Pi retries the same drops (332 retries, 0
crashes).
Engine (turn_loop + streaming policy):
- New should_resume_after_network_drop policy: in headless hosts
(exec / stream-json; terminal_chrome_enabled = false) a network-class
stream error after partial content now schedules a full request
re-issue, bounded by MAX_STREAM_RETRIES, exactly like the #2990
sleep-resume. The partial fragment was never committed and no tool
from the incomplete response executed, so replaying from the last
committed boundary cannot duplicate side effects. Interactive TUI
keeps the #103 surface-the-warning behavior. No error event is
emitted for attempts that will be retried; the budget-exhausted final
attempt still reports the real error.
Exec exit semantics (main.rs):
- Terminal failures with error_category network/timeout now exit 75
(EX_TEMPFAIL) instead of 1, so harnesses can distinguish retryable
infra failures from genuine task failures (still exit 1). No error is
masked: the stream-json error event, terminal metadata status=failed,
and error_category are unchanged.
- Recoverable mid-turn error events (e.g. stream-stall warnings) no
longer poison the exec run summary; the terminal TurnComplete carries
the authoritative outcome. Previously any recoverable warning forced
a non-zero exit even when the turn later completed.
Regression coverage:
- Pure policy tests for the headless/network/budget/cancel matrix.
- Engine-level tests with a flaky mock client: mid-stream drop recovers
(2 requests, completed, fragment discarded); budget exhaustion fails
with the real error and exactly one error event.
- Process-level acceptance (tests/exec_stream_drop_acceptance.rs): raw
TCP server truncates the SSE body mid-content-length, reproducing the
production decode error against the real binary — exit 0 after
recovery, exit 75 with error-channel reporting after exhaustion.
Gates: cargo fmt --all --check; cargo check -p codewhale-tui; targeted
tests 18/18 + acceptance 2/2; full codewhale-tui suite 10141 passed,
21 failed — all in the known pre-existing env-key/qa_pty set
(provider-catalog API-key panics + PTY visual matrix), none in the
touched paths.
Verified each claim against the code before editing:
- [capacity]: the 15-key controller was documented in CONFIGURATION.md
and config.example.toml but has zero matches anywhere under crates/
— silently ignored on parse. Removed, along with the link to the
nonexistent docs/capacity_controller.md and two prose mentions.
- [context] seam keys: verbatim_window_turns, l1/l2/l3_threshold and
seam_model are all 'Ignored (was: …)' in crates/tui/src/config.rs
(2036-2048); docs presented them as a live opt-in. Both files now
document only the live keys (enabled, project_pack) and mark the
seam keys ignored.
- Settings keys: show_thinking / thinking_default_expanded /
cost_currency were misfiled in config.example.toml; they belong to
~/.codewhale/settings.toml (settings.rs:344,414) and Config has no
deny_unknown_fields, so users got silently ignored settings.
Replaced with a pointer comment.
- Hotbar default was inverted in docs: KEYBINDINGS.md and
config.example.toml claimed fresh configs show the default bar;
since #3807 a missing hotbar key renders no bar (sidebar.rs:192-195).
- MCP tool naming: docs/MCP.md claimed mcp_deepseek_shell; the rule
is mcp_{server}_{tool} (mcp.rs:3022) with default server name
codewhale, i.e. mcp_codewhale_shell.
- MODES.md said 'DeepSeek-TUI'; memory_path bullet described the
deleted legacy single-file fallback — both fixed for the native
store (see 1135a1e65).
Evidence: cross-surface-tech-debt-audit-2026-08-03.md findings 74-80;
§11.3 docs-truth row.
Publish the implemented authorization order and lock its precedence with regression coverage. Preserve the contributor's documentation, translation, and contract-test work.
Documents the exact Fleet schema, the Adaptive Reasoning Router as a saved
service a Fleet references by name, and the permission ceilings a member
carries, across FLEET.md, MODES.md, and SUBAGENTS.md.
Role copy stops calling a session "the operation". The operator directs the
overall work and assigns managers to Workflows; the manager runs one
Workflow. "Operation" read as a distinct product concept that does not
exist, and the hierarchy is easier to state without it.
`FleetRoster::from_members` supports run-scoped rosters that are not a merge
of the config layers — an exact Fleet's members are frozen at Workflow start
and must not pick up built-in or workspace profiles by name, which is what
would let a saved route be shadowed after the fact.
The `oracle`/`advisor` → `consultant` rename is already landed on this
branch, so the harvested terminology changes reduced to the docs and the
copy above; `worker_profile.rs` needed no change at all once its conflict
resolved to this branch's spelling.
Keep the canonical idle-composer wording contiguous so the public-surface contract can verify it without weakening the assertion.
Verified: web check:facts, check:docs, 143/143 tests, lint, and production build.
Route interactive mode, reasoning, model, and permission changes through one busy-turn lock and a cross-process settings transaction. Atomic no-clobber migration, startup-write shutdown draining, localized failure receipts, and same-live selection outcomes keep the next launch truthful without blocking the TUI event loop.
Give each composer chord one stable role: Enter sends or queues, Ctrl+Enter steers, newline chords always add a line, Ctrl+G/Ctrl+S only stash, and Tab never submits text. Empty Enter now promotes the oldest queued follow-up explicitly.
Keep modified Enter chords out of paste-burst suppression, align hints/help/locales/docs, and cover the contract with unit and PTY runtime regressions.
Rewrite OPERATE_MODE into hard conductor doctrine (goal → dispatch →
background → verify → synthesize). Dispatching sub-agents is the default
multitask path — no /multitask verb. Write-capable children get a spawn-time
VERDICT PASS/FAIL evidence contract; the agent tool description prefers
implementer/verifier pairs and worktrees. Ship operate_* starter workflows
and strengthen the best-of-n skill so winners apply only after PASS.
Document the exact nine default-active tools, deferred Web behavior, and replay-only aliases from the implemented runtime contract. Align current mode, permission-posture, Fleet vocabulary, fanout, MCP, provider, and operations guidance while preserving historical lifecycle provenance.
Signed-off-by: Hunter B <hmbown@gmail.com>
Align permission posture behavior, compact the approval surface, make Alt/Option+V the sole details chord, register runtime MCP handlers consistently, and keep recursive plugin review hashing off worker stacks. Preserve user questions outside Auto-Review while failing non-bypassable Full Access holds closed without a modal.
Derive Ask, Auto-Review, Full Access, and read-only question guidance from the effective runtime approval posture after provenance narrowing. This keeps tool execution authority separate from authority to invent user intent and updates the user-facing mode contract.
Fixes#4511
Signed-off-by: Hunter B <hmbown@gmail.com>
Remove the Operate-only parent tool blocker so its direct tool surface follows the same posture, shell, sandbox, ask-rule, and repository-law path as Act.
Keep Fleet delegation preferred for parallel and background work, preserve Plan's write boundary, and align prompt, docs, and website copy with the runtime.
Let an approved root Operate worker edit and run only the fixed built-in verification surfaces while keeping raw shell, custom verifier commands, Cargo argv, and nested delegation approval-gated.\n\nDeduplicate idle and in-turn completion delivery, release claims when route setup fails before transcript recording, and prevent child-authored handoffs from inheriting standing Full Access authority.\n\nAlign Workflow and Fleet copy with the message-first Operate contract and distinguish profile availability from filesystem authority.
Explain that personal Fleet profiles travel across repositories without widening a running operation. Direct multi-repository work through a shared parent workspace, and surface the same boundary in Fleet setup.
Signed-off-by: Hunter B <hmbown@gmail.com>
Accept ordinary messages and async agent dispatch, keep detached workflows available for genuinely staged work, and enforce the coordinator/worker boundary against actual tool capabilities rather than prose heuristics. Keep queued-task copy and docs aligned while preserving exact dispatch versus completion receipts.
Update workspace, npm, changelogs, docs, and generated site facts for the 0.8.68 release. Refresh the public mode and Workflow language to match the shipped Plan/Act/Operate surface.
Reconciled the 0.8.68 train with 80 upstream commits:
- state: kept the held-connection read_thread_goal shape for the
thread-goal deadlock both sides fixed independently (upstream 5331d10d6)
- workflow tests: consolidated on upstream's workflow_test_retry_guard
(locks + clears retry state); dropped the local rate_limit_window_guard
- run card: merged upstream's schema_errors field/count into the 0.8.68
card; kept the Wave 5c contract (header owns lifecycle, no body
status KV) and both run-card test variants deduped to the 5c-aware ones
- ui: kept the recovery-snapshot tick alongside upstream's
should_tick_status_animation refactor
- qa_pty: header assertion accepts the new Act/Multitask/Operate labels
Full gate on the merged tree: workspace tests green (TUI 5976 passed,
qa_pty 7/7), clippy -D warnings clean, fmt clean.
Record the 0.8.68 train in CHANGELOG [Unreleased]; update KEYBINDINGS
for Ctrl+T/Ctrl+Shift+T/Shift+Tab; mark YOLO deprecated in MODES; add
the release tracker with wave dispositions, deep-dive table, review-pass
verification evidence, and GitHub close-out ledger.
docs/FLEET.md: bare /fleet + roster aliases open the roster, not the wizard; the wizard now picks a concrete model (inherit or a provider model), not a 'model class' (per 04249e7dc). docs/MODES.md + docs/SUBAGENTS.md: subagent limits are 64 default / 128 ceiling (DEFAULT_MAX_SUBAGENTS / MAX_SUBAGENTS), not 20. AGENTS.md: generic scratch-branch version placeholder.
Signed-off-by: CodeWhale Agent <codewhale-agent@hmbown.local>
Add 'cancel <run_id>' to CmdWorkflowDescription in all six locale packs so the localized help matches the command usage. Delete the orphaned CmdSwarmDescription key (zh-Hans) and reword the swarm prose in docs/FLEET.md and docs/MODES.md to reference Workflow/Fleet fan-out.
Signed-off-by: CodeWhale Agent <codewhale-agent@hmbown.local>
Keep the direct multiline exec_shell safety block in place, but make the blocked result explain that allow_shell only controls shell availability and does not disable built-in safety validation.
Document the supported workarounds for heredocs and embedded scripts: use single-line commands, write a script/file first, or use task_shell_start/background shell for long manual flows.
Fixes#3827.
Remove public benchmark docs/scripts and the shipped SWE-bench CLI surface from the CodeWhale repo; benchmark work belongs outside this release repo.
Trim public docs that routed users into private maintainer runbooks, remove stale deleted-doc links, tone down release-facing copy, update CodeWhale crate descriptions, and expose the residue ledger as /debt while keeping quiet legacy dispatch compatibility.
Verification:\n- cargo fmt --all -- --check\n- git diff --check\n- ./scripts/release/check-versions.sh\n- cargo check -p codewhale-tui --bin codewhale-tui --locked\n- cargo test -p codewhale-tui --bin codewhale-tui --locked command_registry\n- cargo test -p codewhale-tui --bin codewhale-tui --locked every_command_alias_dispatches_to_a_handler\n- cargo test -p codewhale-cli --locked
WIP branch for v0.8.61 sub-agent cutover. Removes old lifecycle/tool-agent surface, runtime tag injection, heartbeat scaffolding, and capacity/coherence code, but release readiness is not final: interactive fanout can still freeze the TUI and needs follow-up investigation before shipping.
Disables the old prompt-only /swarm fanout path and documents that swarm must wait for the durable Train-3 worker and goal re-dispatch substrate.
Refs: #3218
The second feature-flag gate in tool_setup.rs was calling
with_shell_tools() again when allow_shell was already true, causing
duplicate tool registration. Remove the redundant gate since
with_agent_tools() already handles the allow_shell check.
Also add task_shell_wait to MODES.md alongside task_shell_start.
task_shell_start delegates to ExecShellTool, providing the same shell
execution capability as exec_shell. Previously, task_shell_start was
registered unconditionally in with_runtime_task_tools while exec_shell
was gated behind allow_shell, creating an inconsistent security gate.
This caused the model to try exec_shell first, fail, then fall back to
task_shell_start — wasting tokens and bypassing the intended security
boundary.
Split TaskShellStartTool and TaskShellWaitTool out of
with_runtime_task_tools into a new with_runtime_task_shell_tools method,
and gate both behind the allow_shell check in with_agent_tools.
Closes#2303
Harvested and vetted — no malware, no external deps, no injection:
- #1859 (@harvey2011888): loop guard now reports Failed on halt
- #1870 (@victorcheng2333): honour DEEPSEEK_YOLO env on startup
- #1935 (@IIzzaya): replace [x] with [✓] completion markers
- #1837 (@PurplePulse): fix macOS title centering (pin to top)
- #1967 (@cyq1017): show base_url in /config view
- #1906 (@knqiufan): copy transcript without visual-wrap newlines
Also fix cycle_manager archive_dir_for to use resolve_state_dir
so recall_archive tests pass with the migrated sessions path.
Co-authored-by: victorcheng2333 <victorcheng2333@users.noreply.github.com>
Co-authored-by: IIzzaya <IIzzaya@users.noreply.github.com>
Co-authored-by: PurplePulse <PurplePulse@users.noreply.github.com>
Co-authored-by: cyq1017 <cyq1017@users.noreply.github.com>
Co-authored-by: knqiufan <knqiufan@users.noreply.github.com>
- Separate model auto-routing from Plan/Agent/YOLO TUI modes across all
READMEs and docs/MODES.md
- Introduce Fin as the fast thinking-off deepseek-v4-flash seam for
routing, summaries, RLM child calls, and coordination work
- Document /goal as current session tracking (not a TUI mode), with note
that a future Goal work surface should stay distinct from --model auto
- Extend deprecation shim timeline from 'one release cycle' to
through v0.8.x in REBRAND.md and npm READMEs
- Fix selection_to_text test to expect inline thinking preview
(short completed thinking now renders inline without Ctrl+O
affordance)
Sweep brand mentions of `DeepSeek TUI` / `deepseek-tui` / bare
`deepseek` (the dispatcher binary) across all user-facing docs to
the new `codewhale` brand. The DeepSeek **provider** integration is
left untouched throughout: env vars (`DEEPSEEK_*`), model IDs
(`deepseek-v4-pro`, `deepseek-v4-flash`, `deepseek-chat`,
`deepseek-reasoner`), the `api.deepseek.com` host, the
`~/.deepseek/` config dir, and the `--provider deepseek` argument
value all keep the legacy spelling.
Anti-scope items deliberately left as the legacy `deepseek-tui`:
- Homebrew tap and formula (`Hmbown/homebrew-deepseek-tui`,
`brew install deepseek-tui`, `scoop install deepseek-tui`). The
tap rename ships separately.
- Docker image (`ghcr.io/hmbown/deepseek-tui`). Image-tag rename
ships separately.
- CNB mirror namespace (`cnb.cool/deepseek-tui.com/DeepSeek-TUI`).
Third-party hosted path.
- Security contact email (`security@deepseek-tui.com`).
- GitHub repo URL (`Hmbown/DeepSeek-TUI`).
New artifact:
- `docs/REBRAND.md` documents what changed, what didn't, the
deprecation window, and migration commands for npm / Cargo /
Homebrew / manual installs.
CHANGELOG entries:
- Root `CHANGELOG.md` and `crates/tui/CHANGELOG.md` both gain a
new `[Unreleased]` section describing the rename and the one-
release deprecation window. Historical entries are untouched.
Issue templates:
- `.github/ISSUE_TEMPLATE/bug_report.md` and `feature_request.md`
refer to "codewhale" / `codewhale --version` instead of the old
brand name in their environment fields.
The rebrand sweep was driven by a perl script with bulk patterns
(`deepseek-tui` -> `codewhale-tui`, `DeepSeek TUI` -> `codewhale`,
bare `deepseek` -> `codewhale` with provider/model/host/env-var/
config-path negative lookbehind/lookahead) followed by targeted
reverts for the anti-scope items above. Output was visually
reviewed file-by-file before committing.
Verified:
- `cargo check --workspace --all-targets --locked` — pass.
- `cargo test --workspace --all-features --locked` — pass (no
test source touched here; suite stayed green to confirm no
doc-from-string assertions broke).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
CodeWhale Bot