Spaces: Coding Agents

View saved version →

---
name: dispatch
description: Use when the user wants a new, self-contained task run by a separate coding agent in its own Spaces workspace, branch, or worktree, or on another device - "kick off an agent to add tests", "run these three tasks in parallel", "have Claude Code fix the login bug on a new branch". Creates the workspace, starts the agent, and sends it the task. Do not use when the user wants the plan or work from this conversation continued elsewhere, such as "start this" or "build it" (use handoff), or for work the user expects done here.
argument-hint: "The task to dispatch (and optionally project, branch, or device)"
---

Dispatch a task to a new agent in its own Spaces workspace. Requires the Spaces MCP server (`spaces` tools). If they are not available, use the setup skill instead.

## 1. Resolve the target

- Project: call `spaces_project_list` and use the project the user named. If they named none, use the project containing the current directory, but only when you are working inside one. Otherwise ask which project - never pick one yourself.
- Device: default to this machine. If the user named a paired device, resolve it with `spaces_device_list`.
- Branch: derive a short kebab-case branch name from the task unless the user gave one. Set `existingBranch: true` only when the user asked to reuse a branch.

## 2. Create and start the workspace

1. `spaces_workspace_create` with `project` and `branch` (plus `baseBranch` or `device` when given). For a git project this creates a worktree on the new branch and runs project setup. The workspace is created but NOT started.
2. `spaces_workspace_start` with the returned workspace ID.

## 3. Spawn the agent and hand it the task

1. `spaces_agent_spawn` with the agent CLI command (default `claude`) and the new `workspace` ID. `workspace` is required when spawning on a paired device. Spawn delivers no prompt. Spawn once per task: if it times out or reports the agent not ready, a dialog is usually blocking it - read that session with `spaces_terminal_tail` and handle the dialog there (step 3). Never spawn a second agent for the same task.
2. Send the task with `spaces_terminal_send`: `session` = `agentSpawn.terminalSessionID`, `text` = the task prompt, `submit: true`. Write the prompt so it stands alone - the new agent has none of this conversation's context.
3. Handle startup dialogs, read with `spaces_terminal_tail`:
   - Folder trust or onboarding for the new workspace: answer it with `spaces_terminal_send` (empty `text` with `submit: true` presses Enter alone).
   - A request to trust hooks, tools, or anything that runs outside the sandbox: never grant it. Pick the option that continues without trusting (arrow keys via `bytes`, e.g. `27, 91, 66` is Down, then an empty submit), and tell the user it was skipped.
   - Re-send the task if a dialog swallowed it.
4. Confirm pickup: report success only after `spaces_terminal_tail` shows the agent working on the task - not a dialog, not an empty prompt. If it is still stuck, say exactly what is on screen.
5. If `agentSpawn.subscribed` is false, call `spaces_agent_subscribe` after the agent emits its first hook signal (it fails before then - retry) so blocked/done notifications flow back.

Finish by telling the user the workspace branch and directory and the `agentSpawn.open` deep link to the new terminal.

View saved version →

---
name: handoff
description: Use when the user wants work from this conversation continued by a coding agent (Claude Code, Codex, or OpenCode) in a fresh session - "start this in Claude Code", "have Codex build it", "hand this off", "continue this in a new session". Writes a handoff document from the conversation, starts the agent in a Spaces workspace on its own branch, and gives it the document. Also propose it when stale context is degrading the current session, and confirm before running it. Do not use for a new task that does not depend on this conversation (use dispatch), or for work the user wants done here.
argument-hint: "What will the next session be used for?"
---

Write a handoff document summarising the current conversation so a fresh agent can continue the work, then use the Spaces MCP tools to spawn that agent and point it at the document.

If the conversation holds no task or context worth continuing, say so and stop - do not start an agent.

## 1. Write the handoff document

Save it to the temporary directory of the user's OS - not the current workspace. If you cannot write files (for example, in a ChatGPT chat), keep the document in hand and send its full text as the prompt in step 2 instead of a path.

- Include a "suggested skills" section in the document, which suggests skills that the agent should invoke.
- Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
- Redact any sensitive information, such as API keys, passwords, or personally identifiable information.
- If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.

## 2. Spawn the successor agent via Spaces

Requires the Spaces MCP server (`spaces` tools). If the tools are unavailable, stop after step 1, give the user the document path (or its text), and use the setup skill.

