Projects
Two crates, cut once.
The workspace splits exactly once, and the boundary is a hard
constraint rather than a preference: crab-core may contain no terminal dependency and
no println!. That single rule is what makes a mock provider possible, what lets the
loop be tested headlessly, and what would let someone embed the agent without dragging in
crossterm.
A finer split — separate crates for sessions, pricing,
metrics, MCP — was considered and rejected. The problem a single crate with modules has is not that
it is inelegant; it is that it makes it far too easy for println! to leak into the
loop. One enforced cut solves that. Seven crates would mostly add ceremony.
Arrows point from dependent to dependency. Only crab-core and crab-cli
are workspace members; everything else is crates.io. Release profile: lto = "thin",
codegen-units = 1, strip = true — and deliberately no
panic = "abort".
Workspace
The two crates.
Both at v0.4.0, both Apache-2.0, both in the same repository.
crab-core
stableThe agent loop, the session log, the provider client, the seven tools, prompt assembly,
compaction, the MCP client, and skills discovery. No terminal dependency, no
println! — so it can be driven by a mock provider in a millisecond-scale test, or
embedded by someone who does not want a TUI.
The files worth reading if you want to know how a
coding agent actually works: agent.rs (turn loop, abort semantics),
stream.rs (the SSE state machine, a pure function), tool.rs plus
tools/ (contracts and their descriptions), compact.rs (shed and
summarise), mcp.rs, skills.rs.
crab-cli
stableThe binary you run: clap, crossterm, reedline, the renderer, the permission prompt, the
status line, and the trace / metrics subcommands. It owns
presentation and the database, and nothing else — BASE_PROMPT lives here because
it is terminal-shaped configuration, not domain logic.
rmcp
upstreamThe official Rust MCP SDK. crab uses it rather than writing its own protocol implementation, which is why MCP support landed without a second client to debug. It is also where the project learned that a handshake without a timeout can hang forever on a non-MCP subprocess.
docs/dogfood-log.md
recordThe log of every task handed to crab in its own repository: what was asked, what it did, what it got wrong, what a human had to fix. It is the most useful document in the project for anyone deciding whether to trust an agent with their own repo.
Adjacent
What crab borrows from.
None of this is original. The design record cites it, and the credit is genuine.
pi
The starting point. crab borrows the concept model — an agent loop, a session log, tool descriptions that live next to the tool — and its stance on minimalism. It borrows none of pi's source, prompt text or session schema, and makes no attempt at compatibility.
Model Context Protocol
The reason crab has no plugin ABI. Every external tool goes through MCP, which means the whole existing server ecosystem is available on day one instead of after an ABI design cycle.
Agent Skills
A directory with a SKILL.md and frontmatter. Boring on purpose: the format is a
file, so skills are reviewable, diffable and shareable without a registry.
DeepSeek Harness notes
An in-repo analysis of another pi-style harness settled three rules crab adopted: the log is the single source of truth, measurement replays the log instead of calling a model, and telemetry never enters the model context. Also where the four-way token split came from.
Guarantees
What the build enforces.
Claims are cheap. These are checkable in CI.
Binary size ceiling
A hard assert: the release binary must stay under 16 MiB. Measured 6.90 MiB at the CLI
milestone; roughly 10 MiB on macOS and 12.5 MiB on Linux once MCP and web_fetch
landed. Size is deterministic in CI, which is why it is asserted there and start-up time is
not.
fmt, clippy, tests
cargo fmt --check, clippy -D warnings on all targets and features,
and the full test suite. No live model is called: a CI that exercises a model tests the model,
flakes, and costs money.
340 tests, no network
MockProvider for the loop, recorded SSE fixtures per provider for the parser,
wiremock for 429 backoff and mid-stream disconnects, assert_cmd for
the CLI contract, insta snapshots for rendered output.
Contribute
The next commit could still be crab's.
The project's own bar is unchanged: a diff that crab produced, reviewed by a human. Issues with a trace attached are the most useful kind.