forge-orchestrator is a Rust-based MCP server that coordinates multiple AI tools and adapters (Claude Code, Codex CLI, Gemini CLI) within a single, governed workflow. It provides file locking, knowledge capture, task planning, drift detection, and multi-tool orchestration all through a unified state directory (.forge). Tools connect to this MCP server via standard MCP IO channels, share a single source of truth, and operate without conflicting edits. You’ll use it to manage cross-tool tasks, monitor lock states, and track decisions across sessions. The system exposes a plan-driven workflow where tasks are decomposed, dependencies tracked, and tools assigned automatically or by human-in-the-loop, with drift detection to flag divergences from specs.

To use it, start the forge-orchestrator server in the environment where you’ve installed it. Tools connect to the MCP server to read and write their configured state and artifacts. You can inspect the live state via the provided dashboard and interact with the plan using the forge CLI (init, plan --generate, run, dashboard, status). This MCP server serves as the policy core that enforces ordering, locking, and knowledge consolidation while adapters present state through their respective interfaces (L1 safety plugin, L3 UI, and MCP stdio).

Prerequisites:

• Rust toolchain (stable) installed on your machine
• curl and Git
• A Unix-like shell environment (Linux/macOS) or WSL on Windows

Install and run from source:

1. Clone the repository: git clone https://github.com/nxtg-ai/forge-orchestrator cd forge-orchestrator

2. Build the release binary: cargo build --release

3. Run the MCP server locally: ./target/release/forge-orchestrator

   The server will start and listen for MCP tool connections on the default ports

Optional one-liner install script (per project README): curl -fsSL https://forge.nxtg.ai/install.sh | sh forge init

Notes:

• The orchestrator is a single binary (~4MB) with no runtime dependencies beyond the system Rust runtime.
• After starting, you can initialize a project directory with forge init and begin planning tasks with forge plan --generate.

Tips and common considerations:

• State is stored in .forge/; ensure this directory is writable and backed up if needed.
• The MCP server enforces file locking to prevent concurrent edits across tools.
• Use forge dashboard for a live view of task status, locks, and tool activity.
• If you integrate with external UI (Forge UI) or plugins, ensure their adapters are compatible with the MCP stdio and filesystem conventions.
• Environment variables can tune behavior (e.g., FORGE_STATE_DIR to override the default state directory, LOG_LEVEL for verbosity).
• When upgrading, debris from previous sessions may linger in .forge/knowledge; consider pruning or archiving stale entries if needed.