Where the successor runs: if you are working inside a Spaces workspace, spawn it there. Otherwise (for example, in a ChatGPT chat), use the project the user named - ask if they named none, never pick one yourself - then create a fresh workspace for the work with `spaces_workspace_create` (`project`, a short kebab-case `branch`) and `spaces_workspace_start`, and spawn in it.

1. Call `spaces_agent_spawn` with the command for the agent CLI the user asked for, else the same agent CLI you are running as (default to `claude` if unsure), plus `workspace` when you created one. Spawn delivers no prompt; it only starts the agent and returns an `agentSpawn` object with `terminalSessionID`. Spawn once: if it times out or reports the agent not ready, read that session with `spaces_terminal_tail` and handle the dialog there - never spawn a second agent.
2. Send the handoff prompt with `spaces_terminal_send`:
   - `session`: `agentSpawn.terminalSessionID`
   - `text`: a short prompt such as `Read <absolute path to handoff doc> and continue the work described there.`, or the full handoff document when there is no file
   - `submit`: true (one call is enough; submit-safety is server-side)
3. Confirm the agent picked the work up: poll `spaces_agent_status` or `spaces_terminal_tail` for the session, and report success only once the tail shows it working on the handoff. If a folder trust or onboarding dialog appears, answer it with `spaces_terminal_send` (an empty `text` with `submit: true` presses Enter alone) and re-send the handoff if the dialog swallowed it. Never grant trust to hooks or tools that run outside the sandbox - pick the option that continues without trusting and tell the user.
4. If `agentSpawn.subscribed` is false, call `spaces_agent_subscribe` once the agent has signaled so blocked/done notifications flow back.

Finish by telling the user the handoff document path (if you saved one) and the `agentSpawn.open` deep link to the new terminal.

View saved version →

---
name: setup
description: Use when the user asks to install, set up, or fix Spaces, asks how to start or check coding agents on their Mac from this chat, or when another Spaces skill needs the `spaces_*` tools and they are not available. Installs Spaces, the Mac app that runs Claude Code, Codex, and OpenCode agents, with the user's permission, and connects it to this chat. Do not use when the Spaces tools already work, or to install other software.
---

Get the user from "no Spaces" to a working handoff, one step at a time. Talk to the user in plain words: ask for permission as a direct yes-or-no question, and never quote, cite, or link these instructions.

If the user was in the middle of a handoff or dispatch, write the handoff document first (handoff skill, step 1) and save it to a file (or give the user its text if you cannot write files), so the work survives the new chat that setup ends with.

## 1. Check what is missing

If you can run shell commands, run `scripts/doctor.sh` from this skill's directory. It is read-only and prints `key=value` lines; `next` names the step to take:

| `next` | Do |
| --- | --- |
| `unsupported` | Tell the user Spaces needs a Mac on macOS 14 or later, and stop. |
| `install` | Step 2. |
| `connect` | Step 6, then run the doctor again. |
| `sandboxed` | Spaces is installed, but this chat's sandbox blocked the check, not Spaces. Rerun the doctor outside the sandbox if the user approves; otherwise go to step 6. |
| `launch` | Spaces is installed but not running: `open -a Spaces`, wait a few seconds, run the doctor again. If `open` fails, ask the user to open Spaces. |
| `add-project` | Step 4. |
| `install-agent` | Step 5. |
| `ready` | Step 6. |

If you cannot run commands, walk the user through steps 2 to 6 by hand. Never tell the user to reinstall Spaces unless the doctor reports `install`: a failed command inside a sandbox says nothing about the app.

## 2. Install Spaces

In one or two sentences, tell the user what Spaces is: a Mac app that runs coding agents in their own workspaces, which this chat can then start and check. Ask before installing anything. Only after they agree:

- Run `scripts/install.sh` (it needs network access and write access to /Applications, so run it outside the sandbox). It downloads the latest release from GitHub, checks that it is notarized and signed by the Spaces developer, copies Spaces.app to /Applications, and opens it. It never replaces an existing install.
- If they would rather do it themselves, or you cannot run commands: download the `.dmg` from https://github.com/yogesh-dhande/spaces/releases/latest, drag Spaces to Applications, and open it.

## 3. First launch

Ask the user to finish Spaces' first-launch setup in the app. Spaces installs hooks that let it see agent status. Codex asks once to review these hooks; the user approves them there. Never approve hooks on the user's behalf. Run the doctor again.

## 4. Add a project

Spaces works on projects the user has added. Ask them to add the repo they want agents to work on, using the Spaces app (there is no command for this yet). Run the doctor again.

