Quickstart — docs

Five steps from nothing to a session you can explain. This page assumes a folder with git in it, because the interesting parts of crab are easier to see when there is something to break.

1. Install

One command, assuming a Rust toolchain is already present:

curl -fsSL https://crabagent.ai/install.sh | sh

$ crab --version
crab 0.4.0

That is the whole install. It builds from the repository because crab is not on crates.io yet — the install guide covers prebuilt binaries and building from a clone.

2. Point it at a model

Fastest path — one variable and the OpenAI defaults:

export CRAB_API_KEY=sk-...

Or use a profile. Any OpenAI-compatible endpoint works:

# ~/.crab/config.toml
default_provider = "deepseek"

[providers.deepseek]
base_url       = "https://api.deepseek.com/v1"
model          = "deepseek-chat"
api_key        = "sk-..."
context_window = 128000

context_window is not decoration. It drives the "running out of window" warning and the auto-compaction threshold, so a wrong number means either wasted context or a compaction at the wrong moment. If you do not know the real figure, understate it — see Providers & models.

3. Start in a project

cd ~/src/my-project
crab

crab uses the working directory for four things: where tools read and write, where .crab/sessions/ and .crab/metrics.sqlite live, and where it looks for AGENTS.md.

4. Give it a task

Be specific about the outcome, not the steps. The loop iterates happily; it is bad at guessing what "clean this up" means to you. Type / to browse slash commands.

crab> add a --json flag to the metrics command and cover it with a test

On the first mutating tool call you get one prompt:

⚠ edit — crates/crab-cli/src/metrics.rs
allow? [y]es/[n]o/[a]ll:

y: Allow this call. The next call to the same tool asks again.
n: Refuse. The refusal goes back to the model as the tool result, which is usually enough for it to change approach.
a: Allow that class of tool for the rest of the session only. It does not persist across restarts.

Read-only operations — read, glob, grep, and bash commands classified as read-only — never prompt. Ctrl+C aborts the current run without exiting: text produced and tool results completed so far stay on disk.

5. Read what happened

Leave the session, then read it back. This is the step people skip and then complain that agents are opaque.

$ crab trace .crab/sessions/session-1792661000878881000.jsonl
run 0 · 63 spans
├── ✓ llm  openai/deepseek-chat · 5663ms · ↑254 ↓257.7k (cr0 cw257.7k)
├── ✓ tool read · 4ms │ read {"path":"crates/crab-cli/src/metrics.rs"}
├── ✓ tool bash · 5392ms │ bash {"command":"cargo test -p crab-cli"}
└── ✓ llm  openai/deepseek-chat · 2896ms · ↑275 ↓258.8k (cr257.9k cw921)

$ crab metrics
crab metrics · last 7 day(s)

BY DAY
  2026-10-22  turns 2  ↑3.6k ↓309.2k  cr308.6k cw622  cost $0.0064  tool-err 0%  p50 5481ms p90 5481ms

The ↓ column is everything you sent; cr is how much of it the provider had cached. On a long session that ratio is the difference between a cheap run and an expensive one — and it is invisible in every tool that does not show it.

Where people go next

How crab works — the turn loop and where tokens are counted.
Sessions & compaction — --continue, and what compaction actually records.
Run crab safely — before you use --yolo on a real repo.
Providers & models — profiles, local models, and MCP servers.

← PreviousInstall Next →How crab works