forge

Multi-model coding with a reviewer that reads the code: plan, build in parallel worktrees, review every real diff, merge only what passes.

A skill for Claude Code, Codex, OpenCode, OpenClaude, Antigravity and Grok.

Install · Quick start · How it works · forge-ui · Docs · Changelog

_{The run from Quick start in forge-ui: its tasks in the waves the plan gave them, then as they really ran, the failed attempts and their retries included. Demo data.}

You hand forge a coding goal and pick the models. Dwarves implement it. A qa reviewer
reads each dwarf's real diff, never the dwarf's summary of its own work. A model grading its own
homework isn't a check: the second stage is worth having because it sees the code, not the claim.

• Any model, any CLI. --dwarf sol:xhigh --qa opus runs GPT through Codex and Claude Opus
  through Claude Code in one command, from whichever CLI you are in. → Models
• Parallel when you want it. --decompose-level splits the goal into tasks, routes each to a
  model by difficulty, and runs them concurrently in isolated git worktrees.
  → Decomposed runs
• Only reviewed work merges. Every task is reviewed on its own diff. A failed task keeps its
  branch for a retry with the reviewer's findings, and only passing tasks merge.
  → Reviews
• You decide what gets spent and what lands. A decomposed run shows you the task table and
  stops before any dispatch. Solo changes stay uncommitted, decomposed work lands on your branch
  only through integrate --approved, and forge never pushes. → Safety
• It learns your repo. What a run discovers goes into a small .forge/memory.md, and every
  later run is given it. → Project memory
• You can watch it live. forge-ui draws every run in 3D, with diffs, findings and a model
  leaderboard. → forge-ui

Install

npm install -g @giamme/forge
forge install                  # links forge into every agent CLI it finds

Update with npm install -g @giamme/forge@latest && forge install. Or install from a git
checkout:

git clone https://github.com/Giamme/forge.git ~/.claude/skills/forge
bash ~/.claude/skills/forge/scripts/forge-install.sh

forge runs on macOS and Linux. It needs bash, git, Python 3.9 or later, and the agent CLIs
you route models through; the doctor shows which
ones it can reach. Foundry's forge shares the name: see
the Foundry note.

→ Install and update

Quick start

Inside any agent CLI where forge is installed:

/forge "add retry with exponential backoff to the HTTP client" --dwarf sol:high

That's the whole minimum. sol builds it at high effort on Codex, opus reviews the diff at
xhigh (the default reviewer), and you get back a summary of the change plus qa's findings.

# pick both sides
/forge "fix the off-by-one in the pagination cursor" --dwarf luna:max --qa sol:xhigh

# the same model, through a different CLI
/forge "port the config loader to TOML" --dwarf sol:high:openclaude --qa opus

# let the dwarf leave the sandbox to install deps and run the suite
/forge "add integration tests against a real Postgres container" --dwarf sol:xhigh --yolo-dwarf

# several dwarves in parallel, routed by difficulty
/forge "add auth: middleware, token model, login route, and docs" \
  --decompose-level medium \
  --dwarf-high sol:xhigh --dwarf-low gemini:low:antigravity --dwarf luna:high

A decomposed run plans the tasks, rates and routes each one, then shows you the table and
stops before spending anything. Before an interactive run, forge also asks whether to use
Fractal and whether to open forge-ui.

→ Every flag, with more examples

How it works

flowchart LR
    goal(["your goal"]) --> plan["plan: tasks and models,<br/>then you read the table"] --> dwarf["each task: a dwarf<br/>implements it in<br/>its own worktree"] --> qa["qa reads<br/>the real diff"]
    qa -. "FAIL: retry with<br/>the findings" .-> dwarf
    qa -- PASS --> merge["merged into<br/>integration"] --> deliver(["verification, final review,<br/>integrate --approved"])

Without --decompose-level, the whole goal is one task: one dwarf, and one review of its diff.
With optional Fractal execution, an implementer can delegate bounded child
tasks inside the paths it owns. forge still reviews the combined diff.

Every model is named by one spec, alias:effort:harness. Each field after the alias is optional:

Either role can run through any of six agent CLIs:

→ Effort ladders, clamping, sandboxes and adding a model

forge-ui

forge-ui is an opt-in, read-only local page that watches any run live, drawn as a 3D map. It
shows every run on one plate, tasks in their waves and as they really ran, and the prompt, model,
timings and P0–P3 findings behind every step. forge offers it at the start of every new run and
never opens it without a yes.

A run, as planned. Tasks in their waves with dependency cables, ending in integration, verification and the final review. Click a task to open its attempts, dwarves and reviews.	And as it ran. One block per attempt in the lane it ran in, failed ones in red, against --max-parallel; the inspector names the critical path.
Findings on their lines. Any diff of a task, or exactly the diff one reviewer read, with each P0–P3 finding under the line it names.	Models, measured on your runs. First-attempt pass rate with a confidence interval, retries, escalations, time and tokens; reviewers' verdicts and shadow agreement.
Who touched which file. Planned, changed, drifted into or conflicted on, wave by wave; a cell opens that file's diff.	Every run, by repo. One block per run with a lamp per task, filtered by state, repo, model, age or review verdict.

To look around before your first run, open it on made-up runs (the ones pictured here) from a
git checkout:

python3 ui/tools/demo_runs.py /tmp/forge-demo
(cd ui && python3 -m forge_ui --no-registry --root /tmp/forge-demo --open)

→ forge-ui

Documentation

License

forge is released under the MIT License. forge-ui's 3D view ports code from
archivision, iso-glow and iso-figure, all MIT-licensed; their notices are in
ui/THIRD_PARTY_NOTICES.md.