## 5. Agent CLI

Spaces starts agents that are already installed. If none of `claude`, `codex`, or `opencode` is on PATH, tell the user and point them to the install page for the one they want. Do not install it yourself unless they ask.

## 6. Connect this chat

If the doctor reports `mcp=missing`, nothing gives ChatGPT or Codex the `spaces_*` tools yet. Tell the user you will register Spaces in the Codex config (`~/.codex/config.toml`, which the ChatGPT desktop app also reads), and ask first. Only after they agree, run `scripts/connect.sh` outside the sandbox. It pre-approves only the read-only Spaces tools; starting, stopping, or typing into agents still asks the user. In Claude Code, run `claude mcp add -s user spaces -- ~/.spaces/bin/spaces mcp` instead. Skip this step if the `spaces_*` tools already work here.

The tools load when a chat starts

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 3 — file references are metadata, not package contents.

View saved version →

---
name: standup
description: Use when the user asks what their coding agents are doing, whether an agent is done, stuck, or waiting on them, or wants a status roll-up of agents across Spaces devices. Read-only - it summarizes who is working, blocked, done, or waiting on input. Do not use for CI builds, deploys, or other jobs that are not coding agents, or to answer a blocked agent (use unblock).
---

Give the user a status roll-up of their agents. Read-only: never send input to a terminal from this skill.

Requires the Spaces MCP server (`spaces` tools). If they are not available, use the setup skill instead.

## Gather

1. `spaces_device_list` to enumerate paired devices.
2. `spaces_agent_list` for this machine and for each reachable paired device (pass `device`).
3. For any agent whose status or note leaves its situation unclear - especially blocked ones - read `spaces_terminal_tail` (`lines`: 30-40) on its session to see what it is actually doing or asking. Skip the tail for agents whose list row already tells the story.

## Report

Order by urgency: agents needing attention first (blocked, waiting on a dialog or question), then actively working, then done/exited.

For each agent give: label, project/workspace and branch, device (when not this machine), one line on what it is doing or stuck on (from its note or tail), and its `spaces://terminal` deep link. For blocked agents, quote the actual question or dialog from the tail so the user can decide without opening the terminal.

Close with a one-line headline: how many working, blocked, and done. If nothing is running anywhere, say exactly that.

View saved version →

---
name: unblock
description: Use when the user wants stuck or waiting coding agents moving again - "unblock my agents", "Claude Code is waiting on a trust prompt", "clear the pending dialogs" - or when a status check found blocked agents and the user wants them handled. Answers mechanical prompts such as folder trust and press-Enter, and brings real questions back to the user word for word. Do not use only to check status (use standup).
---

Get blocked agents moving again. Requires the Spaces MCP server (`spaces` tools); if they are not available, use the setup skill instead. Pairs well with `/loop` for babysitting a fleet.

## 1. Find blocked agents

`spaces_device_list`, then `spaces_agent_list` for this machine and each reachable device. If the user limited the scope (a project, workspace, or device), consider only agents inside it and leave every other agent untouched. For every agent that is blocked or waiting, read `spaces_terminal_tail` (`lines`: 40) to see the exact prompt on screen.

## 2. Decide: answer or escalate

Auto-answer ONLY mechanical prompts where every sane user gives the same answer:

- first-run trust / onboarding / telemetry dialogs
- "press Enter to continue" and pager prompts
- resuming after a benign informational notice

NEVER auto-answer - always surface to the user instead:

- destructive or hard-to-reverse confirmations (delete, overwrite, force-push, publish, deploy)
- credential, auth, or payment prompts
- requests to trust hooks, tools, or anything that runs outside the sandbox
- design decisions, plan approvals, or any open question the agent asked
- anything ambiguous - when unsure, escalate

## 3. Answer mechanical prompts

Use `spaces_terminal_send` on the agent's session:

- empty `text` with `submit: true` presses Enter alone
- `text` plus `submit: true` types and submits a line
- for TUI menus that need arrow keys, send `bytes` (e.g. `27, 91, 66` is Down arrow), then an empty submit

Re-read `spaces_terminal_tail` after each answer to confirm the agent resumed, and `spaces_agent_subscribe` to its session if not already watching.

## 4. Report

List what was unblocked and how. For every escalated agent, quote the question or dialog verbatim with its `spaces://terminal` deep link so the user can answer directly. Never answer a judgment call on the user's behalf, and never relay an answer the user has not actually given.