Symphony Forge

Forge takes a change from an idea to a merged pull request. An AI coding agent, Claude Code or Codex, does the work: it plans, writes the code, runs the tests and gets it reviewed. You stay in charge of the decisions: what gets built, which option to pick, and when it goes in.

A pull request is a proposed change to the code that gets checked before it is added. Merging it is the moment the change becomes part of the real project.

In April 2026 OpenAI published An open-source spec for Codex orchestration: Symphony (openai/symphony). Its idea: the slow part of building with AI agents was never the agents, it was people watching them. So stop supervising agent sessions one by one and hand them whole pieces of work instead. The spec is a description of the idea, not a tool.

Symphony Forge is that idea made into a working tool. It keeps the core (you assign work, agents do it) and differs in three ways:

• Developers: every change runs in its own branch, and it isn't ready until the tests pass and an automatic code review finds no serious problem. Nothing is committed straight to the main branch.
• Product people who don't code: you approve a short plan written in plain English, and follow progress on a simple board page instead of in code.
• Vibe coders who build with AI: you don't need to know git. Forge handles branches, commits and pull requests for your agent, and tells you the next step whenever you're unsure.
• Salespeople starting a prototype: follow the Start a prototype checklist from an empty repo to a live customer demo.

After a new client's prototype is signed off, each story follows this loop:

1. A short story doc. The agent writes one short page: what changes for you, why, when it's done, and the tasks.
2. One independent read. A second AI agent, not the one that wrote the plan, reads it cold and points out problems. The plan is fixed once.
3. You approve once. Nothing is built until you say yes.
4. The work runs on its own. Each task gets its own branch (a separate line of work) and its own folder, so tasks don't get in each other's way. A Codex or Claude worker writes the code.
5. Tests and review must pass. An automatic code review runs, and the tests must be green. Only then is the pull request marked ready.
6. It merges. Before client sign-off, the agent merges ready prototype changes. After sign-off, you click merge by default. Set merge = "agent" in the project's forge.toml if you want the agent to run forge merge for each ready change instead.

There are two sizes of change:

• Story: a bigger change, one that touches an interface or more than five code files. It gets the plan, the independent read and your approval.
• Fix: a small change. It needs only a one-line reason and a "done when", but still gets its own branch, the tests and the review.

This is the path for a new client project, from the first conversation to running in production. The agent starts as a forward deployed engineer (FDE): it learns the customer's problem and builds the smallest working prototype that tests it. A salesperson can start this work; a developer can take over using the discovery notes and answers page. To start one, follow the prototype checklist.

Before sign-off, the prototype uses fixes even when the work is larger than an ordinary fix. Each still goes through tests, review and a pull request. The agent confirms specs during this work, then adds them to the roadmap after sign-off. See decision 0095 for why this order replaces the earlier roadmap-before-sign-off order.

You do three things:

• Approve a story's plan.
• Choose between options when the agent asks.
• Merge the finished pull request after client sign-off, unless you let the agent do it (merge = "agent"). The agent merges ready prototype changes before sign-off.

The agent does everything else: the plan, the code, the tests, fixing what the review finds, and keeping Forge's settings file up to date.

Not sure where things stand? Run forge next, or just ask your agent "what's next?". It says where things are in one sentence and gives the exact next step.

• git, which keeps track of changes.
• GitHub CLI (gh), signed in with gh auth login.
• uv, a tool that installs Python programs. Get it from docs.astral.sh/uv.
• Python 3.11 or later. uv can install it for you.
• Claude Code and Codex. You talk to either one. Forge uses the other one for the independent read.

uv tool install --python 3.11 "git+https://github.com/knacklabs/symphony-forge@v1.2.10"

Check it worked with forge --version. Each project pins the Forge version it uses, and Forge prints the exact install line if yours doesn't match.

• A new project: create an empty repository on GitHub (no files yet), clone it, and run forge init inside it. It writes Forge's settings, a starter docs folder and the agent instructions, makes the first commit and protects the main branch.
• A project with an older, copied-in Forge: run forge migrate. It moves you over in one pull request.
• Every new copy of a project on your machine: run forge sync once, then forge doctor to check your setup. Doctor prints a fix for each problem it finds.

Tell your agent "upgrade Forge". It asks which release, recommending the newest, then runs forge upgrade <release> from the main branch with nothing uncommitted. That one command installs the release, has it refresh Forge's files for Claude Code and Codex (your own text and settings stay), and opens the upgrade's pull request, which merges like any other change. If it stops, its Next: line says what to do; running it again picks up where it stopped.

Open Claude Code or Codex in the project and ask "what's next?", or run forge next yourself. Then describe the change you want.

Clone this repository, then run uv sync and uv run pytest to run the tests. The Codex SDK is not needed for the tests. Start fixes with forge fix start "<why>" --done "<done when>" so the pull request uses a Forge branch; the pull-request check accepts only Forge branches.

Forge's own CI balances its test groups using the committed .test_durations file. Refresh it from the repository root after changes to slow tests:

uv run --python 3.11 pytest tests -q -n auto -o faulthandler_timeout=120 --timeout=150 --timeout-method=thread --store-durations --clean-durations

Commit the refreshed file after the full run passes. Check the latest CI run on all three platforms: each group, including setup, must finish within seven minutes on Ubuntu and macOS, and fourteen minutes on Windows (70% of its job limit). These settings affect only Forge's own repository; new and existing client repositories get no change.

Your agent runs these for you. You'll see them in its messages.

The full command list is in the Forge guide.

• Forge guide: installing, every command, the two sizes of change, closing, upgrading and releasing.
• Standards: the engineering rules every worker follows.
• Specs: the detailed designs behind how Forge behaves, starting with Forge v1.