Workspaces

Core Concept

Each workspace = one git branch. Workspaces are isolated git worktrees with their own directory, terminal, and ports. The exception: sessions, which get a managed scratch folder instead of a branch.

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 Superset generates a name from your prompt. Per-project Naming instructions (in project settings) steer generated names, e.g. "prefix branches with fix/ or feat/".

Each workspace gets:

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

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 "…"

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

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.

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

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