Stage

An open-source 3D scene engine that AI agents drive and people walk through. An agent writes one JSON scene file and checks, queries, and renders it from the command line or over MCP. A person opens the same file in a browser, watches it change as the agent works, and walks through it at eye level.

Two layers, used together or alone. Objects are anything: primitives, glTF models, library pieces, and assemblies built from parts that move as one, for a product, a device, a creature, a set, an explanation in space. Buildings are rooms, doors, windows, stairs, and furniture, from a floor plan or a description: walls come from room edges, levels stack, and whole houses work, with the architect's drawing under each plan. A library of about two hundred CC0 pieces with real sizes serves both, and the open model libraries are a search away for everything else.

No rooms at all: a desk, a computer, and a duck built from parts	A house from a floor plan

From the front door	The bedroom

The same house from the roof	A shared garden between two houses

Every camera and every room on one sheet	The plan, with sizes

Try it in a browser

The two-storey house is live at https://dvrshil.github.io/stage/two-storey/ and the desk at https://dvrshil.github.io/stage/desk/: press Walk inside, then W A S D and the mouse. No install.

Use it with an agent

Stage is an MCP server, and that is the way to use it. Clone it, install it, and add it to your agent from inside the folder, so the path takes care of itself:

git clone https://github.com/dvrshil/stage
cd stage
npm install                     # also builds the viewer
node bin/stage.js assets fetch  # 40 MB of CC0 textures, models, and sky, into ~/.cache/stage

# Claude Code
claude mcp add --scope user stage -- node "$PWD/bin/stage.js" mcp

# Codex
codex mcp add stage -- node "$PWD/bin/stage.js" mcp

Cursor, Claude Desktop, Gemini CLI, VS Code, and any other MCP client take the same command, node <the folder>/bin/stage.js mcp, in their JSON config; docs/mcp.md has each one, and the two optional keys for the model libraries. Opening this repository itself in Claude Code offers the server from its .mcp.json.

Then start a fresh session and ask: "Build me a rubber duck on a desk and open it in my browser." Or: "Start a scene from the two-storey example, open it, and move the sofa under the window." The agent sees every render it asks for; you see every change in your browser as it lands.

The server carries its own guide, so an agent that has never seen Stage knows the format and the order of work before its first call: a group and its parts for a thing, rooms then openings then furniture for a building, looking at a render after each step. The tools say what they are for, query and check answer in words that name the entity and the fix, and render hands the image back into the conversation. node bin/stage.js skill install also installs the guide as a skill for Claude Code and Codex, for agents that read skills before tools.

Stage needs Node 22.18 or later (24 or later is best), and Chromium or Chrome for headless renders; the viewer runs in any browser. Without assets fetch, everything still works: textures fall back to patterns drawn in code and furniture to pieces built from primitives. npm install -g . puts a stage command on your path; the examples below spell it out as node bin/stage.js.

For anything the library lacks, find_model searches the open model libraries: Poly Haven (CC0 scans), Sketchfab (CC0 and CC-BY, the largest), the Icosa Gallery (the Google Poly archive), and Poly Pizza (low-poly packs). The first three need no key; Poly Pizza wants a free key in POLY_PIZZA_KEY, and downloading from Sketchfab wants your free account token in SKETCHFAB_TOKEN. Every fetched model lands beside the scene with its license and author recorded, and share writes the credits.

The scene file

Meters and degrees; plan coordinates [x, y] with x east and y north, z up. Objects stand anywhere by their bottom center, turned by facing (clockwise from north), pitch, and roll; a parent puts one in another's frame, so an assembly moves as one. Kinds: box, sphere, cylinder (a cone with top: 0), plane, extrude (a polygon pulled up), model (any glTF beside the scene or at a URL), asset (a library piece), and group. A material by name or a color, plus roughness, metalness, opacity, and glow.

{
  "stage": "0.1",
  "name": "A duck",
  "objects": [
    { "id": "duck", "kind": "group", "at": [0, 0, 0.8], "facing": 215 },
    { "id": "body", "kind": "sphere", "parent": "duck", "radius": 0.07, "scale": [1, 1.35, 0.85], "color": "#f2c21b" },
    { "id": "head", "kind": "sphere", "parent": "duck", "radius": 0.045, "at": [0, 0.05, 0.1], "color": "#f2c21b", "label": "rubber duck" },
    { "id": "beak", "kind": "cylinder", "parent": "duck", "radius": 0.018, "top": 0, "height": 0.045, "at": [0, 0.085, 0.14], "pitch": -90, "color": "#f07a1e" }
  ]
}

Buildings are rooms: floor polygons, with walls built from their edges, shared where two rooms meet. Openings sit on a room's edge. Items are library assets placed by their center in a room and turned by facing.

This is the beginning of the README. Read the rest at the original. Read the full README ↗