@giamme/forge

中文文档
0.19.0发布于 2026/11/16MIT零依赖构建来源已验证近 30 天下载 3109

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

原始使用文档
文档目录6 节
  1. Install
  2. Quick start
  3. How it works
  4. forge-ui
  5. Documentation
  6. License

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.

npm version Latest release License: MIT Changelog

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

A decomposed run in forge-ui's 3D view: eight tasks on a plate in their planned waves, five merged in green and two running in amber, with a mark over each block for every review finding, then the same run on wall-clock time, where two first attempts that failed review show in red beside the retries that passed.

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 high (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:

SpecMeans
solsol at the role's default effort, on its default CLI (codex)
sol:xhighthe same model at xhigh effort
sol:xhigh:openclaudethe same model and effort, run through openclaude

Either role can run through any of six agent CLIs:

codexclaudeopenclaudeopencodeantigravitygrok
binarycodexclaudeopenclaudeopencodeagygrok

→ 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.

The run cloud: about seventy runs as blocks in five project spirals, orbited, then laid out as galaxies and as a timeline with one lane per project.

forge-ui's window: the runs list, a run's eight tasks on a 3D plate in their planned waves with dependency cables, finding marks and the finish nodes, and the run's inspector.
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.
The same run on wall-clock time: one block per attempt, failed attempts in red with their finding marks, a plane marking now, the concurrency strip, and the inspector's timeline and critical path.
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.
The diff a reviewer read, with a P1 finding pinned under the line comparing token digests and a P2 finding under the revoke function.
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.
The model leaderboard: per implementer, tasks, first-attempt pass rate with a 95% interval bar, retries, escalations, timeouts, accepts, median model time and tokens.
Models, measured on your runs. First-attempt pass rate with a confidence interval, retries, escalations, time and tokens; reviewers' verdicts and shadow agreement.
The files heatmap: files grouped by directory against tasks grouped by wave, with planned, touched, drift and same-wave overlap marks.
Who touched which file. Planned, changed, drifted into or conflicted on, wave by wave; a cell opens that file's diff.
The map of every run: one block per run in a district per repo, green when done, amber while running, red with failures.
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

PageWhat's in it
Install and updatenpm or a git checkout, the doctor, what the installer does per CLI, updating
Command referenceevery /forge flag with examples, the forge command, the runner scripts and their exit codes
Models, efforts and harnessesthe alias:effort:harness spec, effort ladders and clamping, yolo mode, the model registry
Decomposed runsdecompose levels and difficulty, routing, waves, capsules, planning, resuming, split and combine, tasks.tsv
Reviews, retries and recoveryverdicts, retries, infrastructure stops, severity thresholds, accepting, whole-run and shadow reviews, guards, verification, fail-first
Fractal executionthe optional nested-execution backend: install, run, inspect, bounds and recovery
Project memory.forge/memory.md and the ledger, what each role is told, whether to commit it, spend
forge-uithe run viewer: commands, the shared server, environment variables, privacy
Run datasetevery run's inputs and outcomes, kept for training decision models
Run artifactsthe run directory, a plan's files, worktrees and branches
Safetywhat forge never does to your branch, preconditions, execution integrity
Ripwire and Jevoptional repository context and advisory judgments
Troubleshootingsymptoms, causes and fixes
Developmentrepository layout, offline checks, runtime measurement

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.

版本与发布记录

@giamme/forge 共发布 17 个版本,首次发布于 2026/10/21;过去 12 个月发布了 17 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.19.0latest2026/11/16今天
0.18.02026/11/132 天前
0.17.02026/11/114 天前
0.16.02026/11/079 天前
0.15.02026/11/0411 天前
0.14.12026/11/0312 天前

关于 @giamme/forge 的常见问题

@giamme/forge 是什么?

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

如何安装 @giamme/forge?

在项目目录运行 npm install @giamme/forge,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 forge,可以用 npx forge 直接运行。

@giamme/forge 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/giamme__forge 是否存在。

@giamme/forge 可以商用吗?

@giamme/forge 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@giamme/forge 的下载量有多少?

根据 npm 官方下载统计,@giamme/forge 在 2026/10/17 – 2026/11/15 这 30 天内被下载 3,109 次,日均约 104 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@giamme/forge 还在维护吗?

最新版本 0.19.0 发布于 2026/11/16(今天);至今共发布 17 个版本,其中过去 12 个月发布了 17 个;首次发布于 2026/10/21。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。