FORGE

Ship features, not prompts.

Describe what you want. Forge plans it, runs parallel AI agents, reviews every line, and opens a pull request.

Claude Code for thinking. Forge for shipping.

Why Forge? · Install · How It Works · In Action · Multi-Repo · Configuration · CLI Reference

forge tui

Type your task. Hit Ctrl+S. Walk away. Come back to a pull request.

Why not just use Claude Code?

Claude Code is great. Forge is built on it. Every Forge agent IS a Claude Code session. The planner IS a Claude Code session. So why not just use Claude Code directly?

Because you're the bottleneck.

Claude Code handles one task at a time. You prompt, you wait, you review, you prompt the next thing. For a 5-task feature, that's 5 rounds of your attention. Forge runs all 5 in parallel while you do something else.

Forge doesn't replace Claude Code. It removes the human scheduling layer. You still approve the plan. You still review the PR. But the 45 minutes between "approve plan" and "PR ready" — that's Forge, not you.

When to use what

• Claude Code → Debugging, exploration, quick fixes, learning a codebase
• Forge → Features, migrations, multi-file changes, anything with 2+ parallel tasks

What makes Forge different

Forge isn't another chat wrapper. It's an orchestration engine with systems that compound over time.

See it in action

Planning — Forge reads your codebase and builds a task graph

The planner has the same power as Claude Code — full access to your CLAUDE.md, skills, memory, and MCP servers. It explores your codebase deeply, asks clarifying questions if something is ambiguous, and produces a structured task graph.

Plan review — Approve, edit, or reject before agents run

Every plan shows tasks with complexity, dependencies, file ownership, and a cost estimate. You can edit the plan, reorder tasks, or reject and re-plan with different instructions.

Execution — Parallel agents with real-time learning

Each agent runs in its own git worktree with a focused prompt. When an agent fails and succeeds on retry, Forge captures what it learned and applies it to future runs. A health monitor watches for stuck tasks and deadlocks.

Code review — Inspect every diff before merge

Done — PR created, cost tracked, ready to merge

Install

Prerequisites: Git 2.20+ and Claude Code CLI (claude login). Optional: gh CLI for automatic PR creation.

curl -fsSL https://raw.githubusercontent.com/tarunms7/forge-orchestrator/main/install.sh | sh

The installer handles Python 3.12, uv, the Forge CLI, and all dependencies. Safe to re-run to upgrade.

To upgrade later:

forge upgrade

git clone https://github.com/tarunms7/forge-orchestrator.git
cd forge-orchestrator
uv tool install --python 3.12 ".[web]"
forge doctor

Quick start

cd your-project
forge tui

Type what you want. Hit Ctrl+S. Forge auto-creates .forge/ on first run.

Or skip the TUI:

forge run "Add input validation to all API endpoints"

Fix a GitHub issue directly:

forge fix 42    # Fetches issue #42 and builds a pipeline to fix it

How it works

You: "Build a REST API with JWT auth and tests"
                    │
              1. PRE-FLIGHT
              Validates tools, branches, disk space
              — catches problems before spending money
                    │
              2. PLAN
              Full Claude Code power — reads codebase,
              asks clarifying questions, builds task DAG
                    │
              3. CONTRACT
              Generates binding API & type specs so
              agents agree on interfaces before coding
                    │
              4. EXECUTE
              Parallel agents in isolated git worktrees
              with real-time health monitoring
                    │
              5. REVIEW
              5-gate pipeline per task:
              build › lint › test › LLM review › contracts
                    │
              6. FORMAT + MERGE
              Auto-format, rebase, fast-forward merge,
              then gh pr create

The Contract Builder

Two agents writing a backend API and a frontend client will invent different field names and response shapes. Forge solves this with binding contracts generated before any code is written:

POST /api/templates
  Request:  { name: string, description: string, tasks: TaskConfig[] }
  Response: { id: string, name: string, created_at: string }
  Producer: task-1 (backend)  │  Consumer: task-2 (frontend)

