> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/superset-sh/superset/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Info>
  Before starting, make sure you've [installed Superset](/installation) on your system.
</Info>

## Get started in 5 steps

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

<Steps>
  <Step title="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.

    <Tip>
      If you built from source, run `bun run dev` from the repository directory to start Superset in development mode.
    </Tip>
  </Step>

  <Step title="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

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

  <Step title="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`:

    ```json .superset/config.json theme={null}
    {
      "setup": ["./.superset/setup.sh"],
      "teardown": ["./.superset/teardown.sh"]
    }
    ```

    A typical setup script might look like:

    ```bash .superset/setup.sh theme={null}
    #!/bin/bash

    # Copy environment variables from main repo
    cp ../.env .env

    # Install dependencies
    bun install

    # Run any other setup tasks
    echo "Workspace ready!"
    ```

    <Note>
      Setup scripts have access to these environment variables:

      * `SUPERSET_WORKSPACE_NAME` — Name of the workspace
      * `SUPERSET_ROOT_PATH` — Path to the main repository
    </Note>
  </Step>

  <Step title="Run your first agent">
    Now that your workspace is ready, run a coding agent in the terminal:

    <CodeGroup>
      ```bash Claude Code theme={null}
      # Run Claude Code with a task
      claude-code "Add a user authentication endpoint to the API"
      ```

      ```bash OpenCode theme={null}
      # Run OpenCode with a task
      opencode "Implement the dashboard charts component"
      ```

      ```bash Cursor Agent theme={null}
      # Run Cursor Agent
      cursor-agent "Fix the TypeScript errors in src/utils"
      ```

      ```bash Codex theme={null}
      # Run OpenAI Codex CLI
      codex "Write unit tests for the authentication module"
      ```
    </CodeGroup>

    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

    <Tip>
      **Pro tip:** Open multiple workspaces and run different agents on separate features in parallel. Superset handles the isolation automatically.
    </Tip>
  </Step>

  <Step title="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
    ```

    <Warning>
      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.
    </Warning>
  </Step>
</Steps>

## 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:

<CardGroup cols={2}>
  <Card title="Keyboard shortcuts" icon="keyboard" href="/guides/keyboard-shortcuts">
    Master all shortcuts for maximum productivity
  </Card>

  <Card title="Workspace management" icon="layer-group" href="/guides/workspace-management">
    Learn advanced workspace creation, organization, and deletion
  </Card>

  <Card title="Setup scripts" icon="file-code" href="/guides/setup-teardown-scripts">
    Automate complex environment setup for each workspace
  </Card>

  <Card title="Running agents" icon="robot" href="/guides/running-agents">
    Best practices for running different CLI agents
  </Card>

  <Card title="Git worktrees" icon="code-branch" href="/concepts/worktrees">
    Deep dive into how Superset uses git worktrees for isolation
  </Card>

  <Card title="MCP servers" icon="plug" href="/guides/mcp-servers">
    Connect Model Context Protocol servers to enhance agent capabilities
  </Card>
</CardGroup>

## Common workflows

Here are some common workflows to try next:

<AccordionGroup>
  <Accordion title="Run multiple agents in parallel" icon="layer-group">
    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.
  </Accordion>

  <Accordion title="Test different approaches" icon="flask">
    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
  </Accordion>

  <Accordion title="Iterate on agent output" icon="rotate">
    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
  </Accordion>

  <Accordion title="Organize by feature branches" icon="code-branch">
    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)
  </Accordion>
</AccordionGroup>

## Tips for success

<Tip>
  **Start small** — Begin with a single workspace and simple agent task before running multiple agents in parallel.
</Tip>

<Tip>
  **Use descriptive names** — Name workspaces after features or tasks (e.g., "add-auth", "fix-bug-123") to stay organized.
</Tip>

<Tip>
  **Review regularly** — Check agent progress frequently rather than waiting for completion. Use `⌘L` to quickly view changes.
</Tip>

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

<Tip>
  **Clean up workspaces** — Delete completed workspaces to keep your list manageable. Superset handles the git worktree cleanup automatically.
</Tip>

## Need help?

If you run into issues:

* Check the [Troubleshooting guide](/resources/troubleshooting)
* Browse the [FAQ](/resources/faq)
* Ask in the [Discord community](https://discord.gg/cZeD9WYcV7)
* Open an issue on [GitHub](https://github.com/superset-sh/superset/issues)