Skip to content
Back to search

forge-orchestrator

Forge Orchestrator: Multi-AI task orchestration. File locking, knowledge capture, drift detection. Rust.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/nxtg-ai/forge-orchestrator with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/nxtg-ai/forge-orchestrator'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/nxtg-ai--forge-orchestrator/badge.svg)](/listings/nxtg-ai--forge-orchestrator)

HTML

<a href="/listings/nxtg-ai--forge-orchestrator"><img src="/api/listings/nxtg-ai--forge-orchestrator/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

curl -fsSL https://forge.nxtg.ai/install.sh | sh
forge init

Single binary. 4.7 MB. No runtime dependencies.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 260 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="assets/forge-logo.png" alt="Forge" width="120">
  3. </p>
  4. # forge-orchestrator
  5. [![stage: alpha](https://img.shields.io/badge/stage-alpha-blue)](STAGE) [![MCP Registry](https://img.shields.io/badge/MCP_Registry-active-00b4ab)](https://registry.modelcontextprotocol.io) [![License: FSL-1.1-ALv2](https://img.shields.io/badge/License-FSL--1.1--ALv2-blue.svg)](LICENSE.md) [![Version](https://img.shields.io/badge/version-v1.8.0-blue)](https://github.com/nxtg-ai/forge-orchestrator/releases/tag/v1.8.0) [![docs.rs](https://img.shields.io/docsrs/forge-orchestrator/1.8.0)](https://docs.rs/forge-orchestrator/1.8.0/forge_orchestrator/) [![CI](https://github.com/nxtg-ai/forge-orchestrator/actions/workflows/ci.yml/badge.svg)](https://github.com/nxtg-ai/forge-orchestrator/actions) [![GitHub stars](https://img.shields.io/github/stars/nxtg-ai/forge-orchestrator)](https://github.com/nxtg-ai/forge-orchestrator) [![crates.io](https://img.shields.io/crates/v/forge-orchestrator)](https://crates.io/crates/forge-orchestrator)
  6. **Stage: Alpha.** The Forge plugin and orchestrator are in alpha. On 2026-10-15 (UTC) a separate NXTG.AI team (product-oracle) ran the pre-registered core-job test on a clean install of the plugin (v3.14.0) and the orchestrator (forge 1.7.0). The test passed; each repeated check passed 3 of 3 (run 7). The evidence is attached to the forge-plugin v3.14.0 release. No SLA; interfaces may change without notice.
  7. **Orchestration for Claude Code on shared repos, with Codex CLI and Antigravity CLI (`agy`) as task runners — single Rust binary, zero deps.**
  8. Multi-agent inside a single tool works fine. Claude Code runs 20 subagents and they stay aligned because the tool manages that orchestration internally. The problem is multi-tool: several AI coding tools on the same repo with no shared state. That's what the orchestrator solves: today for Claude Code, with Codex CLI and Antigravity CLI (`agy`) as task runners. The orchestrator launches `agy` as a task runner; Forge makes no other claim about `agy`.
  9. It adds file locking, knowledge capture, task planning, drift detection, and multi-tool orchestration to your development workflow. The tools read from and write to a single state directory. A 12-tool MCP server exposes the full orchestration state to any connected AI client, and can create, claim and complete tasks.
  10. The orchestrator exists because I ran two AI tools on the same codebase and watched them fail in the same ways human teams fail. Claude refactored a module. Codex updated tests against the pre-refactor interface. Both saved. Tests failed. Neither tool knew the other existed. I'd spent 23 years watching this exact scenario with talented human teams. The solution was always the same: orchestration infrastructure.
  11. ## Install
  12. ```bash
  13. curl -fsSL https://forge.nxtg.ai/install.sh | sh
  14. export PATH="$HOME/.local/bin:$PATH" # this shell only; new shells already have it
  15. forge init
  16. ```
  17. The installer installs Forge v1.8.0, the pinned release, not whichever release is newest. It puts `forge` in `~/.local/bin` (change it with `FORGE_INSTALL_DIR`) and adds that directory to your PATH with one guarded line in `~/.profile`, `~/.bashrc` and, if you have zsh, `~/.zshenv`. Set `FORGE_NO_MODIFY_PATH=1` to leave your shell files alone.
  18. If the `claude` CLI is on your PATH, the installer then adds forge's MCP tools to Claude Code, using only that CLI: it adds and refreshes the `nxtg-forge` marketplace (`nxtg-ai/forge-plugin`), updates `nxtg-forge@nxtg-forge` if you already have it, and installs the companion plugin `nxtg-forge-orchestrator@nxtg-forge`. It prints one line per change and changes no Claude configuration any other way. Without `claude`, or if a step fails, it prints the commands for you to run and still exits 0. Set `FORGE_NO_CLAUDE_PLUGIN=1` to skip it.
  19. Single binary. No runtime dependencies.
  20. ## Connect Codex CLI to the MCP server
  21. Register the orchestrator's MCP server with Codex CLI, then check that Codex lists it:
  22. ```bash
  23. codex mcp add forge -- forge mcp
  24. codex mcp list
  25. ```
  26. This writes the entry to `~/.codex/config.toml`:
  27. ```toml
  28. [mcp_servers.forge]
  29. command = "forge"
  30. args = ["mcp"]
  31. ```
  32. The server works on the project in the directory it starts in. To pin one project, bind it when you register: `codex mcp add forge --env FORGE_PROJECT_ROOT=/path/to/project -- forge mcp`. Checked with codex-cli 0.162.1: `codex mcp list` shows `forge` enabled over stdio, and the server answers `tools/list` with its 12 tools. A tool call made through this registration from inside a Codex session has not been measured.
  33. ## Quick Demo
  34. Four commands from zero to task board:
  35. ```bash
  36. # 1. Initialize — creates .forge/ directory with state, event log, knowledge base
  37. forge init
  38. # 2. Configure the AI brain — choose 'openai' (needs API key) or 'rule-based' (free)
  39. forge config brain openai
  40. # 3. Generate tasks — reads your SPEC.md or README, creates dependency-aware task graph
  41. forge plan --generate
  42. # 4. See the result — task board with assignments, dependencies, and project health
  43. forge status
  44. ```
  45. From here you can:
  46. - `forge run` — execute tasks headlessly (autonomous mode, great for CI)
  47. - `forge dashboard --pty` — launch the TUI dashboard with interactive agent panes
  48. ## Past Result: Stargate Mode (before v1.6.1)
  49. From a 94-line specification, an earlier version of the orchestrator coordinated three AI coding tools to build a complete CLI toolkit. That run drove the retired Gemini CLI; since v1.6.1 the adapter launches Antigravity CLI (`agy`) instead, and the run has not been re-measured.
  50. ```
  51. SPEC.md (94 lines) → forge plan --generate → 15 tasks
  52. Claude Code: 6 design tasks → completed
  53. Codex CLI: 6 implementation → completed
  54. Gemini CLI: 3 test/doc tasks → completed (pre-1.6.1 adapter)
  55. Result: 5,306 lines of working code
  56. 10 auto-committed git entries
  57. 13 Python files (CLI + tests)
  58. Zero file conflicts
  59. ```
  60. Three companies. Three tools. One orchestrator. One command:
  61. ```bash
  62. forge dashboard --pty
  63. ```
  64. ## What You Get
  65. | Feature | What It Does |
  66. |---------|-------------|
  67. | File locking | A task names the files it touches; a claim through MCP or `forge run --task … --agent …` is refused while another task holds one of them |
  68. | Knowledge flywheel | Captures decisions, patterns, learnings across tools. Auto-classified and searchable. |
  69. | Plan generation | `forge plan --generate` decomposes specs into dependency-aware task graphs |
  70. | Drift detection | Compares completed tasks against SPEC.md. Needs the `openai` brain; the default rule-based brain does not score drift |
  71. | Task board | Dependency-tracked tasks, tool assignment, progress monitoring |
  72. | Multi-tool adapters | Claude Code (MCP stdio); Codex CLI and Antigravity CLI (`agy`) as task runners (filesystem). Codex CLI can also register the MCP server (see below) |
  73. | TUI dashboard | `forge dashboard`: live tool panes, task status, lock state |
  74. | Headless mode | `forge run`: autonomous execution for CI/CD pipelines |
  75. | MCP server | 12 tools accessible by any connected AI tool via stdio, including `forge_create_task` |
  76. ## Key Commands
  77. ```bash
  78. forge init # Initialize Forge in a project
  79. forge plan --generate # Generate task plan from spec
  80. forge dashboard # Live TUI dashboard
  81. forge dashboard --pty # TUI with interactive agent panes (Stargate)
  82. forge run # Headless autonomous mode
  83. forge status # Current state summary
  84. forge verify # Create verify tasks for completed build tasks
  85. forge uat # Interactive UAT test runner
  86. forge ship # Ship phase: changelog, archive, clean state for the next cycle
  87. ```
  88. Every command and its options, as the binary prints them. CI regenerates this block from `forge --help` and fails if it differs:
  89. <!-- forge-help:start (generated by .github/scripts/readme-cli.py --write; do not edit) -->
  90. ```text
  91. $ forge --help
  92. Forge orchestrates Claude Code on shared repos, with Codex CLI and Antigravity CLI (agy) as task runners: file locking, knowledge capture and a shared task board.
  93. Usage: forge [OPTIONS] <COMMAND>
  94. Commands:
  95. init Initialize Forge in a project — scaffold .forge/, detect AI tools
  96. plan Show or generate the master plan
  97. status Show orchestration status — task board, agent activity, governance
  98. run Execute tasks headlessly. Omit --task/--agent for autonomous parallel mode
  99. start Start autonomous orchestration — run all tasks with auto-claim/complete
  100. sync Reconcile state — update summaries, render adapter configs, check governance
  101. mcp Start the MCP server (stdio transport) — AI tools connect to query/update state
  102. dashboard Live TUI dashboard — task board, agent output, event log
  103. doctor Aggregate health verdict — quality, release debt, and drift in one fail-closed exit code
  104. pod Declarative tmux pod management — start, stop, and recover multi-pane agent pods
  105. verify Generate verify subtasks for completed build tasks
  106. uat Interactive UAT — describe issues naturally, capture findings
  107. ship Ship phase — generate changelog, archive artifacts, clean state for next cycle
  108. uninstall Uninstall Forge — remove binary and optionally project data
  109. config Get or set configuration values
  110. help Print this message or the help of the given subcommand(s)
  111. Options:
  112. --project <PROJECT>
  113. Path to the project root (defaults to current directory)
  114. [default: .]
  115. -h, --help
  116. Print help (see a summary with '-h')
  117. -V, --version
  118. Print version
  119. ```
  120. <!-- forge-help:end -->
  121. ## Use as a library
  122. Since v1.8.0, the crate also builds a library, `forge_orchestrator`, for tools that read or write a project's `.forge/` directory without running `forge`. Its documented surface is `forge_orchestrator::core`: project state and file locks, tasks, the event log, the knowledge base and the plan. The rest of the crate is the binary's internals, hidden from the docs. Like the binary, the library is alpha, and its API may change.
  123. ```toml
  124. [dependencies]
  125. forge-orchestrator = "1.8" # the first version with the library
  126. ```
  127. ```rust
  128. use forge_orchestrator::core::task::{Task, TaskManager};
  129. let tasks = TaskManager::new(".forge");
  130. tasks.create_task(&Task::new("T-001", "Parse the config", "Read forge.toml into Config"))?;
  131. for task in tasks.list_tasks()? {
  132. println!("{} {:?} {}", task.id, task.status, task.title);
  133. }
  134. ```
  135. API docs: https://docs.rs/forge-orchestrator. To build them locally: `cargo doc --open` in a checkout.
  136. Runnable examples, run in CI against the built binary:
  137. - [`examples/task_board.rs`](examples/task_board.rs): print a project's task board from `.forge/`.
  138. - [`examples/capture_knowledge.rs`](examples/capture_knowledge.rs): capture a decision and list that category.
  139. - [`examples/mcp_stdio.rs`](examples/mcp_stdio.rs): talk to `forge mcp` as an MCP client: initialize, list the 12 tools, create a task.
  140. ```bash
  141. cargo build && cargo run --example mcp_stdio -- target/debug/forge /tmp/demo
  142. cargo run --example task_board -- /tmp/demo
  143. ```
  144. ## Architecture
  145. The orchestrator holds Forge's shared state: tasks, file locks, knowledge and the event log. The plugin (L1: Vibe Coder) adds Claude Code commands, skills and hooks, and its guard hooks run inside Claude Code. The UI (L3: Ship Lord) is a separate React dashboard.
  146. ```
  147. ┌──────────────────────────────────────┐
  148. │ forge-orchestrator │
  149. │ (Rust) │
  150. │ │
  151. │ File locking · Task planning │
  152. │ Knowledge · Governance · MCP │
  153. │ Multi-tool adapters │
  154. │ │
  155. │ Shared state lives here. │
  156. │ Guard hooks live in forge-plugin. │
  157. └───────────┬──────────────────┬───────┘
  158. │ │
  159. ┌────────┴────────┐ ┌────┴────────┐
  160. │ forge-plugin │ │ forge-ui │
  161. │ (L1 Safety) │ │ (L3 MC) │
  162. │ Claude Code │ │ React │
  163. │ adapter │ │ dashboard │
  164. └─────────────────┘ └─────────────┘
  165. ```
  166. **Communication**: `.forge/` filesystem + MCP stdio. No daemon. No database. State is files.
  167. **Tool adapters**: Claude Code uses MCP stdio. Codex CLI and Antigravity CLI (`agy`) run tasks through filesystem conventions. The `agy` adapter keeps the agent id `gemini` in task files, config keys and MCP arguments, so existing projects keep working. Each tool reads its own config format. No Forge-specific configuration language.
  168. ## How File Locking Works
  169. File locking exists because I've watched teams lose days to conflicting edits.
  170. Each task lists the files it touches. A claim through the `forge_claim_task` MCP tool or single-task `forge run --task <id> --agent <agent>` first checks those files against the locks held in `.forge/state.json`. If any overlap, the claim is refused, and the refusal names the task and agent that hold them; otherwise the files are recorded as locked by that task. `forge start` and the dashboard record locks the same way when they launch a task, but do not check for overlap first. Autonomous `forge run` (no `--task`) neither checks for overlap nor records locks. Finishing the task releases its locks.
  171. The lock governs claims, not edits: it does not stop a tool from writing a file. Locks have no timeout: if the process that took a lock dies, the lock stays in the state file. The state file is read and rewritten without a cross-process lock, so two claims made at the same moment can both succeed.
  172. ## How the Knowledge Flywheel Works
  173. The knowledge flywheel exists because I've watched decisions evaporate between sprints.
  174. Decisions, patterns, learnings and research captured through `forge_capture_knowledge` are stored in `.forge/knowledge/`, one directory per category, and classified automatically. Any tool connected to the MCP server can search them with `forge_get_knowledge`, in a later session as well as the current one.
  175. ## Forge UI
  176. [forge-ui](https://github.com/nxtg-ai/forge-ui) is a separate React dashboard for Forge, released on its own; its README states its stage. To run it from source:
  177. ```bash
  178. git clone https://github.com/nxtg-ai/forge-ui && cd forge-ui && npm install && npm run dev
  179. ```
  180. ## Links
  181. - [Forge Product Page](https://forge.nxtg.ai)
  182. - [Forge Plugin](https://github.com/nxtg-ai/forge-plugin) (L1: Vibe Coder)
  183. - [Forge UI](https://github.com/nxtg-ai/forge-ui) (L3: Ship Lord)
  184. - [Documentation](https://forge.nxtg.ai/docs)
  185. - MCP Registry: `mcp-name: io.github.nxtg-ai/forge-orchestrator`
  186. ## License
  187. Source available under the [Functional Source License 1.1 (FSL-1.1-ALv2)](./LICENSE.md). Converts to Apache License 2.0 on 2028-03-18. See [LICENSE.md](./LICENSE.md) for full terms.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.