Your first run
Pick something small you'd normally do yourself: a bug fix, a helper, a test. A first run takes minutes, and nothing it does is hard to throw away.
- Open your agent CLI in the repo
Start Claude Code, Codex or any CLI forge is installed in, from your project's folder. Commit or stash your own edits first, so forge's change is the only thing in
git diff. - Give it a goal and a builder
/forge "add retry with exponential backoff to the HTTP client" --dwarf sol:high
That's the whole minimum.
solbuilds it athigheffort on Codex;opusreviews it athighon Claude Code, because that's the default reviewer. Write the goal like a good issue: what should change and how you'll know it works. The dwarf can't ask you questions halfway through. - Answer two quick questions
forge asks whether to use Fractal (say no for now) and whether to open forge-ui to watch. Answer up front with
--no-fractaland--uior--no-ui. - The dwarf builds, the reviewer reads
The dwarf edits your code and can run your tests in its sandbox. forge then captures exactly what changed, new files included, and hands that diff to the reviewer, who runs what it needs, lists findings and ends with a verdict.
- Read what comes back
You get a summary and the review: each finding rated P0 to P3, with its file and line. The change is in your working tree, uncommitted. Read it with
git diff, then keep, edit or drop it like your own work.
Try a few variations
# a strong reviewer for a tricky change /forge "fix the off-by-one in the pagination cursor" --dwarf luna:max --qa sol:xhigh # the same model, through another CLI /forge "port the config loader to TOML" --dwarf sol:high:openclaude # a cheap builder and an expensive reviewer /forge "update the docstrings to match the new signatures" --dwarf haiku --qa opus:max # another repo /forge "bump the pinned deps and fix the fallout" --dwarf sol:xhigh --repo ~/dev/other-project # a saved routing profile /forge "add CRUD endpoints for projects, users and teams" --decompose-level medium --profile balanced
When the dwarf needs out of its sandbox
A dwarf can edit files and run tests, but not install packages, write outside the repo or use the network. If the goal needs that, say so with --yolo-dwarf. It frees the builder only; the reviewer stays sandboxed and still can't edit what it's judging.
/forge "add integration tests against a real Postgres container" --dwarf sol:xhigh --yolo-dwarf
Bigger goals
When a goal has several parts, add --decompose-level and forge splits it into tasks that run in parallel, each reviewed on its own. You approve the plan before anything is spent. See Parallel runs.
Full reference Every flag and edge case: docs/commands.md