Troubleshooting

Browser sessions

• • A browser session does not open or focus Chrome. Spaces controls Google Chrome under the macOS Automation permission. Enable Spaces for Google Chrome under System Settings ▸ Privacy & Security ▸ Automation.
• • The permission prompt never appears. Reset the stale record with tccutil reset AppleEvents dev.usespaces.spaces in Terminal, then click “Recheck”.
• • A session opens nothing. Confirm the session has a valid URL and that Chrome is installed.

Setup failed

See Setup for the setup screen and its retry, log, and repair-terminal options. If a process exits during startup, its output shows in its own pane.

Something keeps running after Stop

Add the teardown command to the workspace's stop script so Stop cleans up state Spaces does not manage on its own.

A shortcut does nothing

Another app owns that key combination. Rebind Spaces' shortcut in Settings → Shortcuts; see Changing shortcuts.

A device is unreachable or blocked

Work through the checklist in Remote machines. If it is a version mismatch, see Updates.

Agent status missing

Check Settings → Coding Agents for the agent's hook state; see Status hooks. An agent running inside tmux or screen doesn't report status. For a Codex row that stays idle while Codex works, see Codex's background server. If Codex stops with "unexpected argument '--no-daemon'", update Codex to 0.156 or later.

A pane says "Session failed"

The device lost track of the session without recording how it ended, usually after a reboot or a crash of the Spaces service, not a normal Stop or Restart. See What survives a restart.

See recent output

spaces terminal tail <session-id> prints a session's recent output from the command line.

Report a bug

Open an issue on GitHub.