Skip to main content

Configuration

Claude Code and Codex​

Both agents share one local Stage server and the same set of stages. They differ in how a session hears about comments you send:

  • Claude Code: the plugin's comment monitor starts the first time the agent loads Stage's stage-design skill in a session. It checks for new comments every 2 seconds and wakes an idle session. Without it, as in non-interactive sessions, your next message there carries the comments.
  • Codex: on your first message in a session, the plugin starts a watcher that hands each comment you send to codex queue, which makes the idle session take a turn. The watcher exits when that Codex process does.
Codex comment delivery

codex queue is experimental in Codex itself, so comment delivery in Codex may change as Codex does.

Codex doesn't tell plugins which folder a session works in, so pass absolute file paths there. Relative paths are refused with an error that says so.

Settings​

Set these environment variables before starting your agent:

VariableDefaultEffect
STAGE_PORT47318Viewer and API port
STAGE_DIR~/.playcanvas-stageState directory
STAGE_AUTO_OPENon0 stops opening new stages in the browser
CHROME_PATHautoChrome binary for headless previews

Stopping the Server​

The Stage server starts on the first Stage tool call and keeps running after the session ends, so your stages stay open. Stop it with:

kill $(jq .pid ~/.playcanvas-stage/server.json)

Data and Network Use​

info

Stage has no telemetry and makes no outbound requests of its own. Scaffolding a new project runs npx create-playcanvas@latest from npm, and any other traffic is only what your app and its pages load.

  • Local only. The server binds to 127.0.0.1 and accepts only localhost addresses.
  • State. Stages, comments, edits and diagnostics are kept in ~/.playcanvas-stage.
  • Access. The agent's API needs a token kept in ~/.playcanvas-stage/server.json, readable only by you. Comments can only be written from the viewer.
  • Dev server. Only the agent can point a stage at a dev server, and only at http on localhost, 127.0.0.1 or [::1].
Keep the token private

~/.playcanvas-stage/server.json holds the token that lets an agent read and write your stages. Don't share it or commit it.

The plugin reference on GitHub has every key, tool and trust boundary in full.