Producers implement the spec. Consumers call the spec. The reviewer checks compliance.

Self-evolving learning

Forge gets smarter with every pipeline it runs:

• Adaptive timeouts — ESLint took 180s and failed? Next run starts at 360s. Automatically.
• Agent learnings — When a task fails then succeeds on retry, Forge asks "what did you do differently?" and stores the answer as a lesson.
• Noise filtering — Server 503s and transient errors aren't stored. Only real pattern changes become lessons.
• Cross-pipeline — Lessons persist across projects. What Forge learns on one repo helps on the next.

forge lessons list    # See what Forge has learned
forge lessons add     # Manually teach Forge something

Pre-flight validation

Before any pipeline starts, Forge runs 8 fast checks:

• Claude CLI installed and authenticated
• Git repo valid, base branch exists
• gh CLI available (for PR creation)
• Sufficient disk space (>1 GB)
• No uncommitted changes that would interfere
• Build/test commands resolvable

If anything fails, you get a clear error with a fix command — not a cryptic failure 5 minutes into planning.

Pipeline health monitor

During execution, a background watchdog detects:

• Stuck tasks — in_progress for >15 minutes with no activity
• Stuck reviews — review gate running for >10 minutes
• Deadlocks — all tasks blocked with no way to make progress
• Dependency cascades — failed task blocking downstream work

Problems are logged and surfaced immediately, not discovered after the pipeline "completes."

Multi-repo workspaces

Forge natively supports monorepos and multi-repo setups. Point it at a directory with multiple git repos:

super-repo/
  backend/     ← git repo on 'develop' branch
  frontend/    ← git repo on 'main' branch
  shared-lib/  ← git repo on 'main' branch

cd super-repo
forge tui

Forge auto-detects the repos and uses whatever branch each repo is currently checked out to as the base. No config needed. The TUI shows branch selectors for each repo so you can override at submission time.

Agents get repo-aware prompts. The planner understands cross-repo dependencies. Contracts ensure APIs match across repos.

Configuration

All settings use the FORGE_ prefix. Build and test commands are auto-detected from your project.

FORGE_BUDGET_LIMIT_USD=5 forge run "Refactor auth to OAuth2"

Project config

Drop a forge.toml in your .forge/ directory for per-project settings:

[agents]
max_parallel = 4
timeout_seconds = 300

[review]
max_retries = 3

[lint]
check_cmd = "npm run lint"
fix_cmd = "npm run lint:fix"

Model routing

CLI reference

Web dashboard

forge serve   # Backend :8000 + Frontend :3000

Live pipeline progress via WebSocket, interactive plan editing, contract viewer, review gate results, and cost tracking. Set FORGE_JWT_SECRET for multi-user auth.

Requires a git clone install, not the one-line installer.

Architecture

forge/
  cli/           # Click CLI — 14 commands
  tui/           # Textual TUI — full terminal UI with live pipeline view
  core/          # Orchestration — daemon, planner, executor, scheduler, health monitor
  agents/        # Claude Code SDK adapter — agent runtime, prompt building
  merge/         # Git worktree lifecycle — create, merge, cleanup
  review/        # Multi-gate review — lint, build, test, LLM review
  learning/      # Self-evolving — lesson store, runtime guard, extractor
  storage/       # SQLite via SQLAlchemy async — tasks, pipelines, events, analytics
  config/        # Settings, project config, forge.toml, workspace.toml
  api/           # FastAPI backend for web dashboard
web/             # Next.js frontend — TypeScript, Tailwind, Zustand

Troubleshooting

Contributing

git clone https://github.com/tarunms7/forge-orchestrator.git
cd forge-orchestrator
python -m venv .venv && source .venv/bin/activate
pip install -e '.[dev,web]'
python -m pytest forge/ -q

CI runs ruff lint + format + 2200+ tests on every PR.

License

MIT