How forge works
A forge run is a route from your goal to reviewed code on your branch. Every station below is a page of these docs. Pick one to see what happens there, what you control, and the command that drives it.
Solid lines are the run itself; dashed lines are what you can do beside it. Press a station, or use Tab and Enter. Esc clears the route.
Install
forge installs from npm and links itself into every agent CLI it finds. The doctor tells you which CLIs it can reach.
npm install -g @giamme/forge forge install
Plan
For a big goal, forge splits it into tasks and rates each one low, medium or high by the judgment it needs, not its size. Your routing sends each tier to a model and CLI. One planner designs every task's approach, so the seams fit.
/forge "add auth: tokens, middleware, login" \ --decompose-level medium --profile balanced
Approve
forge shows you the table: every task, its difficulty, the model that builds it and the one that reviews it, and its approach. Then it stops. Retier a row or swap a model for free; nothing is dispatched until you say so. Brief mode can also ask you questions here.
Build
Each task goes to a dwarf, an implementer model, alone in its own git worktree with a fresh session and a short brief. Tasks run in waves: together only when they don't share files.
Review
qa, a reviewer model, reads the task's real diff in a throwaway copy of your repo and rates every finding P0 to P3. forge decides from the findings: a confirmed P2 or worse fails the task.
Retry
A failed task keeps its branch. A retry hands the dwarf the reviewer's findings in the same worktree, optionally on a stronger model, and the next review reads the whole task again.
forge-parallel.sh retry "$PLAN" token-model --dwarf sol:xhigh
Merge
A passing task merges into an integration branch forge made for itself. When the run ends, your verify command runs once on the combined result, lane by lane if you set lanes.
Integrate
Your branch changes only when you run integrate --approved. Ask for a final whole-run review first, or open a draft pull request with forge pr. forge never pushes.
forge-parallel.sh integrate "$PLAN" --approved
Project memory
What a run learns about your repo (the test command, a file never to hand-edit, a bug that keeps coming back) goes into a small .forge/memory.md that every later run reads.
Steer
Change a live run without stopping it: drain, resume, stop, retry a task, pin a model, change the review threshold or accept a task. Every change is logged.
forge control drain "$PLAN"
forge-ui
An optional local page that draws every run in 3D, with each diff, each finding on its line, each agent's conversation, and how your models compare.
forge ui open
Measure
Every run records its inputs and outcomes outside your repos, so forge can forecast a plan, grade reviewers, and show which models pass first time on your code.
forge dataset forecast "$PLAN"
The words forge uses
- goal
- What you want done, in your own words, after
/forge. - run
- One trip from a goal to reviewed code, with a folder of records.
- task
- A piece of the goal. A small goal is one task.
- dwarf
- The model that builds a task. You pick it with
--dwarf. - qa
- The model that reviews a task's diff.
--qa;opusif you don't say. - finding
- A problem the reviewer found: P0 data loss, security or crash, P1 wrong on realistic input, P2 an edge case, P3 minor.
- wave
- Tasks that can run at the same time because they don't share files.
- harness
- An agent CLI forge sends work through: codex, claude, openclaude, opencode, antigravity or grok.
- spec
- How you name a model:
alias:effort:harness, likesol:xhigh:codex.
Every page
Start and run
- Installnpm, the doctor, updating
- Your first runOne goal, one dwarf, one review
- Models and CLIsThe spec, efforts, profiles
- Parallel runsSplit, route, approve, waves
- Questions before a taskBrief mode, summaries, retro notes
- Reviews and retriesVerdicts, findings, thresholds
During and after
- Merge and verificationLanes, final review, integrate, PRs
- Steering a live runforge control, adopt, accept
- forge-uiThe 3D viewer
- From the terminalwatch, runs, issues, rerun
- Project memory.forge/memory.md and the ledger
- Measuring modelsThe dataset, routing, reviewers
Reference
- Disk and cleanupforge du, compact, rm
- What forge never doesThe guarantees
- When something goes wrongStatuses and fixes
- What's comingDev branch and planned work
- Full referenceEvery flag, in the repo
Full reference Every flag and edge case: docs/README.md