Forge

A verification boundary for autonomous agents. Define outcomes, not procedures.

One agent, one prompt, full autonomy. Forge doesn't tell the agent what to do — it verifies whether the outcome was met. Verification is external, objective, and automatic.

$ forge run --spec specs/power-ups.md "implement power-ups"
# 8 power-ups implemented, verification passed — $6.03, ~8 min

Installation

# From npm
npm install -g @vieko/forge

# From source
git clone https://github.com/vieko/forge.git
cd forge
bun install
bun run build

Usage

forge run "implement feature X"                          # Run a task
forge run --spec specs/feature.md "implement this"       # From a spec file
forge run --spec-dir ./specs/ -P "implement these"       # Parallel specs
forge run --pending -P "implement pending"               # Run only pending specs
forge run --resume <session-id> "continue"               # Resume session

forge define "build auth system"                         # Generate specs from description
forge audit specs/                                       # Audit codebase against specs
forge review                                             # Review git changes
forge watch                                              # Live-tail session logs
forge status                                             # View recent results
forge specs                                              # List tracked specs with status
forge specs --add                                        # Register all untracked specs
forge specs --resolve game.md                            # Mark spec as passed
forge specs --check                                      # Auto-resolve implemented specs

See forge --help or forge <command> --help for all options.

How It Works

1. Prompt — wraps your task in an outcome-focused template
2. Agent — single autonomous call, no orchestration
3. Verify — auto-detects project type, runs build/test, feeds errors back (up to 3 attempts)
4. Save — results, session logs, and cost to .forge/results/

Specs can declare dependencies via frontmatter (depends: [a.md, b.md]) for ordered execution. Parallel runs use auto-tuned concurrency. A manifest (.forge/specs.json) tracks every spec from registration through execution. Failed specs can be rerun. Pending specs can be run selectively. Manually completed specs can be resolved. Sessions can be resumed or forked. Destructive commands are blocked. Transient errors retry automatically.

Configuration

export ANTHROPIC_API_KEY=sk-ant-...

Project-level overrides in .forge/config.json:

{ "maxTurns": 100, "maxBudgetUsd": 10.00 }

Works With

• Bonfire — Session context persistence. Use /bonfire spec to create specs, then run them with Forge.

Read More

• The Orchestrator I Didn't Build

Development

bun run src/index.ts run "test task"  # Dev mode
bun run typecheck                      # Type check
bun run build                          # Build
bun test                               # Run tests

Credits

Animation by Jon Romero Ruiz.

License

MIT