Workspaces

Core Concept

A workspace gives a task its own directory, terminals, and ports. Local project workspaces use isolated git worktrees; cloud workspaces use separate clones. Sessions use a managed scratch folder without requiring a project.

Create Workspaces

Press ⌘N or click "New Workspace". Create from:

• New branch - Fresh branch from main
• Existing branch - Continue work on a branch
• Pull request - Review or continue a PR

In the prompt-first workspace flow, Link pull request lets you search by title or PR number, or paste the full PR URL to match it directly. The prompt box also keeps a searchable history of your previous prompts; click the history icon to reuse one.

If you type a workspace name yourself, the branch name is derived from it (slugified to kebab-case). Otherwise the workspace opens right away as New workspace (or New session), and Superset names it in the background from your prompt and any linked GitHub issue or pull request, usually within a few seconds. The branch gets the generated name plus a short unique suffix; the worktree folder keeps the name it was created with. If the first name is vague or naming fails, Superset tries again after the agent's next reply. The branch is renamed only while it is unpushed. Renaming the workspace yourself stops automatic naming. Per-project Naming instructions (in project settings) steer generated names, e.g. "prefix branches with fix/ or feat/".

Each new branch-based workspace gets:

• Own git branch
• Own working directory
• Own terminal sessions
• Workspace-scoped port detection and controls

New local worktrees use <worktrees path>/<project name>/<branch> directories. Existing worktrees keep their paths.

Cloud Workspaces

Cloud workspaces run in the cloud and are available from desktop, iPhone, and iPad without keeping your own computer connected. Superset creates a new working branch from the selected base. For multiple repositories, it uses the same working branch name in each. Attach images to the initial prompt to give the agent visual context when it starts.

Import Worktrees

If you have existing git worktrees on disk, use the Import tab in the New Workspace modal to bring them into Superset. Click Import all to bulk-import all discovered worktrees at once.

You can also right-click a project in the sidebar and choose Import untracked worktrees. A confirmation dialog lists the branches and paths that will be imported; the Run setup script checkbox is off by default, since existing worktrees are usually already set up.

Sessions

A session is a workspace without a project. Pick No project in the new-workspace picker, or click + on the sidebar's Sessions section. Each session gets its own git-initialized folder under ~/.superset/sessions. Terminals, agents, chat, and the Changes panel work as usual; there's no branch or PR link.

Sessions created outside the app (by the CLI or a session-mode automation) appear in the sidebar's Sessions section automatically. Placement happens once: if you later remove one from the sidebar, it stays removed.

From the CLI, pass --session explicitly. Creating a host workspace requires either --project <id> or --session; omitting both is an error:

superset workspaces create --session --local --agent claude --prompt "…"

On iPhone or iPad, choose No project in the composer's project picker, or tap + beside No project on Home. Sending your prompt creates a session on the selected online host.

Automations can run in session mode too; see Automations.

Pin Workspaces

Keep active workspaces at the top of the sidebar:

• Right-click a workspace and choose Pin to Sidebar (or Unpin)
• Drag into the Pinned section to pin, drag within it to reorder, drag out to unpin
• Sessions work the same way
• Pinned project workspaces show a project-name prefix, such as project/workspace

If sorting or filtering prevents a sidebar drag, the notice offers an action to restore manual ordering or clear filters.

List and Board Views

The workspaces page toggles between List and Board layouts; Board is the default. Board columns follow workspace state, derived from agent status and PR state: Idle, Working, Needs attention, Needs review, Merged, and Deleted. Merged and Deleted are history: deleted workspaces keep a card instead of vanishing, and both auto-hide while empty when Archived is Hidden (the default).

Toolbar controls live in two menus, shared by both layouts:

• Filter - Project, PR state, Agent, Pinned (All workspaces / Pinned / Unpinned), and Device. Active filters show a count badge and sync to the URL.
• Display - Sort by, the Archived window (Hidden, Past week, Past month, All), and, in Board view, Lanes: a checkbox per column to hide or show it. Lane visibility stays out of the URL and resets on restart.

Restore a Workspace

Right-click an archived card in the Deleted or Merged lane (or an archived row in List view) and choose Restore. Superset re-creates the worktree at its original path on its original branch and makes the workspace live again.

• Only committed work comes back; uncommitted and untracked changes were already lost when the workspace was deleted.
• Restore fails and the workspace stays archived if the branch no longer exists locally or on the remote.
• Restore is unavailable while the device is offline.

Ahead/Behind Status

For local (branch-based) workspaces, the sidebar shows how far the active branch is ahead or behind its remote branch:

• ↑N - N commits ahead of remote (unpushed)
• ↓N - N commits behind remote (needs pull/rebase)

PR Status

PR-based workspaces show pull request state in the sidebar.

Hover a workspace to see review status, CI checks, and GitHub links. If the branch has a deployment preview, you'll also see an Open Preview button.

A branch can have more than one PR. The badge shows a count; click it to list them, open one on GitHub, or remove a stale link. Right-click the workspace for Remove PR Link and Restore PR Link. Removals get an undo toast.

Bulk Actions

Select multiple workspaces within a project to act on them at once:

• ⌘-click toggles a workspace in and out of the selection; Shift-click selects a range
• While workspaces are selected, the Projects header becomes a toolbar with Move, Ungroup, Delete, and Clear
• Move puts the selection into a new or existing group; Ungroup removes grouped members from their group
• Bulk delete previews every workspace and flags dirty or unpushed changes before you confirm

Delete a Project

Right-click a project in the sidebar and choose Delete Project…, or use Delete project in the project's settings. An organization owner or the owner of the device can delete a project.

• Choose the devices to delete it from. The dialog shows what other people have running on each device. If someone else has terminals or agents running, you type the project name to confirm.
• Deleting stops the project's terminals and agents and archives its workspaces. Worktrees stay on disk while the project can be restored.
• From the sidebar, Hide from sidebar removes the project only for you.
• Click Undo in the toast, or restore the project from Settings → Projects → Recently deleted for 30 days. After 30 days, Superset removes the project and its clean worktrees. Worktrees with uncommitted changes and the repository folder stay on disk.
• Delete permanently on the Recently deleted page removes the project now.

Use Cases

• Parallel features - Work on multiple features simultaneously
• AI agents - Run Claude Code in separate workspaces
• Code review - Review PRs while continuing your work

Best Practices

• Use descriptive branch names: feature/auth, fix/login-bug
• Don't work directly on main
• Delete workspaces after merging