f2ba5d15e4
docs/TOOL_SURFACE.md carried four claims the runtime's own tests contradict:
1. "The default-active policy contains exactly these ten names" listing
`update_plan`. `DEFAULT_ACTIVE_NATIVE_TOOLS`
(crates/tui/src/core/engine/tool_catalog.rs:44-58) has eight entries and
`update_plan` is not among them — it appears nowhere in tool_catalog.rs. The
policy is nine (those eight plus synthetic `tool_search`), eight with memory
disabled. `update_plan` is registered (crates/tui/src/tools/plan.rs:401) but
reachable only through `tool_search`; the tool table now says so.
2. "A memory-disabled or Moraine-fallback runtime". There is no Moraine
fallback — docs/MEMORY.md:11-13 records the removal, and
crates/tui/src/prompts.rs:2445-2449 is a test asserting MEMORY_GUIDANCE must
not contain the word.
3. A "Replay-only aliases" table promising "saved transcripts, sessions, and
recorded automation replay without migration" for 23 names, 16 of which are
asserted REMOVED at crates/tui/src/tools/registry.rs:2066-2088 ("{retired}
must stay removed") and 6 more at :2290-2304 ("{alias} must be removed").
Split into a "Removed spellings" section (with the registry.rs:313-316 note
that resolve has no fuzzy step, so those calls fail rather than dispatch) and
a "Replay-only aliases" section holding only what is still registered:
apply_patch, task_*, github_*, automation_*, rlm_*, checklist_*/todo_*.
4. A "Release verification" block whose three cargo filters name tests that do
not exist (`rg` finds those three strings only in that doc). `cargo test`
exits 0 with "0 passed; N filtered out" on a filter that matches nothing, so
a release engineer following it got three green checkmarks having verified
nothing. Replaced with the real names —
`shell_surface_contains_only_the_canonical_bash_tool` (registry.rs:2290) and
`runtime_task_families_expose_only_canonical_tools` (registry.rs:2333) — plus
the receipt test, and a warning about the silent-pass failure mode.
docs/RUNTIME_SIMPLIFICATION_DESIGN.md repeats errors 1 and 3 and is designated
authoritative by docs/TOOL_LIFECYCLE.md:3-7, but carries no status marker. Given
a status banner naming both divergences and pointing at TOOL_SURFACE.md; the
"Rejected alternatives" provenance is worth keeping, so not deleted.
docs/SUBAGENTS.md:
- "a bounded queue of up to 200 running plus queued sub-agents by default" —
`MAX_SUBAGENT_ADMISSION` is 1024 (crates/tui/src/config/subagent_limits.rs:21),
which is what docs/TOOL_SURFACE.md:182 already said. The 64/128 concurrency
figures on the same page were correct and are untouched.
- The memory section described a `memory.md` that does not exist and omitted the
`scope` parameter. crates/tui/src/tools/remember.rs:165 states the legacy
single-file path was removed in v0.9.4; writes go through
`NativeMemoryStore::remember(scope, workspace_id, note)` (remember.rs:77-108).
config.example.toml documented two key sets that do not exist. Neither struct has
`deny_unknown_fields`, so both were silently discarded rather than rejected:
- `[advisor] max_tool_pairs` / `system_prompt`. `AdvisorConfigToml`
(crates/config/src/lib.rs:2369-2394) has enabled, max_tool_calls (default 10,
clamped 1-50 — the doc said 8, max 32), rate_limit_secs, dedup_window_secs,
and model. `model` was undocumented; now it is.
- `[fleet.profiles.*.permissions] allow_tools` / `deny_tools`.
`FleetProfilePermissions` (lib.rs:1966-1977) has allow_shell, trust,
approval_required. `rg 'allow_tools|deny_tools' crates/` finds nothing. The
example value was `"exec_shell"`, itself a removed tool name.
docs/CONFIGURATION.md: deleted the "Parsed but currently unused" section. Its one
entry, `tools_file`, is not parsed by anything — the field was removed in
346bfe3b6 and the doc bullet was orphaned. Repo-wide `rg` finds the string only
in that section, and nothing links a #parsed-but-currently-unused anchor.
docs/TTC_DESIGN.md said implementation "is deferred beyond v0.9.0". The `verify`
tool shipped and is default-on (crates/tui/src/tools/verify.rs,
features.rs:262, registry.rs:1040-1041 with verify_tool_enabled defaulted true).
Retitled as landed-in-part; capability (B) is still genuinely deferred, so the
doc stays. Its interface line said `with_verify(critic)`; the real signature is
`with_verify_tool(client, model)` (registry.rs:886).
docs/skills/README.md advertised `gh-plan-issues`, deleted in 18de2ebc0, and
credited these skills to "the v0.8.61 release" at a 0.9.4 release.
docs/architecture/provider-model-settings-v091.md pinned
`provider_is_configured` to config.rs:8625-8669; it is at :10160 and that region
is now unrelated code. Replaced with the symbol name, since config.rs is under
active edit.
docs/architecture/command-dispatch.md:133 claimed EPIC-002 was "ready for PR".
The PR (#3706) merged and #2870 closed 2026-08-01. Line 145 was an empty
"Current Evidence (Draft)" heading with no content; removed.
.gitignore: `git check-ignore -v` attributes .claude/settings.json,
scheduled_tasks.lock, worktrees/, and *.local.* to the blanket `.claude/` at
line 126, not to the specific rules above them. Dropped the redundant ones and
annotated why the HANDOFF_/CODEMAP_ patterns are deliberately kept.
Codewhale
An open source coding agent for your terminal — bring your own model.
Codewhale started as a native experience for DeepSeek. It has since grown into a community-driven project: one coding harness that fits a growing international community and supports as many models and providers as possible — open models first, hosted or local, none privileged over the rest.
Give it a provider, a model, and a task. It reads your code, edits files, runs
commands, and checks its own work, then stops when the job is done or it needs
you. Switch models mid-task with /model. Work interactively in the TUI, or run
codewhale exec in scripts and CI. It's written in Rust, licensed MIT, and runs
on your machine.
We're always looking for contributors and ways to improve. If a model or provider you use is missing, or something breaks, telling us is one of the most useful things you can do — see Contributing.
简体中文 · 日本語 · Tiếng Việt · Bahasa Indonesia · 한국어 · Español · Português · Русский · Українська · codewhale.net · Docs · Changelog · Discord
Install
npm install -g codewhale
Cargo, Docker, Nix, Scoop, prebuilt archives, Android/Termux, and a CNB mirror
for anyone who can't reach GitHub are covered in
docs/INSTALL.md. Coming from deepseek-tui? Your config and
sessions carry over — see docs/REBRAND.md.
Use
codewhale auth set --provider deepseek # or export ANTHROPIC_API_KEY, etc.
codewhale account login # optional Codewhale account sign-in
codewhale # open the TUI
codewhale exec "fix the failing test" # headless
codewhale web # local browser client on 127.0.0.1
Provider authentication and Codewhale account authentication are separate.
codewhale auth configures the model used by the local runtime.
codewhale account login opens the system browser, completes the device flow at
app.codewhale.net, and stores the resulting session in the OS credential
manager. Use codewhale account status, codewhale account logout, and
codewhale account keys to inspect the signed-in profile or manage
account-scoped BYOK credentials; the compatibility prefix codewhale cloud
remains accepted. Tokens and provider-key values are never printed.
In the TUI: /model switches provider and model together, /fleet runs a team
of workers, /undo reverts the last turn, and /restore <N> rolls the
workspace back to an earlier snapshot (bare /restore lists them). Tab
cycles Plan / Act / Operate when the composer is empty — with text in it, Tab
completes slash commands and @ mentions instead. Shift+Tab cycles the
Ask / Auto-Review / Full Access permission posture at any time. ! runs a
shell command through the normal approval path.
What it does
- Any model, any provider. DeepSeek, Claude, GPT, Kimi, GLM, and 30+ providers, plus your own vLLM, SGLang, or Ollama with no key — all through one runtime and one toolset. Context limits and prices come from the real route, and an unknown price shows as unknown rather than $0.
- Read-only until you allow more. Plan mode can't change files, and
approvals gate risky commands. When an OS sandbox actually wraps a command,
Codewhale says so: Seatbelt on macOS where available, opt-in bubblewrap on
Linux. A repo's
constitution.jsoncompiles into write holds that even Full Access can't skip. - Work you can resume. A fleet records every step to an append-only ledger,
so
fleet resumepicks up where you left off.
Learn more
- docs/PROVIDERS.md — every provider route: hosted, gateway, and local
- docs/FLEET.md — fleets, the ledger, and resume
- docs/WORKFLOW_EXPERIMENTAL_SEARCH.md — frozen, provider-neutral experimental search within Workflow
- docs/CONFIGURATION.md —
config.toml, hooks, and the constitution - docs/AUTHORIZATION_ORDER.md — how modes, hooks, permission rules, safety floors, repo law, approvals, and sandboxing compose
- docs/HOOKS.md — the eleven TUI lifecycle hook events, their
payloads, and which three of them can steer a turn (
codewhale execand the CLI subcommands do not fire hooks) - docs/WEB.md — the loopback-only browser client and its one-time authentication boundary
Everything else — modes, keybindings, sandbox details, MCP, the runtime API, and architecture — lives in docs and on codewhale.net.
Contributing
Issues, PRs, repro steps, logs, and feature requests are all real project work, and first contributions are welcome. When a PR can't merge as-is, maintainers harvest what works and keep the author credited — in the commit, the changelog, and docs/CONTRIBUTORS.md.
- Open issues — good first contributions live here
- CONTRIBUTING.md — dev setup and PR flow
- docs/CONTRIBUTORS.md — everyone who has shaped this
- Buy me a coffee
Thanks to DeepSeek for the models and support that started the project, DataWhale 🐋 for welcoming us into the Whale Brother family, and OpenWarp and Open Design for collaborating on the terminal-agent experience.
License
MIT. An independent community project, not affiliated with any model provider.