A real tester thought Forge was the whole tool. That's on us, not them.

A tester trying Forge on their own machine came away thinking Forge itself was the thing you program with — opening it up expecting it to write the whole feature end-to-end, and not understanding why the result felt like scaffolding instead of a finished build. That’s not how it’s meant to work. The intended model is: Claude Code (or another coding assistant) is the one actually writing and organizing your code, and Forge is the background assistant feeding it project context and doing the legwork. Forge’s own standalone generation mode exists for quick sketches, not as the main way to build something real.

Nowhere did we actually say that. Not on the website, not in the onboarding wizard, not anywhere in Forge’s own interface. We’d been assuming the relationship was obvious from how the pieces fit together. It wasn’t, and a tester proved that the honest way — by using it and landing somewhere we didn’t intend.

What we fixed

The confusing part wasn’t a feature, it was silence. So the fix is mostly saying the thing out loud, at the moment it matters:

• The first time a project exists, Forge now tells you plainly that Claude Code (or your coding assistant) is meant to be the one writing the code, with Forge working alongside it.
• The onboarding wizard carries the same message instead of only describing Forge’s own generation mode.
• AGENTS.md, the file Forge writes for your coding assistant to read, now states Forge’s role the same way — so the message reaches whichever tool is actually reading project context, not just the human.

The other half: showing the collaboration, not just describing it

Telling you the roles isn’t enough if you can’t see them working together. Forge already talks to Claude Code over MCP — but until tonight, that conversation was invisible. The console can now show the exact tool name, parameters, and result for every single exchange between Claude Code and Forge, instead of just a thin “something happened” strip. Turn it on in Settings; it’s off by default, because most people don’t want a firehose of protocol detail they never asked for.

Alongside that, Forge now exposes structured project state directly over MCP: FORGE.md, lessons learned from previous runs, stub warnings, fragile files, checkpoints, project memory, and — for the first time — a narrow tool that lets Claude Code write back into Forge’s own tracked state instead of only reading it. Forge also now pushes a plain notice at the start of a session telling Claude Code it’s expected to verify its own claims against the real project, not just assert them.

What else turned up while we were in there

An external field test on a second machine is a good forcing function — it finds things a self-check never would, because it’s someone else’s hands on the keyboard, not ours. The same pass that found the role confusion also turned up:

• A code-quality check (structural_verifier) that could silently report “no issues” on real ruff failures instead of surfacing them.
• Five project templates shipping a .gitignore that leaked Forge’s own internal files into the user’s new repo.
• New projects weren’t showing the same visual project map (Planet Axonris) that existing projects got — they’d been pointed at an older, abandoned view by mistake.
• Eleven of forge_mcp_server.py’s tool imports were missing from the shipped build’s own self-test, meaning a broken import there could have shipped silently.
• Six more places where two things writing to the same file at once could quietly lose one of the writes — the same class of bug we fixed a batch of last release, found again in different files.

None of these are dramatic on their own. All of them are the kind of thing that erodes trust in small, hard-to-report ways long before anyone files a bug.

Where that leaves things

Forge 1.24.0 is live now. The role-clarity fix is a message, not a mechanism — it tells you what’s intended, it doesn’t enforce it. Whether that message alone is enough, or whether the product itself needs to make the Claude-Code-first path more obviously the default, is exactly the kind of thing we want real usage to tell us, not another assumption from our side of the screen.