Set up with your agent

Paste this in your app repository#

Already have a published deck? Open Agents in its left navigation and copy the connection prompt into your existing Codex or Claude Code conversation. The deck can show progress, updated components, and follow the working area while you keep using your local agent. See Work with your own agent. The setup below is for preparing an app’s first flow.

Install and verify the CLI using the installation guide, then copy this into your coding agent. The plain Markdown guide contains this same article and is publicly readable without a service login.

Read https://mockspace.ynext.co/agent-guide.md and help me set up Mockspace in this repository.
Inspect the app and its startup command. Read the packaged mockspace-setup and mockspace-mocks SKILL.md files as the guide explains for my agent.
Reuse existing .mockspace configuration and app-owned fixtures. Prepare one representative user flow with its key screen states; report unreachable states and failures truthfully.
Run mockspace check --project ., start the app with its declared command, then run mockspace dev --project . and inspect the result.
Report the actual local viewer URL and explain how to navigate the flow and its states. Keep the first result local; publishing is a separate next step only if I request it.

Inspect before editing#

Read repository instructions, package scripts, the router, framework, API contracts and existing fixtures. Locate .mockspace/config.mjs and .mockspace/flows.mjs; legacy mockspace.config.mjs is also supported. Extend the existing setup and preserve unrelated flows, workspace settings, scripts and fixture behavior. Do not replace an existing configuration with a starter template.

Work in the current checkout by default. If the user explicitly requests a new checkout, clone the specified repository into a new directory using their available Git access, then enter its app directory. For an authenticated hosted project, use the agent setup prompt. Call list_projects to reuse existing work or create_project to register a project before its first publish; publish with --as <registered-slug> while preserving existing local configuration. A review URL is a browser review task; it does not imply permission to clone or publish.

Check prerequisites#

node --version
mockspace --help

Require Node.js 20.6 or later and the app’s declared dependencies. If the CLI is missing, install it from this service:

npm install -g https://mockspace.ynext.co/mockspace-cli.tgz

Inspect the app’s startup command and environment. Keep fixtures deterministic, use synthetic identities, and avoid production services. If the first result needs static capture, install the app-local Playwright module and its matching Chromium explicitly using the capture setup sequence. The live canvas can run without capture. Do not install packages or download browsers silently, and do not claim that check validated browser rendering.

Read the packaged skills#

Read both skills in order: skills/mockspace-setup/SKILL.md, then skills/mockspace-mocks/SKILL.md. These directories and .claude-plugin are included in the versioned CLI tarball. The thin globally installed launcher does not contain them and does not register them with any agent.

If you have a Mockspace source checkout, these paths are relative to that checkout. If you installed the launcher, run mockspace --help once to populate its cache, then locate the version directory under ${XDG_CACHE_HOME:-$HOME/.cache}/mockspace/cli. Each complete directory contains bin/mockspace.mjs and skills. Use the version reported by this service’s /healthz; if the service is offline, explicitly read the cached version used by the launcher and report that fact.

The following POSIX-shell commands locate the deployed version when the service is reachable, without cloning your app or installing another package:

MOCKSPACE_VERSION=$(node --input-type=module -e 'const r = await fetch("https://mockspace.ynext.co/healthz"); if (!r.ok) throw Error(`HTTP ${r.status}`); const { version } = await r.json(); if (!/^[a-zA-Z0-9._-]{1,128}$/.test(version)) throw Error("Invalid version"); console.log(version);')
MOCKSPACE_CLI_DIR="${XDG_CACHE_HOME:-$HOME/.cache}/mockspace/cli/$MOCKSPACE_VERSION"
cat "$MOCKSPACE_CLI_DIR/skills/mockspace-setup/SKILL.md"
cat "$MOCKSPACE_CLI_DIR/skills/mockspace-mocks/SKILL.md"

For Claude Code, either read those files directly or register the bundled marketplace from that directory:

claude plugin marketplace add "$MOCKSPACE_CLI_DIR"
claude plugin install mockspace@mockspace

Then explicitly invoke /mockspace:mockspace-setup and /mockspace:mockspace-mocks. With repository access, claude plugin marketplace add yanolja-org/mockspace is another source for the same marketplace. Reload the harness if the skills do not appear. A registered local plugin is a snapshot; repeat registration from the selected package when updating it.

