forge-orchestrator

The tech lead that never sleeps.

Plan work. Assign it to the right AI. Track progress. Prevent conflicts. Capture knowledge. Ship faster.

Quick Start | Why Forge? | MCP Server | Architecture | Contributing

The Problem

You have Claude Code, Codex CLI, and Gemini CLI installed. They're powerful alone. But when two AI tools edit the same file? Chaos. When nobody remembers why a decision was made last Tuesday? Lost knowledge. When your spec says "build auth" but the AI is refactoring CSS? Drift.

Forge coordinates your AI tools like a senior tech lead coordinates junior developers.

Why Forge?

Install

One-liner (Linux/macOS):

curl -sSL https://raw.githubusercontent.com/nxtg-ai/forge-orchestrator/main/install.sh | sh

Windows (PowerShell):

Download from latest release, extract forge.exe, and add to PATH.

From source (any platform with Rust):

git clone https://github.com/nxtg-ai/forge-orchestrator.git
cd forge-orchestrator
cargo install --path .

Quick Start

# 1. Initialize in any project (must be a git repo)
cd your-project
forge init

# 2. Write a SPEC.md describing what you want to build

# 3. Generate a plan from your spec
forge plan --generate        # AI decomposes spec into tasks with dependencies

# 4. See the task board
forge status                 # Full task table with deps, statuses, agents

# 5. Launch the TUI dashboard (recommended)
forge dashboard              # Live multi-agent orchestration with real-time output

# Or run headlessly (CI/CD, SSH, scripting)
forge run                    # Parallel autonomous execution, no TUI
forge run --dry-run           # Preview execution plan without running
forge run --parallel 1        # Sequential mode

# Or run a single task manually
forge run --task T-001 --agent codex

30-Second Setup with Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "forge": {
      "type": "stdio",
      "command": "forge",
      "args": ["mcp", "--project", "."]
    }
  }
}

Restart Claude Code. Now Claude can call forge_get_tasks(), forge_claim_task(), forge_check_drift() — all 9 tools are native.

How It Works

You write SPEC.md
        │
        ▼
┌──────────────────┐      ┌─────────────────┐
│  forge plan      │────▶│  ForgeBrain     │  GPT-4.1 decomposes spec
│  --generate      │      │ (pluggable LLM) │  into tasks with deps
└──────────────────┘      └─────────────────┘
        │
        ▼
┌──────────────────┐      ┌─────────────────┐
│  forge dashboard │────▶│  Adapters       │  Claude, Codex, Gemini
│  (TUI) or        │      │ (tool-specific) │  run in parallel with
│  forge run       │      │                 │  dependency scheduling
│  (headless)      │      │                 │  + rate limit backoff
└──────────────────┘      └─────────────────┘
        │
        ▼
┌──────────────────┐      ┌─────────────────┐
│  Auto-commit per │◀───▶│  .forge/        │  File-based state
│  task + status   │      │  state.json     │  MCP live queries
│  forge mcp       │      │  tasks/ events/ │  Knowledge flywheel
└──────────────────┘      └─────────────────┘

CLI Commands

MCP Server

Forge includes a built-in Model Context Protocol server. Any MCP-compatible AI tool can query and update orchestration state in real-time.

9 Tools

Connecting AI Tools

{
  "mcpServers": {
    "forge": {
      "type": "stdio",
      "command": "forge",
      "args": ["mcp", "--project", "."]
    }
  }
}

forge sync  # renders AGENTS.md with current tasks and state
codex --agents-md AGENTS.md

forge sync  # renders GEMINI.md
gemini --context GEMINI.md

Architecture

┌─────────────────────────────────────────────────────────────┐
│  CLI (clap)                                                 │
│  init | plan | dashboard | run | start | status | sync | mcp│
├─────────────────────────────────────────────────────────────┤
│  TUI Dashboard (ratatui + crossterm)                        │
│  Task board | Agent panes | Shell panes | Event log         │
│  Rate limit backoff | Auto-commit | Key legend              │
├─────────────────────────────────────────────────────────────┤
│  ForgeBrain (pluggable)                                     │
│  RuleBasedBrain (free) | OpenAIBrain (gpt-4.1) | ...        │
├─────────────────────────────────────────────────────────────┤
│  Core Engine                                                │
│  TaskManager | StateManager | EventLogger | PlanManager     │
│  KnowledgeManager | GovernanceChecker                       │
├─────────────────────────────────────────────────────────────┤
│  MCP Server (JSON-RPC 2.0 / stdio)                          │
│  9 tools for real-time AI-tool integration                  │
├─────────────────────────────────────────────────────────────┤
│  Adapters                                                   │
│  ClaudeAdapter | CodexAdapter | GeminiAdapter               │
├─────────────────────────────────────────────────────────────┤
│  .forge/ (file-based state)                                 │
│  state.json | tasks/ | knowledge/ | events.jsonl | plan.md  │
└─────────────────────────────────────────────────────────────┘

