Forge

Forge

Delegate complex, multi-step development work to an autonomous agent that builds and verifies code. Forge is driven entirely through its CLI.

Hard rules

Read these first. They override patterns you've used for other tools.

1. ALWAYS pass --detach when running a detachable SDK command from inside Claude Code. The detachable SDK commands are run, define, audit, proof, verify, and pipeline. Without --detach the nested-session guard (CLAUDECODE=1) rejects them — the Agent SDK can't nest inside an active session. With --detach, forge auto-starts the executor daemon, runs the SDK in a separate process, and prints a task ID immediately.
2. After dispatching, poll with forge task <id> --wait (blocks until the task reaches a terminal state) or forge task <id> --json (one-shot status). Poll from the same repo you dispatched to (add -C <repo> if it's a different repo).
3. NEVER spawn a new Claude Code instance (tmux pane, new terminal, subagent) to run forge. --detach replaces tmux dispatch entirely. If the user wants to watch, point them at forge tui or forge watch.
4. Pack warm context into the prompt. The prompt string is the context — file paths, decisions, and constraints you've already discovered. Don't make the agent re-explore what you already know.
5. Read-only queries and safe mutations run directly via Bash (no --detach, no guard): status, stats, specs, tasks, watch, worktree list/status, config; and the mutations specs --add/--resolve/--unresolve/--manualize/--archive, worktree mark-review/mark-merged, pipeline gate, pipeline control.
6. Three SDK commands have no detach path -- go, review, and specs --check. Inside Claude Code the guard rejects them and there's no --detach bypass. Either present the exact command for the user to run in a separate terminal, or use a detachable equivalent: pipeline/run instead of go; review the diff yourself instead of review; audit --detach instead of specs --check for gap analysis.

When to use forge

• The work is complex enough to benefit from autonomous agent execution with verification
• The task targets a different repo (-C ~/other-project)
• You have spec files describing outcomes to implement
• You want to run multiple specs in parallel

The handoff pattern — most common use case

When the user says "hand this off to forge", "delegate to forge", "dispatch to forge", or similar:

1. Pack your research into the prompt — file paths, findings, decisions, constraints. Keep it tight; the agent does its own exploration.
2. Dispatch with --detach and capture the task ID. Use forge pipeline --detach for the full define → run → verify flow (the default for "hand off"); use a single SDK command (forge run --detach) when the user wants one specific stage.
3. Block on completion with forge task <id> --wait, or offer forge watch for live logs.
4. Stay in this session. Don't spawn a new Claude Code or tmux pane.

id=$(forge pipeline --detach -C /Users/me/project \
  "implement rate limiting for the API. Token-bucket; key files src/middleware/auth.ts \
   and src/routes/api.ts; Redis already configured in src/lib/redis.ts; must support \
   per-user and per-endpoint limits; 100 req/min default (team decision).")
forge task "$id" --wait -C /Users/me/project    # blocks until terminal state
# or, for live logs:
forge watch -C /Users/me/project

SDK dispatch reference

Each detachable SDK command (run, define, audit, proof, verify, pipeline) accepts -D, --detach (queue the work, auto-start the executor, return a task ID) and --json (emit {task_id, status, source} instead of plain text). The plain-text form prints just the ID, so it captures cleanly: id=$(forge run --detach "...").

Task lookups are repo-scoped: poll with the same -C <repo> you dispatched to.

Polling cadence

• forge task <id> --wait when you need the result before continuing (most handoffs). It blocks to a terminal state (completed | failed | cancelled); tune with --interval <ms> (default 1000) and --timeout <ms> (default: wait forever).
• forge task <id> --json one-shot when you want to check status without blocking.
• forge watch when the user wants live logs; it auto-follows batch runs and exits after the final session.
• Unattended wall-clock timeout (#254): detached/executor runs (no TTY) fail-fast with RUN_TIMEOUT if a single agent invocation (or verify attempt) exceeds config.runTimeout (default 60 min) -- this catches a run stalled on auth/network instead of letting it idle for hours. Interactive foreground runs are unbounded. Override with FORGE_RUN_TIMEOUT=<ms> (set it for runs that legitimately need longer).
• While a pipeline runs it owns the repo — don't commit, push, or open PRs, and don't run individual stages it already ran. The verify stage opens a PR automatically when the pipeline completes.

Anti-patterns — don't do these

• forge run "implement feature" from inside Claude Code without --detach — rejected by the nested guard.
• tmux split-window -h 'forge run ...' — dispatch with --detach and let the user observe via TUI/watch.
• Agent(subagent_type=..., prompt="run forge ...") — subagents can't run nested SDK either; dispatch with --detach from here.
• Dispatching with an empty or thin prompt — pack the warm context you already have.
• Manually parallelizing (forge run a.md & forge run b.md & wait) — use --spec-dir; forge owns dependency ordering, skip-passed, and concurrency.

Operating model

Treat forge in two modes:

• Authoring mode: define, proof, and similar planning/spec-generation flows can operate against the current checkout.
• Execution mode: run --isolate, worktree-backed execution, and dependency-level consolidation should be treated as committed-state validation.

Rules that matter in practice:

• spawned isolate worktrees are created from git refs, not from uncommitted filesystem state
• if a worktree-backed run depends on a local forge/runtime fix, commit that fix first
• after changing forge runtime code, rebuild with bun run build so the executor picks up the fresh build before you trust results
• prefer mechanical verification over narrative agent judgment whenever possible

Commands

forge run

forge run --detach "add auth middleware"                  # Simple task (dispatch + task ID)
forge run --detach --spec specs/auth.md "implement this"  # With one spec file
forge run --detach --spec-dir ./specs/ "implement all"    # Parallel specs (default)
forge run --detach -C ~/other-repo "fix the login bug"    # Target a different repo
forge run --detach --rerun-failed "fix failures"          # Rerun failed specs
forge run --detach --pending "implement pending"          # Run only pending specs
forge run --detach --resume <session-id> "continue"       # Resume an interrupted session
forge run --detach --plan-only "design API for auth"      # Plan without implementing
forge --detach "quick task"                               # Shorthand (no 'run')

Key flags (forge run --help for the full list):

• -s, --spec <path> — one spec file (shorthand resolves via manifest). The prompt becomes additional context.
• -S, --spec-dir <path> — a directory of specs. Shared-worktree runs execute sequentially by default; add -I, --isolate for parallel worktree-per-spec. Already-passed specs are skipped.
• -F, --force — re-run all specs including already passed.
• -B, --branch <name> — run in an isolated git worktree on the named branch; auto-commits on success, cleans up after.
• --in-place — run directly in the current checkout, skipping worktree creation (incompatible with --branch/--isolate).
• --concurrency <n> / --sequential / --sequential-first <n> — tune parallelism.
• --no-escalate — disable graduated model/effort escalation on verify-fail retry (#297). By default a failed verification retries with a stronger config (effort first, then model — e.g. sonnet@low -> sonnet@high -> opus@high) up to 3 attempts. Pin the config across attempts for clean cost/quality measurement.
• -t, --max-turns <n> (default 250), -b, --max-budget <usd>, --dry-run, -v/-q.

forge go

Smart shortcut for terminal use: auto-detects the stage from spec state (define if no specs, run if pending, etc.). Not detachable -- the nested guard rejects it inside Claude Code, so dispatch forge pipeline --detach or forge run --detach directly instead, or have the user run go in a separate terminal.

forge go "build auth system"                     # Separate terminal only (not inside Claude Code)

forge define

Analyzes the codebase and generates outcome spec files from a high-level description. Closes the loop: define → specs → run --spec-dir "implement".

forge define --detach "build auth system"            # Generate specs in specs/
forge define --detach "add rate limiting" -o specs/api/
forge define --detach "refactor database" -C ~/project

forge audit

Reviews the codebase against specs. Produces new spec files for remaining work — feed them back into forge run --spec-dir.

forge audit --detach specs/                      # Audit all specs in a directory
forge audit --detach specs/auth.md               # Audit a single spec
forge audit --detach specs/ "focus on auth"      # With additional context
forge audit --detach specs/ --fix                # Audit-fix loop (audit -> fix -> re-audit)
forge audit --detach specs/ --fix --fix-rounds 5 # Custom max rounds (default: 3)

forge proof

Generates real test files from implemented specs: .test.ts files colocated with source, a manual.md checklist, and a manifest.json. Auto-detects test framework. forge prove is a backward-compatible alias.

forge proof --detach specs/feature.md            # Single spec
forge proof --detach specs/                      # All specs in a directory
forge proof --detach specs/a.md specs/b.md       # Multiple specific specs
forge proof --detach specs/ -o ./custom-proofs/

forge verify

Executes generated proof tests and prepares a PR/manifests around the verification run.

forge verify --detach proofs/
forge verify --detach proofs/ -C ~/other-repo

forge review

Reviews recent git changes for bugs and quality issues. Not detachable -- inside Claude Code, present it for the user to run in a separate terminal (or review the diff yourself).

forge review                                     # Review main...HEAD
forge review HEAD~5...HEAD                        # Specific range
forge review --dry-run -o findings.md             # Report only, write to file

forge pipeline

Chains define → run → verify into one automated flow with observable gates. The pipeline process stays alive and polls for gate changes — the TUI and pipeline gate/pipeline control approve gates by writing state, not by spawning processes.

forge pipeline --detach "build auth system"            # Full pipeline
forge pipeline --detach --from run --spec-dir specs/ "go"  # Start at run with existing specs
forge pipeline --detach --gate-all confirm "careful build" # Pause at every gate
forge pipeline status [id] [--json]                    # Show pipeline state
forge pipeline gate <define|run> [id] [--skip]         # Approve (or --skip) a waiting gate
forge pipeline control [id] --pause|--cancel           # Pause or cancel
forge pipeline --resume <pipeline-id>                  # Resume a paused/failed pipeline

Gates default to: auto (define→run), confirm (run→verify). TUI controls: a advance, s skip, p pause, c cancel. pipeline gate/pipeline control/pipeline status are read/mutation commands — run them directly (no --detach).

Read-only inspection

forge status [--all] [-n 5] [-C ~/repo]          # Run results (latest / N / all)
forge stats [--by-spec|--by-model|--by-source]   # Aggregate cost + success rate
forge stats --since 2026-03-01
forge tasks [--active] [--json] [-C ~/repo]       # Queued/running tasks across CLI/TUI
forge task <id> [--wait] [--json] [-C ~/repo]     # A single task (poll/block)
forge config [-C ~/repo]                          # Effective config with source tracking
forge watch [<session-id>] [-C ~/repo]            # Live-tail session logs
forge tui                                         # Interactive dashboard

Spec lifecycle

forge specs [--pending|--failed|--passed]        # List tracked specs (filtered)
forge specs [--orphaned|--untracked|--summary]   # Diagnostics / roll-up
forge specs --add [specs/new.md]                 # Register untracked spec(s)
forge specs --resolve game.md                    # Mark passed without running
forge specs --unresolve game.md                  # Reset to pending, clear run history
forge specs --manualize game.md                  # Toggle manual follow-up (excluded from batch)
forge specs --archive game.md                    # Toggle archived (excluded from batch)
forge specs --reconcile                          # Backfill state from results history
forge specs --prune                              # Archive orphaned entries (file missing)
forge specs --prune-pending                      # Dry-run: list phantom pending rows (scanner noise)
forge specs --prune-pending --apply              # Delete them (no run history, outside spec dirs)
forge specs --check                              # SDK (not detachable): triage pending specs, auto-resolve implemented ones

forge specs --check is an SDK command with no detach path (it runs a Sonnet agent) -- inside Claude Code, present it for the user to run in a separate terminal, or use forge audit --detach for a detachable gap analysis. Lifecycle recovery rules of thumb: --add when the spec exists and should be tracked; --reconcile when there's run history to backfill; --manualize when the remaining work is operator/manual; --archive when the spec is intentionally no longer active backlog; --prune-pending when forge specs shows phantom pending rows that were never real specs (scanner-ingested files with no run history, outside spec dirs -- dry-run first, then --apply); leave a spec pending without strong evidence to resolve otherwise. SQLite is the source of truth; .forge/specs.json is a regenerated export — never edit it by hand.

Worktree + consolidation

forge worktree list [--status awaiting_review]
forge worktree status <id>
forge worktree mark-review <id>                  # Ready for review
forge worktree mark-merged <id>                  # After the PR lands
forge worktree prune [--dry-run]
forge worktree repair                            # Defaults to dry-run; --fix to apply
forge consolidate [--work-group <id>]            # Merge one awaiting-review group, open a PR
forge consolidate --all-ready                    # One consolidation per awaiting-review group
forge consolidate --dry-run                      # Preview the merge plan

Typical flow: mark-review <id> when implementation is ready → for a single awaiting-review worktree, review and PR the forge/* branch directly → consolidate --work-group <id> only when a group has multiple awaiting-review worktrees needing one combined review branch → mark-merged <id> after that PR lands. Consolidation opens PRs to main; it never merges into local main directly.

forge executor

Starts the task executor daemon (drains the local queue: CLI --detach, TUI). --detach auto-starts it, so you rarely run this by hand — use it when tasks are queued but nothing is picking them up.

forge executor

Important

Never manually orchestrate parallel forge runs (e.g. forge run a.md & forge run b.md & wait). Forge handles parallelism, dependency ordering, and skip-passed internally via --spec-dir. Manual orchestration bypasses the dependency graph, manifest tracking, and batch grouping.

Always prefer --spec-dir over running individual specs. It skips already-passed specs (use --force to override), resolves depends: frontmatter into a topological order, tracks the batch with grouped cost reporting, and auto-tunes concurrency.

For --isolate, commit first. Isolate worktrees only see committed branch state. If the run depends on local forge/runtime changes, commit them, rebuild, and let the executor pick up the fresh build.

--spec takes exactly one file. The prompt is always the last positional argument (a quoted string). Bare file paths without a flag are interpreted as the prompt, not as spec files. To run multiple specs, use --spec-dir.

Shorthand resolution: spec paths resolve automatically. forge run --spec login.md finds the spec via manifest lookup; forge run --spec-dir proj-580 finds .bonfire/specs/proj-580/. Full paths always work too.

Pipeline is autonomous end-to-end. When you dispatch forge pipeline --detach, wait for it via forge task <id> --wait. Don't run individual stages afterward (it already ran them), and don't commit/push/PR while it runs — verify opens the PR on completion.

Common mistakes

# WRONG: SDK command inside Claude Code without --detach (nested guard rejects)
forge run --spec-dir specs/ "implement all"
forge go "build auth"
forge define "add feature"

# WRONG: dispatching to a tmux pane
tmux send-keys -t 2.2 'forge run ...' Enter

# RIGHT: dispatch with --detach, then poll
id=$(forge run --detach --spec-dir specs/ "implement all")
forge task "$id" --wait

# WRONG: bare paths without --spec are treated as the prompt string
forge run --detach specs/auth.md specs/login.md

# WRONG: --spec only takes one file
forge run --detach --spec specs/auth.md specs/login.md "implement"

# WRONG: manually running specs one-by-one bypasses dependency ordering
forge run --detach --spec 01-schema.md "go" && forge run --detach --spec 02-api.md "go"

# RIGHT: a directory of specs via --spec-dir
forge run --detach --spec-dir specs/ "implement all"

# RIGHT: a single spec via --spec
forge run --detach --spec specs/auth.md "implement this"

Recipes

Spec-driven development

# 1. Write specs as .md files (see references/writing-specs.md)
# 2. Run them in parallel and block on completion
id=$(forge run --detach --spec-dir ./specs/ "implement all specs")
forge task "$id" --wait
# 3. Rerun any failures
forge run --detach --rerun-failed "fix failures"
# 4. Check results
forge status

Triage then run pending

forge specs --pending                                  # See what's pending
forge specs --check                                    # Separate terminal: auto-resolve implemented specs
id=$(forge run --detach --pending "implement remaining")
forge task "$id" --wait

Audit-then-fix loop

# Manual: audit, then run remediation specs
id=$(forge audit --detach specs/ -C ~/project); forge task "$id" --wait -C ~/project
forge run --detach --spec-dir specs/audit/ -C ~/project "fix remaining"
# Automated: convergence loop (audit -> fix -> re-audit, default 3 rounds)
forge audit --detach specs/ --fix -C ~/project

Deep-dive references