Forge

Plan. Run. Review. Ship. Don't watch.

Turn an approved rolling epic into a reviewed, tested draft pull request without babysitting agent sessions.

Forge treats coding-agent sessions as durable jobs. Plan with one lead agent, approve the boundaries, then let Forge execute rolling waves of implementation, tests, independent review, and bounded fixes. You get one draft pull request—or a precise question. Forge is for experienced engineers who trust headless agents.

Why Forge

• Leave the session. Detached controllers outlive the initiating agent.
• Keep the plan honest. Forge reassesses only predeclared, unstarted work; changed outcomes, scope, or authority stop for your decision.
• Bring your own agents. Use Claude Code, Codex, or Pi with your own accounts.
• Scale past one terminal. Submit multiple epics and inspect durable status instead of watching tool-call streams.
• Keep control. Forge may integrate clean child work, but never merges the default branch.

flowchart LR
    A["Plan and approve"] --> B["Implement, test,<br/>and review a wave"]
    B --> C{"Work remains?"}
    C -->|Yes| D["Reassess only<br/>unstarted work"]
    D --> B
    C -->|No| E["Integration assurance"]
    E --> F["Draft PR for you"]
    D -->|Contract must change| G["Input required"]

Loading

Forge keeps state under ~/.anvil, adds no hooks or policy files to target repos, and requires no Forge-hosted service. Network access uses only services you configure.

Install

Starting with the published v0.5.0 release, the installer checks the archive against the release's SHA-256 manifest, then installs the CLI and plugin bundle under ~/.local:

curl -fsSL https://github.com/tcashel/forge/releases/latest/download/install.sh | sh

The CLI lands at $HOME/.local/bin/forged; the plugin lands at $HOME/.local/share/forge. The installer does not use sudo, edit shell profiles, register plugins, initialize state, start services, or touch a repo. Add the CLI directory to PATH yourself if needed.

Conflicts are preserved unless you request replacement:

curl -fsSL https://github.com/tcashel/forge/releases/latest/download/install.sh | sh -s -- --force

Uninstall removes installer-owned files while preserving ~/.anvil, Beads data, credentials, and repositories:

# macOS only, if you installed the managed supervisor:
forged service uninstall
curl -fsSL https://github.com/tcashel/forge/releases/latest/download/uninstall.sh | sh

Connect your lead agent

Registration is explicit. For Claude Code, replace <HOME> with the absolute value of $HOME:

/plugin marketplace add <HOME>/.local/share/forge
/plugin install forged@forge

Codex:

codex plugin marketplace add "$HOME/.local/share/forge"
codex plugin add forged@forge

Pi:

pi install "$HOME/.local/share/forge"

See the plugin guide for host-specific details.

Start an epic

In the target repository, run /forged:setup (/skill:setup in Pi) to verify configuration.

Then describe the outcome, not the machinery:

Plan this work as a rolling Forge epic. Critique it and bring me the decisions
I need to approve.

After you approve the specification and epic:

Run epic <id> with Forge using standard assurance. Stop at a draft pull request.

For an existing approved Beads epic, use the same handoff through the CLI:

forged epic start --epic "$EPIC_ID" --repo "$PWD" \
  --profile standard --roster default --rolling
forged epic submit --epic "$EPIC_ID"

Submission returns immediately. The agent may leave; the host machine must remain awake and available while local controllers and agents run.

Prerequisites and boundaries

• x86_64 or arm64 macOS, or GNU/Linux with glibc 2.35+; musl/Alpine and other architectures have no prebuilt archive.
• git, authenticated gh, and Beads with Forge's required epic and lease capabilities. Forge v0.5.0 is release-qualified with exact bd 1.2.1; upstream bd 1.2.2 lacks required commands and is unsupported. Setup verifies behavior, and Forge never installs, upgrades, or downgrades Beads.
• Your roster's provider CLIs. The default uses Claude Code and Codex; Pi is opt-in.
• Project-specific build and test commands configured before unattended work.
• Agents you trust with local user privileges. Read the security model.
• The CLI and controllers support macOS and Linux; the managed supervisor is macOS-only.
• Normal completion means a reviewed draft PR. Unsafe drift, exhausted budgets, ambiguity, or missing authority becomes explicit input-required state.

Documentation

• Lead-agent plugin and host setup
• CLI and operations guide
• Provider-neutral orchestration
• Planning and execution boundaries
• Changelog
• Release process
• Contributing
• Security policy

See the repository license before use or distribution.