forge

Purpose

Forge is a native plugin for Claude Code whose goal is to turn a "one-line idea" into a "tested, reviewed, and committed code branch," that is, an automated pipeline from brainstorm to commit. It is intended to replace the developer's role as the "glue"—where previously a person had to repeatedly write prompts, review code, re-prompt, and re-explain context, Forge takes on this coordination work through an autonomous loop. The user only needs to read the diff in the morning.

Main capabilities

• Five-phase autonomous loop:
  1. brainstorm: the idea becomes a specification (spec) with R-numbered items, including testable acceptance criteria.
  2. plan: the spec becomes a dependency-ordered task DAG, with token estimates attached.
  3. execute: each task runs under TDD in an independent git worktree; passing tasks are atomically squash-merged.
  4. review + verify: the reviewer checks the code, and the verifier checks each R number item by item across four levels (existence, substantive non-stub, wired usage imported, runtime).
  5. backprop: when a runtime failure exposes a spec gap, the gap becomes a new acceptance criterion + regression test, and the loop continues.
• State persisted to disk: state is saved on disk .forge/ directory, rather than in the conversation window, so crashes, context resets, and OOM can all be recovered from.
• Isolation and atomic merge: each task runs in an independent git worktree, and failed tasks do not touch the main branch; on success it is squash-merged with a structured commit message, and on failure the worktree is discarded.
• Crash recovery: lock files with heartbeats, step-by-step checkpoints, forensic recovery from git log; after a mid-way restart, /forge:resume can be used to rebuild state and continue.
• Token budget control: per-task and session budgets are hard caps, and when 100% is reached the state machine writes a handoff at .forge/resume.md and stops cleanly;/forge:resume continues from where it left off.
• Token-saving mechanisms: the PostToolUse filter trims long Bash output (such as npm install、git diff、tsc、find、curl) to head + warnings + tail; a 120-second read tool cache reduces repeated file reads; caveman compression removes filler from inter-agent handoff text; per-role max_tokens caps (2k–16k).
• Headless-ready: with correct exit codes, about 2 ms JSON status queries, and zero interactive prompts, /forge:status --json can be connected to Prometheus or cron.
• Multiplayer mode (optional): enabled via /forge:collaborate , optionally using Ably for sub-second cross-machine coordination; two or more people in the same repository can drive different tasks in parallel through a distributed claim queue (120-second lease).

How to use

Installation takes two minutes and requires Claude Code v1.0.33+; the single-player path does not require npm install. The basic flow is three commands, one autonomous loop, and one squash-merge: after writing the idea, run the corresponding command, then leave; when it is done, read the diff and merge the branch. The pipeline is strictly ordered and program-enforced: brainstorm → plan → execute, and you cannot skip brainstorming, skip planning, or bypass the approval gate.

When the loop completes but the feature still has problems (<promise>FORGE_COMPLETE</promise> is a structural gate: the task is complete, tests pass, the reviewer is satisfied, and the verifier is satisfied, yet it may still behave abnormally in the browser, for example a blurry canvas, a blank panel, or an incorrect state after clicking, because unit tests do not render pixels):

1. Manual smoke test: open the dev server, click for 90 seconds, and write down the problems in plain language.
2. Run /forge:backprop "<问题描述>". Backprop will trace back to the R-numbered acceptance criterion that should have caught the problem, propose a tightened criterion, and generate a regression test that would fail against the released code.
3. If backprop cannot locate the gap, read the spec. Criteria such as "the feature exists" or "the tests pass" are usually the culprit; rewrite them as observable behavior (for example, "after clicking logout, the URL becomes /login and the session cookie is cleared"), then rerun /forge:execute.

For visual acceptance criteria in 0.3+, the verifier may choose the perceptual gate:[visual] path=/login occluded_check=true selector="#login-form" runs through Playwright, with deterministic readiness (document.fonts.ready + animations disabled + 2× rAF) and occlusion detection based on elementFromPoint , so that targets hidden behind a modal fail instead of silently passing.

Regarding permissions: full mode assumes that when you run /forge:execute --autonomy full you have already authorized the side-effect category, but it still refuses destructive git operations and pauses before pushing.

When to use it

Suitable for individual developers building features in Claude Code, to reduce the overhead of acting as project manager, state machine, and glue; also suitable for teams that need multiple people to drive different tasks in the same repository in parallel and want AI decisions committed to git as tagged commits that can be reviewed asynchronously. It is also suitable for headless automation scenarios that want to connect state queries to monitoring or scheduled tasks.

Limitations

• Requires Claude Code v1.0.33+.
• The pipeline is strictly sequential; brainstorming, planning, or approval gates cannot be skipped.
• Features that pass all four layers of verification may still behave abnormally in the browser, because unit tests do not render pixels, requiring manual smoke testing and backprop.
• Actual token savings depend heavily on the task: workloads with no filterable Bash, no repeated reads, and no lengthy handoffs see almost 0% reduction.
• Multiplayer mode is optional and requires additional configuration (for example, Ably).

Other

Repository address:https://github.com/LucasDuys/forge . Documentation includes docs/commands.md, docs/budgets.md, docs/configuration.md, docs/comparison.md, docs/architecture.md, docs/agents.md, docs/verification.md, docs/recovery.md, docs/backpropagation.md, docs/collaborate.md, docs/visual-verification.md, docs/worktrees.md, docs/headless.md . Contribution process: Fork the repository, create a feature branch, make changes, run the tests node scripts/run-tests.cjs, open a pull request; see CONTRIBUTING.md for details. The Caveman skill is adapted from JuliusBrussee/caveman (MIT); the Ralph Loop pattern comes from Geoffrey Huntley; the spec-driven development concept comes from TÂCHES' GSD v1; the Karpathy guardrails come from andrej-karpathy-skills; the Claude Code plugin system is provided by Anthropic, and Forge is a native extension rather than a wrapper. Specific pricing and billing information is not currently provided.