Forge

Delegate complex, multi-step development work to an autonomous agent that builds and verifies code.

When to Use Forge

Use forge when:

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

Don't use forge when:

•The task is a simple edit you can make directly
•The user is asking a question, not requesting implementation
•The work is in the current file / current repo and straightforward

Commands

forge run

bash

forge run "add auth middleware"                          # Simple task
forge run --spec specs/auth.md "implement this"          # With spec file
forge run --spec-dir ./specs/ -P "implement all"         # Parallel specs
forge run -C ~/other-repo "fix the login bug"            # Target different repo
forge run --rerun-failed -P "fix failures"               # Rerun failed specs
forge run --resume <session-id> "continue"               # Resume interrupted session
forge "quick task"                                       # Shorthand (no 'run')

Important flags:

•-s, --spec <path> -- Spec file. Prompt becomes additional context.
•-S, --spec-dir <path> -- Directory of specs. Each .md runs separately.
•-P, --parallel -- Run specs concurrently (auto-tuned concurrency).
•--sequential-first <n> -- Run first N specs sequentially, then parallelize.
•-C, --cwd <path> -- Target repo directory.
•-w, --watch -- Auto-split tmux pane with live logs.
•--dry-run -- Preview tasks and estimate cost without executing.

Run forge run --help for all flags.

forge audit

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

bash

forge audit specs/                              # Audit, output to specs/audit/
forge audit specs/ -o ./remediation/            # Custom output dir
forge audit specs/ -C ~/target-repo             # Different repo

forge review

Reviews recent git changes for bugs and quality issues.

bash

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 watch

Live-tail session logs with colored output. Auto-exits when session completes.

bash

forge watch                                     # Watch latest session
forge watch <session-id>                        # Watch specific session

forge status

bash

forge status                                    # Latest run
forge status --all                              # All runs
forge status -n 5                               # Last 5 runs

Recipes

Spec-driven development

bash

# 1. Write specs as .md files (see references/writing-specs.md)
# 2. Run them in parallel
forge run --spec-dir ./specs/ -P "implement all specs"
# 3. Rerun any failures
forge run --rerun-failed -P "fix failures"
# 4. Check results
forge status

Foundation specs first, then parallelize

Number-prefix specs for ordering. Foundations run sequentially before the parallel phase:

bash

forge run --spec-dir ./specs/ -P --sequential-first 2 "implement"
# Runs 01-*.md, 02-*.md sequentially, then 03+ in parallel

Audit-then-fix loop

bash

forge audit specs/ -C ~/project                 # Find gaps
forge run --spec-dir specs/audit/ -P -C ~/project "fix remaining"

Resume or fork after interruption

bash

forge run --resume <session-id> "continue"               # Pick up where you left off
forge run --fork <session-id> "try different approach"    # Branch from that point

Deep-Dive References

Reference	Load when
writing-specs.md	Writing spec files for forge to execute
parallel-execution.md	Tuning concurrency, understanding cost, monitoring parallel runs