Skip to main content
Workspaces in Superset are isolated git worktrees that allow you to run multiple coding tasks in parallel without context switching. Each workspace has its own branch, dependencies, and environment.

​
Creating Workspaces

1

New Workspace

Press ⌘N to open the workspace creation dialog. You’ll be prompted to:
  • Select a project (git repository)
  • Choose a base branch
  • Name your workspace
  • Set up initial configuration
Superset will create a new git worktree and run setup scripts automatically.
2

Quick Create

Press ⌘⇧N for quick workspace creation with default settings. This is useful when you need to spin up a workspace fast.
3

Open Existing Project

Press ⌘⇧O to open an existing project directory. This adds the project to Superset without creating a worktree.

​
Switching Between Workspaces

Workspace switching is instantaneous. All terminal sessions, scroll positions, and UI state are preserved when you switch away.

​
Keyboard Navigation

ShortcutAction
⌘1-9Jump directly to workspace 1-9
⌘⌥↑Switch to previous workspace
⌘⌥↓Switch to next workspace

​
Using the Sidebar

Press ⌘B to toggle the workspaces sidebar. Click any workspace to switch to it.

​
Managing Workspace Files

​
Opening in External Apps

Press ⌘O to open the current workspace in your default editor or IDE. Superset detects common editors like:
  • VS Code
  • Cursor
  • Sublime Text
  • IntelliJ IDEA
  • And more
You can configure your preferred editor in Settings > Editor Preferences.

​
Copying Paths

Press ⌘⇧C to copy the current workspace’s absolute path to your clipboard. Useful for:
  • Opening in external tools
  • Scripting and automation
  • Sharing workspace locations

​
Reviewing Changes

Press ⌘L to toggle the changes panel. This shows:
  • Modified files
  • Staged changes
  • Untracked files
  • Diff previews
You can:
  • Click files to view diffs
  • Stage/unstage changes
  • Commit directly from the panel
  • Open files in the editor

​
Deleting Workspaces

Deleting a workspace removes the git worktree and runs teardown scripts. Make sure you’ve committed or saved any important changes.
1

Open Workspace Menu

Right-click a workspace in the sidebar or use the workspace dropdown menu.
2

Select Delete

Choose Delete Workspace from the menu.
3

Confirm Deletion

Review the warning dialog and confirm. Superset will:
  • Run teardown scripts (clean up databases, Docker containers, etc.)
  • Remove the worktree
  • Delete workspace-specific data

​
Workspace State Persistence

Superset automatically saves and restores:
  • Open terminal tabs
  • Terminal scroll positions
  • Split pane layouts
  • Working directories
  • UI panel visibility
When you switch back to a workspace, everything is exactly as you left it.

​
Best Practices

Name Workspaces by Task

Use descriptive names like fix-auth-bug or add-user-profile instead of generic names like workspace-1.

Use Setup Scripts

Automate dependency installation and environment setup with .superset/config.json scripts. See Setup/Teardown Scripts for details.

Commit Often

Each workspace is a separate git worktree. Commit your work regularly so you can safely switch between tasks.

Clean Up Old Workspaces

Delete workspaces when you’re done with them to free up disk space and keep your workspace list manageable.

​
Troubleshooting

If a workspace appears stuck:
  1. Check if any processes are waiting for input
  2. Force-close blocking processes with Ctrl+C
  3. Try switching to a different workspace first
If workspace creation fails during setup:
  1. Check the terminal output for error messages
  2. Fix any missing dependencies
  3. Delete the workspace and try again
  4. See Setup/Teardown Scripts for debugging tips
If files seem to disappear after switching workspaces:
  1. Remember that each workspace is a separate git worktree
  2. Changes in one workspace don’t appear in others
  3. Use git status to check what branch you’re on

Running Agents

Learn how to run coding agents in your workspaces

Setup Scripts

Automate workspace initialization and cleanup

Keyboard Shortcuts

Master all available shortcuts

Integrations

Connect Superset with your favorite tools

Build docs developers (and LLMs) love

Get started for freeTalk to us