Documentation
Spaces in five minutes.
Spaces runs your terminals, dev servers, and coding agents in parallel workspaces, one per branch, and keeps them running independent of any client. A native Mac app and an iPhone app drive the Spaces service on each of your machines: your Mac, another Mac, or a Linux box. Terminals, processes, and coding agents run in that service, so they keep running when you close the app or lose the connection.
Glossary
Core concepts.
The small vocabulary the rest of the docs use.
- Device
- A Mac or Linux machine running Spaces. Your Mac is one device; each paired machine is another.
- Project
- A folder or Git repository added to a device, with settings for how its workspaces run.
- Workspace
- One branch of a Git project in its own worktree, or a folder project's single directory, with its own processes, services, and terminals.
- Worktree
- The git worktree each Git workspace gets: its own branch checkout, sharing the project's one clone.
- Default workspace
- The workspace created with a project, on the repository's default branch, or the folder itself for a folder project. Listed first and cannot be deleted.
- Home workspace (~)
- Every device's workspace for terminals that belong to no project.
- Service
- A name a project declares; each workspace gets its own port for it and a stable URL that stays the same across restarts.
- Process
- A long-running command a workspace starts, such as a dev server.
- Terminal
- An ad hoc shell, a process, or a coding agent, running on a device and shown as a pane in its workspace.
- Tab and pane
- How terminals are arranged in a workspace's panel: tabs across the top, split into panes.
- Browser session
- A name and a URL a workspace opens as a Chrome tab when you focus it.
- Target
- A numbered row under a workspace, a browser session, process, agent, or terminal, that you can jump to with a keystroke.
- Coding agent
- Claude Code, Codex, opencode, GitHub Copilot CLI, pi, or Amp, run in a terminal, whose state Spaces shows using hooks it installs for the agent.
- Alert
- A row for something that needs you: a blocked or finished agent, an exited process or terminal, a bell, a failed automation run, or a terminal you marked to come back to.
- Automation
- A script or agent Spaces runs on a device, by hand or on a schedule.
- Cycling mode
- What the cycle shortcuts step through: a workspace's windows, your alerts, every agent, or every open session.
- Editor
- The window for reviewing a workspace's diff and editing its files.
Overview
All docs
Grouped by task, from first launch through troubleshooting.
Get started
Workspaces
Projects
Add a folder or Git repository on your Mac or a paired device, and set how its workspaces run.
Read pageWorkspaces
Create, set up, start, stop, hide, and delete workspaces.
Read pageTerminals, tabs, and panes
Open terminals, arrange them in tabs, split panes, and separate windows, and what happens when you close one.
Read pageThe Editor
Review a workspace's changes, edit files with previews, and send line comments to a coding agent.
Read pageFinding your way around
The sidebar, numbered targets, the command palette, and cycling through windows.
Read pageAlerts
One list of what needs you: blocked and finished agents, exited processes and terminals, bells, failed automation runs, and terminals you marked to come back to.
Read pageRun your app
Services and URLs
Named services get a port per workspace and a stable URL that stays the same across restarts.
Read pageProcesses
The long-running commands a workspace starts, and what happens when one exits.
Read pageBrowser sessions
Named Chrome tabs a workspace opens on focus and closes when it stops.
Read pageCoding agents
Agent status
How Spaces knows whether Claude Code, Codex, opencode, GitHub Copilot CLI, pi, or Amp is working, waiting for you, or done.
Read pageOrchestrate agents
Let one agent spawn, watch, and stop other agents across your workspaces and devices.
Read pageAutomations
Run a script or an agent on any device, by hand or on a schedule, and review each run.
Read pageWhat survives a restart
What keeps running when you quit Spaces, restart your Mac, or update, and how agents come back.
Read pageDevices
Reference
CLI
Every `spaces` command and flag.
Read pageMCP tools
Connect Claude Code, Codex, opencode, GitHub Copilot CLI, pi, or Amp to Spaces and see the tools they get.
Read pagespaces.yaml
The file that describes a project's setup, services, processes, and browser sessions.
Read pageKeyboard shortcuts
Spaces' shortcuts, which ones work from any app, and how to change them.
Read pageSettings
The Mac and iPhone settings, and where each is explained.
Read pageEnvironment variables
The variables Spaces sets for processes, terminals, and scripts in a workspace.
Read pageHelp
Articles
Run coding agents from your iPhone
See which agent is waiting for you and answer it in the same terminal, from your iPhone.
Read pageRun coding agents on a remote server and keep them running
Keep agents running on a Linux server after you disconnect, and bring them back with one Restore after a reboot.
Read pageLet Claude Code, Codex, and opencode work together
Let any agent start another in its own worktree, hear back when it is done, and read what it found.
Read page