forge runs a session in the background, one per worktree. Its parts are the watch-mode compiler and, when you ask, a Studio with its Rojo. The compiler part rebuilds on every save, so you read its builds instead of compiling.
Run forge from the project root through the project's package manager
(pnpm exec forge, npx forge), with --json on every command. The last line
is the result: ok, then data, or error with a stable code, message,
and hint. Branch on error.code and the exit code.
Loop
- Start:
forge up --jsononce, at the start of the task. It starts a session with the compiler alone, or joins the running one. The session is yours whendata.startedistrue. - Edit the code.
- Read the fresh build:
forge status --json --wait. It waits for the compile of your last edit, then givesdata.services.compiler.lastBuild:errors, anddiagnosticswithfile,line,column,code,message. Only--waitmakes the build fresh; a plainstatuscan show the build before your edit. A Luau watch command reports no builds:status --waitreturns at once with nolastBuild, andforge logs compilerhas its output. - Test: with a fresh build at 0 errors, run the unit tests on the compiled output. Go back to step 2.
- End:
forge down --jsonwhen the task is done and the session is yours. Leave a session someone else started running.
Failures
service_failedfromstatus --wait: the compiler part stopped.forge logs compilerhas its output. Fix the cause, thenforge up --jsonstarts it again.not_running(exit 3): no session runs. Aftersession.idleTimeoutminutes (default 30) with no activity, a session stops its parts with no owner.forge up --json, then continue.session_replaced(exit 3): a new session runs in place of yours.forge up --jsonjoins it (data.started: false), so it is not yours.compile_timeout: no fresh build came within 300 s. Readforge logs compiler.edit_not_compiled: the compiler started no compile for the edited file inerror.details.path. Save it again, or readforge logs compiler.- A deleted output folder or a reinstalled
node_modules:forge restart --jsonrestarts the parts with no owner. session_stopping(exit 6): the session is still ending. Run the command again once it is gone.- Other exit 5 or 6 errors: forge cannot verify or stop a process. Report the
errorto the user.
Studio
Studio is for verification and debugging; the loop above runs without it. Close each Studio you open, once you are done with it.
- Look once: after a fresh build,
forge open --jsonbuilds a snapshot of the place (data.place) and opens it outside the session.forge stop --place <data.place> --jsoncloses that Studio alone. Edits in a snapshot stay in the snapshot; to see a new edit, stop and open again.downand the idle timeout leave snapshot Studios open. - Change in Studio:
forge up --studio --jsonattaches a Studio and its Rojo to the session, and Rojo live-syncs your edits. Rojo serves ondata.services.rojo.port; give that port to the user and ask them to connect the Rojo plugin. When you know at the start that you will work in Studio, use this instead of a snapshot.forge stop --jsoncloses the Studio and its Rojo, and every snapshot Studio; the compiler runs on. - The user's Studio: when
up --studioreports that a Studio already has the place open, the session uses that Studio. It is the user's: ask the user before you close it, andforge syncafter their save first. - Play, and read the console, with the Roblox Studio MCP.
- Syncback: after the user saves the place,
forge sync --jsonpulls the Studio edits into the project and runs its hooks; read the files it changed before you edit them.stop,restart,down, and the idle timeout close Studio without a save, so sync each save first.
Owners
A part with owner: "start" belongs to the user's forge start terminal, and
stays theirs. down keeps it and succeeds (data.parts.kept). stop on their
Studio fails with studio_owned: tell the user, and leave that Studio open.
Other agents in the worktree share the session too, so restart and down
reach their work as well.
Setup
No config file, a config or tool error (config_not_found,
config_invalid, config_load_failed, compiler_missing, rojo_missing,
native_missing), or a change to the config or to generated service types:
see SETUP.md.