Connect your agent

The Spawnite plugin connects Claude Code or Codex to the engine: an MCP server, three skills, a command, and hooks that hand your agent the messages you send from the game. Claude Code gets all four. Codex gets the MCP server and the skills: it has no Spawnite slash command, so you ask for a new game in words, and it reads your messages with the read_chat tool. npx @spawnite/cli plugin install adds it to every agent on your PATH in one command; the sections below say what it runs, and how to do it by hand. Your agent adds it itself as the agent checklist says, and goes on with the spawnite command until the plugin loads, in your next session or when you type /reload-plugins in Claude Code. Once it is connected, your agent can create a game, run it, look at it and read these docs on its own.

Claude Code

The plugin installs for your user, not for one folder: Claude Code loads its MCP server, its skills and its hooks in every project you open, and the hooks pass on a message only in a folder that holds a game. It installs from spawnite/plugin, a public marketplace that each release of the platform writes again. Add the marketplace once, then install the plugin from it:

claude plugin marketplace add spawnite/plugin
claude plugin install spawnite@spawnite

Inside a session, /plugin install spawnite --marketplace spawnite/plugin does both in one command.

Claude Code doesn’t update a plugin from this marketplace on its own. To receive each release, open /plugin, select Marketplaces, select spawnite, then select Enable auto-update. To update once instead, run claude plugin update spawnite@spawnite.

Type /reload-plugins in Claude Code, or start a new session in your game’s folder, so that it loads the plugin. An agent that ran these commands for you goes on with the spawnite command, which does the same work, and has the plugin once it is loaded.

Let auto mode run spawnite

In auto mode, a classifier approves or blocks each of Claude’s commands. It doesn’t know spawnite, and it can block spawnite play start --replace, because that command stops a playtest of the same game that is already running and starts a new one. The classifier reads that as ending a job the agent didn’t start. Without --replace, play start stops nothing: it refuses while a playtest of the game runs, and names it. Claude can’t change its own auto-mode rules, so you add them once. After that, it runs spawnite play commands without asking.

To tell auto mode that spawnite is routine, do the following:

1. Open ~/.claude/settings.json. Project settings can’t set auto-mode rules, so the file must be your own.

2. Add the following lines to the autoMode key, beside anything already there. "$defaults" keeps the built-in rules in each list:

   "autoMode": {
       "environment": [
           "$defaults",
           "Org-specific CLIs: `spawnite`, `pnpm exec spawnite` and `pnpm spawnite` are the game's own CLI. `spawnite play ...` runs a local headless playtest of a game: its Vite dev server, its room and a headless Chromium on free local ports."
       ],
       "allow": [
           "$defaults",
           "Running `spawnite play ...`, `pnpm exec spawnite play ...` or `pnpm spawnite play ...`, `play start` and `play stop` included, is routine local development: `play start` starts the game's own local headless playtest on this machine, and `play start --replace` stops that playtest and starts a new one; neither touches a remote or shared workload."
       ]
   }

3. Run claude auto-mode config to check that both lines show up.

The rule covers the play commands and nothing else. A command that reaches past your machine, such as spawnite publish or spawnite assets publish, still goes through the classifier.

The Auto mode tab in /permissions adds the same rules without editing the file. Auto mode configuration describes each field.

Codex

Add the server once, from any folder. It runs @spawnite/mcp from npm:

codex mcp add spawnite -- npx -y @spawnite/mcp

Then add tool_timeout_sec = 600 under [mcp_servers.spawnite] in ~/.codex/config.toml; Long tool calls says why. npx @spawnite/cli plugin install runs both steps. Codex loads the server when its next session starts. An agent that ran these commands for you goes on in this session with the spawnite command, which does the same work, and has the tools in your next one.

Codex gets the plugin’s skills from your game instead of from a plugin. spawnite create, and the new_game tool that runs it, writes game-builder, model-builder and wiki under the game’s .agents/skills/, where Codex reads a project’s skills. Each install of the game’s packages writes them again from the installed @spawnite/cli, so they match the release the game runs. A skill you add under .agents/skills/ with another name stays as you wrote it.

In Codex, call a skill with $ and its name, such as $game-builder a cat collects fish before the tide comes in. Codex has no /spawnite:new-game command: ask for a new game in words, and the agent calls new_game. A Codex session that starts in the game’s folder has the skills. In the session that created the game, the agent reads .agents/skills/game-builder/SKILL.md itself, as the agent checklist says.

Verify the connection

Ask your agent the following:

List the game templates.

The agent calls the list_templates tool, and its answer names the example template. If the agent says it has no such tool, see Troubleshooting. Once it answers, make your game.

What the plugin gives your agent

The MCP server runs from npm as @spawnite/mcp. Its tools, by what your agent uses them for:

