crab is a coding agent for the terminal. You point it at a folder, describe the work, and it reads, edits and runs things through seven tools. Everything it does is written down twice: as a message you can re-read, and as a span you can time and price.
What it is
A single Rust binary, inspired by pi. It owns the agent loop, the provider client, the tool implementations, the session log, context compaction, an MCP client and skills discovery. It does not own your model, your isolation, or your workflow.
- Binary
- ~12 MiB, one executable, no runtime dependency. The CI asserts a 16 MiB ceiling.
- Tools
- Seven built-ins: read, write, edit, bash, glob, grep, web_fetch. Anything else arrives over MCP.
- Providers
- Any OpenAI-compatible endpoint, as a profile in
~/.crab/config.toml. - Sessions
- Append-only JSONL in
.crab/sessions/, format version 2. - Ledger
- Cost and latency per run in
.crab/metrics.sqlite. - License
- Apache-2.0.
- Version
- 0.4.0 — "early but real".
Lineage, stated plainly
crab borrows pi's concept model — an agent loop, a session log, tool descriptions that live next to
the tool — but it is its own thing: its own session format, its own extension mechanism, and
no attempt at compatibility. There is no .pi/ half-compatibility layer, because a
half-compatible tail makes users expect full compatibility.
What it deliberately does not copy is pi's source, system-prompt text, or session schema text. The concepts are not copyrightable; the strings and formats are. That is why this repository is Apache-2.0.
Three things worth knowing first
It is a client, not a platform. crab talks to whatever endpoint you configure. There is no crab account, no proxy, and no telemetry endpoint. If you want a gateway in the middle, put one there.
It keeps a receipt. Two subcommands exist only to read back what happened:
crab trace for the shape of a run, crab metrics for the money and the
latency. The session log is the single source of truth for both.
The permission gate is a seatbelt, not a security boundary. It stops typos and confused
models. It does not stop a determined one, and the docs say so. Read
Run crab safely before you use --yolo anywhere that
matters.
Where to go next
How crab works
The turn loop, request assembly, streaming, compaction and where the numbers come from.
Design record
Twenty-one sealed decisions, including the alternatives that were rejected and why.
Status
crab is at 0.4.0. The core loop, the seven tools, config, MCP, skills, the TUI, compaction and both reporting subcommands are working and tested — 340 tests, three of them timing-sensitive and ignored in CI. What is not there yet: an extension API, themes, and session fork/branch. Those are listed on the landing page alongside the reason each was deferred.
The two contracts worth pinning against are the session format_version and the
turns table. Both are documented, and both will carry a compatibility note when they
change.