Quickstart

Get your first coding agent running in Superset in under 5 minutes

This guide will take you from zero to running your first coding agent in a Superset workspace in under 5 minutes.

Before starting, make sure you’ve installed Superset on your system.

Get started in 5 steps

Follow these steps to create your first workspace and run a coding agent:

1. Launch Superset

   Open the Superset application from your Applications folder or Spotlight.

   On first launch, you’ll see the welcome screen with an empty workspace list.

   If you built from source, run bun run dev from the repository directory to start Superset in development mode.

2. Create your first workspace

   Create a new workspace for your project:

   Option 1: Quick create (recommended for first time)

   Press ⌘⇧N (Quick create workspace)
   

   This creates a workspace with auto-generated name in your current git repository.

   Option 2: Full setup

   Press ⌘N (New workspace)
   

   This opens a dialog where you can:

   • Choose the git repository
   • Set a custom workspace name
   • Configure initial setup options

   Superset will create a new git worktree for this workspace, giving it an isolated branch and working directory.

3. Understand workspace setup

   When a workspace is created, Superset automatically:

   1. Creates a git worktree — Isolated working directory on a new branch
   2. Runs setup scripts — Executes commands defined in .superset/config.json
   3. Opens a terminal — Ready for you to run your agent

   The setup scripts are defined in your repository’s .superset/config.json:

   .superset/config.json

   {
     "setup": ["./.superset/setup.sh"],
     "teardown": ["./.superset/teardown.sh"]
   }
   

   A typical setup script might look like:

   .superset/setup.sh

   #!/bin/bash
   
   # Copy environment variables from main repo
   cp ../.env .env
   
   # Install dependencies
   bun install
   
   # Run any other setup tasks
   echo "Workspace ready!"
   

   Setup scripts have access to these environment variables:

   • SUPERSET_WORKSPACE_NAME — Name of the workspace
   • SUPERSET_ROOT_PATH — Path to the main repository
4. Run your first agent

   Now that your workspace is ready, run a coding agent in the terminal:

   Claude Code

   # Run Claude Code with a task
   claude-code "Add a user authentication endpoint to the API"
   

   Your agent will start working on the task. You can:

   • Watch its progress in real-time in the terminal
   • Switch to other workspaces while it runs (⌘1-9 or ⌘⌥↑/↓)
   • Monitor multiple agents across different workspaces simultaneously

   Pro tip: Open multiple workspaces and run different agents on separate features in parallel. Superset handles the isolation automatically.

5. Review and manage changes

   When your agent completes its task, review the changes:

   View changes in the diff viewer:

   Press ⌘L (Toggle changes panel)
   

   This opens Superset’s built-in diff viewer showing:

   • All modified files
   • Line-by-line differences
   • Ability to edit directly in the viewer

   Open in your external editor:

   Press ⌘O (Open in external app)
   

   This opens the workspace directory in your default code editor (VS Code, Cursor, etc.).

   Other useful shortcuts:

   ⌘⇧C — Copy workspace path to clipboard
   ⌘B — Toggle workspaces sidebar
   ⌘K — Clear terminal
   ⌘F — Find in terminal
   

   Changes are isolated to this workspace’s worktree. To merge them to your main branch, use standard git commands like git merge or create a pull request.

What you just learned

Congratulations! You’ve successfully:

• ✅ Created an isolated workspace with git worktree
• ✅ Ran setup scripts automatically via .superset/config.json
• ✅ Executed a coding agent in the workspace terminal
• ✅ Reviewed agent changes in the diff viewer
• ✅ Learned essential keyboard shortcuts

Next steps

Now that you have a basic workflow, explore more advanced features:

Keyboard shortcuts

Master all shortcuts for maximum productivity

Workspace management

Learn advanced workspace creation, organization, and deletion

Setup scripts

Automate complex environment setup for each workspace

Running agents

Best practices for running different CLI agents

Git worktrees

Deep dive into how Superset uses git worktrees for isolation

MCP servers

Connect Model Context Protocol servers to enhance agent capabilities

Common workflows

Here are some common workflows to try next:

Run multiple agents in parallel

Create multiple workspaces and run different agents simultaneously:

1. Press ⌘⇧N to create workspace 1 (e.g., “feature-auth”)
2. Run an agent: claude-code "Implement authentication"
3. Press ⌘⇧N to create workspace 2 (e.g., “feature-dashboard”)
4. Run another agent: opencode "Build the analytics dashboard"
5. Use ⌘1, ⌘2, etc. to switch between workspaces

Both agents work simultaneously without interfering with each other.

Test different approaches

Create multiple workspaces to test different solutions:

1. Create workspace “approach-a”
2. Run: claude-code "Implement feature X using React hooks"
3. Create workspace “approach-b”
4. Run: claude-code "Implement feature X using Redux"
5. Compare results in the diff viewer (⌘L)
6. Keep the best approach and delete the other workspace

Iterate on agent output

Review and refine agent work iteratively:

1. Agent completes initial implementation
2. Press ⌘L to review changes in diff viewer
3. Identify issues or improvements needed
4. Run agent again with refined prompt: claude-code "Fix the error handling in the API endpoint"
5. Review again until satisfied
6. Commit and merge to main branch

Organize by feature branches

Use workspace names that match your feature branch strategy:

1. Create workspace: “feat/user-authentication”
2. Agent implements the feature
3. Review changes
4. From terminal: git push origin feat/user-authentication
5. Create PR from the workspace branch
6. After merge, delete workspace (⌘W from workspace view)

Tips for success

Start small — Begin with a single workspace and simple agent task before running multiple agents in parallel.

Use descriptive names — Name workspaces after features or tasks (e.g., “add-auth”, “fix-bug-123”) to stay organized.

Review regularly — Check agent progress frequently rather than waiting for completion. Use ⌘L to quickly view changes.

Leverage setup scripts — Put common setup tasks (dependency installation, env file copying) in .superset/setup.sh to automate workspace creation.

Clean up workspaces — Delete completed workspaces to keep your list manageable. Superset handles the git worktree cleanup automatically.

Need help?

If you run into issues:

• Check the Troubleshooting guide
• Browse the FAQ
• Ask in the Discord community
• Open an issue on GitHub