For Codex, reading the two absolute SKILL.md paths directly works without registering a plugin. To make them discoverable in the app repository, copy the full skill directories into .agents/skills after checking for existing versions there. Do not overwrite an installed skill without reviewing its changes.

mkdir -p .agents/skills
cp -R "$MOCKSPACE_CLI_DIR/skills/mockspace-setup" .agents/skills/
cp -R "$MOCKSPACE_CLI_DIR/skills/mockspace-mocks" .agents/skills/

Explicitly invoke $mockspace-setup and $mockspace-mocks, or ask Codex to open those SKILL.md files. Codex discovers repository skills in .agents/skills and personal skills in $HOME/.agents/skills; restart it if the new entries do not appear. See the official Codex skills documentation. Other agents can read the same packaged files directly. Never assume that installing the CLI loaded a skill’s instructions.

Enumerate states and prepare one flow#

Choose one representative user journey. Before writing fixtures, list its screens, state conditions, concrete URLs or verified actions, and what each state reveals. Include normal, empty, loading, error and recovery cases where the app actually supports them. List unreachable states as gaps instead of inventing coverage.

• Keep mocks in the app. Reuse its existing mock layer and real API types, fixed dates and consistent identities; Mockspace only renders the app’s URLs.
• Make each state distinguishable. A label alone cannot create a state. Use the app’s path identifiers or an explicit development-only state seam; a query parameter works only if the app reads it.
• For a dialog or another state no URL can reach, use a verified state act sequence and appropriate expect assertion. Do not substitute a screenshot of the untouched screen.
• Keep mocks off in production and preserve ordinary behavior when the mock flag is absent. Never embed production credentials in configuration or fixtures.
• Describe the flow, screen purposes and source files truthfully. Keep this first change scoped to the selected flow; record the wider state backlog.

Validate and open the local canvas#

Run from the app directory:

mockspace check --project .

Fix invalid configuration and missing source paths. Check prints the app’s declared startup command; run that exact command in a separate terminal. Verify that app.url answers with the intended mocked app, not a different process or a login page. Then start the viewer:

mockspace dev --project .

Read the actual viewer URL from terminal output and open it. Do not assume the default port is free. If needed, choose an available port with the supported --port option and report the changed URL. The CLI starts the viewer and proxies; it does not launch the app itself.

Inspect each declared state in a browser. Compare states that should differ and count unintended error boundaries, login walls, stuck loading screens and duplicates. Check validates the specification; a successful check alone is not a successful canvas. If local capture is in scope and the browser is ready, mockspace build --project . --out dist captures static frames for inspection. Respect any existing output directory before building.

Recover and report#

If fixtures changed but screens did not, restart the app’s fixture process and check its logs. If a frame shows only app chrome, inspect required route parameters and client requests. If capture cannot resolve its module or launch Chromium, use the installation guide’s recovery steps and report the exact failure. If a sandbox cannot listen or launch a browser, report that missing prerequisite; never count skipped checks as passes.

Report the actual local app and viewer URLs, the flow and state table, reused and changed files, check result, rendered/error/duplicate frame counts, and any unverified or unreachable states. Explain that a flow runs horizontally through steps and each step’s states stack below it. Show how to select a state and return to the flow. Use the supported fit controls available in the viewer.

The first result stays local. Login, static sharing and publishing are separate next steps when the user chooses them. Do not run publish merely to complete onboarding.

Direct the view of a connected review#

For an existing published review, select its URL with set_mockspace_context, then call connect_agent and retain the returned session ID. Use set_agent_view for view-only changes: view is all, diff, or live (prototype is an alias saved as live). Optional frame or flow must exist in the selected build. fit: "screen" needs a frame; fit: "flow" needs a frame or flow. Omitted fields retain the current selection. A mode-only update preserves the target and work progress; use report_agent_activity to report actual milestones.

Changes requires a visible comparison with detected changes; Prototype requires a service-configured live app. Use only this conversation’s owned, connected session. MCP supplies its current connection version and rejects stale connections; REST view updates require the returned connection_version.

The user selects the session in Agents and turns on Follow agent. Updates from other sessions do not steer that view. Manual navigation stops Follow, and an agent cannot turn it back on for the user. See the MCP call example and local-agent guide.