Skip to main content

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.

​
General

Superset is a turbocharged terminal that allows you to run multiple CLI coding agents simultaneously. It provides workspace isolation using git worktrees, built-in diff viewing, agent monitoring, and tools to 10x your development workflow.
Yes! Superset is open source and distributed under the Apache 2.0 License. You can view the source code, contribute, and use it freely at github.com/superset-sh/superset.
Superset is free and open source. You can download and use it at no cost.

​
Platform Support

Superset is currently built for macOS. Windows and Linux support is untested. Since it’s open source, community contributions for cross-platform support are welcome!
Superset requires:
  • OS: macOS (Windows/Linux untested)
  • Runtime: Bun v1.0+
  • Version Control: Git 2.20+
  • GitHub CLI: gh
  • Caddy: caddy (for dev server)
See the Installation guide for installation instructions.

​
Agents

Superset works with any CLI-based coding agent, including:
  • Claude Code
  • OpenAI Codex CLI
  • Cursor Agent
  • Gemini CLI
  • GitHub Copilot
  • OpenCode
  • Any other agent that runs in a terminal
If it runs in a terminal, it runs on Superset.
You can run as many agents as your system resources allow. Superset is designed to handle 10+ agents running in parallel. Each agent runs in its own isolated workspace (git worktree), so they don’t interfere with each other.Performance depends on your:
  • Available CPU and memory
  • Number of active workspaces
  • Resource usage of individual agents
No. Each workspace runs in its own git worktree with its own branch and working directory. Changes made by one agent are completely isolated from others until you’re ready to merge them.

​
Workspaces

Superset uses git worktrees to create isolated workspaces. Each workspace:
  • Gets its own branch
  • Has its own working directory
  • Shares the same git repository and history
  • Can be merged back into your main branch like any other git branch
Your main repository and git history remain untouched unless you explicitly merge changes.
Create a .superset/config.json file in your repository:
{
  "setup": ["./.superset/setup.sh"],
  "teardown": ["./.superset/teardown.sh"]
}
Setup scripts run when creating a workspace, teardown scripts run when deleting one. Scripts have access to:
  • SUPERSET_WORKSPACE_NAME - Name of the workspace
  • SUPERSET_ROOT_PATH - Path to the main repository
See the Setup & Teardown Scripts guide for details.
Yes! Superset includes a built-in diff viewer for reviewing changes, but you can open any workspace in your favorite editor with ⌘O. The workspace is just a standard git worktree, so it works with any editor or IDE.
When you delete a workspace:
  1. Any teardown scripts (from .superset/config.json) run first
  2. The git worktree is removed
  3. The workspace branch remains in your repository
You can manually delete the branch with git branch -D <branch-name> if desired.

​
Features

Running agents manually:
  • ❌ Can only run one at a time
  • ❌ Need to manually manage branches and context switching
  • ❌ Changes can conflict
  • ❌ No centralized monitoring
  • ❌ Tedious setup for each task
With Superset:
  • ✅ Run 10+ agents in parallel
  • ✅ Automatic workspace isolation with git worktrees
  • ✅ Built-in diff viewer and change monitoring
  • ✅ See all agent status at a glance
  • ✅ Automated setup/teardown scripts
  • ✅ Quick context switching with keyboard shortcuts
Yes! All shortcuts are customizable via Settings > Keyboard Shortcuts (⌘/). See the Keyboard Shortcuts documentation for the full list.
No. Superset is a terminal application that helps you run and manage existing CLI coding agents. It doesn’t include its own agent - instead, it makes it easier to use agents you already have (Claude Code, Cursor, OpenCode, etc.).

​
Development

Absolutely! Superset is open source and welcomes contributions. See the Contributing guide for:
  • How to fork and create a PR
  • Development setup instructions
  • Code style guidelines
  • Community guidelines
You can also:
Clone the repository and follow the build instructions:
git clone https://github.com/superset-sh/superset.git
cd superset

# Set up environment
cp .env.example .env
echo 'SKIP_ENV_VALIDATION=1' >> .env

# Install Caddy and create config
brew install caddy
cp Caddyfile.example Caddyfile

# Install and run
bun install
bun run dev

# Build desktop app
bun run build
open apps/desktop/release
See the README for detailed instructions.
Superset is built with:
  • Desktop: Electron
  • Frontend: React + TailwindCSS v4
  • Runtime: Bun
  • Build: Turborepo (monorepo)
  • Database: Drizzle ORM + Neon PostgreSQL
  • UI Components: shadcn/ui
  • Code Quality: Biome (formatting + linting)
It’s a Bun + Turbo monorepo with multiple apps and shared packages.

​
Support

If you need help:
  1. Check the docs: Browse the documentation for guides and tutorials
  2. Troubleshooting: See the Troubleshooting page for common issues
  3. Discord: Join the Discord community for real-time support
  4. GitHub Discussions: Ask questions in Discussions
  5. GitHub Issues: Report bugs via Issues
  1. Search existing issues to avoid duplicates
  2. Create a new issue with:
    • Clear description of the problem
    • Steps to reproduce
    • Expected vs actual behavior
    • System information (macOS version, Bun version, etc.)
    • Error messages or logs
See the Troubleshooting page for details.
Better yet, if you’re able to implement it, contribute a pull request!