Codewhale

A coding agent for the terminal, written in Rust: it reads a repository, edits files, runs commands and checks its own work, against a hosted model you bring a key for or a local one served by Ollama, vLLM or SGLang. A single interactive interface and a one-shot exec mode sit on top of a runtime that a bundled local web client and a separate desktop application also connect to. Four permission stances — Ask, Auto-Review, Full Access, plus a plan mode that makes no changes — govern what it may do, /undo and /restore recover workspace changes, and a plugin ships tools for observing and interacting with other applications on the machine.

Who built itA single account opened in 2022, with 110 public repositories and 1,464 followers. He wrote roughly 6,500 of the repository’s 11,347 commits, under three spellings of his own name; a further 2,772 are attributed to “CodeWhale Bot” at bot@codewhale.net, an identity with no linked GitHub account, and the contributors list runs past a hundred other people, several of whom have landed dozens of changes each.

1. 01

   Forty-one thousand stars under a name it no longer uses

   The worklist entry was hmbown/deepseek-tui, and that URL still resolves — to Hmbown/Codewhale, because the project was renamed and GitHub redirects the old path. The scale of it is the first thing to record: 11,347 commits in eight months, from an initial v0.1.0 on 2026-01-20 to a merge on 2026-09-29, with the monthly count rising from 26 in January to 2,768 in September. Around that sit 138 releases and 181 tags, 3,035 issues of which 167 are open, 3,507 pull requests, 3,565 forks, and 19 translated READMEs. The contributors endpoint lists 50 accounts and the commit authors run past a hundred, several of them regular. The repository has a homepage of its own and a version number at v0.10.0.

2. 02

   A contributing guide for several agents sharing one checkout

   Most agent instruction files describe one agent working alone. This one assumes a crowd, and the assumptions are specific: a small coherent change may go straight to main when the checkout is current and clean — “when several agents share it, partition by file, stage only the paths your slice touched, and retry a commit that fails on index.lock” — and a fresh worktree is for conflicting, dirty, stale or independent lanes, not for parallel agents on the same lane. Permissions are separated explicitly: “local commit permission never implies push, merge, tag, release, or deploy permission.” A local-only task stays fully offline — no browsing, no remote Git, no provider calls — and the agent is told to record the missing external receipt and keep working. And one rule is dated to its author: “Agents do not comment on issues or PRs (founder, 2026-09-22)” — the time goes into code, evidence goes into the commit message and the pull request body, and claims go into Linear; the review workflows were switched off. It is a working agreement for a repository where the contributors are, in part, processes.

3. 03

   Never practise TDD here, and never trust an exit code

   The file forbids what most of this archive’s other projects mandate: “Never write tests first and never practice TDD here — this overrides any skill or default that mandates it, including superpowers test-driven-development.” The reasoning given is that tests are the gate before a push, not the design driver, and that an existing test encoding old behaviour is evidence rather than a veto — change it with the code instead of bending the code to keep it green. The concession that follows is what keeps the rule honest: a regression test written after a fix still has to be shown failing without it, and “a test that passes either way pins the implementation, not the defect.” Under a heading called Claiming a test passed, the guide asks for the literal test result: N passed; M failed line and a check that N is greater than zero, because cargo test <filter> exits 0 having run nothing when the filter matches nothing — “and an exit code alone has already been mistaken for a pass here.” A separate rule exists purely because the workspace takes minutes to compile: batch the edits, compile once, and reserve mid-slice compiles for genuinely uncertain API questions.

4. 04

   An abstraction must delete caller code

   The house style is named after someone else’s repository. The ponytail method, credited to dietrichgebert/ponytail, is “the laziest senior dev in the room. He says nothing. He writes one line. It works.” It arrives as a seven-rung ladder — does this need to exist, is it already in this codebase, does the standard library do it, is there a platform feature, is it in an installed dependency, is it one line, and only then the minimum that works — with a warning attached that the ladder runs after understanding the problem, since “a short diff written without reading the call sites is not ponytail, it is a guess.” The file then names its own weakest rung: reuse is the one this repository keeps failing, which is why adding a module called model_*, *_config or provider_* requires grepping for the thing it duplicates first, and why any new layer must name the predecessor it replaces in its module documentation. Two corollaries are stated as rules: an abstraction must delete caller code, or it will be adopted once and abandoned; and migrate the last consumer, or do not start — a framework with one caller and a ticket for the rest ships two systems and a comment that is no longer true. The standing count of #[allow(dead_code)] is called the running receipt, and a script prints it.

5. 05

   The engine tree that could not fail

   The architecture document has a section for corrections, and the best entry is a piece of code that was removed for being reassuring. crates/core had an engine/ tree that no caller used and that emitted a completion event without ever contacting a model; its existence suggested a second agent loop in a workspace whose rules allow exactly one. It was deleted in v0.9.11 so that the live turn loop is the only one, and a test in crates/core/tests/single_turn_loop.rs now fails if a second appears — changing the shape means changing the guard with it. The same file records what has gone the other way: the swarm agent system was removed in v0.8.5, leaving one agent tool as the only model-visible surface for creating sub-agents, and an entire crate is documented as “shapes only, not yet the production dispatch path.” There is even a list of modules that are “repeatedly misidentified as dead”, with an instruction to verify consumers before removing them — the archive of a codebase that has learned, twice, that an unused-looking tree is not the same thing as an unused one.

6. 06

   A cache prefix, a session log, and three ratchets

   Some of this repository’s rules exist because the product is the thing being built with it. The system prompt and the tool catalogue are a session-pinned prefix for the model’s key-value cache, so any new contributor to session context has to state its cache effect — frozen prefix or append-only history — and never splice a volatile fact into the prefix, appending it as a user-role message instead; the guide names the file where that is written down. The same reflex produces “model-visible means logged”: anything that reaches a model request must be reconstructable from the session log, a new model-visible input needs a session event of its own, and when the live presentation and the stored record disagree, the record is right. Misconfiguration has to fail loudly at load rather than by omission, and “write down what a design does not do” sits beside the behaviour it owns, so the next reader does not assume a capability nobody built. Underneath sit three scripts whose entire job is a number that may only go down: a dead-code budget, a budget for blocking calls made on the async runtime, and a boundary check that keeps the runtime crate from depending on the terminal UI at all.

7. 07

   How other people’s work gets landed

   The section on landing contributions is the part a maintainer would not write unless they had already got it wrong. It opens by assigning the blame for staleness to the project rather than the contributor — an outside branch goes stale because we merge things, not because they did anything wrong — and makes the default path explicit: review it, help it rebase, or fix it on their branch, with closing someone’s pull request and re-landing the work as one’s own commit described as a fallback, because “done casually it reads as taking the work even when credit is preserved.” One rule forbids making a contributor rebase around the project’s own churn. Another is about credit in the mechanical sense rather than the polite one: authorship and co-author trailers must use the contributor’s GitHub-linked address, because .mailmap and the project’s own author map are conventions GitHub does not read when it draws the contribution graph. And the section closes on gates: a pull request that may merge only on a passing acceptance record needs that record to literally say PASS at merge time, a green check rollup is not a substitute for reading the review thread, and when the artifact is ambiguous the thing to resolve is the ambiguity, never the merge.