superset

USP

Unlike traditional IDEs or single-agent setups, Superset provides a dedicated environment for parallel agent orchestration, isolating each task in its own git worktree and offering integrated review tools for rapid iteration.

Use cases

• 01Running multiple AI coding agents in parallel
• 02Managing isolated development tasks with git worktrees
• 03Reviewing and integrating AI-generated code changes
• 04Automating environment setup for agent tasks
• 05Orchestrating AI agents from Claude Code CLI

Detected files (4)

• skills/superset/SKILL.mdskill
  Show content (5762 bytes)

  ---
  name: superset
  description: Drives the Superset CLI to orchestrate coding agents across devices. Use when the user wants to spawn an agent, create or manage workspaces, schedule automations, or interact with Superset projects, hosts, or tasks from the terminal.
  allowed-tools: Bash(superset:*)
  ---
  
  # Superset CLI
  
  The `superset` command provides fast access to spawning subagents and creating copies of projects in isolated workspaces.
  
  If the CLI is not installed, you can install it using `curl -fsSL https://superset.sh/cli/install.sh | sh`.
  
  ## Core Workflow
  
  1. **Pick a project and host**: `superset projects list` and `superset hosts list`.
  2. **Create a Workspace**: `superset workspaces create --project <id> --host <id> --name "..." --branch <branch>` (or `--pr <number>`, or `--local` instead of `--host`).
  3. **Spawn an agent**: `superset agents run --workspace <id> --agent claude --prompt "..."`.
  4. **Plan work**: `superset tasks create --title "..."` then `tasks update <id-or-slug>` as work progresses.
  
  ## Runtime Context
  
  When invoked from inside a Superset workspace or terminal, these environment variables are set and can provide you with context about your session:
  
  - `$SUPERSET_WORKSPACE_ID` — current workspace id (use directly with `agents run --workspace`, `automations create --workspace`, etc.)
  - `$SUPERSET_TERMINAL_ID` — current terminal session id
  
  If `$SUPERSET_WORKSPACE_ID` is unset, you're not inside a Superset workspace — follow the Core Workflow above to create one.
  
  ## Workspaces
  
  ```bash
  superset workspaces create --project <id> --host <id> --name "..." --branch <branch>
  superset workspaces create --project <id> --local --name "..." --pr <number>
  superset workspaces list [--host <id> | --local]
  superset workspaces update <id> --name "..."
  superset workspaces delete <id> [<id>...]
  ```
  
  Provide exactly one of `--branch` or `--pr`. With `--pr`, the host runs `gh pr checkout`. `--base-branch <name>` is the fork point when `--branch` doesn't exist yet.
  
  ## Agents
  
  ```bash
  superset agents list --host <id>                 # Configured agents on a host (LABEL, PRESET, COMMAND, ID)
  superset agents list --local                     # Same, for this machine
  superset agents run --workspace <id> --agent claude --prompt "..."
  ```
  
  `--agent` accepts a preset id (e.g. `claude`, `codex`) or a HostAgentConfig instance UUID. Pass `--attachment-id <uuid>` once per attachment. Use `agents list` first if you don't already know which agents are installed on the target host.
  
  ## Tasks
  
  ```bash
  superset tasks list                              # List tasks in active org
  superset tasks list --priority high --assignee-me
  superset tasks get <id-or-slug>
  superset tasks create --title "..." [--priority high]
  superset tasks update <id-or-slug> --status-id <id>
  superset tasks delete <id-or-slug>
  ```
  
  Filter flags: `--status`, `--priority`, `--assignee`, `--assignee-me` (`-m`), `--creator-me`, `--search` (`-s`), `--limit`, `--offset`.
  
  ## Projects
  
  ```bash
  superset projects list                           # NAME, SLUG, REPO, ID
  ```
  
  A project is a checked-out repo. You'll need a project ID to create workspaces or schedule automations.
  
  ## Hosts
  
  ```bash
  superset hosts list                              # NAME, ONLINE, ID
  ```
  
  A host is a registered machine that can run workspaces. Use `--local` on workspace commands to target this machine.
  
  ## Automations (alias: `auto`)
  
  Automations run an agent session on a schedule. Each fire dispatches to a host and produces a workspace you (or a teammate) can open and continue interactively. Two modes:
  
  Provide one or both of `--project` or `--workspace`. Schedules are stored as [RFC 5545 RRules](https://datatracker.ietf.org/doc/html/rfc5545#section-3.8.5). Runs are dispatched at-least-once — design prompts to be idempotent. If the target host is offline at fire time, the run is marked `skipped_offline` and the next occurrence schedules normally. 
  If a workspace is omitted, it will create a fresh clone of a repo for the automation to run in.
  
  ```bash
  superset automations list
  superset automations get <id-or-slug>
  superset automations create --name "..." --rrule "FREQ=DAILY;BYHOUR=9" \
    --project <id> --agent claude --prompt-file prompt.md
  superset automations create --name "..." --rrule "FREQ=WEEKLY;BYDAY=MO" \
    --workspace <id> --agent claude --prompt "Inline prompt"
  superset automations update <id> --name "..."
  superset automations pause <id>
  superset automations resume <id>
  superset automations run <id>                    # One-off run
  superset automations delete <id>
  superset automations logs <id> [--limit N]       # Recent runs
  superset automations prompt get <id>             # Print prompt to stdout
  superset automations prompt set <id> --from-file prompt.md
  ```
  
  `prompt get | prompt set` round-trips byte-exact, so:
  
  ```bash
  superset automations prompt get <id> > prompt.md
  $EDITOR prompt.md
  superset automations prompt set <id> --from-file prompt.md
  ```
  
  ## Common Workflows
  
  ### Run an automation and inspect the result
  
  ```bash
  superset automations list --json | jq '.[] | {id, name}'
  superset automations run <id> --json
  superset automations get <id> --json
  ```
  
  ## Tips
  
  1. **Always use `--json`** when scripting or running as an agent — `--json` output is consistent per-command.
  2. **`auth whoami` before anything else** — most failures trace back to an empty `organizationId` in config or an expired token.
  
  ## Troubleshooting
  
  - **"No active organization"**: run `superset organization list && superset organization switch <id>`.
  - **"Host is offline / error connecting to host"**: the host's relay tunnel is not connected. Check to make sure both the cli and the target machine are on the latest versions of Superset.
  

• .claude/agents/project-structure-validator.mdagent
  Show content (2271 bytes)

  ---
  name: project-structure-validator
  description: Validates project structure against co-location and architecture patterns defined in AGENTS.md
  color: blue
  ---
  
  You are a project structure validator that checks AND fixes violations.
  
  ## Workflow
  
  **1. Visualize structure with tree**:
  ```bash
  tree [directory] -I node_modules
  ```
  
  **2. Read AGENTS.md** to understand the rules.
  
  **3. Identify violations** by comparing tree output against rules.
  
  **4. Fix violations directly** using file operations (mv, mkdir, Edit tool).
  
  **5. Verify changes** by running:
  ```bash
  bun run typecheck
  bun run lint
  ```
  
  ## Rules
  
  ### Folder Structure
  Every module (component, hook, constant, util, store) uses the barrel pattern:
  ```
  moduleName/
  ├── moduleName.ts(x)
  └── index.ts          # re-exports from moduleName.ts(x)
  ```
  
  **No barrel `index.ts` for parent directories** - only for individual modules.
  ```
  constants/
  ├── viewport/
  │   ├── viewport.ts   # exports VIEWPORT_SIZES, HEADER_HEIGHT
  │   └── index.ts      # re-exports from viewport.ts
  └── (NO index.ts here)
  ```
  
  ### Component Placement
  1. Used once → nest under parent's `components/`
  2. Used 2+ → promote to shared parent's `components/`
  3. One component per file
  
  ### Context Pattern
  Context files export both the Provider AND the hook together - don't extract hooks from contexts:
  ```tsx
  // ✅ Keep together in FooContext.tsx
  export const FooContext = createContext(...);
  export function FooProvider({ children }) { ... }
  export function useFoo() { return useContext(FooContext); }
  ```
  
  ### Exceptions
  - `src/components/ui/`, `src/components/ai-elements`, and `src/components/react-flow/` use shadcn format (kebab-case single files like `button.tsx`)
  
  ## Output Format
  
  ```markdown
  ## Summary
  [N] components | [N] violations found | [N] fixed
  
  ## Changes Made
  - [file moved/created/updated]
  
  ## Verification
  - Type errors: [none or list]
  - Lint errors: [none or list]
  
  ## Remaining Issues (if any)
  - [issue that couldn't be auto-fixed]
  
  ## Feedback for Improvement
  What would have helped this agent perform better? Suggest specific improvements to:
  - This agent's instructions (.claude/agents/project-structure-validator.md)
  - The project structure rules (AGENTS.md)
  ```
  

• .mastracode/mcp.jsonmcp_server
  Show content (611 bytes)

  {
  	"mcpServers": {
  		"superset": {
  			"command": "npx",
  			"args": ["-y", "mcp-remote", "https://api.superset.sh/api/agent/mcp"]
  		},
  		"maestro": {
  			"command": "maestro",
  			"args": ["mcp"]
  		},
  		"neon": {
  			"command": "npx",
  			"args": ["-y", "mcp-remote", "https://mcp.neon.tech/mcp"]
  		},
  		"linear": {
  			"command": "npx",
  			"args": ["-y", "mcp-remote", "https://mcp.linear.app/mcp"]
  		},
  		"sentry": {
  			"command": "npx",
  			"args": ["-y", "mcp-remote", "https://mcp.sentry.dev/mcp"]
  		},
  		"desktop-automation": {
  			"command": "bun",
  			"args": ["run", "packages/desktop-mcp/src/bin.ts"]
  		}
  	}
  }
  

• .claude-plugin/marketplace.jsonmarketplace
  Show content (303 bytes)

  {
  	"name": "superset",
  	"owner": {
  		"name": "Superset",
  		"url": "https://superset.sh"
  	},
  	"plugins": [
  		{
  			"name": "superset",
  			"source": "./plugins/superset",
  			"description": "Use Superset to spawn agents, create workspaces, manage tasks, and schedule automations from Claude Code."
  		}
  	]
  }
  

README

The Code Editor for AI Agents

Orchestrate swarms of Claude Code, Codex, and more in parallel.
Works with any CLI agent. Built for local worktree-based development.

Download for macOS  •  Documentation  •  Changelog  •  Discord

Code 10x Faster With No Switching Cost

Superset orchestrates CLI-based coding agents across isolated git worktrees, with built-in terminal, review, and open-in-editor workflows.

• Run multiple agents simultaneously without context switching overhead
• Isolate each task in its own git worktree so agents don't interfere with each other
• Monitor all your agents from one place and get notified when they need attention
• Review and edit changes quickly with the built-in diff viewer and editor
• Open any workspace where you need it with one-click handoff to your editor or terminal

Wait less, ship more.

Features

Feature	Description
Parallel Execution	Run 10+ coding agents simultaneously on your machine
Worktree Isolation	Each task gets its own branch and working directory
Agent Monitoring	Track agent status and get notified when changes are ready
Built-in Diff Viewer	Inspect and edit agent changes without leaving the app
Workspace Presets	Automate env setup, dependency installation, and more
Universal Compatibility	Works with any CLI agent that runs in a terminal
Quick Context Switching	Jump between tasks as they need your attention
IDE Integration	Open any workspace in your favorite editor with one click

Supported Agents

Superset works with any CLI-based coding agent, including:

Agent	Status
Amp Code	Fully supported
Claude Code	Fully supported
OpenAI Codex CLI	Fully supported
Cursor Agent	Fully supported
Gemini CLI	Fully supported
GitHub Copilot	Fully supported
OpenCode	Fully supported
Pi	Fully supported
Any CLI agent	Will work

If it runs in a terminal, it runs on Superset

Requirements

Requirement	Details
OS	macOS (Windows/Linux untested)
Runtime	Bun v1.0+
Version Control	Git 2.20+
GitHub CLI	gh
Caddy	caddy (for dev server)

Getting Started

Quick Start (Pre-built)

Download Superset for macOS

Build from Source

Click to expand build instructions

1. Clone the repository

git clone https://github.com/superset-sh/superset.git
cd superset

2. Set up environment variables (choose one):

Option A: Full setup

cp .env.example .env
# Edit .env and fill in the values

Option B: Skip env validation (for quick local testing)

cp .env.example .env
echo 'SKIP_ENV_VALIDATION=1' >> .env

3. Set up Caddy (reverse proxy for Electric SQL streams):

# Install caddy: brew install caddy (macOS) or see https://caddyserver.com/docs/install
cp Caddyfile.example Caddyfile

# Without this, Chromium rejects https://localhost:* with ERR_CERT_AUTHORITY_INVALID.
# Prompts for sudo once.
caddy trust

4. Install dependencies and run

bun install
bun run dev

5. Build the desktop app

bun run build
open apps/desktop/release

Keyboard Shortcuts

All shortcuts are customizable via Settings > Keyboard Shortcuts (⌘/). See full documentation.

Workspace Navigation

Shortcut	Action
⌘1-9	Switch to workspace 1-9
⌘⌥↑/↓	Previous/next workspace
⌘N	New workspace
⌘⇧N	Quick create workspace
⌘⇧O	Open project

Terminal

Shortcut	Action
⌘T	New tab
⌘W	Close pane/terminal
⌘D	Split right
⌘⇧D	Split down
⌘K	Clear terminal
⌘F	Find in terminal
⌘⌥←/→	Previous/next tab
Ctrl+1-9	Open preset 1-9

Layout

Shortcut	Action
⌘B	Toggle workspaces sidebar
⌘L	Toggle changes panel
⌘O	Open in external app
⌘⇧C	Copy path

Configuration

Configure workspace setup and teardown in .superset/config.json. See full documentation.

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

Option	Type	Description
setup	string[]	Commands to run when creating a workspace
teardown	string[]	Commands to run when deleting a workspace

Example setup script

#!/bin/bash
# .superset/setup.sh

# Copy environment variables
cp ../.env .env

# Install dependencies
bun install

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

Scripts have access to environment variables:

• SUPERSET_WORKSPACE_NAME — Name of the workspace
• SUPERSET_ROOT_PATH — Path to the main repository

Mastra Dependencies

This repo uses the published upstream mastracode and @mastra/* packages directly. Avoid adding custom tarball overrides unless there is a repo-specific blocker.

Tech Stack

Private by Default

• Source Available — Full source is available on GitHub under Elastic License 2.0 (ELv2).
• Explicit Connections — You choose which agents, providers, and integrations to connect.

Contributing

We welcome contributions! If you have a suggestion that would make Superset better:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

You can also open issues for bugs or feature requests.

See CONTRIBUTING.md for detailed instructions and code of conduct.

Community

Join the Superset community to get help, share feedback, and connect with other users:

• Discord — Chat with the team and community
• Twitter — Follow for updates and announcements
• GitHub Issues — Report bugs and request features
• GitHub Discussions — Ask questions and share ideas

Team

License

Distributed under the Elastic License 2.0 (ELv2). See LICENSE.md for more information.