From install to an approved merge

This guide follows one piece of work from the first install to a merged pull request. Steps 1 and 2 happen on your computer only. Step 3 publishes a shared review, and everything after it happens in that hosted project.

Who can do what#

Project roles apply to people listed as members of the project. The owner and admins add members in Project settings.

• Viewer: open the project’s reviews and comment on them.
• Editor: also publish reviews and ask for changes.
• Reviewer: also review results and request changes.
• Admin or owner: also approve and merge, and manage project settings and members.

Once a project has a member list, people who are not on it cannot open the project. A project without a member list follows older, looser rules, described in step 3. Approving a merge always needs a project with a member list and an admin or owner account.

1. Install Mockspace#

Use Node.js 20.6 or later. Run this once in your terminal:

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

You should see the list of CLI commands. If the install fails, see the installation guide.

2. Set up your app with your coding agent#

Open your app’s repository folder in Claude Code, Codex or another coding agent. Paste this prompt into the agent’s chat and send it:

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.

The agent inspects your app, prepares one representative flow, checks the configuration, and starts your app and the viewer. Open the local link it returns. This canvas runs only on your computer: nothing is shared yet, and you need no account for it. The quickstart explains this step in more detail.

3. Publish a shared review#

To review with your team, publish the canvas to a hosted project. You need:

• A project on this service. Follow the setup instructions on the New project page, or ask your agent to call create_project. See Projects.
• The editor role or above in that project. A project that has no member list yet accepts any signed-in account.
• Capture set up on your computer, with your app running. See Prepare capture.

Then sign in, capture, and publish from your app’s folder:

mockspace login --service https://mockspace.ynext.co
mockspace check --project .
mockspace build --project . --out dist
mockspace publish --project . --dist dist --service https://mockspace.ynext.co

The publish goes to the project named by name in .mockspace/config.mjs and prints the review link. Share that link with your team. The review and share guide covers visibility and links.

4. Connect your agents#

Open the published project and select Agents in the left navigation. Copy the connection prompt and paste it into the agent conversation you use for that repository. The agent can then read the review you are looking at and report its progress beside the canvas. The connection acts with the signed-in account's project permissions, so the agent can read what that account can read in Mockspace. It does not upload your local source code.

To run several agents at once, open each work area in its own tab and use Connect another for each conversation. Give each task a short name so the Agents list stays readable. Turn on Share my focus to let an agent read what you have selected, or Follow agent to move your canvas to the work an agent reports.

5. Recover a lost agent#

If a conversation ends or a connection drops, the work is not lost. Select the task in Agents and open Restore this agent, or use Restore connection on a disconnected task. Paste the restore prompt into the conversation that will continue the work. Disconnected tasks stay under Previous connections.

You can also find and restore a task from the terminal:

mockspace agent list --service https://mockspace.ynext.co --project my-app
mockspace agent restore --service https://mockspace.ynext.co --project my-app --session agent_saved-id

Restoring brings back the review, the reported work and the activity history. It does not restore chat transcripts, terminal processes or local files. The local agents guide covers recovery in detail.

6. Ask for a change#

Editors and above can start a New request from the workbench. A request is tracked work: by default the agent writes a plan, someone selects Approve the plan, and then the agent builds and publishes a new draft. If an admin turns on Start work after a request in Project settings, a request skips plan approval and goes straight to the agent queue.

Each request has an urgency: Low, Normal (the default) or High, chosen in the form. Reviewers, admins and owners can also mark a request Urgent and can change any request's urgency later; the person who asked can re-rank their own among Low, Normal and High. A bug report takes its urgency from its severity: Critical becomes High, and Major and Minor become Normal. Urgency only decides which waiting request an agent takes first. It never skips the plan approval or the review.

While a request waits on automation, its status says which of these is true:

• Queued for a worker: a worker is checking in.
• A worker is on it.
• Retrying · attempt 2 of 3: a run did not finish and the request is being tried again.
• Queued · no worker has checked in recently.
• Can’t start: the project has no repository or source folder on record yet.

After three runs that do not finish, the request stops retrying and waits for you. Its thread says what happened, and sending it back gives it a fresh start. A request you stopped stays stopped until you reply to it or move it.

Requests are carried out only when the service has agent automation. The service operator must provide the agent runner, a trusted GitHub connection and publishing for the project; Project settings turns permitted automation on or off but cannot provide these by itself. Until they are ready, a request waits in the queue and the workbench says what is missing. Without automation, ask your own connected agent from step 4 for the change and publish its result.

7. Review the result#

When a result is ready, select Open latest review so the exact draft appears on the canvas. Use Changes to compare it with the version it was built on, and leave comments on the frames that need attention.

Reviewers and admins can send a result back: select Request changes, describe what should change, and select Send changes. A private request must first be shared with Share with project reviewers before anyone else can review it.

8. Approve and merge (admins only)#

Approve & merge is available to admins and the owner, on a pull request draft from the project’s connected GitHub repository, when the project turns on automatic merge in Project settings. Open the exact draft on the canvas and select Approve & merge above it. Mockspace records the approval, waits for the repository’s checks and protections, and merges that exact commit.

When automatic merge is off, the request offers Create pull request for manual merge instead; merge it through your usual process. Reviewers and editors see a note that an admin or owner must approve the merge.

Change the interface language#

Open Settings from the account menu and choose a language under Language. When you are signed in, your choice is saved to your account and follows you to your next sign-in. Commands, prompts, names and captured screens are never translated.