How Forge works — the complete guide

Forge is a living plan for people who build software with AI coding agents. You design in structured, agent-readable pieces; agents read the plan over MCP before building, claim work so they never collide, and report back what they actually built. This page walks through everything you can do — including wiring up your first agent.

~8 minute read · free during open beta, no credit card · works with Claude Code, Cursor, Copilot, Codex, Cline and any MCP client

1What Forge is (and isn't)

Coding agents are fast and amnesiac. Every session starts blank, so the same context gets re-pasted; a decision made three sessions ago gets quietly undone; two agents rewrite the same module. A better document doesn't fix that — a document can't know whether it was read, and can't notice the code walking away from it.

Forge makes the plan a thing agents transact with. Your design lives as structured Systems — each with a Goal, a Boundary (what it must not touch), and Acceptance criteria — plus ordered milestones of tasks. Agents read that over MCP before building, claim tasks, report which files implement which system, and propose changes back. Nothing an agent proposes is applied until you adopt it.

Honest boundary: if you hand-code without agents, a markdown file is enough — you don't need Forge. It earns its keep the moment agents write your code, or several people (and agents) must share one plan.

2The loop — 90 seconds

Every agent interaction is one of four verbs: READ the plan · CLAIM a task (so parallel agents never overlap) · REPORT what was built (status + the actual files) · PROPOSE a change (which lands in your Inbox, never directly in the design).

3Start a project

1. Sign in at forgeengine.app — Google or email/password. Everything is free during the open beta.
2. New Project — pick a kind (game / app / web / other; it tunes the vocabulary and AI help), name it, and optionally describe the idea in one line.
3. Write on the Idea tab — paragraphs, lists, tables, diagrams. This is your free-form thinking space.
4. Generate Systems — the ✨ button compiles your Idea into structured Systems. Review each one, edit freely, then Approve it. Approved = an agent may build it.
5. Plan milestones — on the Milestones tab, ✨ Plan milestones drafts an ordered build plan from your Systems; drag to reorder, tick tasks as they finish.

Already have code instead of a blank page? Skip to Import a codebase — an agent can reverse-engineer the design from your repo.

4Your workspace, tab by tab

The milestone timeline: ordered phases, each with its task list, estimates, and agent claims.

Ask AI answers from the real project — systems, milestones, history — not from a generic model's guess.

5Connect your coding agent (MCP)

This is the moment Forge becomes a loop instead of a document. Once connected, your agent can read the briefing in one call, pick the right next task, check a change's blast radius before touching code, and report the build back — and its proposals land in your Inbox.

Recommended: the Forge CLI (one login, every client)

1. Install the runtime (needs Node.js):

   npm i -g @forgeengine/cli

2. Log in once. In the app, open Connect Agent (sidebar → Workspace), generate an Account Key (forge_sk_…, shown once — treat it like a password), then run:

   forge login

   and paste the key. It's stored locally; no key ever goes into a client config file.
3. Wire your client — pick yours:
   • Claude Code — run once in a terminal (not inside a chat):

     claude mcp add --scope user forge -- forge mcp

   • Cursor — add to ~/.cursor/mcp.json:

     { "mcpServers": { "forge": { "command": "forge", "args": ["mcp"] } } }

   • Claude Desktop — Settings → Developer → Edit Config, same JSON as Cursor in claude_desktop_config.json. (No terminal at all? The Connect Agent page offers a one-click .mcpb extension instead.)
   • VS Code / Copilot — .vscode/mcp.json:

     { "servers": { "forge": { "command": "forge", "args": ["mcp"] } } }

   • Codex — ~/.codex/config.toml:

     [mcp_servers.forge]
     command = "forge"
     args = ["mcp"]

   • Any other MCP client — the Cursor JSON works everywhere stdio servers are supported. If the app can't find forge, use the full path from which forge (macOS/Linux) or where forge (Windows).

No Node? Connect over HTTP directly

Forge is also a hosted MCP server (listed on the official MCP Registry as app.forgeengine/forge). Point any HTTP-capable client at the endpoint with your key:

{ "mcpServers": { "forge": {
  "type": "http",
  "url": "https://mmvdabzadclebfxyzudg.supabase.co/functions/v1/forge-mcp",
  "headers": { "Authorization": "Bearer forge_sk_YOUR_KEY" }
} } }

Discovery is public — initialize and tools/list need no token, so your client can see the whole tool surface before signing in. Only tool calls authenticate.

First prompt to try

6Import an existing codebase

Don't start from a blank page if the code already exists. With an agent connected, say: "Import this codebase into my Forge project." The agent walks your repo and proposes the design it finds — systems with real Goals and Boundaries, mapped to the actual files. The whole batch lands in your Inbox as one group: skim it, fix what it got wrong, and adopt. Ten minutes later your existing project has a living, agent-readable plan.

7The Inbox — nothing lands behind your back

Agent proposals queue as reviewable cards — updates show a diff against the current spec.

• Everything an agent proposes waits here: new systems it discovered while building, spec updates (with a diff), new screens and milestones, imported batches.
• Adopt safe takes every clean, non-conflicting addition in one click; duplicates and conflicts wait for your eyes. Adopt-all is atomic — a partial adopt never drops items.
• Declining matters too: a declined proposal tells the agent its build diverged — the dashboard tracks declined items until an agent brings the code back in line.
• Deletes always show their blast radius and are never bulk-adopted.

8Share your design with any AI (or any human)

Each project can mint one public link — forgeengine.app/d/<token> — that serves the entire design as server-rendered text, compiled live on every read. Paste it into Gemini, Claude, or Grok and the assistant answers over your real design with no account, no key, no MCP setup. Hand it to a teammate and it opens as a normal page.

• Read-only — proposals still come back only through the authenticated MCP loop.
• Opt-in per project and revocable at any time; privacy comes from the unguessable token, not from crawler directives.
• ChatGPT is the one known exception: it doesn't open links like this (it web-searches instead and claims the page needs a login). The share panel has a one-click "Copy the document itself" for pasting into ChatGPT directly.

Balance Lab boards get their own kind of share link too: a public calculator anyone can tweak — visitors' changes never touch your project.

9No agent on the team? Repo loop-back

Artists, designers, and CI pipelines don't run coding agents — but their commits still change the build. The repo loop-back stamps Forge with one POST per push, so "which commit last touched this system" stays true with zero agent involvement. One command installs it for git or Plastic SCM / Unity Version Control; GitLab needs only a webhook, Perforce one trigger line. Full recipes: the loop-back guide (also in-app under Connect Agent → Repo loop-back).

10FAQ