Getting Started

Requirements

• • macOS 14 or later.
• • Google Chrome installed for browser sessions.
• • Permission for Spaces to control Google Chrome (the macOS Automation permission), so Spaces can focus browser sessions.

First Session Flow

1. 1. Install the dependencies above and launch Spaces. On first launch, if the permission to control Google Chrome is missing, Spaces shows an “Allow Spaces to control Google Chrome” screen. Choose Grant Access to approve the macOS prompt, or open System Settings ▸ Privacy & Security ▸ Automation if Spaces was previously denied. Spaces continues to the workspace UI as soon as access is granted.
2. 2. Add a project from a local directory or a Git URL.
3. 3. Create a workspace for the branch or task you're starting.
4. 4. Launch the workspace. Spaces starts its processes; browser sessions open when you focus them.
5. 5. Open or focus any of the workspace's ordered targets with cmd+1 through cmd+0, or cycle through already-open windows with cmd+alt+] / cmd+alt+[.

Add Your First Project

Point Spaces at a local directory or paste a Git URL. Spaces creates a default workspace automatically — for a Git repo it corresponds to main / master; for a plain directory it corresponds to the directory itself.

Create a Workspace

Use the + button on a project in the sidebar, or press cmd+n. For a Git project, pick an existing branch or name a new one; the base branch defaults to main or master. Spaces sets up a git worktree for the branch.

Launch and Validate

Launching a workspace starts its processes in Spaces terminal windows. Confirm it worked:

• • The workspace shows as running in the sidebar.
• • Processes start in dedicated Spaces terminal windows.
• • Focusing a browser session opens its URL in Chrome.