forge

AI development flow orchestrator — from GitHub issue to merged PR, fully automated.

Claude plans and implements. A dedicated Claude reviewer reviews the plan. Two parallel Claude instances review the PR (security + architecture). A third Claude synthesises both PR reviews into a single verdict.

Issue → Claude: plan
      → Claude [Plan Reviewer]: review → PLAN_APPROVED? → yes: implement
                                       → no: planner revises (resumes session)
                                       → max rounds: final revision → implement
      → Claude: implement + open PR
      → CI: poll every 30s → pass: PR review
                           → fail: implementor fixes (resumes session) → re-poll
                           → max CI rounds: pause, manual review
      → Claude [Security] + Claude [Architecture]: review PR (parallel, each posts own comment)
      → Claude: merge verdict → PR_APPROVED? → merge → git checkout main && git pull
                              → no: implementor fixes (resumes session)
                              → max rounds: pause, manual review

Prerequisites

• claude CLI installed and authenticated:

  npm i -g @anthropic-ai/claude-code
  claude login

• gh CLI authenticated:

  gh auth login

• ANTHROPIC_API_KEY in env (optional — only needed if not using claude login)

Install

npm install -g @torm89/forge

Or run without installing:

npx @torm89/forge run --issue 42 --repo owner/name

From source

git clone https://github.com/torm89/forge
cd forge
npm install
npm link          # auto-builds and makes `forge` available globally

Usage

forge run --issue <n> --repo <owner/repo> [options]

OPTIONS
  --issue,       -i  <number>   GitHub issue number (required)
  --repo,        -r  <string>   GitHub repo in owner/repo format (required)
  --dir,         -d  <string>   Local path to the repo (default: current dir)
  --model,       -m  <string>   Claude model for implementation
                                (default: claude-sonnet-4-6)
  --effort           <level>    Effort level for all Claude agents:
                                low, medium, high, xhigh, max (default: high)
  --plan-rounds      <number>   Max plan review iterations (default: 3)
  --ci-rounds        <number>   Max CI fix iterations (default: 3)
  --ci-polls         <number>   Max CI poll attempts, 30s each (default: 20)
  --pr-rounds        <number>   Max PR review iterations (default: 3)
  --base-branch      <branch>   Branch to target PRs against and return to
                                after merge (default: main)
  --from-step        <step>     Start from a specific step:
                                plan, plan-review, implement, ci, pr-review
  --interactive                 Pause after each step for manual review/guidance

OTHER COMMANDS
  forge help     Show help
  forge version  Show version

Examples

# Run from inside the target repo
cd ~/projects/my-app
forge run --issue 42 --repo torm89/my-app

# Explicit path + custom rounds
forge run -i 42 -r torm89/my-app -d ~/projects/my-app --plan-rounds 2 --pr-rounds 5

# Heavier model for complex issues
forge run -i 42 -r torm89/my-app --model claude-opus-4-5

# Interactive mode — pause after each step, optionally add guidance
forge run -i 42 -r torm89/my-app --interactive

# Skip CI fix loop (CI failures won't block PR review)
forge run -i 42 -r torm89/my-app --ci-rounds 0

# Resume from CI step (PR is auto-detected from the issue)
forge run -i 42 -r torm89/my-app --from-step ci

# Jump straight to PR review
forge run -i 42 -r torm89/my-app --from-step pr-review

Interactive mode

With --interactive, forge pauses at 4 checkpoints:

1. After plan creation — read the plan before review starts
2. After each plan review round — see feedback, add guidance or skip revision
3. Before implementation — last chance to adjust before Claude writes code
4. After each PR review round — see review, add guidance or skip to merge

At each pause you can:

• [c] continue
• [a] add a note — injected as guidance into Claude's next prompt
• [s] skip this step
• [q] quit

Review strategy

Plan review

A single dedicated Claude reviewer checks the plan each round:

• Writes only what needs changing (not a full re-review)
• Returns PLAN_APPROVED if the plan is ready → loop exits immediately
• If max rounds reached, planner revises one final time before implementation

PR review

Two Claude instances run in parallel:

| Reviewer | Focus | |---|---| | Security & Correctness Auditor | Bugs, edge cases, auth issues, input validation, race conditions | | Architecture & Maintainability Reviewer | Design patterns, readability, SOLID, performance, testability |

A third Claude call merges both reviews into a structured verdict:

• Summary of Findings — grouped, deduplicated issues
• Must Fix — blocking issues
• Nice to Have — non-blocking suggestions
• Verdict — PR_APPROVED / PR_NEEDS_CHANGES

CI integration

After a PR is opened, forge polls gh pr checks every 30 seconds (up to 10 minutes):

• All checks green → proceeds to PR review
• Any check red → Claude (implementor) fetches logs via gh run view --log-failed, fixes, pushes, re-polls
• Timeout or max CI rounds reached → warning posted on PR, proceeds to PR review

Session persistence

Forge saves Claude session IDs per issue per actor under .forge/issue-<N>/, alongside the persisted flow state.json:

| File | Actor | |---|---| | planner.session | Plan author + revisions | | plan-reviewer.session | Plan reviewer | | implementor.session | Implementation + PR fixes + CI fixes | | pr-reviewer-security.session | PR security reviewer | | pr-reviewer-architecture.session | PR architecture reviewer |

Sessions allow Claude to resume context across rounds without re-reading the entire history. The .forge/ directory is git-ignored.

Project structure

src/
├── index.ts            ← entrypoint
├── cli.ts              ← argument parser + config builder
├── orchestrator.ts     ← main flow controller
├── types.ts            ← shared types
├── runners/
│   ├── claude.ts       ← claude -p wrapper with spinner progress display
│   └── review.ts       ← plan review + parallel PR review + merge synthesis
├── steps/
│   └── index.ts        ← stepCreatePlan, stepPlanReviewLoop, stepImplement,
│                          stepCILoop, stepPRReviewLoop
├── github/
│   └── client.ts       ← gh CLI wrapper
└── utils/
    ├── logger.ts        ← colored terminal output
    ├── interactive.ts   ← checkpoint prompts + user note injection
    └── sessions.ts      ← session ID persistence per issue per actor

Configuration

Configuration cascade: CLI flags → .forge.json → built-in defaults.

Optional .forge.json at the repo root lets you set defaults per project:

{
  "model": "claude-sonnet-4-6",
  "effort": "high",
  "planRounds": 3,
  "prRounds": 3,
  "ciRounds": 3,
  "ciPolls": 20,
  "baseBranch": "main"
}

| Flag | Default | Description | |---|---|---| | --model | claude-sonnet-4-6 | Claude model for implementation | | --effort | high | Effort level: low, medium, high, xhigh, max | | --plan-rounds | 3 | Max plan review → revise iterations | | --ci-rounds | 3 | Max CI fix iterations | | --ci-polls | 20 | Max CI poll attempts (30s each) | | --pr-rounds | 3 | Max PR review → fix iterations | | --base-branch | main | Branch to target PRs against | | --from-step | plan | Start from: plan, plan-review, implement, ci, pr-review | | --interactive | off | Pause after each step |

Environment variables

| Variable | Required | Description | |---|---|---| | ANTHROPIC_API_KEY | optional | Only needed if not using claude login |

Running tests

npm test              # run all unit tests
npm run test:watch    # watch mode
npm run test:coverage # with coverage report

License

MIT © torm