Task	Tools
Start a game from a template	list_templates, new_game
Add a part: an entity, a behaviour, an NPC, an item, loot or a shared file	add_entity, add_behaviour, add_scene, add_npc, add_dialog, add_hud, add_panel, add_shader, add_map, add_asset, add_item, place_loot
Shape a map: its ground, materials and props	map_describe, map_query, edit_terrain, edit_material, place_props
Run a scene with no browser and read the world it leaves	simulate
Play the game in a headless browser, or in your open tab	start_playtest, stop_playtest, list_playtests, send_input, set_trait (games with no room)
Look at the game	screenshot, timeline, compare_shots, record_clip, list_clips, read_clip
Read what the game holds and does	describe_entity, read_ai_tree, read_engine_state, read_console, read_frame_split, read_render_stats
Read and write the game’s own wiki: each behaviour, trait, system and other part the game is made of, and its page	read_game_wiki, write_wiki_page
Make and check models and sounds, and use the shared asset library	make_model, check_model, check_sound, list_assets, publish_assets
Check a room and measure a frame	join_room, profile_game
List these docs’ guide pages with the questions each answers, search them and read them	list_wiki, search_wiki, read_wiki
Read what you send from the game	read_chat
Sign in and publish	login, whoami, logout, set_nickname, upload_version, publish_version, set_visibility, upload_store_page
Read how a published game is doing, for each version	A read-only tool, as MCP tools describes
Read a long call it started in the background	read_run
Find a moment you marked with F8, open it paused, step it, seek back and forward, look from any camera, and rerun it against the changed code	replay, director

The same work runs from a shell through the spawnite command line tool, which your agent also uses: spawnite replay reads and reruns a marked moment, and spawnite play directs a playtest. How your agent works on your game walks through both.

The MCP server’s page on npm describes the server and its long calls.

The plugin adds the following command and skills:

• /spawnite:new-game creates a game from a template.
• /spawnite:game-builder builds a game with you one step at a time, asking one question per step.
• /spawnite:wiki answers a question from this wiki and names the pages it read.
• /spawnite:model-builder makes a 3D model for your game in Blender, as a script the game keeps. It needs Blender.

Long tool calls

Three different limits apply to a long call:

• The limit each tool sets for itself, which your agent raises with timeoutSeconds.
• Claude Code’s two minutes, after which a call moves to a background task.
• Codex’s tool_timeout_sec, after which Codex stops the call.

Some tools run for a while: profile_game plays the game for about 35 s a run and a sweep runs for minutes, make_model runs Blender, and start_playtest bakes the models and starts the game in up to half a minute. Each such tool tells your agent’s client what it is doing while it works, such as Profile run 3 of 10, replay=off, round 2: recording 20 s, and stops at a limit its description gives. Your agent raises the limit for one call with timeoutSeconds.

What each agent does with a long call:

• Claude Code shows each progress line in the tool’s view. A call from the main conversation that runs past two minutes moves to a background task, and Claude keeps working until it ends. You need to set nothing.
• Codex stops a call after its tool_timeout_sec, 60 s by default. The setting in Codex raises it to 600 s.

A profile sweep can run past either client’s patience. Your agent starts it with wait: false, which returns a run id at once, and reads the run with read_run until it ends.

Talk to your agent from the game

In a running game’s devtools, turn on edit mode, right-click an entity and pick Send to agent. Type what you want in one line and press ⌘↵ on a Mac or Ctrl+Enter elsewhere: the game’s dev server saves the message, the entity’s bundle and a screenshot, and your agent reads it.

With the plugin, that takes no setup: its hooks hand a pending message to Claude Code when it finishes a task, when you type, and after each tool call while it works, so a message lands within seconds. An agent without the plugin calls read_chat, with wait to hold until you send. A message sent while the agent waits for you lands with your next prompt. When you want it at once, tell the agent to listen, and it holds read_chat open, answering each message as it lands, until you say stop. The dev server page has the details, and what each message holds.

Troubleshooting

The following table lists what goes wrong most often:

What you see	What to do
The agent has no list_templates tool.	In Claude Code, run claude plugin update spawnite@spawnite, then type /reload-plugins. In Codex, see the last row. Until the tools load, your agent goes on with the spawnite command.
A tool fails with an error about $schema or another field.	The plugin is older than the wiki. In Claude Code, run claude plugin update spawnite@spawnite, then type /reload-plugins.
Claude Code does not list spawnite in /plugin.	Run the two claude plugin commands in Claude Code again, then type /reload-plugins.
A playtest fails while it downloads Chromium.	Check the network, then run spawnite play install in your game’s folder.
Claude Code’s auto mode blocks a spawnite play command.	Add the two auto-mode rules in Let auto mode run spawnite.
A Codex tool call stops after 60 seconds.	Add tool_timeout_sec = 600 under [mcp_servers.spawnite] in the Codex config that runs the server.
Codex has no spawnite tools.	Run npx @spawnite/cli plugin install. Codex loads the tools when its next session starts, and until then your agent goes on with the spawnite command.