Dual Engine Design

Forge separates deterministic operations (state, locks, events) from intelligent decisions (plan decomposition, drift detection). The deterministic engine runs zero LLM tokens. The brain is pluggable.

Configure with:

forge config brain openai
forge config brain.model gpt-4.1    # or gpt-5, gpt-5.3-codex

Requires OPENAI_API_KEY in environment or .env file.

File Locking

When an agent claims a task, Forge locks the associated files in state.json. Other agents see the conflict before starting work. Locks are released automatically on task completion.

Agent A claims T-001 → locks: src/auth.rs, src/middleware.rs
Agent B claims T-002 → checks locks → no conflict → proceeds
Agent C claims T-003 → checks locks → CONFLICT on src/auth.rs → blocked

Knowledge Flywheel

Every interaction can generate intelligence. Forge captures and classifies it automatically:

forge_capture_knowledge("JWT tokens expire after 24h", source: "debugging")
  → auto-classified as "learning"
  → stored in .forge/knowledge/learnings/
  → searchable via forge_get_knowledge
  → aggregated into SKILL.md files

Governance

The forge_get_health tool runs a 5-dimension check:

Returns a health score out of 100 with actionable findings.

.forge/ Directory

.forge/
├── state.json              # Project state, tool inventory, brain config, file locks
├── plan.md                 # Master plan (human-readable)
├── events.jsonl            # Append-only event log
├── tasks/
│   ├── T-001.json          # Task definitions with deps, acceptance criteria
│   └── T-001.md            # Human-readable task cards
├── results/                # Agent execution results
└── knowledge/
    ├── decisions/          # Architectural decisions (ADRs)
    ├── learnings/          # Lessons learned
    ├── research/           # Research findings
    └── patterns/           # Discovered patterns

Comparison

Forge doesn't replace your AI tools. It makes them work together.

Stats

Development

# Clone
git clone https://github.com/nxtg-ai/forge-orchestrator.git
cd forge-orchestrator

# Build
cargo build

# Test
cargo test

# Build release (~3 MB binary)
cargo build --release

# Run
./target/release/forge --help

Project Structure

src/
├── main.rs              # Entry point, CLI dispatch
├── cli/                 # Command implementations
│   ├── init.rs          # Project initialization
│   ├── plan.rs          # Plan generation (uses ForgeBrain)
│   ├── dashboard.rs     # TUI dashboard launcher
│   ├── start.rs         # Sequential orchestration with retry
│   ├── run.rs           # Headless autonomous + single-task execution
│   ├── status.rs        # Full task table with dependencies
│   ├── sync.rs          # State reconciliation
│   └── config.rs        # Brain configuration
├── tui/                 # Terminal UI (ratatui + crossterm)
│   ├── app.rs           # Dashboard state, scheduler, key handling
│   ├── ui.rs            # Layout rendering (task board, agent panes, event log)
│   └── event.rs         # Terminal event polling
├── core/                # Core engine
│   ├── state.rs         # State management (.forge/state.json)
│   ├── task.rs          # Task lifecycle, file locking
│   ├── event.rs         # Event logging
│   ├── plan.rs          # Plan parsing and templates
│   ├── knowledge.rs     # Knowledge capture and retrieval
│   └── governance.rs    # Health checks, drift detection
├── brain/               # Pluggable LLM backends
│   ├── rule_based.rs    # Free heuristic brain
│   └── openai.rs        # Real OpenAI API integration
├── adapters/            # AI tool adapters
│   ├── claude.rs        # Claude Code adapter
│   ├── codex.rs         # Codex CLI adapter
│   └── gemini.rs        # Gemini CLI adapter
├── mcp/                 # MCP server
│   ├── server.rs        # JSON-RPC 2.0 dispatcher
│   ├── protocol.rs      # MCP protocol types
│   └── tools.rs         # 9 tool implementations
└── detect/              # AI tool auto-detection
    └── mod.rs

Ecosystem

Forge is three repos that work together:

The orchestrator plans and coordinates. The plugin adds governance to Claude Code. The dashboard adds visual oversight for teams.

Contributing

Forge is MIT-licensed and contributions are welcome.

Good first issues:

• Add a ClaudeBrain implementation (Claude API for plan decomposition)
• Add forge worktree command (git worktree per task for parallel agent isolation)
• Add forge uat command (interactive acceptance testing checklist)
• Add forge report command (session summary from events.jsonl)
• Embedded interactive agent TUIs (PTY bridge per pane — "Stargate" mode)

Before submitting a PR:

cargo test          # All 139 tests must pass
cargo clippy        # No warnings
cargo fmt --check   # Formatted

License

MIT -- LICENSE