# AI Agents
Source: https://docs.superset.sh/agent-integration
Use Claude Code and other AI agents
## Overview [#overview]
Run AI coding agents in isolated workspaces. Each agent works independently without interfering with others.
## Supported Agents [#supported-agents]
* **Claude Code** - Anthropic's CLI
* **Amp** - Amp Code CLI
* **Codex** - OpenAI's assistant
* **Gemini CLI** - Google's CLI agent
* **Mastracode** - Mastra's terminal coding agent
* **OpenCode** - Open-source alternative
* **Pi** - Minimal terminal coding harness
* **Oh My Pi** - Terminal-first coding agent with session-aware workflows
* **Copilot** - GitHub's coding agent
* **Mistral Vibe** - Mistral's terminal coding agent
* **Kimi Code** - Moonshot AI's CLI coding agent
* **Grok** - xAI's CLI coding agent (Grok Build)
* **Cursor Agent** - Cursor AI agent
* **Droid** - Factory's autonomous coding agent
* **Polygraph** - Meta-harness with cross-repo visibility and persistent memory
* **Hermes** - Nous Research's autonomous coding and research agent
* **Muse Code** - Meta's terminal coding agent with persistent subagents
* **Devin** - Cognition's Devin agent in the terminal, with Devin Cloud handoff
* **fx** - Vercel's terminal coding agent
* **Antigravity** - Google's Antigravity CLI (`agy`)
* **Kiro** - AWS's spec-driven CLI coding agent
* **UFO** - UFO's workspace assistant for local and remote terminal workflows
## Chat [#chat]
Superset includes a built-in chat panel for AI interactions without leaving the app.
* Use the model picker to choose supported models and connect providers
* Chat session titles are generated automatically from the conversation
* Use the thinking level control to adjust reasoning effort for the selected model
## Models and Reasoning Effort [#models-and-reasoning-effort]
The model pickers include **GPT-6 Astra**, **GPT-6 Sol**, and **GPT-6 Luna**,
and **Opus 5.5** and **Sonnet 5.5**, wherever the agent supports them: Claude
Code (Claude models), Codex (GPT models), Copilot, OpenCode, Oh My Pi, and Superset
Chat. In the Codex picker, **GPT-5.5** is under **Retiring 2026-10-14**, and
the retired GPT-5.4 and GPT-5.3 Codex are gone. Available reasoning levels depend on the agent and model; see the [launch options](/cli/cli-reference#agent-effort-levels).
## Agent Settings [#agent-settings]
Go to **Settings → Agents** to customize launch behavior for each built-in agent.
* **Enabled** - Show or hide the agent in launchers
* **Command (No Prompt)** - Base command for terminal agents
* **Command (With Prompt)** - Prompt-aware command for terminal agents
* **Prompt Command Suffix** - Optional flags appended after the prompt payload
* **Task Prompt Template** - Template used when launching an agent from a task
* **Resume Args** - Arguments used to restore a killed session by its id (e.g. `--resume`)
* **Fork Args** - Arguments used to clone a session by its id. Put `{sessionId}` where the id belongs (e.g. `--resume {sessionId} --fork-session`); leave empty if the agent cannot fork
* **Model Override** - Optional model override for Superset Chat
* **Reset to Defaults** - Restore the shipped configuration for that agent
## Usage [#usage]
Run agents directly in the terminal:
```bash
claude "Add error handling to fetchUser"
```
## Auto-Run Command [#auto-run-command]
When launching an agent from a task, the **Auto-run command** toggle controls whether it executes immediately.
* **On** - Terminal agents run their command right away, and Superset Chat sends the task prompt immediately
* **Off** - Terminal agents stage the command without pressing Enter, and Superset Chat opens as a draft instead
The setting is remembered between sessions.
## Agent Sessions & Forking [#agent-sessions--forking]
Resume an interrupted session, fork a session, or hand its work to another agent. See [Agent Sessions & Forking](/agent-sessions).
## Parallel Agents [#parallel-agents]
Create multiple workspaces and run an agent in each. Compare results and merge the best solution.
## Inline Prompts [#inline-prompts]
Agents can pause and ask questions, request tool approval, and ask for plan review directly in the chat pane.
## Sandbox Access [#sandbox-access]
When an agent needs access to files outside its workspace, it will prompt for permission in chat so you can approve or deny the request inline.
## Notifications [#notifications]
Get notified when agents finish. Configure sounds in Settings.
## Agent Skills [#agent-skills]
Teach any agent to drive Superset itself with the official [skills](https://github.com/superset-sh/skills), one for the `superset` CLI and one for the [MCP server](/mcp-server):
```bash
npx skills add superset-sh/skills
```
---
# Agent Sessions & Forking
Source: https://docs.superset.sh/agent-sessions
Resume, fork, and hand off agent sessions
An agent session is one agent conversation running in one terminal. Superset can bring a session back after its terminal dies, copy it into a new session of the same agent, or pass its recent context to a different agent.
## Resume Interrupted Sessions [#resume-interrupted-sessions]
If an agent's terminal dies under it (a crash, a reboot, a killed process), Superset resumes the session automatically: the pane relaunches the agent with its resume command (e.g. `claude --resume `) and shows a "Resuming…" pill while it happens. Only unexpected deaths qualify: sessions you close or kill deliberately, and agents that exited cleanly, stay down.
If the resume fails, the pill turns into "Failed to resume" with a **Retry** button and a dismiss control.
Works for agents with an id-based resume command (the **Resume Args** field under **Settings → Agents**). From the CLI:
```bash
superset agents create --workspace ws_… --agent claude --resume-session
```
## Fork and Hand Off Sessions [#fork-and-hand-off-sessions]
The fork icon in an agent terminal's header opens two actions. Both open the new session in a split pane or a new tab.
* **Continue with another agent** - Starts a fresh session of the agent you pick, seeded with this terminal's recent context. Use it when a session is stuck, out of context, or the wrong tool for the job. The dialog shows how many characters (and about how many tokens) it will send before you continue.
* **Fork session** - Starts a native copy of this session in the same agent, with the same conversation. The original session keeps running unchanged.
### Fork [#fork]
Fork uses the agent's own fork command, so the copy has the full conversation. Built-in agents that can fork, with the fork part of each command:
| Agent | Fork command |
| ----------- | ------------------------------------- |
| Claude Code | `claude --resume --fork-session` |
| Codex | `codex fork ` |
| OpenCode | `opencode --session --fork` |
| Pi | `pi --fork ` |
| Grok | `grok --resume --fork-session` |
| Droid | `droid --fork ` |
Superset also passes the agent's launch flags, such as `--dangerously-skip-permissions` for Claude Code, so a fork runs with the same permissions as a new session. **Settings → Agents** shows each agent's command and fork args.
For other agents, set **Fork Args** under **Settings → Agents**. **Fork session** is disabled until Superset knows the agent's session id, and for agents without fork args. For Claude Code, Codex, OpenCode, and Pi, Superset refuses the fork if the agent has deleted the source session. For other agents, Superset cannot check, so the new pane opens and the agent reports the missing session there.
A fork copies the conversation, not the files. Both sessions work in the same workspace.
### Continue with another agent [#continue-with-another-agent]
The new session gets a prompt that contains the last 36,000 characters of this terminal's context, marked as read-only history. The prompt tells the agent to check `git status` and the files first, because the workspace, not the transcript, is the source of truth. For Claude Code and Codex, Superset reads the agent's own saved conversation when it can. Otherwise it reads the terminal's recorded output stream, not only the visible screen.
A handoff sends terminal output to the target agent's provider. Superset removes terminal control codes but does not redact anything, so tokens, keys, or connection strings that a command printed go with it. If the session showed credentials, ask the agent for a summary and start the new agent with that instead.
## Find Session and Terminal IDs [#find-session-and-terminal-ids]
Click the copy icon in an agent terminal's header (**Copy IDs**):
* **Copy agent session ID** - The agent's own session id, used by `--resume-session` and `--fork-session`
* **Copy terminal ID** - The Superset terminal id, used by `--from-terminal` and `superset agents read`
## From the CLI [#from-the-cli]
```bash
# Fork a session
superset agents create --workspace --agent claude --fork-session
# Continue in another agent
superset agents create --workspace --agent codex --from-terminal
```
`--from-terminal` builds its own prompt, so it does not accept `--prompt`. Use `--context-chars` to send less than 36,000 characters. See [`agents create`](/cli/cli-reference#agents).
## Read an Agent's Transcript [#read-an-agents-transcript]
`superset agents read` returns the agent's saved conversation, including what scrolled off a full-screen interface. Superset can read saved transcripts for Claude Code and Codex. The command fails for other agents, and when the saved transcript is missing. It does not fall back to terminal output.
```bash
superset agents read --local --workspace --terminal
```
---
# Agent Status & Notifications
Source: https://docs.superset.sh/agent-status
How Superset knows what your agents are doing, and how it tells you
## The Activity Strip [#the-activity-strip]
Each workspace in the sidebar shows an activity strip:
* **Running agents and open ports** appear inline on the workspace item
* **Running and PR state persist across restarts**
* Workspaces with live work are visually emphasized so in-progress items stand out
* Agent chips stay hidden unless multiple agents are running in that workspace
If a workspace shows as running after you've stopped its agent (for example after force-quitting the agent), use **Clear Status** on the workspace to reset the indicator.
## How Status Is Detected [#how-status-is-detected]
Superset installs lifecycle hooks and command wrappers into each agent's config (the entries in `~/.superset/bin` and files like `superset-hooks`). Those hooks report when an agent starts, finishes, or is waiting for input. That's why status only works for agents launched through Superset, and why removing the hooks disables status and notifications.
The hooks no-op outside Superset terminals (they check for a Superset-supplied env var). To remove them from an agent's config entirely, turn off the agent's **Superset hooks** toggle in **Settings → Agents**.
## Notifications [#notifications]
* **Finished / waiting for input**: get notified when an agent finishes or pauses for your input. Configure sounds in Settings.
* **Support varies by agent.** Claude Code reports both finished and waiting states. Some agents don't emit a waiting-for-input signal yet, so you'll only get completion notifications for them.
* **Inline prompts**: agents can pause to ask questions, request tool approval, or ask for plan review directly in the chat pane, and the workspace is flagged as needing attention.
## Dock Badge [#dock-badge]
The macOS dock icon shows a badge for workspaces with unread activity or that need your attention.
macOS only shows dock badges when Superset has notification permission. If you don't see badges, check **System Settings → Notifications → Superset**.
---
# Automations
Source: https://docs.superset.sh/automations
Schedule agent sessions to run on a recurring basis
## Overview [#overview]
Automations run an agent session against a project on a schedule, like a cron job, but the output is a live workspace you (or a teammate) can open, review, and continue interactively.
Typical uses:
* **Standups**: a nightly summary of PRs, issues, and activity
* **Release notes**: generate a draft from merged commits
* **Audits**: scan for security issues or deprecated APIs each morning
* **Dependency sweeps**: check for outdated packages weekly
The list shows 7-day health stats (Active, Created, Failed), groups enabled automations by soonest run under **Up next**, and splits into **Mine** and **Team** tabs. Team automations are read-only; only the owner can edit, pause, run, or delete one.
## Requirements [#requirements]
* **A Pro plan**: Automations are a [Pro feature](https://superset.sh/pricing). Creating, running, and resuming an automation needs a Pro or Enterprise subscription on the organization, from the app, the CLI, or the SDK alike. An organization that downgrades keeps its automations and can still edit, pause, or delete them, but they stop firing until it upgrades again.
* **A project, or session mode**: automations usually run against a v2 project linked to a GitHub repo. Pick **No project** and each run creates a [session workspace](/workspaces#sessions) instead.
* **A target device**: The run fires on the device you pick when creating the automation.
## Create an Automation [#create-an-automation]
Click **Automations → New automation** and fill in:
* **Title**: how the automation appears in the list
* **Prompt**: the instructions the agent will receive at dispatch time. Supports markdown, `@file/path` mentions (scoped to the selected project), `:emoji:` shortcodes, and `/` slash commands.
* **Device**: which host runs the session. Defaults to this device.
* **Project**: the v2 project the session runs against, or **No project** for a session per run.
* **Schedule**: pick a preset or enter a custom RRule. Times use your timezone at creation.
* **Agent**: Claude, Codex, Amp, or anything else you've set up under **Settings → Agents**.
## Triggers and Schedules [#triggers-and-schedules]
On the automation's detail page, schedules live in a **Triggers** list; each row shows its cadence and next run inline. **Add Trigger** adds another schedule: one automation can fire on several cadences, and every automation needs at least one trigger. Hover a row to remove it. Edits are drafts until you press **Save triggers** (or **Discard**).
Schedules are stored as [RFC 5545 RRules](https://datatracker.ietf.org/doc/html/rfc5545#section-3.8.5). The picker has presets for common cadences (Hourly, Daily, Weekdays, Weekly); use **Custom** for anything else. Custom rules are validated inline: invalid rules, rules with no upcoming runs, and one-shot rules (`COUNT`/`UNTIL`) are rejected before saving.
Examples:
* `FREQ=DAILY;BYHOUR=9;BYMINUTE=0`: every day at 9:00 AM
* `FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=9;BYMINUTE=0`: weekdays at 9:00 AM
* `FREQ=WEEKLY;BYDAY=FR;BYHOUR=17;BYMINUTE=0`: every Friday at 5:00 PM
## Runs [#runs]
Each time an automation fires, a **run** is recorded. Runs show up on the automation detail page's **Run History** tab with a status:
* **created**: the workspace was created on the target device (a run's success state)
* **creating**: the handoff is in flight
* **failed**: the device was offline at fire time or the handoff broke. The error shows inline under the run, selectable for copying
The schedule advances to the next occurrence either way.
When a run dispatches in "new workspace" mode, a fresh workspace is created from the project's repo for that run (or a fresh session workspace when the automation has no project). Open it from the run row to see the agent's work.
## Pause, Run Now, Delete [#pause-run-now-delete]
From the automation's detail page (**Settings** tab):
* **Pause**: flip the Active switch. Runs are kept, and each schedule row on a paused automation still shows when it *would* next run, so schedule edits are previewable.
* **Run now**: dispatches immediately. The run appears under **Run History** within seconds.
* **Delete**: in the ⋯ overflow menu; removes the automation and its run history.
## Retry Failed Runs [#retry-failed-runs]
On the **Mine** tab, **Retry all** appears in the header when any of your automations' latest run failed, and re-dispatches all of them. The **Failed** stat card filters to failing automations. Hover a row you own for **Run now** to re-dispatch one.
## Limits [#limits]
* **At-least-once delivery**: Automations may dispatch more than once in rare cases (e.g. dispatcher retries). Design prompts that are safe to re-run.
* **No agent-outcome tracking**: a successful run means its workspace was created; the detail page doesn't show whether the agent's work succeeded. Open the workspace to see what happened.
* **Offline hosts fail the run**: if the target device is offline at fire time, the run records as failed and the next occurrence is scheduled normally. Use **Retry all** once the device is back.
* **One prompt per automation**: Each automation has one prompt (though it can have several schedule triggers). To run multiple prompts on a schedule, create multiple automations.
## CLI [#cli]
```bash
superset automations list
superset automations create --name "Nightly audit" --rrule "FREQ=DAILY;BYHOUR=3;BYMINUTE=0" --project --prompt-file prompt.md --agent claude
# Omit --project and --workspace for session mode (a session workspace per run)
superset automations create --name "Scratch triage" --rrule "FREQ=DAILY;BYHOUR=8;BYMINUTE=0" --prompt "…"
# Each run's workspace carries the automation's tags and groups into the matching
# sidebar folders. Default tag: "automation" — runs collect in an "automation"
# folder per project. --tag (repeatable) files them elsewhere; clearing the tags
# in the editor opts out of grouping.
superset automations create --name "Nightly audit" --rrule "FREQ=DAILY;BYHOUR=3;BYMINUTE=0" --project --prompt "…" --tag audits
superset automations update --session # switch an existing automation to session mode
superset automations get
superset automations run
superset automations pause
superset automations resume
superset automations delete
```
---
# In-App Browser
Source: https://docs.superset.sh/browser
Built-in browser pane for previewing your running services
## Overview [#overview]
Superset includes a built-in browser pane so you can preview your running services without leaving the app.
## Open a Browser Tab [#open-a-browser-tab]
* Press **⌘⇧B** to open a new browser tab
* Click the external link icon on any detected port in the sidebar to open it in the browser
## Navigation [#navigation]
The browser pane includes a full address bar with:
* Back, forward, and reload buttons
* URL autocomplete based on your browsing history
* Favicon display for visited sites
## Browsing History [#browsing-history]
URLs you visit are saved locally and appear as autocomplete suggestions. To clear your history:
1. Click the overflow menu (⋯) in the browser toolbar
2. Select **Clear Browsing History**
## DevTools [#devtools]
Open the DevTools pane alongside any browser tab to inspect and debug the page running in the browser.
## Design Mode [#design-mode]
Click **Design** in the browser toolbar to arm an element picker inside the page. Click any element and a prompt card opens under it: describe the change, pick an agent, and send. The agent receives the element's DOM, computed styles, React component metadata, and a cropped screenshot along with your note, in an existing agent terminal or a fresh session.
* Press **esc** to pick a different element; **esc** again (or the banner's ✕) exits design mode
* Works on any page the pane can load, including your local dev server
## Ports Integration [#ports-integration]
When Superset detects a port in use (e.g. `localhost:3000`), clicking its external link icon opens it in an in-app browser tab instead of the system browser.
For workspaces on a [remote host](/remote-access), the desktop app forwards detected ports while that workspace is selected. See [Remote Access](/remote-access#ports-on-a-remote-host) for requirements and port conflicts.
## Drive it from the CLI and agents [#drive-it-from-the-cli-and-agents]
Browser panes can be driven programmatically with the [`superset browser`](/cli/cli-reference#browser) commands, so an agent can open a page, read it, screenshot it, and interact with it in the same pane you're watching.
```bash
# Open a page and get its pane id back
superset browser open --workspace --url http://localhost:3000 --target new-tab
# Read, screenshot, and evaluate in the pane
superset browser eval --workspace --pane --code "document.title"
superset browser screenshot --workspace --pane --out shot.png
superset browser console --workspace --pane
```
For full interaction (clicking, typing, scrolling, form flows), `superset browser cdp` prints a raw [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) WebSocket endpoint you can point a browser-use / Playwright-class client at. The endpoint drives only that pane's page (never the Superset app itself), and pane operations are scoped to their workspace.
Agents pick this up automatically through the [`superset:browser` skill](/skills). A pane runs against the browser's real, logged-in session; agents are instructed to treat it accordingly and to confirm before consequential actions.
## Pane or standalone browser? [#pane-or-standalone-browser]
The `superset:browser` skill is engine-generic with the in-app pane as the default: when a page is (or can be) open in a workspace pane (previewing a dev server, verifying UI you're watching, clicking through a flow), agents use the `superset browser` commands above.
Some targets are out of the panes' reach: a real Chrome window outside Superset, a host running without the desktop app attached, or work that needs an isolated or cloud browser. For those, the skill routes to [Browser Use 3.0](https://docs.browser-use.com/open-source/browser-use-cli) as a second engine.
### Browser Use 3.0 [#browser-use-30]
Browser Use is built by [Browser Use](https://browser-use.com), not by Superset, and nothing in Superset requires it; the in-app pane engine works with no extra install. Only add it if you want standalone automation, and note that attaching it to your running Chrome hands agents your signed-in sessions.
Browser Use 3.0 is a CLI that lets agents execute Python against a browser over the Chrome DevTools Protocol. It isn't bundled with Superset; agents check for it and ask before installing. To install it yourself (requires [uv](https://docs.astral.sh/uv/)) so the `browser-use` command lands on your `PATH`:
```bash
uv tool install browser-use
browser-use --help
```
You can also run it ephemerally with `uvx --from 'browser-use[cli]' browser-use …`, but that doesn't add `browser-use` to your `PATH`; each call needs the full `uvx --from` prefix.
By default it attaches to your running Chrome (your real, signed-in profile), so the skill requires your explicit consent before taking that path; otherwise agents use a scratch browser or a Browser Use cloud browser (which bills until stopped, so they ask first and stop it after). `browser-use --doctor` diagnoses connection problems, and `browser-use skill` prints the engine's own usage reference.
Browser Use can also drive an in-app pane: point it at the pane's endpoint from `superset browser cdp` (as `BU_CDP_WS`) and the pane presents itself as a single page target. For panes the `superset browser` verbs are the simpler default, but this lets Browser Use's harness reach the same pane when you want it.
---
# Community & Support
Source: https://docs.superset.sh/community
Get help, follow along, and talk to us
## Get Help [#get-help]
The fastest way to get answers, from the team and other users.
Bug reports and feature requests.
Account, billing, and anything private.
Before filing: check [Troubleshooting](/troubleshooting) and the [FAQ](/faq).
## Follow Along [#follow-along]
What shipped, weekly.
Launches and demos.
Walkthroughs and feature videos.
Company news.
---
# Computer Control
Source: https://docs.superset.sh/computer
Let agents operate native desktop applications through an accessibility-first driver
## Overview [#overview]
Superset includes a `computer` skill that teaches agents to operate native
desktop applications through an accessibility-first driver. It can inspect
windows, read accessibility state and screenshots, click, type, scroll, use
native menus, and verify the resulting UI state on macOS, Windows, and Linux.
The skill's workflow is driver-agnostic; [Cua
Driver](https://cua.ai/docs/cua-driver) is the default. On macOS,
[Peekaboo](https://peekaboo.sh) works as an alternative — agents use whichever
supported driver you have installed, and ask before installing one.
The agent works in the actual app window you can see. Cua Driver targets a
specific process and window and uses background interaction when the platform
supports it, so routine automation does not need to take over your mouse or
bring the target app to the front.
## Install a driver [#install-a-driver]
Drivers are not built or maintained by Superset — Cua Driver comes from
[Cua](https://cua.ai) and Peekaboo from [its open-source
project](https://peekaboo.sh) — and nothing in Superset requires one:
without a driver installed, this skill simply isn't used. Installing a
driver and granting it Accessibility and Screen Recording gives it, and
agents driving it, deep control of your machine — extend it the same trust
as any system-level tool.
The skill is bundled with Superset, but the driver runtime is installed
separately. Cua Driver is the default:
**macOS and Linux**
```bash
/bin/bash -c "$(curl -fsSL https://cua.ai/driver/install.sh)"
```
**Windows (PowerShell)**
```powershell
irm https://cua.ai/driver/install.ps1 | iex
cua-driver autostart enable
cua-driver autostart kick
```
Then verify the host:
```bash
cua-driver --version
cua-driver doctor
```
macOS also requires Accessibility and Screen Recording permission for the
CuaDriver app. Run `cua-driver permissions grant` and follow the System
Settings prompts. See the complete [installation and permissions
guide](https://cua.ai/docs/how-to-guides/driver/install).
Cua Driver enables anonymous telemetry by default; turn it off with
`cua-driver telemetry disable`.
**Prefer Peekaboo? (macOS only)**
```bash
brew install steipete/tap/peekaboo
```
[Peekaboo](https://peekaboo.sh) needs the same Accessibility and Screen
Recording permissions. Agents use whichever supported driver is installed, so
installing Peekaboo instead of Cua Driver selects it.
## Hand an app to your agent [#hand-an-app-to-your-agent]
Ask naturally, or invoke `/superset:computer` in Claude Code and
`/superset/computer` in Superset's in-app chat:
```text
Open Calculator, compute 27 × 14, and tell me the displayed result.
```
```text
Use the open design app to export the current canvas as a PNG, then verify the
file appeared in the chosen folder.
```
The skill makes the agent declare a task-scoped session, identify the exact app
and window, take a fresh state snapshot before every action, and verify the UI
afterward. It starts with accessibility targets, uses pixels only when needed,
and escalates to foreground or full-desktop control only after observed failure.
## Computer or browser? [#computer-or-browser]
Use [`browser`](/browser) for a page open in Superset's in-app browser pane. It
provides direct DOM, console, screenshot, and Chrome DevTools Protocol access.
Use `computer` for native applications, the Superset desktop UI itself, browser
chrome, or a browser engine that is not available through the in-app browser
skill.
## Safety [#safety]
The agent sees the real state of the targeted application. The skill tells it
to avoid unrelated private data, preserve your other windows, and ask before
consequential actions such as sending a message, submitting a form that creates
an external commitment, publishing, purchasing, deleting data, or changing
account settings.
---
# Custom Themes
Source: https://docs.superset.sh/custom-themes
Build, edit, and import your own Superset theme files
You can import a theme file from the Marketplace or create your own from a base file in desktop settings.
## Quick Workflow [#quick-workflow]
1. Open `Settings → Appearance → Theme`.
2. Either click `Marketplace` to download a shared theme, or click `Download Base File` to start from your current theme.
3. If you downloaded a base file, edit the JSON manually or ask an agent to customize it.
4. Click `Import Theme` and select the file.
5. Pick the imported theme from the theme grid.
Marketplace themes are available from the Marketplace page or the `Marketplace` link in `Settings → Appearance → Theme`.
## Ask An Agent To Customize It [#ask-an-agent-to-customize-it]
After downloading the base file, you can prompt an agent with something like:
```text
Customize this Superset theme JSON to feel like a neon cyberpunk arcade.
Keep the schema valid. Preserve all required ui and terminal keys.
Return the full JSON file contents only.
```
Then save the returned JSON and import it in Superset.
## Theme File Format [#theme-file-format]
Superset accepts:
* A single theme object
* An array of theme objects
* An object with `themes: [...]`
The importer supports:
* `id`, `name`, `type` (`dark` or `light`)
* `ui` color overrides
* `terminal` color overrides
* `colors` as an alias for `terminal`
Missing values fall back to Superset defaults for the selected theme type.
## Example: Single Theme [#example-single-theme]
```json
{
"id": "my-neon-theme",
"name": "My Neon Theme",
"type": "dark",
"author": "You",
"description": "Neon terminal and UI accents",
"ui": {
"background": "#12061f",
"foreground": "#f7f5ff",
"primary": "#39ff14",
"accent": "#00e5ff",
"border": "#7b2dff"
},
"terminal": {
"background": "#0b0314",
"foreground": "#f8f2ff",
"cursor": "#39ff14",
"red": "#ff2b70",
"green": "#39ff14",
"yellow": "#ffef00",
"blue": "#00b7ff",
"magenta": "#ff5ecf",
"cyan": "#00ffd1",
"white": "#e9dcff",
"black": "#18082a",
"brightBlack": "#6e3ea5",
"brightRed": "#ff6fa2",
"brightGreen": "#7dff5a",
"brightYellow": "#fff86a",
"brightBlue": "#59dbff",
"brightMagenta": "#ff9be8",
"brightCyan": "#8dffe8",
"brightWhite": "#ffffff"
}
}
```
## Notes [#notes]
* Theme IDs must be unique and not reserved (`system`, built-in theme IDs like `dark`/`light`).
* Very large files are rejected in the desktop importer.
---
# Customization
Source: https://docs.superset.sh/customization
Personalize Superset to your workflow
## Notification Sounds [#notification-sounds]
Get audio notifications when agents finish or terminals exit.
Settings → Notifications → Choose a sound
Import custom ringtone audio files (MP3, WAV, OGG, up to 20MB) from **Settings → Notifications**. Preview any imported sound and set it as your active notification.
## Project Colors [#project-colors]
Color-code your projects in the sidebar for quick identification.
Click the project thumbnail in project settings to open the icon picker: choose an accent color, pick a glyph, or upload a custom image. Colors set on v1 projects carry over when they're imported.
## Default Editor [#default-editor]
Set which editor opens when you press ⌘O.
Settings → Editor → Select Cursor, VS Code, or other
## File Open Mode [#file-open-mode]
Control how files open when clicked in the file tree or changes view.
Settings → Files & Editor → Opening files → File open mode
* **Split pane** (default) - Opens files by splitting the current tab
* **New tab** - Opens files in a new tab
Preview pane reuse works in both modes. This setting only affects the fallback when no reusable pane exists.
To choose what a click, Shift-click, Cmd/Ctrl-click, or Cmd/Ctrl+Shift-click does on a row in the file tree, changes list, or diff header, use **Sidebar file rows** in the same section.
## Terminal Scripts [#terminal-scripts]
Save reusable terminal commands, group them into panes or tabs, and launch them
from the Scripts bar or CLI.
Settings → Terminal → Terminal Scripts
These are separate from repository setup, run, and teardown behavior, which
uses [project lifecycle scripts](/setup-teardown-scripts). See the full
[Terminal Scripts guide](/terminal-scripts).
## Custom Themes [#custom-themes]
Download a theme from the Marketplace, or start from a base theme JSON and customize it before importing.
Settings → Appearance → Theme → Marketplace / Download Base File / Import Theme
See full guide: [Custom Themes](/custom-themes)
## Settings Sync [#settings-sync]
Your settings sync across devices when signed in.
---
# Diff Viewer
Source: https://docs.superset.sh/diff-viewer
Review code changes and manage your git workflow
## Overview [#overview]
Review changes, stage files, commit, and push, all from one interface.
## Features [#features]
* **View changes** - See modified, staged, and untracked files
* **Stage/unstage** - Select files for commit
* **Commit** - Write message and commit
* **Push/Pull** - Sync with remote
* **Create PR** - Open pull request on GitHub
The Changes control sits at the top of the right sidebar beside **Pages** and **Run**. Before the branch has a PR, it shows diff stats when files have changed, with the ship actions (commit, push, create PR) in a chevron menu beside them. With no changed files, it shows the next ship action that applies as a button. Once a PR exists, it shows the PR badge. Click the diff stats or the PR badge to open or close the Changes pane; the ship actions do not toggle it. The control is hidden while the right sidebar is closed.
## Diff Layouts [#diff-layouts]
* **Split view** - Side by side comparison
* **Unified view** - Inline changes
## Text Selection [#text-selection]
Select text directly in the diff and copy it from the context menu.
Double-click a diff line, or right-click and choose **Edit Here**, to open the raw editor at the matching location.
## Review Tab [#review-tab]
The changes sidebar has a dedicated **Review** tab for PR review comments: read, filter, and respond without leaving the app.
* Resolved comments are separated from open ones so you can focus on what still needs attention
* Stays in sync with GitHub, refreshing automatically after PR mutations
* PR check status appears in the changes sidebar alongside the review state
## Send PR Feedback to an Agent [#send-pr-feedback-to-an-agent]
To ask an agent to change specific PR lines, open **Pull requests** in the dashboard sidebar and select the PR's **Code** tab. Select the lines and send your feedback to a running agent or a new session. Posting the comment to GitHub is optional.
The agent receives the file, line range, and selected side of the diff. If the PR has no linked workspace, Superset creates a PR-checkout workspace for the new session. Inspect the revision and run the relevant tests before merging.
See [Pull Requests](/pull-requests#comment-straight-to-an-agent) for the controls or [send PR feedback to your coding agent](https://superset.sh/blog/send-pr-feedback-to-your-agent) for a walkthrough.
## Focus Mode [#focus-mode]
Review one file at a time with navigation controls.
Toggle focus mode in the diff toolbar (target icon) to:
* View a single file with minimal distraction
* Navigate between files with Prev/Next buttons
* Jump between sections (Against base, Commits, Staged, Unstaged) via the section dropdown
* See per-section file counts and position (e.g., "2/5 in Staged")
Click files in the sidebar to jump directly to them in focus mode.
---
# Editor & Files
Source: https://docs.superset.sh/editor
File explorer, built-in editor, and cross-workspace search
Each workspace has a file tree, a built-in editor, and search across workspaces.
## File Explorer [#file-explorer]
Browse and manage your workspace's files from the sidebar:
* Hierarchical tree with **git decorations** showing changed files
* Create, rename, delete, move, and copy files with context menus
* Rename inline, and drag files or folders to move them. Open editors, including ones with unsaved edits, follow the new path
* Toggle hidden files; refresh directory listings
* Search files with instant results
* **Material icon theme** for at-a-glance file types
## Built-in Editor [#built-in-editor]
Ways in:
* Click any file in the explorer
* From a diff: double-click a line or right-click → **Edit Here** to jump to that exact spot in the raw file (see [Diff Viewer](/diff-viewer))
The editor also opens files outside the workspace, including files reached through a symlink, and saves your edits to them. Creating, deleting, moving, and copying files stay inside the workspace.
For longer editing sessions, **⌘O** opens the workspace in your IDE ([IDE Integration](/use-with-ide)).
## Save and Review External Changes [#save-and-review-external-changes]
Use **Save** or **⌘S** to write your edits. If an agent or script changes the file while you have unsaved edits, the editor keeps your buffer and shows an external-change banner. Click **Compare** to review the disk and local versions side by side. Saving a conflicted file opens the same review.
* **Keep editing** preserves your unsaved edits without writing to disk.
* **Reload from disk** replaces your buffer with the disk version. It is unavailable if the file cannot be read.
* **Overwrite file** replaces the disk version with your edits.
The editor does not merge simultaneous edits.
## Auto Save [#auto-save]
Auto Save is off by default. Set it in **Settings → Files & Editor → Editing → Auto Save**:
* **After delay (3s)**: saves 3 seconds after you stop typing
* **On focus change**: saves when you leave the file's pane or the Superset window
* **On window change**: saves when the Superset window loses focus
Auto Save applies to files you edit by hand, including files in editors that are not active. It pauses for a file with a save conflict or a failed save until you resolve it.
## Markdown Links [#markdown-links]
Web links in Markdown previews follow **Settings → Browser → URL links**, and links to Superset Pages follow **Settings → Files & Editor → Page links**. By default, Shift-click opens a new tab, Cmd/Ctrl-click opens a split browser pane, and Cmd/Ctrl+Shift-click opens the system browser. A plain click keeps you editing.
**⌘C** in a rendered Markdown view copies the text as you see it, without backticks or fences. To copy the Markdown source, right-click the selection and choose **Copy as Markdown**.
## Cross-Workspace Search [#cross-workspace-search]
The search bar searches across all open workspaces.
## Image Viewer [#image-viewer]
Images open fitted to the pane, with standard viewer navigation:
* **Zoom**: pinch, or Ctrl/⌘ + scroll (anchored at the cursor, 25%–1600%)
* **Pan**: two-finger scroll, or click and drag
* **Keyboard**: **+**/**−** to zoom, arrow keys to pan, **0** to reset
* **Reset**: double-click, or click the zoom badge that appears while zoomed
## Tabs, Splits, and Panes [#tabs-splits-and-panes]
Drop a pane onto the tab strip to create a new tab; mix terminals, files, diffs, and browser panes in one layout. The browser pane keeps its state when you switch workspaces.
If one pane fails to render, it shows **This pane hit an error** with **Retry** and **Close pane**. The rest of the workspace keeps working. **Close pane** also removes the pane from the saved layout, so it does not come back after a reload.
---
# FAQ
Source: https://docs.superset.sh/faq
Frequently asked questions
## Platforms [#platforms]
**What platforms are supported?**
macOS (Apple Silicon and Intel) is the supported target. A Linux x64 AppImage ships with each release but is experimental and untested. Windows is planned with no date. The CLI also supports Linux x64 and arm64.
**Is Superset a terminal app?**
No. It's a desktop app with a full interface. Agents run in terminals, and next to them you get the [Changes pane](/diff-viewer), [pull requests](/pull-requests) with checks and review threads, an [in-app browser](/browser) with Design Mode, and a [file editor](/editor).
**Is there a mobile app or web dashboard?**
Yes, [Superset for iPhone and iPad](/install#iphone-and-ipad) is on the App Store. It needs iOS 26 or iPadOS 26 or later and Superset Pro. Push notifications are coming. Android is not available yet; join the [Android waitlist](https://superset.sh/mobile#android). There's no supported web dashboard today.
**Does it work with GitLab or self-hosted remotes?**
GitHub is fully supported via the `gh` CLI. Repos with other remotes work locally, but cross-machine project identity is currently tied to GitHub, so the same project can show up twice across devices.
**I was looking for the Superset hiring platform.**
That's a different company (joinsuperset.com). This Superset is a desktop app for running AI coding agents.
## Accounts and Billing [#accounts-and-billing]
**I signed in and everything is gone.**
GitHub and Google sign-ins create **separate accounts**, even with the same email. Sign out and back in with the provider you originally used. Also check which organization you're in: updates can land you in a different org, and its workspaces live separately.
**I paid for Pro but can't find the features.**
Pro features (remote access, automations, and more) live in the current v2 interface. If your app looks like the older UI, enable it under **Settings → Experimental**.
**Does Superset bill my model usage?**
No. Superset never proxies model calls. Agents use your own subscriptions and API keys, and your provider bills you directly.
**How do I cancel or get a refund?**
Email [support@superset.sh](mailto:support@superset.sh). Refunds are handled promptly.
**How do I delete my account, change my email, or move projects between orgs?**
These aren't self-serve yet; email [support@superset.sh](mailto:support@superset.sh).
## Workspaces and Git [#workspaces-and-git]
**Do I need a git repo?**
For projects, yes: every project must be a git repository, and its workspaces are git worktrees. For a fresh folder, run `git init && git add -A && git commit -m "init"` first. If you just want a scratch space without setting up a repo, create a [session](/workspaces#sessions) instead.
**Is each worktree a sandbox?**
No. A worktree gives each task its own working files and branch. Agents still run on the same machine, so they share processes, the network, and files outside the worktree. Worktrees also don't prevent merge conflicts.
**Same branch in multiple workspaces?**
No. One branch = one workspace. Create a new branch if needed.
**Where are workspaces stored on disk?**
`~/.superset/worktrees/`, as ordinary git worktrees (sessions live at `~/.superset/sessions/`). Deleting a workspace removes its worktree; Superset never deletes worktrees behind your back.
**I already have worktrees from another tool.**
Use the **Import** tab in the New Workspace modal to bring existing worktrees in. See [Workspaces](/workspaces).
**Why did my branch get a random name like `interesting-forest`?**
Branch names are generated from your prompt by a small model. When no usable model credential is available, naming falls back to random words; check your connected models in Settings.
**Does deleting a workspace touch my repo?**
It removes that worktree and runs your [lifecycle teardown scripts](/setup-teardown-scripts). Your root checkout and other branches are untouched.
## Agents [#agents]
**Which agents are supported?**
See [AI Agents](/agent-integration) for the full list. If an installed agent doesn't appear in launchers, check it's **Enabled** under **Settings → Agents**.
**Where do I set the model or reasoning effort an agent launches with?**
Under **Settings → Agents**, per agent. Preset-level tweaks don't override the agent's own launch settings.
**Why did Superset add hooks to my agent configs?**
Superset installs lifecycle hooks and command wrappers (in `~/.superset/bin`) so it can show agent status and send finished/waiting notifications. Removing them disables those features.
**Do sessions survive restarts?**
Yes. Terminals are backed by a background daemon, so running processes and scrollback survive app restarts and updates.
## Remote and Automations [#remote-and-automations]
**Why does my host show offline when the machine is up?**
"Online" means connected to the Superset relay, not "the process is running." Remote access via relay is **off by default**; enable it under **Settings → Remote Access** (or run `superset start --daemon` on CLI hosts). See [Remote Access](/remote-access). The local CLI works regardless of relay state.
**Can I open a remote host's ports on my Mac?**
Yes. The desktop app forwards detected ports for the selected remote workspace to your machine. If a local port is busy, choose **Use another port**. See [Remote Access](/remote-access#ports-on-a-remote-host) for requirements.
**Why did my automation run fail while my machine was asleep?**
Runs fail when the target device isn't relay-connected at fire time. Use **Retry all** once it's back. See [Troubleshooting](/troubleshooting#automation-run-failed-while-the-device-was-offline).
## Privacy [#privacy]
**Does my code leave my machine?**
Local workspace files live on their host machine. Enabling Remote Access sends workspace traffic through the relay; cloud workspaces run your code in the cloud, and publishing a Page uploads its content. Agents also send prompts and context to the model providers you configure.
**Does it modify git config?**
No. Superset uses standard git commands.
## CLI [#cli]
**`superset projects list` / `workspaces list` shows nothing, but I have projects.**
The CLI works against the v2 local-first model only. If you're on the legacy v1 interface, the CLI won't see those projects; enable v2 under **Settings → Experimental**.
## Getting Help [#getting-help]
* [Troubleshooting](/troubleshooting) for symptom-by-symptom fixes
* [Discord](https://discord.gg/cZeD9WYcV7) for the fastest answers
* Report issues: [github.com/superset-sh/superset/issues](https://github.com/superset-sh/superset/issues)
* Email: [support@superset.sh](mailto:support@superset.sh)
* All channels: [Community & Support](/community)
---
# Your First Parallel Session
Source: https://docs.superset.sh/first-workspace
Go from install to three agents working in parallel, then ship the best result
In about ten minutes you'll add a repo, put three agents to work on isolated branches, and merge the winner.
## 1. Add a Repository [#1-add-a-repository]
Add your repo from a local folder or clone a remote repository. In the clone dialog, search the GitHub repositories available to the selected host's GitHub CLI login, then pick one to fill in the URL and project name. You can also paste a Git URL manually. Check GitHub access with `gh auth status` on that host.
## 2. Create a Workspace with a Prompt [#2-create-a-workspace-with-a-prompt]
Press **⌘N** to create an isolated git worktree on its own branch.
In the prompt-first flow, describe the task, pick an agent, and create. The agent starts working on your prompt immediately.
A good first prompt if your repo needs dependencies or env files:
```text
Set up this project for Superset. Read docs.superset.sh/setup-teardown-scripts
and docs.superset.sh/ports, then author a .superset/config.json for this repo.
```
Future workspaces will then install dependencies and copy env files automatically via [project lifecycle scripts](/setup-teardown-scripts).
## 3. Fan Out to Three Agents [#3-fan-out-to-three-agents]
Press **⌘N** twice more and give each workspace the same prompt with a different agent, say Claude Code, Codex, and Amp:
```text
Find a small bug in this repo and fix it. Explain the bug and the fix
in your final message.
```
## 4. Watch Them Work [#4-watch-them-work]
* The sidebar shows each workspace's status at a glance
* Agents pause in the chat pane when they need input, tool approval, or plan review
* Enable notification sounds in Settings to hear when an agent finishes instead of babysitting terminals
## 5. Review in the Diff Viewer [#5-review-in-the-diff-viewer]
Open each workspace's **Changes** tab to see exactly what its agent did.
* Toggle split or unified view
* Use focus mode (target icon) to step through files one at a time
* Double-click a line or choose **Edit Here** to fix small things yourself
## 6. Ship the Winner [#6-ship-the-winner]
In the workspace with the best result: stage, commit, push, and **Create PR**, all from the diff viewer.
If a losing attempt had one good idea, select those lines in its diff and copy them over before you clean up.
## 7. Clean Up [#7-clean-up]
Delete the other workspaces. [Lifecycle teardown scripts](/setup-teardown-scripts) run automatically, and the worktrees are removed.
## You Now Know the Core Loop [#you-now-know-the-core-loop]
Try these workflows next:
The pattern you just ran, refined.
Feature + bugfix + PR review in parallel.
An agent addresses review comments while you move on.
Split large changes into independent slices.
Scheduled agent runs with Automations.
---
# Superset Documentation
Source: https://docs.superset.sh/
Run AI coding agents in parallel, each in its own isolated workspace
Superset gives every task its own isolated git worktree, so you can delegate to many agents at once and integrate the results through ordinary branches and PRs.
## Start Here [#start-here]
The 60-second version.
Requirements and first launch. Two minutes.
Three agents in parallel, ship the winner. Ten minutes.
The five concepts everything else builds on.
## What You Can Do [#what-you-can-do]
Same prompt, multiple agents, isolated branches. Merge the best diff.
A feature, a bugfix, and a PR review at once, without branch juggling.
Stage, commit, push, and open PRs from the built-in diff viewer.
Schedule agent sessions; wake up to a reviewable workspace.
Claude Code, Codex, Amp, Gemini, and more, or the built-in chat.
Reach workspaces hosted on another machine through the relay.
## Build On It [#build-on-it]
Drive projects, workspaces, and automations from the command line.
Programmatic access to everything the CLI can do.
Let agents drive Superset itself over MCP.
## Help [#help]
Stuck? Check [Troubleshooting](/troubleshooting) and the [FAQ](/faq), or [open an issue](https://github.com/superset-sh/superset/issues).
---
# Install
Source: https://docs.superset.sh/install
Requirements, download, and first launch
## Requirements [#requirements]
* **macOS**, Apple Silicon or Intel. A Linux x64 AppImage ships with each release but is experimental; Windows is not yet available.
* **Git** installed
* **GitHub CLI** for the PR workflows: optional, and Superset offers to install it during onboarding. Run `gh auth status` to check.
* At least one coding agent you already use (Claude Code, Codex, Amp, ...). Superset launches agents; it doesn't replace your subscriptions.
## Download [#download]
On an Intel Mac? [Download Superset-x64.dmg](https://github.com/superset-sh/superset/releases/latest/download/Superset-x64.dmg) instead.
## First Launch [#first-launch]
Onboarding checks your prerequisites with live detection: install or sign in to anything missing and the checklist updates on its own.
1. **GitHub CLI**: install it if needed, then sign in. You can run `gh auth login` right inside the app.
2. **Agents**: Superset detects Claude Code and Codex automatically. Everything else is configurable later under **Settings → Agents**.
3. **Add a project**: point Superset at a local folder or a Git URL.
Using Bedrock, Vertex, OpenRouter, or another provider? See [Providers](/providers).
Paid organizations also get a **Get the best out of Pro** sidebar checklist for Remote Access, mobile, and automations. Reopen it from **Help → Get the best out of Pro** if you dismissed it.
## iPhone and iPad [#iphone-and-ipad]
[Download Superset for iPhone and iPad](https://apps.apple.com/app/id6788926383) to continue your agents away from your desk. You need **iOS 26 or iPadOS 26 or later** and **Superset Pro**. Enable **Remote Access** to reach agents on your computer. Cloud workspaces are in early access. If they are enabled for your account, you can use them without a connected computer.
Follow [mobile setup](/remote-access#connect-from-an-iphone-or-ipad) to connect your computer. Android is not available yet; join the [Android waitlist](https://superset.sh/mobile#android).
## Staying Updated [#staying-updated]
Superset checks for updates automatically. New releases ship daily; the [changelog](https://superset.sh/changelog) rounds up each week's highlights.
## Next [#next]
You're two minutes in; the next ten are the fun part: [Your First Parallel Session](/first-workspace).
---
# Keyboard Shortcuts
Source: https://docs.superset.sh/keyboard-shortcuts
Customize hotkeys for common actions
## Workspace [#workspace]
| Action | Shortcut |
| ----------------------- | -------- |
| New Workspace | ⌘N |
| Quick Create Workspace | ⌘⇧N |
| Add Project from Folder | ⌘⇧O |
| Switch to Workspace 1-9 | ⌘1-9 |
| Previous Workspace | ⌘⌥↑ |
| Next Workspace | ⌘⌥↓ |
| Open in Editor | ⌘O |
| Copy Path | ⌘⇧C |
Previous and Next Workspace follow the sidebar order (Pinned, then Sessions, then Projects) and wrap around at the ends.
## Layout [#layout]
| Action | Shortcut |
| ------------------------- | -------- |
| Toggle Changes Tab | ⌘L |
| Open Diff Viewer | ⌘⇧L |
| Toggle Workspaces Sidebar | ⌘B |
| Split Right | ⌘D |
| Split Down | ⌘⇧D |
| Split Along Longer Side | ⌘E |
| Close Pane | ⌘W |
| Quick Open File | ⌘P |
| Focus Task Search | ⌘⇧F |
| New Browser Tab | ⌘⇧B |
**Toggle Workspaces Sidebar** collapses the sidebar to a narrow rail and expands it again.
## Chat [#chat]
| Action | Shortcut |
| ---------------- | -------- |
| Find in Chat | ⌘F |
| Focus Chat Input | ⌘J |
## Terminal [#terminal]
| Action | Shortcut |
| ------------------------ | -------- |
| New Tab | ⌘T |
| Close Tab | ⌘⇧W |
| Close Terminal | ⌘W |
| Clear Terminal | ⌘K |
| Find in Terminal | ⌘F |
| Scroll to Bottom | ⌘⇧↓ |
| Previous Tab | ⌘⌥← |
| Next Tab | ⌘⌥→ |
| Open Terminal Script 1-9 | ⌃1-9 |
## Window [#window]
| Action | Shortcut |
| ----------------------- | -------- |
| Close Window | ⌘⇧Q |
| Show Keyboard Shortcuts | ⌘/ |
| Open Command Palette | ⌘⇧K |
| Check Resources | ⌘⇧U |
## Customize [#customize]
Open Settings → Keyboard Shortcuts to rebind or disable any hotkey. **Reset** next to a shortcut restores its default.
---
# Superset MCP Server
Source: https://docs.superset.sh/mcp-server
Connect AI agents directly to Superset via MCP
The Superset MCP server lives at `https://api.superset.sh/mcp`. The versioned URL (`/api/v2/agent/mcp`) keeps working for existing configurations; the legacy v1 server (`/api/agent/mcp`) has been removed and returns `410 Gone`.
## Overview [#overview]
Superset provides an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that lets AI agents interact with your tasks, workspaces, and devices programmatically.
## Capabilities [#capabilities]
| Category | Operations |
| ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Tasks** | list, get (by id or slug), create, update, delete, list statuses |
| **Workspaces** | list (per host), create on a host, update, delete |
| **Agents** | list agents on a host, launch an agent session in a workspace |
| **Terminals** | create in a workspace, list, send input, read screen, close |
| **Pages** | list, get, list versions, pull content, publish, read storage; list/reply/resolve page comments |
| **Automations** | list, get metadata, get/set prompt body, create, update metadata, pause, resume, run on demand, list runs, delete |
| **Projects** | list projects on a host |
| **Hosts** | list hosts (registered machines) you have access to |
| **Organization** | list members |
## Setup [#setup]
### CLI Options [#cli-options]
```bash title="terminal"
claude mcp add superset --transport http https://api.superset.sh/mcp
```
```bash title="terminal"
codex mcp add superset --url https://api.superset.sh/mcp
```
```bash title="terminal"
gemini mcp add --transport http superset https://api.superset.sh/mcp
```
Run `opencode mcp add` and follow the interactive prompts:
```ansi title="terminal"
opencode mcp add
[2m┌[0m Add MCP server
[2m│[0m
[2m◇[0m Location
[2m│[0m [36mCurrent project[0m
[2m│[0m
[2m◇[0m Enter MCP server name
[2m│[0m [36msuperset[0m
[2m│[0m
[2m◇[0m Select MCP server type
[2m│[0m [36mRemote[0m
[2m│[0m
[2m◇[0m Enter MCP server URL
[2m│[0m [36mhttps://api.superset.sh/mcp[0m
[2m│[0m
[2m◇[0m Does this server require OAuth authentication?
[2m│[0m [36mYes[0m
[2m│[0m
[2m◇[0m Do you have a pre-registered client ID?
[2m│[0m [36mNo[0m
[2m│[0m
[2m└[0m [32mMCP server added successfully[0m
```
```bash title="terminal"
amp mcp add --workspace superset https://api.superset.sh/mcp
```
Add to your `.vibe/config.toml`:
```toml title=".vibe/config.toml"
[[mcp_servers]]
name = "superset"
transport = "http"
url = "https://api.superset.sh/mcp"
```
Run `kimi`, enter `/mcp-config`, and add an HTTP server named `superset` with this URL:
```text title="Kimi Code"
https://api.superset.sh/mcp
```
Then enter `/mcp-config login superset` to authorize it.
Run `grok`, enter `/mcps`, and add an HTTP server named `superset` with this URL:
```text title="Grok"
https://api.superset.sh/mcp
```
### Manual Configuration [#manual-configuration]
Alternatively, you can manually configure the MCP server for each client:
Add a `.mcp.json` to your project root. Claude Code auto-discovers this file and handles OAuth authentication.
```json title=".mcp.json"
{
"mcpServers": {
"superset": {
"type": "http",
"url": "https://api.superset.sh/mcp"
}
}
}
```
Add to your `claude_desktop_config.json`:
```json title="claude_desktop_config.json"
{
"mcpServers": {
"superset": {
"type": "http",
"url": "https://api.superset.sh/mcp"
}
}
}
```
Add to `.cursor/mcp.json` in your project root:
```json title=".cursor/mcp.json"
{
"mcpServers": {
"superset": {
"url": "https://api.superset.sh/mcp"
}
}
}
```
Add to your `~/.codex/config.toml`:
```toml title="config.toml"
[mcp_servers.superset]
url = "https://api.superset.sh/mcp"
```
Add to your `.gemini/settings.json`:
```json title="settings.json"
{
"mcpServers": {
"superset": {
"httpUrl": "https://api.superset.sh/mcp"
}
}
}
```
Add to your `opencode.json`:
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"superset": {
"type": "remote",
"url": "https://api.superset.sh/mcp"
}
}
}
```
Add to `.amp/settings.json` in your project root:
```json title=".amp/settings.json"
{
"amp.mcpServers": {
"superset": {
"url": "https://api.superset.sh/mcp"
}
}
}
```
Add to `.vibe/config.toml` in your project root (or `~/.vibe/config.toml` for global config):
```toml title=".vibe/config.toml"
[[mcp_servers]]
name = "superset"
transport = "http"
url = "https://api.superset.sh/mcp"
```
Add to `.kimi-code/mcp.json` in your project root (or `~/.kimi-code/mcp.json` for global config):
```json title=".kimi-code/mcp.json"
{
"mcpServers": {
"superset": {
"url": "https://api.superset.sh/mcp"
}
}
}
```
Then enter `/mcp-config login superset` in Kimi Code to authorize it.
Add to your `~/.grok/config.toml`:
```toml title="~/.grok/config.toml"
[mcp_servers.superset]
url = "https://api.superset.sh/mcp"
```
## Authentication [#authentication]
The MCP server uses OAuth 2.1. When you first connect, you'll be prompted to authorize the connection in your browser. The token is scoped to your active organization.
### API Key Authentication [#api-key-authentication]
For headless environments, CI/CD pipelines, or scripts where browser-based OAuth isn't practical, you can authenticate with an API key instead.
**Generating an API key:**
1. Open the Superset desktop app
2. Go to **Settings > API Keys**
3. Click **Create API Key**
4. Copy the key (it starts with `sk_live_`). You won't be able to see it again.
**Using the API key:**
Pass the API key as a Bearer token in the `Authorization` header:
```
Authorization: Bearer sk_live_your_api_key_here
```
MCP clients that support custom headers can use this directly. For Claude Code, set the header in your `.mcp.json`:
```json
{
"mcpServers": {
"superset": {
"type": "http",
"url": "https://api.superset.sh/mcp",
"headers": {
"Authorization": "Bearer sk_live_your_api_key_here"
}
}
}
}
```
API keys grant full access to your organization. Keep them secret and never commit them to version control. Use environment variables or secrets managers for CI/CD.
**When to use which method:**
| Method | Best for |
| --------- | ---------------------------------------------------- |
| OAuth 2.1 | Interactive use: Claude Desktop, Claude Code, Cursor |
| API Key | Headless/CI: scripts, automation, pipelines |
## Available Tools [#available-tools]
### Tasks [#tasks]
| Tool | Description |
| --------------------- | ---------------------------------------------------------------------------------- |
| `tasks_list` | List tasks with optional filters (status, priority, assignee, free-text search) |
| `tasks_get` | Get one task by UUID or slug |
| `tasks_create` | Create a task in the active organization |
| `tasks_update` | Update fields on an existing task |
| `tasks_delete` | Soft-delete a task by UUID |
| `tasks_statuses_list` | List the organization's task statuses (for `tasks_create`/`tasks_update` statusId) |
### Workspaces [#workspaces]
| Tool | Description |
| ------------------- | ---------------------------------------------------------------------------------------------------- |
| `workspaces_list` | List workspaces on a host (get the hostId from `hosts_list`) |
| `workspaces_create` | Create a workspace on a host, optionally launching agents with per-launch model and effort overrides |
| `workspaces_update` | Update fields on a workspace on its host |
| `workspaces_delete` | Delete a workspace by UUID on its host |
### Agents [#agents]
| Tool | Description |
| --------------- | ------------------------------------------------------------------------------------ |
| `agents_list` | List agents configured on a host |
| `agents_create` | Create (launch) an agent session with optional per-launch model and effort overrides |
### Terminals [#terminals]
| Tool | Description |
| ------------------ | ------------------------------------------------------------------------------ |
| `terminals_create` | Create a terminal session in a workspace, optionally running a command |
| `terminals_list` | List terminal sessions in a workspace |
| `terminals_send` | Write text into a running terminal (presses Enter by default) |
| `terminals_read` | Read the terminal screen as plain text (current screen plus recent scrollback) |
| `terminals_close` | Close a terminal session and kill its process |
### Pages [#pages]
[Superset Pages](/pages) lets agents present designs and reports to your team and act on feedback left directly on the page. The MCP publish tool accepts a self-contained HTML document and returns a shareable URL. Every publish creates a new version; nothing is overwritten.
| Tool | Description |
| ------------------------ | --------------------------------------------------------------------------------- |
| `pages_list` | Search and paginate pages, optionally scoped to one workspace |
| `pages_get` | Get one page's metadata by id or slug (title, visibility, URL, served version) |
| `pages_versions` | List a page's version history, newest first |
| `pages_pull` | Get a download URL for a page's HTML, plus that version's metadata |
| `pages_storage` | Read what viewers stored on a page, by key, scope or per person |
| `pages_storage_set` | Write a value under a key in a page's storage, as you |
| `pages_storage_remove` | Remove a value under a key in a page's storage, as you |
| `pages_publish` | Publish an HTML document (passed inline, not as a path) and get its shareable URL |
| `pages_comments_list` | List comment threads on a page, with replies and resolved state |
| `pages_comments_reply` | Post a reply into a comment thread |
| `pages_comments_resolve` | Mark a comment thread resolved, or reopen it |
`pages_list` returns `{ items, nextCursor }`, ordered newest-created first.
Pass `search` to match title, slug, or description, `limit` for 1–200 rows
(default 50), and the returned `nextCursor` as `cursor` to continue. Keep
fetching until `nextCursor` is null. `scope` accepts `all` (default), `team`
for shared pages, or `mine` for your private pages.
`pages_publish` accepts `visibility: "just_me"`, `"org"` (the default for new
pages), or `"everyone"` for anonymous read-only access. Pass `workspaceId` and
`entryPath` together to link the page to a workspace. Both are optional;
outside a workspace, save the returned `id` and pass it as `pageId` when
publishing updates. Otherwise each publish creates a separate page.
### Automations [#automations]
| Tool | Description |
| ------------------------ | ------------------------------------------------------------------------------------------------ |
| `automations_list` | List automations the calling user owns |
| `automations_get` | Get one automation's metadata (prompt body omitted) |
| `automations_get_prompt` | Fetch the full markdown prompt for one automation |
| `automations_create` | Schedule a recurring agent run with an RFC 5545 RRULE |
| `automations_update` | Update metadata (name, schedule, agent, host); use `automations_set_prompt` to change the prompt |
| `automations_set_prompt` | Replace the full markdown prompt body |
| `automations_pause` | Pause an automation (schedule stops firing) |
| `automations_resume` | Resume a paused automation |
| `automations_run` | Dispatch an automation immediately, outside its schedule |
| `automations_logs` | List recent runs for an automation |
| `automations_delete` | Delete an automation |
### Projects [#projects]
| Tool | Description |
| --------------- | ------------------------------------------------------------------------------ |
| `projects_list` | List projects (checked-out repos) on a host (get the hostId from `hosts_list`) |
### Hosts [#hosts]
| Tool | Description |
| ------------ | ------------------------------------------------------- |
| `hosts_list` | List the hosts (registered machines) you have access to |
### Organization [#organization]
| Tool | Description |
| --------------------------- | --------------------------------------- |
| `organization_members_list` | List members of the active organization |
## Chat Integration [#chat-integration]
In the built-in chat panel, use the `/mcp` slash command to see your workspace's configured MCP servers: their names, transport type (local/remote), and current state (enabled/disabled/invalid). This reads from your workspace MCP config (`.mastracode/mcp.json`, `.amp/settings.json`, or `.mcp.json`).
## Example Usage [#example-usage]
Once connected, you can ask your AI agent to:
* "Create a task for fixing the login bug"
* "List all my assigned tasks"
* "Create a workspace for the auth feature on my MacBook"
* "Schedule a daily automation that triages new Linear issues at 9 a.m."
* "Pause the nightly cleanup automation"
* "Show me the last 10 runs of my Linear triage automation"
* "Answer the two threads handed to me on the launch-plan page"
---
# Multiple Windows
Source: https://docs.superset.sh/multiple-windows
Keep several workspaces or organizations on screen at once
Open more than one Superset window to watch several workspaces at the same time, or to put two organizations side by side.
## Open a New Window [#open-a-new-window]
* **File → New Window** (**Ctrl+Alt+N** on Linux)
* **New window** in the organization menu
* **New window** in the command palette (**⌘⇧K**)
* On Linux, **New Window** in the launcher or dock menu for Superset. An AppImage shows it only when it is integrated with your desktop.
A new window uses the same organization as the window you opened it from, and opens on the page you visited last in any window.
## Switch and Close Windows [#switch-and-close-windows]
Each window's title is the name of its organization. On macOS, the **Window** menu lists the open windows by that name.
To close the focused window, use **Window → Close** (**⌘⇧Q**) or **File → Close Window**.
## What Each Window Has [#what-each-window-has]
Each window has its own:
* **Page and workspace** - each window navigates on its own
* **Organization** - switching organization in one window doesn't change any other window
* **Active tab and focused pane**
* **Size, position, and zoom level**
All windows share:
* **Settings**, including theme and keyboard shortcuts
* **Workspaces, terminals, and agents** - they run on the host, so closing a window doesn't stop them
* **Sidebar projects and sections, and each workspace's tabs and panes**, for windows on the same organization
The organization you switch to last is also the default for a window that opens without one, such as the window macOS opens when you click the Dock icon with no windows open.
Clicking a desktop notification brings the window you used last to the front, and every open window navigates to that notification's workspace.
## Same Workspace in Two Windows [#same-workspace-in-two-windows]
You can open one workspace in two windows. Its tabs and panes stay in sync: a tab you open, close, or split in one window appears in the other. The selection stays local, so switching tabs or focusing a pane in one window doesn't move the other. If the other window closes your active tab, your window moves to the nearest remaining tab.
## Restore on Relaunch [#restore-on-relaunch]
When you quit, Superset saves every open window with its position, size, zoom level, and organization. On the next launch, each window opens again on its organization. Restored windows all open on the same page, the one you visited last before you quit, not on the pages they each showed.
Closing a window without quitting removes it from the saved set. On macOS, closing the last window keeps Superset running, and the next launch opens one window. On Linux, closing the last window quits Superset, and that window comes back on the next launch.
---
# Agent Orchestration
Source: https://docs.superset.sh/orchestration
Turn the agent you're already talking to into a coordinator of other agents
the fan-out is mechanical: many similar slices, clear acceptance criteria, and results a coordinator can verify against tests. For work you want to review step by step, use the [parallel workstreams recipe](/recipes/parallel-workstreams).
The `superset:orchestrate` skill lets one agent coordinate workers in separate workspaces through the Superset CLI.
The coordinator can be Claude Code or Codex; the workers can be any mix of agents Superset runs.
## Install [#install]
The desktop app includes this skill. For standalone agents, see [Skills installation](/skills#installation).
## What to Ask For [#what-to-ask-for]
* **Fan out a refactor or migration** across several worktrees at once ("split this migration into independent slices and run a worker on each")
* **Hand a branch from one agent to another** with its full terminal context
* **Dispatch to a remote host** and monitor until every worker reports done or blocked
## How It Works [#how-it-works]
Under the hood the coordinator uses the [Superset CLI](/cli/getting-started):
* `superset workspaces create` for an isolated branch per worker
* `superset agents create` to launch a worker with a bounded prompt
* `superset terminals read` / `send` to monitor progress and deliver follow-ups or dependency results
Workers finish by reporting a structured completion or blocked message, which the coordinator verifies before integrating. You review the results the same way as always: one branch and PR per worker.
Related: [Automations](/automations) for scheduled dispatch, and the [MCP server](/mcp-server) for agents that drive Superset over MCP instead of the CLI.
---
# What is Superset?
Source: https://docs.superset.sh/overview
The 60-second version
Superset is a source-available platform for running AI coding agents in parallel, licensed under the Elastic License 2.0. It's available as a desktop IDE, an [iPhone and iPad app](/install#iphone-and-ipad), a command-line interface, and an MCP server.
The core move: every task gets its own **workspace**, an isolated git worktree on its own branch. Agents work in workspaces, so three agents (or ten) can run at once without overwriting each other's files or your `main`. If two agents edit the same lines, you resolve that at merge time, like any branch. You review each result in a built-in diff viewer and integrate through ordinary branches and PRs.
## Who It's For [#who-its-for]
* You use Claude Code, Codex, Amp, or another CLI agent and keep hitting the one-branch-at-a-time wall
* You're juggling a feature, a bugfix, and a PR review, and every switch means stash-checkout-rebuild
* You want scheduled agents doing maintenance while you sleep
Superset is local-first: it works offline and syncs when connected. Your code never leaves your machine unless you say so.
## What Makes It Different [#what-makes-it-different]
* **Worktree isolation, handled for you**: no manual `git worktree` bookkeeping, no stashing, no checkout whiplash
* **Any agent**: Claude Code, Codex, Amp, Gemini, OpenCode, Cursor Agent, and [more](/agent-integration), or the built-in chat
* **The whole loop in one place**: terminals, diffs, commits, PRs, ports, and dev servers per workspace
* **Automations**: agent sessions on a schedule, with a real workspace as the output
* **[Pages](/pages)**: share agent-created designs and reports with your team, and have an agent act on comments directly
## Next Steps [#next-steps]
Requirements and first launch. Two minutes.
The ten-minute tutorial: three agents in parallel, ship the winner.
The five concepts everything else builds on.
Named workflows: race agents, fan out a refactor, wake up to an audit.
---
# Pages
Source: https://docs.superset.sh/pages
Share agent-created designs and reports with your team, and turn comments into updates
Superset Pages gives your agents a way to present designs, reports, and analysis to your team. Teammates comment directly on the page, and an agent picks up the feedback, makes changes, and publishes an updated version.
## The Design Loop [#the-design-loop]
1. **Create.** Ask an agent to build a design doc, report, or proposal and publish it as a Page.
2. **Share.** Send the page's link to your team.
3. **Comment.** Teammates pin feedback to the part of the page they want to discuss.
4. **Iterate.** The agent watching the page receives new comments, updates the source, republishes, and replies to the threads it addressed.
## Create Your First Page [#create-your-first-page]
Open the **Pages** tab and click **Create with AI**. Superset starts an agent session that asks what you want to create, helps build the page, and publishes a link for your team. The help icon beside the **Pages** title opens this guide.
You can also ask an agent in an existing Superset workspace:
```text
Create a design doc for our onboarding flow and publish it as a Superset Page
so the team can review it and leave comments.
```
Or start with work the agent has already done:
```text
Turn your findings into a report and publish it as a Page for the team.
```
The Superset plugin includes a [Pages skill](/skills) that guides agents through building, publishing, and updating pages. A page can be a self-contained HTML file or a directory with an `index.html` and supporting assets. When an agent finishes work that someone else will read, such as a PR walkthrough, a comparison, or a report, the agent offers to publish it as a page and waits for your answer.
To publish from the CLI, run:
```bash
superset pages publish design.html --title "Onboarding design" --label "First draft"
```
The command returns a shareable URL. Publishing does not open the page or move the desktop to another workspace. See the [CLI reference](/cli/cli-reference#pages) for options.
## Find Workspace Pages [#find-workspace-pages]
Open the Pages menu beside **Run**, above **Files / Changes / Review**. It lists pages published from the workspace, your pinned pages, and **All pages**. Choose **New page**, enter a request, and pick an agent to create it. A blue **New** indicator marks a fresh publish until you close the menu.
The main Pages list shows linked workspace names so you can see where a page came from. Clicking a page there does not switch workspaces.
Web links inside a workspace Page follow **Settings → Browser → URL links**, and links to other Pages follow **Settings → Files & Editor → Page links**. Both open outside the Page pane. If no plain-click action is set, a plain click opens a pane. Links in standalone Pages in the desktop app open in the system browser.
## Share a Page [#share-a-page]
Use **Share** to choose who can open the page:
* **Only you**: a private draft.
* **Anyone in your organization**: members of your organization. This is the default for new pages.
* **Anyone with the link**: anyone can read it without signing in. Public access does not grant comment or edit permissions, or access to the rest of the version history.
When a page is public, the **Share** button shows a globe icon.
**Shared version** controls whether the link follows the latest publish or stays on a specific version. Anonymous readers can access only that shared version.
For a new page, the CLI accepts `--visibility just_me`, `--visibility org`, or `--visibility everyone`. Republishing preserves visibility unless you explicitly change it. Shared links include the page thumbnail in link previews, including [Slack unfurls](/use-with-slack).
Anyone viewing a public page can use **Report** to flag it to the Superset team with a reason, optional details, and an optional email. The Superset team reviews reports and can take a page down, which stops its link working.
## Send Feedback Directly to an Agent [#send-feedback-directly-to-an-agent]
Open the page, enter comment mode, and click an element to pin feedback to it. The agent receives the comment along with context identifying the element, so teammates can point to exactly what they want changed.
On iPhone, the comments sheet keeps replies inline. Tap **Reply** to target a thread, or clear the reply target to leave a page-level comment. Resolved threads appear under the resolved-comments disclosure.
Publishing from an agent's Superset terminal attempts to register that session for new comments. Check the command's watch status; a failed registration does not fail the publish. In the workspace page pane, open the **Listening agents** menu in the page header:
* It lists every agent watching the page, including agents on other devices. Click a row to open that agent's terminal.
* The page's creator can click the **X** on a row to stop that agent watching.
* The page's creator can use **Add listening agent** to assign a running agent in the workspace, or start a new agent session and assign it.
Keep the host and agent session running for automatic feedback delivery. If the menu says **No listening agents**, the page's creator can add one. New comments are delivered when the agent is available to handle them.
The agent can change the page, answer a question in the thread, or leave feedback open when it needs more discussion. When it makes a change, it republishes the page, replies with what changed, and resolves the feedback it addressed.
## Keep Iterating on the Same Page [#keep-iterating-on-the-same-page]
Publish the same source path from the same workspace to create a new version of the existing page. Your team keeps using the same link, and earlier versions remain in version history.
```bash
superset pages publish design.html --label "Simplified onboarding after team review"
```
If the source moved or you're publishing from another workspace, pass the existing page ID explicitly:
```bash
superset pages publish design.html --page --label "Updated onboarding flow"
```
Publishing from outside a workspace works too, but there's no path for a later publish to resolve against: every run creates a separate page unless you pass `--page`. The publish tells you when that happened and prints the command to reuse.
Use the page title menu to preview earlier versions read-only, rename the page, or refresh it. You can also inspect version history or retrieve a published version:
```bash
superset pages versions
superset pages pull --version 1 > original-design.html
```
## Read What Viewers Stored [#read-what-viewers-stored]
A page can keep values under each key with `window.superset.storage`. Each call takes an optional `{ scope }`:
| Scope | What it holds |
| ---------------- | --------------------------------------------------------------------------------------------- |
| `slot` (default) | One value per person. Everyone can read all of them. Good for votes and RSVPs. |
| `private` | One value per person. Only that person can read it. Good for drafts and settings. |
| `shared` | One value per key for the whole page. Any member of the page's organization can overwrite it. |
To find keys, `list` returns the keys in one scope that start with a prefix, sorted by key:
```js
const keys = await window.superset.storage.list("pipeline:", { scope: "shared" });
// [{ key: "pipeline:1", records: 1, updatedAt: "2026-10-12T09:30:00.000Z" }]
```
A page can store up to 20 MiB in total. You can read what viewers stored:
```bash
superset pages storage
superset pages storage --key votes
```
The first command lists each key and how many people stored a value under it. With `--key`, it prints each person's value and when they last changed it. With `--scope private`, you see only your own value. Add `--scope` to pick `slot`, `private` or `shared`. Add `--json` for the raw records. On a `just_me` page only the creator can read storage. On an `org` or `everyone` page, members of the page's organization can read it, even when the page is public.
You can also write storage as yourself, for example to refresh data from an automation without a new publish. Both `--set` and `--remove` need `--key`, and `--set` takes a JSON value:
```bash
superset pages storage --key data --scope shared --set '{"deals": 42}'
superset pages storage --key data --scope shared --remove
```
Only signed-in members of the page's organization can write storage, and on a `just_me` page only the creator can. Anyone who can write can overwrite or remove a `shared` value. Someone outside the organization who opens an `everyone` page can read the page, but not its storage. Reading storage and writing it both need membership in the page's organization.
## Show Live Data from Your Tools [#show-live-data-from-your-tools]
A page can call a tool from a plugin, such as a read-only database query or a web search, and show the result. The call runs as the person viewing the page, through their own connected account. The page itself makes no network request; Superset makes the call.
```js
const tools = window.superset?.tools;
if (await tools?.ready) {
const result = await tools.call("neon-readonly", "run_sql", {
sql: "select count(*) from organizations",
});
}
```
* **Consent.** The first time a page calls a plugin, the viewer sees a dialog and chooses whether to allow it. The choice applies to that page and that plugin, for every tool of the plugin, including tools that change data, and for future versions of the page. The viewer may also be asked to install the plugin, connect an account, or choose which account to use.
* **Trust.** A page can send what it reads to other websites, for example in an image URL. Only allow pages you trust.
* **Their data.** Each viewer sees results from their own account, so two people can see different numbers. A signed-out viewer cannot use tools.
* **Read-only databases.** Use the `neon-readonly` plugin for dashboards. Read-only is not enforced yet for an account connected with write access, so do not rely on it for safety. The `exa` plugin gives a page Exa's search tools.
* **Errors.** A call fails with a code in `error.code`: `needs_install`, `needs_connection`, `denied`, `unavailable_signed_out`, `rate_limited`, `invalid`, `tool_error` or `unavailable`. A tool that fails returns `tool_error` with the tool's message. A call times out after 60 seconds. Time the viewer spends in the dialog does not count.
* **Not on mobile.** Tools work in the desktop app and on the web, not in the mobile app.
Removing a page's tool access from the app is not available yet.
Agents connecting through MCP can publish, retrieve versions, read a page's storage, and reply to or resolve comments with the [Pages tools](/mcp-server#pages).
---
# Port Management
Source: https://docs.superset.sh/ports
View and manage active ports per workspace
## Overview [#overview]
Superset does not assign per-workspace port ranges. It discovers listening ports from processes running in each workspace and lets you manage them from the UI.
## Features [#features]
* **View active ports** - See which processes are using which ports
* **Kill processes** - Stop a process by clicking its port
* **Workspace grouping** - Ports are grouped by the workspace that owns the process
* **Terminal focus** - Select a port to jump back to the terminal that owns it
* **Browser actions** - Open local web servers in the in-app browser or externally from the port action
## Port Labels [#port-labels]
Label detected ports by creating `.superset/ports.json` in your repository:
```json
{
"ports": [
{ "port": 3000, "label": "Frontend Dev Server" },
{ "port": 8080, "label": "API Server" },
{ "port": 5432, "label": "PostgreSQL" }
]
}
```
**Fields:**
* `port` - Port number (1-65535)
* `label` - Display text shown in tooltip
**Behavior:**
* Labels apply only to ports detected as listening
* Ports without a matching label still appear
* Each workspace reads labels from its own worktree's file
* Changes are detected automatically
* Ports can be opened at `localhost:PORT` from the browser action (remote workspace ports are [forwarded to your machine](#remote-access) first)
**Error Handling:**
If `ports.json` is malformed, detected ports still appear without labels until you fix the file.
**Tips:**
* Commit `.superset/ports.json` to share port labels with your team
* **Pro tip:** If you want deterministic per-workspace port ranges, implement it in project lifecycle setup/teardown scripts by reserving a range in a shared file (for example `~/.superset/port-allocations.json`) during setup and releasing it during teardown. See this repo's examples: [`.superset/setup.sh`](https://github.com/superset-sh/superset/blob/main/.superset/setup.sh) and [`.superset/teardown.sh`](https://github.com/superset-sh/superset/blob/main/.superset/teardown.sh).
## Remote Access [#remote-access]
The desktop app forwards detected ports from the selected remote workspace to your machine. If a local port is busy, choose **Use another port** from its row. See [remote port forwarding](/remote-access#ports-on-a-remote-host) for requirements and behavior, or forward a port yourself below.
### Forward a port yourself [#forward-a-port-yourself]
**SSH**: forward the port, then open `http://localhost:3000` locally:
```bash
ssh -N -L 3000:localhost:3000 user@remote-host
```
**[Tailscale](https://tailscale.com)**: on the host, expose the port to your tailnet and open the URL it prints:
```bash
tailscale serve 3000
```
Both work for servers that only listen on loopback. If the server binds `0.0.0.0`, you can skip the tunnel and hit the host's Tailscale name directly (`http://remote-host:3000`).
## Discovery and Updates [#discovery-and-updates]
The port list updates as workspace processes start and stop listening.
---
# Use with OpenRouter, Bedrock, Vertex, or Vercel
Source: https://docs.superset.sh/providers
Connect Superset to Vercel AI Gateway, OpenRouter, AWS Bedrock, Google Vertex, and other providers
If you're using Superset in the terminal - any CLI agent (Claude Code, Codex, Curser Agents, etc.)
automatically just work. That's the beauty of us being terminal first.
For the Chat UI, we have a flow for users to get started.
## Chat UI [#chat-ui]
1. Open the model picker at the bottom of the chat
2. Click the **key icon** next to **Anthropic**
3. Select **Use API key**
4. Enter the environment variables for your provider (one per line, `VAR_NAME=value` format)
5. Click **Save settings**
See the provider sections below for the specific variables to use.
## Terminal [#terminal]
Set environment variables in your shell profile or per workspace via **Settings > Env**.
For Anthropic-compatible providers (OpenRouter, Vercel AI Gateway), set `ANTHROPIC_API_KEY` to an empty string to prevent direct Anthropic authentication.
***
## Vercel AI Gateway [#vercel-ai-gateway]
Route requests through the [Vercel AI Gateway](https://vercel.com/docs/ai-gateway).
```bash
ANTHROPIC_BASE_URL=https://ai-gateway.vercel.sh
ANTHROPIC_AUTH_TOKEN=your-vercel-ai-gateway-api-key
ANTHROPIC_API_KEY=
```
## OpenRouter [#openrouter]
[OpenRouter](https://openrouter.ai) provides access to many models through a single API.
```bash
ANTHROPIC_BASE_URL=https://openrouter.ai/api
ANTHROPIC_AUTH_TOKEN=your-openrouter-api-key
ANTHROPIC_API_KEY=
```
## AWS Bedrock [#aws-bedrock]
Use Claude models through your AWS account with [Amazon Bedrock](https://aws.amazon.com/bedrock/).
Ensure your AWS credentials are configured via `aws configure`, environment variables, or SSO profile.
```bash
CLAUDE_CODE_USE_BEDROCK=1
AWS_REGION=us-east-1
```
Optionally override the region for the small/fast model (Haiku):
```bash
ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION=us-west-2
```
Pin specific model versions to prevent breakage when new models are released:
```bash
ANTHROPIC_DEFAULT_OPUS_MODEL=us.anthropic.claude-opus-4-6-v1
ANTHROPIC_DEFAULT_SONNET_MODEL=us.anthropic.claude-sonnet-4-6
ANTHROPIC_DEFAULT_HAIKU_MODEL=us.anthropic.claude-haiku-4-5-20251001-v1:0
```
For full setup details including IAM configuration, see the [Claude Code on Amazon Bedrock docs](https://code.claude.com/docs/en/amazon-bedrock).
## Google Vertex AI [#google-vertex-ai]
Run Claude models on [Google Cloud Vertex AI](https://cloud.google.com/vertex-ai).
Authenticate with `gcloud auth application-default login`, then set:
```bash
CLAUDE_CODE_USE_VERTEX=1
CLOUD_ML_REGION=global
ANTHROPIC_VERTEX_PROJECT_ID=your-project-id
```
Pin specific model versions to prevent breakage when new models are released:
```bash
ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-6
ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6
ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5@20251001
```
For full setup details including IAM configuration, see the [Claude Code on Google Vertex AI docs](https://code.claude.com/docs/en/google-vertex-ai).
## Microsoft Foundry (Azure) [#microsoft-foundry-azure]
Use Claude models via [Microsoft Foundry](https://ai.azure.com).
Authenticate with an API key or Microsoft Entra ID (`az login`), then set:
```bash
CLAUDE_CODE_USE_FOUNDRY=1
ANTHROPIC_FOUNDRY_RESOURCE=your-resource-name
# If using API key authentication:
ANTHROPIC_FOUNDRY_API_KEY=your-azure-api-key
```
Pin specific model versions to prevent breakage when new models are released:
```bash
ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-6
ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6
ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5
```
For full setup details including RBAC configuration, see the [Claude Code on Microsoft Foundry docs](https://code.claude.com/docs/en/microsoft-foundry).
## Other Anthropic-Compatible Providers [#other-anthropic-compatible-providers]
Any provider that exposes an Anthropic-compatible API (such as LiteLLM) can be used:
```bash
ANTHROPIC_BASE_URL=https://your-provider.example.com
ANTHROPIC_AUTH_TOKEN=your-api-key
ANTHROPIC_API_KEY=
```
For LLM gateway configuration details, see the [Claude Code LLM gateway docs](https://code.claude.com/docs/en/llm-gateway).
---
# Pull Requests
Source: https://docs.superset.sh/pull-requests
Review, check, and merge PRs from your projects without leaving the app
Open **Pull requests** in the dashboard sidebar to review PRs from your projects' GitHub repositories. The resizable split view shows the PR list on the left and the selected PR's description, checks, and diff on the right.
## Browse and Filter [#browse-and-filter]
The list shows every PR from the repositories behind your projects. Each row carries the repo, PR number, title, author, a compact CI check summary (passed/total), age, and the +added/−deleted line counts.
* **State tabs**: **All**, **Open**, or **Merged**
* **Repository**: multi-select across your projects' repos
* **Author**: filter to a specific GitHub author
* **Reviews**: review-status filter: *No reviews*, *Review required*, *Approved review*, *Changes requested*, *Reviewed by you*, *Not reviewed by you*, *Awaiting review from you*, or *Awaiting review from you or your team*
* **Search**: find PRs by title or number
Filters persist, so the view comes back the way you left it. Active filters show a count badge next to the search box.
## The Detail View [#the-detail-view]
Selecting a PR opens it in the right pane, with **Summary** and **Code** tabs. Toggles at either end of the header collapse the list or the detail pane when you want more room; on narrow windows the panes stack automatically.
### Summary [#summary]
The Summary tab shows the PR description alongside:
* **Checks**: every CI check with its status and a link to the run on GitHub. The header summarizes the state at a glance ("All 12 passed"). Cancelled checks count as failures, not successes.
* Review status and reviewers for the PR
* The comment thread, with a composer for replying
### Code [#code]
The **Code** tab is a complete diff viewer: a file tree with per-file added/deleted counts and modified/renamed markers, syntax-highlighted diffs, collapsed unmodified regions, and unified or side-by-side layouts. A **Files** dropdown jumps to any file in the changeset.
### Comment Straight to an Agent [#comment-straight-to-an-agent]
Select lines in the Code tab and send a comment to an agent, optionally posting it on GitHub too. The agent receives the file, line range, and diff side:
* If a workspace is already linked to the PR, send it to one of its **running agent terminals**, or start a **new agent session** there
* If no workspace exists yet, Superset **creates a PR-checkout workspace** and launches the agent with your comment as its first prompt
## Actions [#actions]
From the detail header:
* **Start Workspace** - check out the PR into a new workspace to run, test, or continue it. See [Workspaces](/workspaces)
* **Merge** - choose **Squash and merge** (combine all commits), **Merge commit** (preserve commit history), or **Rebase and merge** (reapply all commits)
* **Close** / reopen the PR
* Open the PR on GitHub
Merging, closing, and commenting act on the real PR through your GitHub connection - same permissions, same effects as doing it on github.com.
## Where PRs Come From [#where-prs-come-from]
Connect GitHub under project settings to sync PRs. Linked workspaces also show [PR status](/workspaces#pr-status) in the sidebar. For a review workflow, see the [PR feedback recipe](/recipes/pr-feedback).
---
# Remote Access
Source: https://docs.superset.sh/remote-access
Reach workspaces hosted on another machine
## Overview [#overview]
A workspace lives on the machine that hosts its files, terminal, and ports. **Remote access** lets you reach a workspace that's hosted on a different machine, like a Mac mini under your desk, a sandbox your team shares, or a spare laptop in the office.
**Superset Relay** is a service that provides a secure way to route traffic between your different devices. There are two ways to grant a device remote access through the relay:
## Option 1: Desktop [#option-1-desktop]
Exposing your primary workstation through the relay means anything reachable by your local host service (files, terminals, agent runs) becomes reachable by clients you grant access to. The recommended setup is a **separate machine** provisioned with only the repos and credentials you intend to share. That way a misclick or compromised client can't wipe an unrelated project or leak unrelated secrets.
Use the desktop toggle when you genuinely need it on this machine. Otherwise prefer the CLI path on a dedicated host.
Open the desktop app and go to **Settings → Remote Access**. Flip on **Allow remote access to this device via relay**.
Enabling the toggle restarts the host service, so any running terminals on this device will be interrupted. You'll be asked to type a confirmation phrase before the change applies.
## Option 2: CLI [#option-2-cli]
See the CLI's [Getting Started](/cli/getting-started) and [Host Server](/cli/host-server) docs to get set up.
On the machine you want to add to your shared relay network, sign in and start the host server.
```bash
superset auth login
superset start --daemon
```
`superset start --daemon` runs a small HTTP server in the background and registers the machine with the relay so other clients in your organization can find it.
Verify it's online:
```bash
superset status
```
### Headless (sandbox, CI, or server) [#headless-sandbox-ci-or-server]
On a machine with no browser to complete an interactive login, authenticate with an API key instead. Create one in **Settings → API Keys**, then export it. The CLI reads `SUPERSET_API_KEY` automatically (no `superset auth login` needed):
```bash
export SUPERSET_API_KEY=sk_live_…
superset start --daemon --org
```
Pass `--org` to choose which organization the host registers under. It's required when your key belongs to more than one organization (the CLI won't guess); with a single organization you can omit it. The host claims itself to the key's user on first registration. No desktop step required.
Observe or manage it from the same headless environment. Every `hosts`/`status` command takes the same `--org`:
```bash
superset hosts list --org
superset status --org
```
## Connect from an iPhone or iPad [#connect-from-an-iphone-or-ipad]
Install [Superset for iPhone and iPad](/install#iphone-and-ipad) and check its requirements before connecting.
1. On your computer, enable **Allow remote access to this device via relay** in **Settings → Remote Access**. You can also use the inline toggle in **Settings → Mobile** when that tab is available. Both toggles control the same setting.
2. On your iPhone or iPad, sign in with the same Superset account and select the same organization. The QR code in desktop Mobile settings opens the App Store; it does not sign you in.
3. Select your computer and open a workspace to continue its terminal sessions, send prompts, review diffs, or merge PRs. Keep the computer awake, online, and running Superset.
If your computer does not appear online, see [Remote Host Won’t Connect](/troubleshooting#remote-host-wont-connect).
## Grant teammates access [#grant-teammates-access]
When a host first comes online, the user who started it is the only one with access. Other members of your organization won't see it in their workspaces list until you add them.
Open **Settings → Hosts** in the desktop app, pick the host, and use **Add member** to grant teammates access. Owners can promote members to owner or remove them from the host.
## Reach a remote host from another device [#reach-a-remote-host-from-another-device]
On any other device signed into the same organization, open the desktop app's **Workspaces** list. Use the **Device** filter in the top right to pick a remote host:
* **This device**: workspaces on the machine you're using now
* **Other devices**: each remote host that has opted in, listed by name with an online indicator
Pick a remote host to see the workspaces hosted there. Open one and you get the full Superset experience (terminals, agent runs, the diff viewer) proxied through the relay to the host machine.
### Ports on a remote host [#ports-on-a-remote-host]
The ports sidebar shows ports listening **on the remote host**. When you select a remote workspace, the desktop app forwards each of its ports to the same port number on your machine, so `localhost:3000` reaches the dev server on the host. All traffic for a workspace shares one tunnel, established when you select the workspace; every connection reuses it. When you select another workspace, the app stops those forwards and starts the new workspace's forwards.
Only ports that the workspace started are forwarded. Other services on the host stay unreachable.
If a local process already uses the port, the row shows **local port busy** and offers two actions: stop the local process (only when a Superset workspace started it) or **Use another port**, which maps the remote port to a free local port and shows the mapping, for example `3000 → localhost:54321`.
The remote server sees each forwarded connection as coming from its own loopback address; there is no real client IP. Only TCP is carried; anything UDP (WebRTC media, mDNS) does not ride the forward.
Forwarding needs a host on the current relay running host-service 1.26 or newer. For a host you reach some other way, [forward a port yourself](/ports#forward-a-port-yourself) with SSH or Tailscale.
Forwarded traffic passes through the Superset relay, like terminal traffic does. A browser talking to a forwarded dev server sends whatever it normally would (cookies, auth headers, query strings), so treat a forwarded port like the remote service it reaches, not like localhost.
## Turning access off [#turning-access-off]
* **Desktop**: flip the toggle in **Settings → Remote Access** back off. The host service restarts and stops accepting relay traffic.
* **CLI**: run `superset stop` on the host machine.
In both cases, in-flight terminals and host-backed work on that machine are interrupted.
---
# Project Lifecycle Scripts
Source: https://docs.superset.sh/setup-teardown-scripts
Configure setup, teardown, and Run-button commands for a project
## Overview [#overview]
Run commands automatically when creating or deleting workspaces, and define dev server commands that launch via the Run button.
These are **project lifecycle scripts**: project-owned behavior stored in the
repository or a per-machine override. They are different from
[terminal scripts](/terminal-scripts), which are reusable launches saved in
your Superset settings and shown in the Scripts bar.
Create `.superset/config.json` in your project:
```json
{
"setup": ["bun install", "cp \"$SUPERSET_ROOT_PATH/.env\" .env"],
"teardown": ["docker-compose down"],
"run": ["./.superset/run.sh"]
}
```
## How It Works [#how-it-works]
1. Create workspace → **setup** commands run in a terminal
2. Delete workspace → **teardown** commands run
3. Click the **Run** button → **run** commands execute in a dedicated pane
Setup and teardown commands run sequentially in the workspace directory.
By default, an agent launched at workspace creation starts immediately, in parallel with setup. Enable **Settings → Experimental → Wait for workspace setup before starting agents** to chain the agent after the setup commands in the same terminal: the agent only starts once setup succeeds, and no separate setup pane is left behind.
## Run Script [#run-script]
The `run` field defines commands that start your dev server or other long-running processes. Unlike setup/teardown, run commands are:
* **On-demand**: triggered by the Run button, not automatically on workspace creation
* **Restartable**: stop and restart from the UI without recreating the workspace
* **Dedicated pane**: runs in its own terminal pane separate from your shell
```json
{
"setup": ["npm install"],
"run": ["./.superset/run.sh"]
}
```
## Environment Variables [#environment-variables]
| Variable | Description |
| ------------------------- | ------------------------------ |
| `SUPERSET_ROOT_PATH` | Path to root repository |
| `SUPERSET_WORKSPACE_NAME` | Current workspace name |
| `SUPERSET_WORKSPACE_PATH` | Path to the workspace worktree |
## Examples [#examples]
**Node.js:**
```json
{ "setup": ["bun install", "cp \"$SUPERSET_ROOT_PATH/.env\" .env"] }
```
**Docker:**
```json
{
"setup": ["docker-compose up -d", "bun run db:migrate"],
"teardown": ["docker-compose down -v"]
}
```
**Full config:**
```json
{
"setup": ["./.superset/setup.sh"],
"teardown": ["./.superset/teardown.sh"],
"run": ["./.superset/run.sh"]
}
```
## User Overrides [#user-overrides]
Override project scripts without modifying the repo by placing a `config.json` in your home directory, mirroring the repo's absolute path:
```
~/.superset/projects//config.json
```
For a repo at `/Users/me/work/app`, that's `~/.superset/projects/Users/me/work/app/config.json`. The legacy location keyed by project ID (`~/.superset/projects//config.json`) still works as a fallback.
### Priority Order [#priority-order]
For each key (`setup`, `teardown`, `run`), the highest-priority source that defines it wins:
1. `~/.superset/projects//config.json`: user override
2. `/.superset/config.json`: workspace-specific (setup and teardown only)
3. `/.superset/config.json`: project default
Levels merge per key: a key one level doesn't define falls through to the next. `run` resolves at the project level, so it skips the worktree layer.
### Script Fallback [#script-fallback]
If no commands are configured for a key, Superset looks for a script instead: `.superset/.sh` (`setup.sh`, `teardown.sh`, `run.sh`) in the worktree first, then the main repo. A gitignored script isn't checked out into new worktrees, so it typically exists only in the main repo.
### Working Directory [#working-directory]
Set `cwd` to run commands somewhere other than the workspace root. Relative paths resolve against the worktree:
```json
{ "cwd": "apps/web", "run": ["bun dev"] }
```
### Examples [#examples-1]
**Custom setup script:**
```json
{
"setup": ["~/.superset/projects//setup.sh"],
"teardown": ["~/.superset/projects//teardown.sh"]
}
```
**Skip setup entirely:**
```json
{ "setup": [], "teardown": [] }
```
## Local Config [#local-config]
Extend or override your team's committed scripts without modifying the repo. Create `.superset/config.local.json` alongside `config.json`. It's gitignored automatically.
### Prepend and/or append [#prepend-andor-append]
Add steps before or after the team's scripts:
```json
{
"setup": {
"before": ["echo 'running pre-setup'"],
"after": ["./.superset/my-post-setup.sh"]
},
"teardown": {
"after": ["./.superset/my-cleanup.sh"]
}
}
```
Result: `before` → committed setup scripts → `after`. Keys you don't specify pass through unchanged.
### Override entirely [#override-entirely]
Use a plain array to replace the team's scripts completely:
```json
{
"setup": ["./.superset/my-custom-setup.sh"]
}
```
### Mix and match [#mix-and-match]
Override one key while extending the other:
```json
{
"setup": { "after": ["bun run my-extra-step"] },
"teardown": ["my-custom-teardown.sh"]
}
```
### Resolution order [#resolution-order]
The local config merges on top of whichever base config wins the [priority order](#priority-order). If a `config.local.json` exists in both the worktree and main repo, the worktree's local config takes priority.
## Force Delete [#force-delete]
If teardown scripts fail during workspace deletion, you can force-delete to skip the failed teardown and continue cleanup.
When teardown fails:
1. Error toast appears with "Delete Anyway" and "View Logs" buttons
2. Click "Delete Anyway" to force-delete immediately
3. Or click "View Logs" to review the failure, then force-delete from the dialog
Deleting a workspace through the CLI, SDK, or MCP also runs teardown. Since there's no one to prompt on those surfaces, a teardown failure doesn't block the delete; it's reported in the response's `warnings` instead.
## Tips [#tips]
* Keep setup fast: it runs on every workspace creation
* Commit `.superset/` to share with team
* Use shell scripts for complex logic: `"setup": ["./.superset/setup.sh"]`
* Use `config.local.json` to add personal steps without touching the team's config
* Use user overrides (`~/.superset/projects/`) to replace scripts entirely per-project
* Use `run` for dev servers instead of putting them in `setup`: run scripts are restartable and don't block workspace creation
---
# Skills
Source: https://docs.superset.sh/skills
Superset abilities your coding agents get automatically. Orchestration, automations, feedback, diagnostics, and more
Skills teach the coding agents you already use how to drive Superset: orchestrate parallel agents, create automations, diagnose problems, and more.
## Installation [#installation]
**Using the Superset desktop app?** Skills are already installed. The app provisions them at launch and keeps them updated.
Otherwise, install them directly:
```bash
npx skills add superset-sh/skills
```
Or, in Claude Code, via the plugin marketplace:
```text
/plugin marketplace add superset-sh/superset
```
## What You Get [#what-you-get]
| Skill | What it does |
| :--------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `superset:setup` | Makes a repo Superset-ready: authors `.superset/config.json` and project lifecycle scripts, then verifies with a real workspace |
| `superset:orchestrate` | Turns the agent you're talking to into a coordinator of parallel agents; see [Agent Orchestration](/orchestration) |
| `superset:automate` | Turns a recurring chore into a scheduled [automation](/automations) and reviews its first run with you |
| `superset:page` | Builds and publishes shareable [Pages](/pages), then updates them in response to pinned team comments |
| `superset:browser` | Drives a workspace's [in-app browser](/browser) panes: open, navigate, screenshot, eval, read console, and raw CDP for click/type automation, and routes to [Browser Use 3.0](/browser#browser-use-30) for browsers the panes can't reach |
| `superset:computer` | Drives [native desktop apps](/computer) through an accessibility-first driver (Cua Driver by default): inspect windows, click, type, use menus, and verify results with background interaction when the platform supports it |
| `superset:standup` | Sweeps your workspaces, tasks, and agent terminals into a digest: what needs you, what's in flight, what's blocked |
| `superset:doctor` | Diagnoses Superset problems (expired auth, offline hosts, stale versions) and fixes them one step at a time |
| `superset:feedback` | Files a bug report or feature request: privately to the Superset team (from your account, so we can reply) or as a public GitHub issue |
| `superset:10x` | Audits how you use Superset and teaches the advanced features you're not using yet |
| `superset:contribute` | Sets up a Superset open-source contribution end to end, following the repo's contribution rules |
## Using Skills [#using-skills]
You usually don't invoke them; agents pick the right skill from context:
* "report this bug to the superset team" → `superset:feedback`
* "what did my agents do overnight?" → `superset:standup`
* "run these three refactors in parallel" → `superset:orchestrate`
* "open localhost:3000 and click through the signup flow" → `superset:browser`
* "open the desktop app and change its settings" → `superset:computer`
To invoke one explicitly: `/superset:feedback` in Claude Code, or `/superset/feedback` in the in-app chat. Other agents that read skills (Codex, Kimi, Vibe, Grok) see the same skills with a `superset-` prefix.
## How They're Delivered [#how-theyre-delivered]
At launch, the desktop app writes managed copies into the standard discovery locations: `~/.claude/skills/superset/` (loaded by Claude Code as a plugin, hence the `superset:` namespace), `~/.agents/skills/`, and `~/.agents/commands/`.
* **Your files are never touched.** Managed files carry a marker; a skill or command you authored at the same path is left alone.
* **Updates are automatic.** Managed skills refresh on every app launch, and ones that no longer ship are cleaned up.
---
# The Superset Model
Source: https://docs.superset.sh/superset-model
Five concepts everything else builds on
Superset has one mental model: **delegate in workspaces, integrate through branches and PRs**. Five concepts make it work.
## Projects [#projects]
A project is a repo you've registered with Superset, from a local folder or a Git URL. Everything else happens inside a project. A project can define [project lifecycle scripts](/setup-teardown-scripts) for setup, teardown, and Run-button behavior in `.superset/config.json` so every new workspace comes up ready to work.
## Workspaces [#workspaces]
A workspace is an isolated [git worktree](/workspaces) on its own branch: its own directory, its own terminal sessions, its own ports. Only git-tracked files are copied in; lifecycle setup scripts handle the rest (dependencies, env files).
Workspaces are cheap and disposable by design. Create one per task with **⌘N**, delete it when the branch merges. The workspace is where you delegate; the branch and PR are how the work comes back.
## Terminals [#terminals]
Every workspace gets [persistent terminals](/terminal-integration). Sessions survive app restarts: running processes continue, output history and scrollback are preserved. This is what makes it safe to have five agents running: closing the app doesn't kill their work.
## Agents [#agents]
Any CLI agent runs in any workspace: Claude Code, Codex, Amp, Gemini, and [the rest](/agent-integration), plus a built-in chat. To power [status and notifications](/agent-status), Superset wraps agent launch commands and installs lifecycle hooks into their configs. It never touches model traffic: prompts and tokens go directly from the agent CLI to your provider, on your own accounts.
## Devices [#devices]
A workspace lives on the machine that hosts its files, terminals, and ports; that doesn't have to be the machine you're looking at. [Remote access](/remote-access) reaches workspaces hosted on another device (a Mac mini under the desk, a shared sandbox), and [Automations](/automations) dispatch scheduled agent runs to whichever device you pick.
## How They Compose [#how-they-compose]
Every workflow in the [recipes](/recipes/race-agents) is these five pieces arranged differently: racing is N workspaces with the same prompt; the nightly audit is an automation dispatching to a device that creates a workspace; a fanned-out refactor is one workspace per slice, integrated as PRs.
---
# Tasks
Source: https://docs.superset.sh/tasks
Track work items and delegate them to agents without leaving the app
Open **Tasks** in the dashboard sidebar to browse issues and delegate them to agents. Filters persist between visits. [Pull Requests](/pull-requests) has a separate view.
## Where Tasks Come From [#where-tasks-come-from]
A source toggle at the top of the view switches between:
* **Linear** - issues synced from your connected workspace (see [Linear Integration](/use-with-linear)), listed alongside Superset-native tasks you create in the app
* **GitHub issues** - open issues from your projects' repositories, with a repository filter and per-row **Add to workspace** buttons
The Linear source lists issues from the whole connected workspace; filter by project, status, or assignee to narrow it to yours.
## What You Can Do [#what-you-can-do]
* **List and board views**: a sortable table or a kanban board grouped by status
* **Filters** for project, task state, and assignee; empty filters mean everything
* **Semantic search**: find tasks by meaning, not just keywords
* **Multi-select**: check several tasks and act on them together
* **Create tasks** from the desktop with the **New task** modal: title, description, status, priority, and assignee
Opening a task shows its full detail: an editable title, description, activity, and a properties sidebar for status, priority, and assignee.
## From Task to Workspace [#from-task-to-workspace]
Launch an agent from a task and the task's content becomes the agent's prompt:
* **Run in workspace** on a task (or a multi-selection of tasks) picks a project and an agent, then creates a workspace per task with the agent already working
* The **Auto-run command** toggle controls whether each agent starts immediately or stages the command for review
* The **Task Prompt Template** (per agent, under **Settings → Agents**) controls how a task is turned into the agent's prompt
* On the GitHub issues source, **Add to workspace** does the same for a single issue
After creating a PR, review and merge it from [Pull Requests](/pull-requests).
---
# Terminal
Source: https://docs.superset.sh/terminal-integration
Built-in terminal with multiple tabs and persistence
## Overview [#overview]
Built-in terminal per workspace with multiple tabs and session persistence.
## Multiple Tabs [#multiple-tabs]
Open several terminal tabs per workspace. Each runs independently.
* **⌘T** - New tab
* **⌘W** - Close pane; **⌘⇧W** - Close tab
* **⌘⌥1-9** - Switch tabs (⌘1-9 switches workspaces)
## Session Persistence [#session-persistence]
Sessions survive app restarts:
* Running processes continue
* Output history preserved
* Scrollback maintained
If a terminal has ended, choose **New shell** to start a fresh session in the same pane. Recent output from the previous session stays visible. For agent recovery, see [Resume Interrupted Sessions](/agent-sessions#resume-interrupted-sessions).
## Pane Rename [#pane-rename]
Double-click a pane title to rename it.
## Merge Tabs [#merge-tabs]
Drag a tab onto another tab's split drop zone to merge the source tab's panes into that layout. The source tab closes after the merge.
## Right-Click Menu [#right-click-menu]
Right-click in the terminal for quick actions:
* **Copy** - Copy selected text (enabled when text is selected)
* **Paste** - Paste from clipboard (enabled when clipboard has content)
* **Mark as Unread** - Show the unread indicator again
* Split, Clear, Move to Tab, Close
Copying follows Ghostty's whitespace rules: trailing spaces on each line and trailing blank lines are removed, indentation and blank lines between text are kept, and lines that wrapped only because of the pane width are joined back into one line. The same rules apply to ⌘C, copy on select, and rectangular selections.
## Cmd/Ctrl-Click Links [#cmdctrl-click-links]
Hold `Cmd` (macOS) or `Ctrl` and click links in terminal output:
* URLs open in browser
* File paths open in the built-in file viewer by default. A location such as `src/index.ts:240:7` jumps to line 240, column 7.
* Links to Superset Pages open in a Page pane when the click opens them in the app
* Configure modifier keys for URLs in **Settings → Browser → URL links**, and for file, folder, and page links in **Settings → Files & Editor**
## Environment Variables [#environment-variables]
| Variable | Description |
| ------------------------- | ----------------------- |
| `SUPERSET_ROOT_PATH` | Path to root repository |
| `SUPERSET_WORKSPACE_NAME` | Current workspace name |
---
# Terminal Scripts
Source: https://docs.superset.sh/terminal-scripts
Save and reuse commands that launch in terminals
## Overview [#overview]
Terminal scripts are reusable terminal launches. Give a script a name, one or
more shell commands, an optional working directory, and a launch mode; then run
it from any matching workspace with one click or a keyboard shortcut.
Terminal scripts are different from [project lifecycle scripts](/setup-teardown-scripts):
| Type | Purpose | Stored in |
| ---------------------------- | --------------------------------------------------------------- | ------------------------------------------- |
| **Terminal script** | A reusable command or group of commands you launch from the app | Superset user settings |
| **Project lifecycle script** | Repository setup, teardown, or Run-button behavior | `.superset/config.json` or `.superset/*.sh` |
Older versions of Superset called terminal scripts **presets**. You may still
see `preset` in old links, CLI aliases, or compatibility-oriented API and
storage fields, but the product term is **terminal script**.
## What Terminal Scripts Do [#what-terminal-scripts-do]
* **Launch reusable commands**: start a dev server, agent, test watcher, or any shell command
* **Choose a working directory**: run from the workspace root or a path such as `apps/web`
* **Group commands**: open several commands as panes, tabs, or a sequential workflow
* **Target projects**: make a script available everywhere or only in selected projects
* **Integrate with workspace actions**: use a script for workspace creation, new tabs, or the Run button
* **Import agents**: create terminal scripts linked to configured Claude, Codex, and other agents
## Create a Terminal Script [#create-a-terminal-script]
Go to **Settings → Terminal → Terminal Scripts**, then click **Add Script**.
| Field | Description |
| --------------- | ----------------------------------------------- |
| **Name** | The label shown in Settings and the Scripts bar |
| **Description** | Optional context about what the script launches |
| **Commands** | One or more shell commands, one command per row |
| **Applies to** | Every project or selected projects |
| **Directory** | A workspace-relative path or absolute directory |
| **Launch mode** | Where one or more commands open |
You can also add one from a terminal:
```bash
superset scripts add --name dev --command "bun run dev"
```
Repeat `--command` for a grouped script and use `--execution-mode` to control
its layout:
```bash
superset scripts add \
--name services \
--command "docker compose up" \
--command "bun run dev" \
--execution-mode split-pane
```
To change or remove a script from the same terminal, use its id from
`superset scripts list`:
```bash
superset scripts list
superset scripts edit --command "gh pr view --web"
superset scripts delete
```
When you are iterating on one script, `superset scripts add --upsert` replaces
the script with the same name instead of adding another copy to the Scripts
bar. Changes made with the CLI reach the app the next time it opens or
refocuses with the same organization active, and the running app picks them up
immediately. Scripts created in Settings live in the app profile only, so they
do not show up in `superset scripts list`.
`superset presets add` remains an alias for compatibility. See the
[CLI reference](/cli/cli-reference#scripts) for every option.
## Launch Modes [#launch-modes]
* **New tab**: open the command in a new terminal tab
* **Split pane**: open grouped commands as parallel panes in the current tab
* **New tab with split panes**: create a new tab containing parallel panes
* **Sequential**: run grouped commands in order in one terminal
## Import an Agent [#import-an-agent]
Use **Import agent** in Terminal settings to create a terminal script linked to
an agent configuration. The script uses the agent's current command and icon;
edit the underlying launch command in **Settings → Agents**.
The bundled Claude and Codex configurations default to their most permissive
bypass flags (for example `claude --dangerously-skip-permissions`). Review the
launch command in **Settings → Agents** if you want a stricter permission mode
before importing.
## Scripts Bar [#scripts-bar]
The Scripts bar appears above terminal tabs and shows visible terminal scripts
for one-click access.
* **Show or hide a script**: use its visibility control in Terminal settings or the gear menu
* **Launch**: click a script to open it in the current workspace
* **Choose a target**: right-click to use the current terminal, current tab, or a new tab
* **Reorder**: drag scripts to change their order
* **Manage**: use the gear menu to browse scripts or open Terminal settings
* **Keyboard shortcuts**: press Control+1 through Control+9 to open visible scripts 1 through 9
The bar includes a built-in **Superset CLI** script that runs `superset --help`.
Built-in scripts can be hidden and restored, but not edited or reordered.
## Workspace Actions [#workspace-actions]
A terminal script can participate in three workspace actions:
* **Workspace Run**: the Run button launches this script for matching projects
* **Workspace creation**: launch the script when a new workspace is created
* **New terminal tab**: launch the script when a terminal tab opens
These are explicit per-script controls. Launching a script directly from the
bar, menu, or keyboard shortcut always works regardless of its workspace-action
settings. On v1 desktop builds, the global auto-apply settings (such as
`autoApplyDefaultPreset`, visible in `superset settings list`) also gate
auto-run behavior.
If more than one Run source matches a workspace, Superset uses the first
project-targeted terminal script marked **Use as workspace run**, then the
project lifecycle Run command, then the first matching global terminal script.
Keep only one matching script enabled for Run when you want the choice to be
unambiguous.
---
# Troubleshooting
Source: https://docs.superset.sh/troubleshooting
Symptoms, causes, and fixes for common issues
## All My Workspaces or Projects Disappeared [#all-my-workspaces-or-projects-disappeared]
Almost always a context mix-up, not data loss. Check, in order:
1. **Organization**: updates can switch your active org. Check the org switcher.
2. **Sign-in provider**: GitHub and Google logins are separate accounts even with the same email. Sign out and back in with your original provider.
3. **v1 fallback**: if the app reverted to the legacy interface, re-enable v2 under **Settings → Experimental**.
Your worktrees are still on disk at `~/.superset/worktrees/` either way; Superset only deletes them when you delete a workspace.
If you created your account after using v1, update Superset and relaunch it. Current versions import pre-account workspaces that older v2 releases could miss.
## Update Button Does Nothing [#update-button-does-nothing]
If the app quits and reopens on the same version, the updater hit a known race (fixed in recent releases). Download a fresh copy from [superset.sh/download](https://superset.sh/download) once; updates work normally after that.
## gh, git, or an Agent Works in My Normal Terminal but Not in Superset [#gh-git-or-an-agent-works-in-my-normal-terminal-but-not-in-superset]
Superset terminals differ from Terminal.app in a few specific ways:
* **PATH shims**: Superset puts wrappers in `~/.superset/bin` (for status and notifications). If an agent misbehaves, run `which -a codex` (or `claude`) to spot duplicate installs on your PATH.
* **Copied settings**: new worktrees copy files like `.claude/settings.local.json` from your root checkout. If you rotated an API key, old worktrees may still carry the stale one.
* **Shell**: launch commands assume a POSIX shell. fish or nushell as your login shell breaks agent launches.
* **After an update**: terminal sessions are held by a background daemon that outlives the app. If terminals stay broken after an update, quit Superset fully and relaunch; if that doesn't clear it, reboot.
## New Workspace Is Missing Dependencies or .env [#new-workspace-is-missing-dependencies-or-env]
Workspaces only copy git-tracked files, so `node_modules`, `.env`, and build artifacts don't come along.
**Fix:** add [project lifecycle setup commands](/setup-teardown-scripts) to `.superset/config.json`:
```json
{
"setup": ["bun install", "cp \"$SUPERSET_ROOT_PATH/.env\" .env"]
}
```
Or ask an agent to do it: the "Set up this project for Superset" [sample prompt](/first-workspace#2-create-a-workspace-with-a-prompt) authors the config for you.
## Can't Add a Private Repository [#cant-add-a-private-repository]
Repo access goes through the GitHub CLI.
**Fix:** run `gh auth status` in a terminal. If it fails, `gh auth login` (you can run it inside Superset), then retry.
## Can't Create a Workspace on a Branch [#cant-create-a-workspace-on-a-branch]
One branch = one workspace. If the branch is already checked out in another workspace (or your root checkout), git won't allow a second worktree on it.
**Fix:** open the existing workspace, or create a new branch.
## Agent Isn't Showing Up in the Launcher [#agent-isnt-showing-up-in-the-launcher]
Superset detects installed agents automatically, but each agent can be enabled or disabled.
**Fix:** check **Settings → Agents**: confirm the agent is **Enabled** and its command is correct. **Reset to Defaults** restores the shipped configuration.
## Remote Host Won't Connect [#remote-host-wont-connect]
The host machine must be awake, online, and connected to the relay. On the host, enable **Settings → Remote Access → Allow remote access to this device via relay** (desktop), or run `superset start --daemon` (CLI).
In the mobile app:
* **One step left** means the computer has never connected. Follow the Remote Access setup steps on that computer.
* **Offline** with a last-seen time means it connected before. Check that it is awake, online, and running Superset, then retry.
* **Can’t check** means Superset could not load connection status. Use **Try again**; this message does not establish that the computer is offline.
See [Remote Access](/remote-access) for setup.
## Automation Run Failed While the Device Was Offline [#automation-run-failed-while-the-device-was-offline]
A run whose target device isn't relay-connected at fire time records as **failed**, with the offline error shown inline under the run; the schedule advances normally.
**Fix:** none needed for a one-off. Use **Retry all** in the Automations list once the device is back online, or retarget the automation to a device that stays online. See [Automations](/automations).
## Still Stuck? [#still-stuck]
* Check the [FAQ](/faq)
* [Open an issue](https://github.com/superset-sh/superset/issues) with steps to reproduce
---
# Usage
Source: https://docs.superset.sh/usage
Subscription quota meters, token-cost analytics, machine resources, and multi-account switching
## Overview [#overview]
The **Usage** page (gauge icon in the sidebar) tracks what your agents consume on this machine: signed-in Claude Code and Codex accounts, their session logs, and local processes. Remote hosts aren't aggregated. A pill toggle switches between **Token usage** and **Machine resources**.
## Quota Meters [#quota-meters]
The top of **Token usage** shows official subscription quota for every Claude Code and Codex login on this host, refreshed every 5 minutes (use the refresh button to force it). Each account card shows the email, plan, and one meter per quota window, e.g. **Session (5h)** and **Weekly** for Claude, with the fill percentage and time until reset.
Superset reads quota from the providers' usage endpoints using the agent credentials stored on your host. Some plans (org-managed, education) don't expose limits.
## Multiple Accounts [#multiple-accounts]
Run different agents on different subscriptions from one machine:
* **Add account** creates a second profile. Pick a profile name and billing type, then complete Claude Code or Codex sign-in in the terminal inside the dialog. Click a login URL to open your system browser. Superset detects a successful sign-in automatically. For a remote host, copy the shown command and run it in a terminal on that host.
* **Make default** picks which account new agent launches use. When a provider has several accounts, the cards read as a radio group with the default checked. Switching reaches terminals you already have open too: a running agent keeps its account until you relaunch it.
* Your setup comes along: skills, plugins, MCP servers, and settings are shared across accounts, and for Claude Code there's one conversation history: `--resume` shows the same sessions whichever account is active.
* Logins, credentials, and account identity stay per account. The **…** menu on a card offers **Switch sign-in…** (re-login that profile to a different account) and, for secondary profiles, **Remove…**, which deletes that profile and its credentials, never your shared setup or history. The system-default login can't be removed.
* If a sign-in expires, the card shows the exact login command to run, with click-to-copy.
Under the hood, a profile is just a config dir the CLI is pointed at (`CLAUDE_CONFIG_DIR` / `CODEX_HOME`). Superset's agent wrappers re-resolve the current default every time the agent starts in a Superset terminal, so switching works for agents you launch by hand too, and a value you export yourself always wins.
## Token Costs [#token-costs]
Below the meters, the **Token usage** chart estimates spend from the agents' local session logs, priced at API list rates. Subscription usage isn't billed per token (the page shows **Cost to you: $0**); the estimate is what the same work would cost at API rates, plus how much caching saved.
* Toggle **Cost** / **Tokens** and pick a **7d** / **30d** / **90d** range
* Per-provider split between Claude Code and Codex; click a provider to show or hide it in the chart; click a day for that day's breakdown
* **Model** table and **Workspace** bars break spend down; click a row for a per-model or per-workspace drilldown, or **All N →** for every workspace and project
* Workspace drilldowns list the top sessions by cost; click one to copy its session ID for `claude --resume`
## Leaderboard History [#leaderboard-history]
Joining or rejoining the leaderboard publishes available local usage history
from the last 90 days, starting no earlier than July 29, 2026. Leaving deletes
your published history. Rejoining restores only the history within that window
that is still available in your local session logs.
## Machine Resources [#machine-resources]
The **Machine resources** section is a live view (every 2 seconds) of local CPU and memory: Superset's own usage, the system RAM split, and a process table covering the app and every workspace, grouped by project down to individual terminal panes. Click a workspace or session row to jump to it.
Also reachable via **⌘⇧U** (Check Resources), the command palette, or the **Resources** menu.
---
# IDE Integration
Source: https://docs.superset.sh/use-with-ide
Use with Cursor, VS Code, or other editors
## Open in Editor [#open-in-editor]
Press **⌘O** (**Ctrl+Shift+O** on Windows and Linux), or click the open-in button at the top of the right sidebar, to open the workspace in your editor. The button and the shortcut work only while the right sidebar is open. The command palette's open-in command works at any time. Supported editors:
* Cursor
* VS Code
* VS Code Insiders
* Zed
* Windsurf
* Antigravity
* Sublime Text
* JetBrains IDEs (IntelliJ IDEA, WebStorm, PyCharm, and more)
## Configure Default Editor [#configure-default-editor]
Settings → Editor → Select your preferred editor
## Window Title Tip [#window-title-tip]
Show branch name in editor title bar:
1. Open VS Code/Cursor settings
2. Search `window.title`
3. Set to: `${activeRepositoryBranchName}${separator}${rootName}`
This helps identify which window is which when you have multiple workspaces open.
---
# Linear Integration
Source: https://docs.superset.sh/use-with-linear
Open Linear issues as Superset workspaces with a custom script
Linear's [custom coding tool](https://linear.app/docs/open-issues-with-custom-scripts)
feature can hand an issue off to any local command. With a small wrapper script,
**Work on issue → Custom script** creates a Superset workspace for the issue
(checked out on the issue's branch, with an agent already working on it) and
opens it in the desktop app.
## How it works [#how-it-works]
Linear doesn't use a URL scheme here. It runs a local executable defined in
`~/.linear/coding-tools.json` and passes issue context through `LINEAR_*`
environment variables (`LINEAR_ISSUE_IDENTIFIER`, `LINEAR_ISSUE_BRANCH_NAME`,
`LINEAR_PROMPT`, and others). The wrapper script chains two CLI calls:
1. `superset workspaces create`: creates a local workspace on the issue's
branch and launches an agent with the issue as its prompt.
2. `superset workspaces open`: opens that workspace in the desktop app via its
deep link.
## Prerequisites [#prerequisites]
* The [Superset CLI](/cli/getting-started) installed and signed in
(`superset auth login`).
* The Superset desktop app installed (the script opens workspaces in it).
* A project that's set up locally. Find its ID with:
```bash
superset projects list
```
Copy the `id` of the project you want issues to open against.
## 1. Create the wrapper script [#1-create-the-wrapper-script]
Save this as `~/.linear/open-in-superset.sh` and replace `PROJECT` with the ID
from above:
```bash
#!/usr/bin/env bash
# Linear custom script -> open the issue as a Superset workspace.
set -euo pipefail
PROJECT=""
NAME="${LINEAR_ISSUE_IDENTIFIER:-linear-task}"
BRANCH="${LINEAR_ISSUE_BRANCH_NAME:-$NAME}"
PROMPT="${LINEAR_PROMPT:-Work on Linear issue ${NAME}.}"
# Make sure the local host service is running (idempotent).
superset start --daemon >/dev/null 2>&1 || true
result="$(
superset workspaces create \
--local \
--project "$PROJECT" \
--name "$NAME" \
--branch "$BRANCH" \
--skip-branch-prefix \
--agent claude \
--prompt "$PROMPT" \
--json
)"
id="$(printf '%s' "$result" | jq -r '.workspace.id')"
superset workspaces open "$id"
```
Make it executable:
```bash
chmod +x ~/.linear/open-in-superset.sh
```
The script depends on `superset` being on your `PATH` and `jq` being installed.
If `superset` isn't on your `PATH`, use its full path (the desktop app installs
a shim at `~/.superset/bin/superset`).
The branch named by the issue won't exist yet. `workspaces create` forks it
from the project's default branch automatically. `--skip-branch-prefix` keeps
Linear's exact branch format (so Linear autolinks the branch back to the
issue) even when the project has a branch prefix configured. Re-running on
the same issue reuses the existing workspace instead of creating a duplicate.
With the Linear integration connected, Superset does this natively: linking
an issue in the New Workspace flow (or opening a task in a workspace) uses
Linear's branch name automatically and moves the issue to In Progress. The
script above is for driving it from Linear's side.
## 2. Point Linear at the script [#2-point-linear-at-the-script]
Create `~/.linear/coding-tools.json`:
```json
{
"openIssue": {
"path": "/Users/you/.linear/open-in-superset.sh",
"env": [
"LINEAR_ISSUE_IDENTIFIER",
"LINEAR_ISSUE_BRANCH_NAME",
"LINEAR_PROMPT"
]
}
}
```
Use the absolute path to your script (`~` is not expanded here).
If Linear regenerates this file with a starter config when you enable the
feature, merge the `openIssue` block back in rather than letting it overwrite
your version.
## 3. Enable and run [#3-enable-and-run]
1. In Linear, open **Settings → Code & reviews → Configure coding tools** and
enable **Custom script**.
2. On any issue, choose **Work on issue → Custom script**. The first time,
Linear asks you to **Choose a directory**: this is the working directory
passed to the script, so pick your repo. (The script above doesn't read it,
but Linear requires one.)
Linear runs the script, and the workspace opens in Superset with the agent
running on the issue.
In any macOS file dialog, press **⌘⇧.** to reveal hidden dot-folders, or
**⌘⇧G** to type a path directly.
## Customizing [#customizing]
* **No agent.** To open an empty workspace on the branch without starting an
agent, drop the `--agent` and `--prompt` flags (they're required together).
* **A different agent.** Replace `claude` with any agent preset id (`codex`,
`opencode`, …).
* **Multiple repos.** The project ID is fixed in the script. To route different
Linear teams or projects to different Superset projects, branch on a
`LINEAR_*` variable (for example `LINEAR_PROJECT_NAME`) and set `PROJECT`
accordingly. The `env` array in `coding-tools.json` is an allowlist: any
`LINEAR_*` variable you read in the script must also be added there, or it
won't be present in the script's environment.
---
# Slack Integration
Source: https://docs.superset.sh/use-with-slack
Mention @superset in Slack to file tasks or dispatch coding agents
`@superset` in Slack is an agent, not just a task-filer. Mention it in a channel or DM it, describe what you want, and it acts.
## What It Can Do [#what-it-can-do]
* **Create, update, search, and triage tasks** from the conversation it's standing in, pulling assignees, statuses, and priorities from your team's Linear/Superset setup
* **Spin up a cloud workspace and launch a coding agent** to actually do the work. Code-change requests ("bump our Sentry SDK to v9 across all apps") default to spawning a workspace and agent rather than filing a ticket
* **Read the thread or channel history** on its own to gather context, no copy-pasting prior messages
* **Search the web with citations** when a request needs current information
* **Unfurl Superset task, workspace, and [Page](/pages) links** with rich previews
## Setup [#setup]
1. In the dashboard, go to **Integrations → Slack**
2. Click **Connect** to install the Superset Slack app (OAuth)
3. Mention `@superset` in any channel, or DM the bot, and describe what you want done
## Page Links [#page-links]
A shared [Page](/pages) link unfurls with its thumbnail, description, creator, and last update. Click the preview to open the page's details in Slack.
* Public pages and pages shared with your organization unfurl in the Slack workspace connected to that organization.
* A page only you can see unfurls only when you post it and your Slack account is linked to Superset. If it is not linked, Slack asks you to connect it.
* Deleted pages and pages taken down by the Superset team do not unfurl.
## Connected Plugins [#connected-plugins]
The Slack agent can use a linked user's connected Linear and GitHub plugins to read issues and repositories, file or update issues, comment, and open pull requests. It uses a limited tool set; plugin tools cannot delete resources, merge pull requests, or perform bulk writes. If a requested plugin is not connected, the reply offers a **Connect** button.
## Thread Follow-ups [#thread-follow-ups]
These controls are available when thread follow-ups are enabled for your Slack team:
* Once the agent has replied in a thread, follow-up replies reach it without another mention. Replies sent while it is working are queued for the next turn.
* Send `!mute` to require mentions in that thread again, or `!unmute` to resume automatic follow-ups. Direct mentions still work in a muted thread.
* Send `!stop` or `!cancel` in the thread or DM to end the running Slack turn. Work already completed remains in the reply's Changes footer. This does not undo actions or stop coding agents already launched in workspaces.
Without thread follow-ups enabled, continue to mention `@superset` for each channel request.
## Good First Prompts [#good-first-prompts]
```text
@superset file a bug: the export button 500s on reports over 10k rows.
Assign to whoever owns reporting.
```
```text
@superset bump our Sentry SDK to v9 across all apps and open a PR.
```
The second one creates a workspace, runs an agent, and reports back in-thread.
---
# Monorepos
Source: https://docs.superset.sh/using-monorepos
Working with monorepos
## Overview [#overview]
Superset works with monorepos. Workspaces are created at the repo root with access to all packages.
## Lifecycle Setup Script [#lifecycle-setup-script]
```json
{
"setup": [
"bun install",
"cp \"$SUPERSET_ROOT_PATH/.env\" .env"
]
}
```
## Running Services [#running-services]
Run multiple services from terminal:
```bash
bun run dev # All services
bun run --filter @myapp/web dev & # Specific package
bun run --filter @myapp/api dev
```
## Sparse Checkout [#sparse-checkout]
List the folders your worktrees actually need in the project's **Sparse checkout** setting. New worktrees for that project then materialize only those folders plus the repo-root files (git cone mode).
* Applies only to worktrees created after the setting changes; existing worktrees and the main repo are untouched
* Leave the list empty for a full checkout
* If git rejects the sparse cone, workspace creation falls back to a full checkout instead of failing
## Git Submodules [#git-submodules]
Add to setup script:
```json
{
"setup": ["git submodule update --init --recursive", "bun install"]
}
```
---
# Workspaces
Source: https://docs.superset.sh/workspaces
Isolated environments for each git branch
## Core Concept [#core-concept]
A workspace gives a task its own directory, terminals, and ports. Local project workspaces use isolated git worktrees; cloud workspaces use separate clones. [Sessions](#sessions) use a managed scratch folder without requiring a project.
## Create Workspaces [#create-workspaces]
Press **⌘N** or click "New Workspace". Create from:
* **New branch** - Fresh branch from main
* **Existing branch** - Continue work on a branch
* **Pull request** - Review or continue a PR
In the prompt-first workspace flow, **Link pull request** lets you search by title or PR number, or paste the full PR URL to match it directly. The prompt box also keeps a searchable history of your previous prompts; click the history icon to reuse one.
If you type a workspace name yourself, the branch name is derived from it (slugified to kebab-case). Otherwise the workspace opens right away as **New workspace** (or **New session**), and Superset names it in the background from your prompt and any linked GitHub issue or pull request, usually within a few seconds. The branch gets the generated name plus a short unique suffix; the worktree folder keeps the name it was created with. If the first name is vague or naming fails, Superset tries again after the agent's next reply. The branch is renamed only while it is unpushed. Renaming the workspace yourself stops automatic naming. Per-project **Naming instructions** (in project settings) steer generated names, e.g. "prefix branches with fix/ or feat/".
Each new branch-based workspace gets:
* Own git branch
* Own working directory
* Own terminal sessions
* Workspace-scoped port detection and controls
New local worktrees use `//` directories. Existing worktrees keep their paths.
### Cloud Workspaces [#cloud-workspaces]
Cloud workspaces are in early access and not generally available. When they are available to your account, Superset creates a new working branch from the selected base. For multiple repositories, it uses the same working branch name in each. Attach images to the initial prompt to give the agent visual context when it starts.
## Import Worktrees [#import-worktrees]
If you have existing git worktrees on disk, use the **Import** tab in the New Workspace modal to bring them into Superset. Click **Import all** to bulk-import all discovered worktrees at once.
You can also right-click a project in the sidebar and choose **Import untracked worktrees**. A confirmation dialog lists the branches and paths that will be imported; the **Run setup script** checkbox is off by default, since existing worktrees are usually already set up.
## Sessions [#sessions]
A **session** is a workspace without a project. Pick **No project** in the new-workspace picker, or click **+** on the sidebar's **Sessions** section. Each session gets its own git-initialized folder under `~/.superset/sessions`. Terminals, agents, chat, and the Changes panel work as usual; there's no branch or PR link.
Sessions created outside the app (by the CLI or a session-mode automation) appear in the sidebar's **Sessions** section automatically. Placement happens once: if you later remove one from the sidebar, it stays removed.
From the CLI, pass `--session` explicitly. Creating a host workspace requires
either `--project ` or `--session`; omitting both is an error:
```bash
superset workspaces create --session --local --agent claude --prompt "…"
```
On iPhone, choose **No project** in the composer's project picker, or tap **+** beside **No project** on Home. Sending your prompt creates a session on the selected online host.
Automations can run in session mode too; see [Automations](/automations).
## Pin Workspaces [#pin-workspaces]
Keep active workspaces at the top of the sidebar:
* Right-click a workspace and choose **Pin to Sidebar** (or **Unpin**)
* Drag into the **Pinned** section to pin, drag within it to reorder, drag out to unpin
* Sessions work the same way
* Pinned project workspaces show a project-name prefix, such as `project/workspace`
If sorting or filtering prevents a sidebar drag, the notice offers an action to restore manual ordering or clear filters.
## List and Board Views [#list-and-board-views]
The workspaces page toggles between **List** and **Board** layouts; Board is the default. Board columns follow workspace state, derived from agent status and PR state: **Idle**, **Working**, **Needs attention**, **Needs review**, **Merged**, and **Deleted**. Merged and Deleted are history: deleted workspaces keep a card instead of vanishing, and both auto-hide while empty when Archived is **Hidden** (the default).
Toolbar controls live in two menus, shared by both layouts:
* **Filter** - Project, PR state, Agent, Pinned (All workspaces / Pinned / Unpinned), and Device. Active filters show a count badge and sync to the URL.
* **Display** - **Sort by**, the **Archived** window (Hidden, Past week, Past month, All), and, in Board view, **Lanes**: a checkbox per column to hide or show it. Lane visibility stays out of the URL and resets on restart.
## Restore a Workspace [#restore-a-workspace]
Right-click an archived card in the **Deleted** or **Merged** lane (or an archived row in List view) and choose **Restore**. Superset re-creates the worktree at its original path on its original branch and makes the workspace live again.
* Only committed work comes back; uncommitted and untracked changes were already lost when the workspace was deleted.
* Restore fails and the workspace stays archived if the branch no longer exists locally or on the remote.
* Restore is unavailable while the device is offline.
## Ahead/Behind Status [#aheadbehind-status]
For **local (branch-based) workspaces**, the sidebar shows how far the active branch is ahead or behind its remote branch:
* **↑N** - N commits ahead of remote (unpushed)
* **↓N** - N commits behind remote (needs pull/rebase)
## PR Status [#pr-status]
PR-based workspaces show pull request state in the sidebar.
Hover a workspace to see review status, CI checks, and GitHub links. If the branch has a deployment preview, you'll also see an **Open Preview** button.
A branch can have more than one PR. The badge shows a count; click it to list them, open one on GitHub, or remove a stale link. Right-click the workspace for **Remove PR Link** and **Restore PR Link**. Removals get an undo toast.
## Bulk Actions [#bulk-actions]
Select multiple workspaces within a project to act on them at once:
* **⌘-click** toggles a workspace in and out of the selection; **Shift-click** selects a range
* While workspaces are selected, the Projects header becomes a toolbar with **Move**, **Ungroup**, **Delete**, and **Clear**
* **Move** puts the selection into a new or existing group; **Ungroup** removes grouped members from their group
* Bulk delete previews every workspace and flags dirty or unpushed changes before you confirm
## Delete a Project [#delete-a-project]
Right-click a project in the sidebar and choose **Delete Project…**, or use **Delete project** in the project's settings. An organization owner or the owner of the device can delete a project.
* Choose the devices to delete it from. The dialog shows what other people have running on each device. If someone else has terminals or agents running, you type the project name to confirm.
* Deleting stops the project's terminals and agents and archives its workspaces. Worktrees stay on disk while the project can be restored.
* From the sidebar, **Hide from sidebar** removes the project only for you.
* Click **Undo** in the toast, or restore the project from **Settings → Projects → Recently deleted** for 30 days. After 30 days, Superset removes the project and its clean worktrees. Worktrees with uncommitted changes and the repository folder stay on disk.
* **Delete permanently** on the Recently deleted page removes the project now.
## Use Cases [#use-cases]
* **Parallel features** - Work on multiple features simultaneously
* **AI agents** - Run Claude Code in separate workspaces
* **Code review** - Review PRs while continuing your work
## Best Practices [#best-practices]
* Use descriptive branch names: `feature/auth`, `fix/login-bug`
* Don't work directly on `main`
* Delete workspaces after merging
---
# Superset CLI Reference
Source: https://docs.superset.sh/cli/cli-reference
Complete reference for Superset command-line interface, including commands and flags.
The CLI is currently in Beta. Commands and flags are still evolving. Make sure you're on the latest version of the CLI if you run into issues.
## Synopsis [#synopsis]
```text
superset [subcommand] [options]
```
Run `superset --help` for the top-level command list, or
`superset --help` for any group.
## Global options [#global-options]
These flags are accepted by every command:
| Flag | Env | Description |
| ----------------- | ------------------ | ------------------------------------------------------------------------------- |
| `--json` | | Print the data payload as formatted JSON. |
| `--quiet` | | One ID per line for arrays; the ID for single objects; JSON fallback otherwise. |
| `--api-key ` | `SUPERSET_API_KEY` | Use an API key instead of stored OAuth login. |
| `--help`, `-h` | | Show help for the current command. |
| `--version`, `-v` | | Print the version number and exit. |
***
## Commands [#commands]
### scripts [#scripts]
Reusable terminal launches. These are called terminal scripts in the app;
setup, run, and teardown entries in `.superset/config.json` are project
lifecycle scripts. The legacy `presets` command name remains an alias.
Add a terminal script to the desktop app on this machine. The desktop app must
have been launched once so its local database exists, and the CLI must have an
active organization so the script is imported into the correct v2 profile.
When iterating on one script, pass `--upsert` so each revision replaces the
last instead of piling up copies in the Scripts bar.
```bash
superset scripts add --name dev --command "bun run dev"
superset presets add --name services \
--command "docker compose up" --command "bun run dev" \
--execution-mode split-pane
superset scripts add --name "Open in GitHub" --command "gh pr view --web" --upsert
```
The created terminal script, including its generated ID.
List the terminal scripts on this machine with the id each other command
takes. `status` is `importing` or `deleting` while a change is waiting for the
desktop app to open or refocus with the same organization active. Scripts
created in the desktop app's Settings are stored in the app profile only and
do not appear here.
```bash
superset scripts list
superset scripts list --json
```
Change fields on an existing script. Unspecified fields keep their values, and
the desktop app updates its copy in place, so the script keeps its position in
the Scripts bar. Edits made in the desktop app's Settings do not flow back to
the CLI: an edit here replaces the app's copy with what `superset scripts list`
shows plus your changes.
```bash
superset scripts edit --command "gh pr view --web"
superset scripts edit --name "Open PR" --hidden
superset scripts edit --all-projects --no-hidden
```
Delete a script. The desktop app removes its copy the next time it opens or
refocuses with the same organization active (immediately when it is running);
until then the script lists with status `deleting`.
```bash
superset scripts delete
```
***
### auth [#auth]
Authentication and session inspection.
Authenticate via browser OAuth and store a session token at
`~/.superset/config.json`.
Single-org accounts are selected automatically. With multiple orgs and a
TTY, the CLI prompts; with multiple orgs and no TTY, you must pass
`--organization` or the command exits 1 listing the available slugs.
```bash
superset auth login
superset auth login --organization acme
```
To sign in with an API key (useful for CI or any environment where the
OAuth browser flow isn't an option), pass `--api-key`. The CLI validates
the key, stores it at `~/.superset/config.json`, and clears any prior
OAuth session.
```bash
superset auth login --api-key sk_live_…
superset auth login --api-key sk_live_… --organization acme
```
The newly authenticated user and active organization.
```text
◇ Authorized!
│ Satya Patel (you@example.com)
│ Organization: Acme
└ Logged in successfully.
```
```ts
{
userId: string;
organizationId: string;
organizationName: string;
}
```
Clear stored credentials: both an OAuth session and a stored API key.
Does not call the API and does not clear the active organization (your
preferred org persists across re-logins).
```bash
superset auth logout
```
A confirmation message.
```text
Logged out.
```
```ts
{ message: "Logged out." }
```
Show the current user, active organization, and auth source.
```bash
superset auth whoami
```
The current user and organization context.
```text
Signed in as Satya Patel (you@example.com)
Organization: Acme
Auth: Session (expires in 32 min)
```
```ts
{
userId: string;
email: string;
name: string;
organizationId: string;
organizationName: string;
authSource: "override" | "config" | "oauth";
}
```
***
### start [#start]
Start the local host server: the daemon the CLI and desktop app both
talk to when targeting this machine.
If a manifest exists and the PID is alive, returns the existing
instance's `{ pid, endpoint }`. Otherwise spawns the host server binary,
polls `/trpc/health.check` for up to 10 seconds, and writes the manifest.
Binds to `127.0.0.1` only.
```bash
superset start --daemon
```
The running host server.
```ts
// Freshly started
{
pid: number;
port: number;
organizationId: string;
}
// Already running
{
pid: number;
endpoint: string;
}
```
### stop [#stop]
Stop the local host server.
Sends SIGTERM, waits up to 10 seconds, sends SIGKILL if still alive, then
removes the manifest. If sending SIGTERM itself throws, the command errors
and the manifest is left in place.
The terminal daemon keeps running after the host server stops, so the next
`superset start` picks up the same terminals. With `--terminals`, the command
stops the host server first, then the terminal daemon, the same way. It
signals only the pid the daemon reports over its socket, never the pid in its
manifest, which can be stale. If the socket is missing or refuses the
connection, the manifest is removed without a signal. If the socket accepts
the connection but the daemon does not answer, the command errors after it
has stopped the host server, and leaves the daemon and its manifest in place.
```bash
superset stop
superset stop --terminals
```
The processes the command stopped, if any were running.
```ts
// Nothing running
{ running: false }
// Something stopped
{
pid: number | null; // host server; null if none was running
terminalDaemonPids: number[]; // empty without --terminals or if none was running
organizationId: string;
}
```
### status [#status]
Inspect the local host server.
`healthy` reflects a live `health.check` request (2-second timeout).
```bash
superset status
```
The host server state. Three shapes depending on what's running.
```ts
// No manifest
{ running: false; organizationId: string; hostId: string }
// Manifest exists but PID is dead
{
running: false;
stale: true;
pid: number;
organizationId: string;
hostId: string;
}
// Running
{
running: true;
healthy: boolean;
pid: number;
port: number;
endpoint: string;
organizationId: string;
hostId: string;
hostName: string;
uptimeSec: number;
}
```
### update [#update]
Update the Superset CLI and host server binary.
Downloads the matching `superset-.tar.gz` from GitHub Releases
and atomically replaces the install root. Only available in built
binaries; running from `bun run dev` errors out.
```bash
superset update # upgrade to the latest release
superset update --check # show current → target without installing
superset update --version 0.1.2 # install a specific version (up or down)
```
The current and target version, plus whether anything changed.
```text
Updated 0.1.4 → 0.1.5 (/Users/you/.local/share/superset)
```
```ts
// --check
{
current: string;
target: string;
upToDate: boolean;
pinned: boolean;
}
// install
{
current: string;
target: string;
updated: boolean;
installRoot?: string;
}
```
***
### organization (alias: `org`) [#organization-alias-org]
Manage which organization the CLI targets.
List organizations available to the current auth context. Marks the
active one.
Set the active organization in `~/.superset/config.json`.
```bash
superset organization switch acme
superset org switch org_…
```
List members in the active organization.
```bash
superset organization members list
superset org members list -s satya
```
***
### projects [#projects]
A project is a repository checked out on a host. Projects are host-owned:
each host serves the projects set up on that machine; there is no org-wide
listing. Workspaces branch off a host's checkout.
List projects on a host. Defaults to this machine; pass `--host ` for
another host.
Create a fresh project on a host. Two modes:
* **Clone**: pass `--clone ` and `--parent-dir`. The host clones the
repo into `//`.
* **Import**: pass `--import ` to register a repo that already exists
on disk.
Either way, the project is registered on the host with no workspaces yet;
create one with `superset ws create --project --name local --checkout local --local` (the
repo's checkout as it is) or `--branch ` (its own worktree).
`create` always creates a new cloud project, even if your org already has
one for the same Git URL. Use [`projects setup`](#superset-projects-setup-id)
when adopting an existing project on a fresh machine.
```bash
superset projects create --name "my-app" --local --clone https://github.com/org/my-app.git --parent-dir ~/code
superset projects create --name "my-app" --local --import ~/code/my-app
```
Adopt an existing project onto a host without creating a duplicate cloud
record. Counterpart to [`create`](#superset-projects-create) for the
"new machine, repo already in the org" case.
Find the project ID via [`projects list`](#superset-projects-list).
Idempotent: re-running against a project that's already set up at the same
path is a no-op.
```bash
# Pick an ID from `superset projects list`, then clone it onto this machine
superset projects setup 47c31b04-… --local --parent-dir ~/code
# Or register an existing local checkout
superset projects setup 47c31b04-… --local --import ~/code/my-app
```
***
### hosts [#hosts]
Discover hosts registered to the active organization. To control the
host server running on this machine, use [`start`](#start),
[`stop`](#stop), and [`status`](#status).
List hosts registered to the active organization. A machine registers
itself when `superset start` runs on it, or when you set it up over SSH
with [`hosts add`](#hosts).
```bash
superset hosts list
```
Set up a machine you can SSH into as a host, with nothing typed on it:
installs this CLI's version there, signs it in with a new API key sent over
ssh stdin, runs it as a user service, and waits for it to come online.
Running it again on the same target repairs only what is wrong.
The remote must be macOS or glibc Linux on x64 or arm64 (not Alpine or
Windows) and have `curl`. On Linux it also needs a valid `/etc/machine-id`,
and lingering (`loginctl enable-linger`) to keep running after you log out.
Install and sign in `gh` there to clone private repos.
```bash
superset hosts add me@build-box
superset hosts add build-box --name "Build box" --yes
```
Undo `hosts add`: stop the host over SSH and remove its service. If it finds
the API key `hosts add` created, it revokes it and signs the host out;
otherwise it leaves the host's sign-in alone. The CLI stays installed, and the
host stays listed (offline) until you delete it in Settings → Hosts.
```bash
superset hosts remove me@build-box
```
Set (or clear) the command used to wake a host.
```bash
superset hosts set-wake my-sandbox vercel sandbox resume my-box
superset hosts set-wake my-sandbox --clear
```
Wake a host by running its configured wake command locally, streaming its
output.
```bash
superset hosts wake my-sandbox
```
***
### workspaces (alias: `ws`) [#workspaces-alias-ws]
Workspaces use a shared project checkout, an isolated worktree, or a project-less session folder on a host.
**Routing:** when `--host` resolves to the local machine, the CLI calls
the host server directly over loopback HTTP: no cloud roundtrip, works
offline. Otherwise it routes through the cloud API and the relay.
If the resolved host is the local machine but the host server isn't
responding, the CLI errors out and points you at `superset start` rather
than silently falling through to the cloud.
List workspaces on a host. Defaults to this machine; pass `--host ` for
another host. Workspaces are host-owned; there is no org-wide listing (the
desktop app is the cross-host view). `projectName` falls back to the raw
project id when the host doesn't know the project's name.
Create a workspace on the target host. With `--project`, specify one of
`--checkout local`, `--branch`, `--pr`, or `--task` (`--branch` and `--pr` are mutually
exclusive). If you pass `--agent`, you must also pass `--prompt`. `--command`
runs a one-off shell command in the workspace directory and is independent of
`--agent`/`--prompt`. Pass either or both. `--model` and `--effort` require
`--agent`; see the [agent effort levels](#agent-effort-levels) below.
`--checkout local` shares the project's existing files, git index and checked-out branch.
It does not switch branches or run setup. Do not combine it with `--branch`, `--pr`,
`--base-branch`, or `--skip-branch-prefix`. Local creation requires a host that
supports local workspaces; older hosts reject it without creating a worktree.
`--local` selects this machine and is independent of `--checkout local`.
Pass `--session` explicitly to create a **session**: a project-less workspace backed
by a managed folder under `~/.superset/sessions`, initialized as its own git
repo. Sessions have no branch semantics, so `--branch`, `--pr`, `--task`,
`--base-branch`, `--checkout`, `--skip-branch-prefix`, and `--tag` are rejected, `--name` is
optional, and the output has no `alreadyExists` field. Host workspace creation
requires either `--project ` or `--session`; omitting both is an error.
```bash
superset workspaces create \
--project prj_… \
--name "fix-login-bug" \
--branch fix/login-bug \
--local
superset workspaces create \
--project prj_… \
--name "review-pr-123" \
--pr 123 \
--local
# Project-less session with an agent
superset workspaces create --session --local --agent claude --prompt "…"
# Tags group the workspace into sidebar folders — no folder setup needed
superset workspaces create --project prj_… --name "perf-spike" --branch perf/spike --local --tag perf
```
Archive one or more workspaces. Without `--host` or `--local`, this targets
cloud workspaces if your account has them, else this machine. The old name
`delete` remains an alias.
* **Cloud workspace:** the sandbox stops within a minute and is deleted after
7 days. A restore within those 7 days keeps its disk; after that, the
workspace starts again from a fresh sandbox.
* **Worktree workspace on a host:** its folder is removed, with any uncommitted
changes. Its branch stays, so a restore brings back only committed work. A
workspace that shares the project's own checkout keeps that folder.
`deleted` lists the archived IDs; the field keeps its old name so existing
scripts still work.
```bash
superset workspaces archive ws_a ws_b ws_c
```
Put a cloud workspace to sleep. Its sandbox stops, every terminal and agent in
it ends, and it costs storage only. Files are kept, and opening the workspace
wakes it. An agent can run this as its last step, inside its own workspace.
```bash
superset workspaces sleep ws_a
```
Show details for a single workspace on its host. `--field` is handy in
scripts: `superset workspaces get --field worktreePath`.
```bash
superset workspaces get ws_…
superset workspaces get --field branch # inside a workspace
```
Update a workspace on its host (default: this machine). `--tag` replaces the
whole tag set: tagging is how workspaces group into sidebar folders, so
retagging moves the workspace between folders.
```bash
superset workspaces update ws_… --name "better-name"
superset workspaces update ws_… --task-id tsk_…
superset workspaces update ws_… --tag perf --tag infra
superset workspaces update ws_… --clear-task
```
Open a workspace in the Superset desktop app.
```bash
superset workspaces open ws_…
superset workspaces open ws_… --print
```
#### Opening a specific session [#opening-a-specific-session]
`workspaces open` targets a workspace, not a session. Terminal sessions started
with [`agents create`](#superset-agents-create) are automatically adopted into
panes while their workspace is open. Opening the workspace later also creates
panes for running terminal sessions that aren't already attached, without
stealing focus from the active tab. `workspaces open` can't focus a specific
session, so use a session deep link when focus matters. The same deep link
creates or focuses the pane for a Superset chat session. Choose the query param
from the session `kind` returned by `agents create`:
| `kind` | Example agents | Query param |
| ---------- | ----------------- | ---------------------------- |
| `chat` | `superset` | `?chatSessionId=` |
| `terminal` | `claude`, `codex` | `?terminalId=` |
```bash
# Run the agent with --json, then pull kind + sessionId out of the payload:
session=$(superset agents create --workspace ws_… --agent claude --prompt "…" --json)
kind=$(echo "$session" | jq -r '.kind') # "chat" or "terminal"
sessionId=$(echo "$session" | jq -r '.sessionId')
# Open the session using the query param that matches its kind:
# chat session (kind: "chat")
open "superset://v2-workspace/?chatSessionId=$sessionId"
# terminal session (kind: "terminal")
open "superset://v2-workspace/?terminalId=$sessionId"
```
Append `&focusRequestId=` to force a re-focus when opening the same link
more than once. The session must belong to the workspace in the URL. On
Linux/Windows substitute your platform's URL opener (`xdg-open`, `start`) for
`open`.
***
### agents [#agents]
Agents are terminal-agent rows configured on a host (the same rows shown in
Settings → Agents on that machine). Each row stores a `command`, `args`,
prompt-transport mode, and environment used to launch the agent in a fresh
terminal session inside a workspace.
List agents configured on a host. First call on a fresh host seeds the
bundled defaults.
```bash
superset agents list --local
superset agents list --host host_…
```
Create an agent session in an existing workspace on its host (default: this
machine): starts the named preset (or HostAgentConfig instance) in a fresh
terminal session there.
```bash
superset agents create --workspace ws_… --agent claude --model sonnet --effort high --prompt "Audit the login flow"
superset agents create --workspace ws_… --agent codex --prompt "Review this diff" --attachment ./trace.log
# Restore a killed agent session by the agent's own session id
superset agents create --workspace ws_… --agent claude --resume-session 0b7c…
# Fork a session: a new Claude session with the same conversation
superset agents create --workspace ws_… --agent claude --fork-session 0b7c…
# Hand a terminal's recent output to a different agent
superset agents create --workspace ws_… --agent codex --from-terminal term_…
superset agents create --workspace ws_… --agent codex --from-terminal term_… --context-chars 12000
```
Pass at most one of `--resume-session`, `--fork-session`, and
`--from-terminal`. See [Fork and hand off sessions](/agent-sessions#fork-and-hand-off-sessions)
for which agents can fork and what a handoff sends.
Read the agent's saved transcript, beyond the visible screen returned by
`terminals read`. Without `--host` or `--local`, the target defaults to cloud
when your account has cloud workspaces, otherwise this machine. The command
fails if Superset cannot read a transcript for that terminal.
```bash
superset agents read --local --workspace --terminal
```
The transcript object in JSON mode, or its text in human-readable mode.
Block until an agent reaches a state, instead of polling `terminals read`.
Returns at once if it is already there. Exits 1 on timeout, and at once if the
agent exits.
```bash
T=$(superset agents create --workspace ws_… --agent claude --prompt "Add a /health route" --json | jq -r .sessionId)
superset agents wait --workspace ws_… --terminal "$T"
```
```ts
{
terminalId: string;
state: "starting" | "working" | "blocked" | "idle";
lastEventType: string | null;
}
```
Explain why an agent shows its state: its last hook event and when it arrived,
how an ended session ended, or that no hook has arrived (an agent Superset
can't see). Useful when `agents wait` or `panes list` shows something
unexpected.
```text
claude is idle.
Why: its recorded event is Stop, which means its turn ended: it finished, or it was interrupted.
The last hook arrived 1 second ago; the session started 2 seconds ago.
```
```ts
{
terminalId: string;
state: "starting" | "working" | "blocked" | "idle" | "exited" | "none";
because: string;
details: string[];
lastEventType: string | null;
lastEventAt: number | null;
}
```
#### Agent models [#agent-models]
Model is an explicit override for one launch. If you omit `--model`, Superset
passes no model flag and the agent uses its own configured default. Ids match
the desktop model picker: Claude takes a family alias (`fable`, `opus`,
`sonnet`, `haiku`) that tracks the newest release, or a pinned id such as
`claude-opus-5-5` or `claude-sonnet-5-5`. Codex includes `gpt-6-astra`, `gpt-6-sol`, and `gpt-6-luna`. The host rejects an unknown id before launching the agent,
and the error names every id that agent accepts. Agents without a model
picker, including Superset chat, reject an explicit model override.
#### Agent effort levels [#agent-effort-levels]
Effort is an explicit override for one launch. If you omit `--effort`,
Superset passes no effort flag and the agent uses its own configured default.
The host rejects unsupported values before launching the agent.
| Agent | Supported levels |
| ---------- | -------------------------------------------------------------------------------- |
| Claude | `low`, `medium`, `high`, `xhigh`, `max` |
| Amp | `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` |
| Codex | `low`, `medium`, `high`, `xhigh`; `max` and `ultra` depend on the selected model |
| Mastracode | `off`, `low`, `medium`, `high`, `xhigh` |
| Pi | `off`, `minimal`, `low`, `medium`, `high`, `xhigh` |
| Copilot | `low`, `medium`, `high`, `xhigh` |
GPT-6 Astra and GPT-6 Sol support `max` and `ultra`; GPT-6 Luna supports `max`.
Other agents, including Superset chat, currently use their own default and
reject an explicit effort override.
***
### terminals (alias: `term`) [#terminals-alias-term]
Terminals are PTY sessions on a host, scoped to a workspace. Create one to run
a one-off command in a worktree or to open an interactive shell.
Create a terminal session in an existing workspace on its host (default: this
machine): opens a fresh PTY in the worktree, optionally running a command.
```bash
superset terminals create --workspace ws_… --command "bun install && bun test"
superset terminals create --workspace ws_…
```
List the live terminal sessions in a workspace. Presence in the list means the
PTY exists, not that an agent inside it is working or idle.
Read a terminal's current screen back as text without mutating the session.
```bash
superset terminals read --workspace ws_… --terminal term_… --max-lines 240
```
Send a follow-up message or key presses to a terminal already running in a
workspace, e.g. to give an agent new instructions mid-session, approve a
prompt, or interrupt it.
```bash
superset terminals send --workspace ws_… --terminal term_… --text "Now add a test" --wait
superset terminals send --workspace ws_… --terminal term_… --keys esc
```
Block until a terminal's screen matches a pattern, e.g. a dev server's
"listening on". `matched` is the text the pattern matched, which can span
lines. Exits 1 on timeout, or at once if the terminal exits first.
```bash
superset terminals wait --workspace ws_… --terminal term_… --match "listening on :\d+"
```
```ts
{
terminalId: string;
matched: string;
}
```
Attach this shell to a running terminal. `Ctrl+]` detaches; the terminal keeps running. Needs an interactive terminal and refuses
to run in CI.
```bash
superset terminals attach --workspace ws_… --terminal term_…
superset terminals attach --ssh me@build-box --workspace ws_… --terminal term_…
```
Close (dispose) a terminal running in a workspace. This ends the session.
***
### snapshot [#snapshot]
One read of a host: every workspace, its live terminals, the agent in each with
its state, and the pane layout when the desktop app is attached. Use it instead
of listing terminals and panes workspace by workspace. An unknown `--workspace`
is an error.
```text
acme-web / health-check [health-check] ws_…
terminal ebed… "/health route README section" claude · working
terminal 63c9…
```
```ts
{
workspaces: Array<{
id: string; name: string; project: string | null; branch: string | null;
terminals: Array<{ id: string; title: string | null; agent: { id: string; state: "starting" | "working" | "blocked" | "idle" } | null }>;
layout: PaneLayout | null; // as in `panes list`; null without a desktop app
layoutError: string | null; // set when a desktop app is attached but the layout could not be read
}>;
}
```
### panes [#panes]
Script the pane layout of a workspace in the desktop app. Commands go to the
host, then to the desktop app, which applies them to the live layout. Works for
workspaces on the machine running the desktop app. Only `focus` moves focus.
Tabs and the split tree. `row` splits are side by side and `column` splits are
stacked, as in CSS flexbox; `ratio` is the first pane's share. Each terminal
pane carries its title and the agent running in it with its state.
```text
row 50/50
pane-5f00… terminal terminal 63c9… (active)
pane-03e1… terminal "/health route README section" claude · working terminal ebed…
```
```ts
{
activeTabId: string | null;
tabs: Array<{
id: string; active: boolean; activePaneId: string | null;
layout: PaneNode; // { type: "split", direction: "row" | "column", ratio, first, second } | { type: "pane", paneId }
panes: Array<{
id: string; kind: string; title: string | null; terminalId: string | null; active: boolean;
terminalTitle?: string | null;
agent?: { id: string; state: "starting" | "working" | "blocked" | "idle" } | null;
}>;
}>;
}
```
Open a new tab with a terminal pane, without moving focus.
Split a pane and show a terminal in the new half.
Set a pane's share of the split it sits in. `superset panes equalize --workspace [--tab ]` evens out every split instead.
Move a pane. A tab left empty closes. `superset panes swap --workspace --pane A --with B` exchanges two panes, and `superset panes focus --workspace --pane P` focuses one.
Close a pane and end its terminal, as the close button in the app does.
### notifications [#notifications]
Show a desktop notification. Run from a Superset terminal, clicking it opens
that terminal, so an agent can say "tests pass" and take you straight back.
With `--host`, pass `--workspace` and `--terminal` for a click target; without
them the click only brings the app forward.
```bash
superset notifications show "Tests pass" --body "12 passed" --sound
```
### browser [#browser]
Drive a workspace's [in-app browser](/browser) panes: open and navigate URLs,
screenshot, read console, evaluate JavaScript, and get a raw Chrome DevTools
Protocol endpoint for click/type/scroll automation. Every operation runs in the
pane the user sees, against the browser's real session. Browser panes live in
the desktop app, so a standalone host with no desktop attached has no panes and
these commands error. A `paneId` is scoped to its workspace; pass the same
`--workspace` it was opened under. See the [`browser` skill](/skills) for the
agent-facing protocol.
List the browser panes open in a workspace.
Open a URL in a browser pane and return its `paneId`. Requires the workspace to
be visible in the desktop app (the renderer creates the pane).
```bash
superset browser open --workspace ws_… --url http://localhost:3000 --target new-tab
```
Point an existing pane at a new URL. `file://`, `chrome://`, and custom schemes
are refused.
Capture a PNG screenshot of the pane's page.
Evaluate JavaScript in the page and return the result for
reading or nudging the DOM.
```bash
superset browser eval --workspace ws_… --pane pane_… \
--code "document.querySelector('h1')?.textContent"
```
Read the pane's captured console output.
Print a raw Chrome DevTools Protocol WebSocket endpoint for the pane, for
browser-use / Playwright-class tools (mouse, keyboard, scroll, DOM, network).
The URL embeds an auth token; treat it as a secret.
***
### pages [#pages]
Publish and manage [Pages](/pages) in the active organization.
Without `--limit` or `--cursor`, fetches all matching pages and returns a plain
array. Either pagination flag selects one batch and returns
`{ items, nextCursor }`; `nextCursor` is null at the end. A cursor without a
limit uses 50 rows per batch. Pages are ordered newest-created first.
`--quiet` prints page IDs in either mode. Linked workspaces appear in the
WORKSPACE column and in each row's `workspaceLinks`.
```bash
superset pages list --workspace '' --search onboarding --json
superset pages list --workspace '' --limit 20 --json
superset pages list --workspace '' --limit 20 --cursor '' --json
```
Publishing the same entry path from the same workspace adds a version to the
existing page. Without a workspace, keep the returned ID and pass `--page` on
later publishes to avoid creating another page. Existing visibility is
preserved unless explicitly supplied.
Publishing does not open the page in the desktop.
```bash
superset pages publish report.html --title "Weekly report" --visibility everyone
superset pages publish report.html --page --label "Addressed feedback"
```
Page metadata including `id`, `title`, `version`, and `url`, plus `unanchored`,
`watching`, and asset upload/reuse counts. Unlinked publishes include a
`republish` command. When the publish tries to register the session for comments, `watchNote` says whether it worked.
Delete a page and every version. Interactive terminals ask for confirmation
unless `--yes` is passed; non-interactive input does not prompt.
Read what viewers stored with `window.superset.storage` on a page.
Without `--key`, lists each key with its record count (KEY, RECORDS, UPDATED).
With `--key`, lists each person's value for that key (NAME, VALUE, UPDATED).
On a `just_me` page only the creator can read storage. On an `org` or
`everyone` page, members of the page's organization can read it, even when the
page is public.
```bash
superset pages storage weekly-report
superset pages storage weekly-report --key votes --json
```
***
### tasks (alias: `t`) [#tasks-alias-t]
Tasks are units of work in your organization's task tracker. When the
organization tracks tasks in Linear (an owner's setting), these commands work on
its Linear issues through your own Linear connection; otherwise on Superset
tasks. A command works on one tracker only: in an organization that tracks in
Linear, Superset tasks are not listed or resolved, and the reverse. Pass
`--tracker superset|linear` to reach the other one for a single command.
List tasks in the active organization.
```bash
superset tasks list --assignee-me
superset t list -s "auth" --json
```
Get a task by ID or slug.
```bash
superset tasks get tsk_…
superset tasks get fix-login-bug
```
Create a task.
```bash
superset tasks create --title "Audit auth flow" --priority high
```
Update a task. Same fields as `create`, all optional.
```bash
superset tasks update fix-login-bug --priority urgent
```
Delete one or more tasks. Linear issues are archived.
```bash
superset tasks delete tsk_a tsk_b
```
List task statuses in the active organization. Superset status IDs work with
`tasks list --status`, `tasks create --status-id` and `tasks update --status-id`.
Linear statuses belong to a team: pass their names or IDs to `--status-id` on
create and update; `tasks list --status` takes a category (`active`, `started`, …)
for Linear.
```bash
superset tasks statuses list
```
***
### automations (alias: `auto`) [#automations-alias-auto]
Scheduled agent runs. Schedules use RFC 5545 RRULE bodies, e.g.
`FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=9;BYMINUTE=0`.
List automations in the active organization.
Get an automation's metadata. The prompt body is omitted. Use
[`automations prompt get`](#superset-automations-prompt-get-id) to read it.
Use [`automations logs`](#superset-automations-logs-id) for run history.
Create an automation. Automations are a Pro feature: `create`, `run`, and
`resume` need a Pro or Enterprise subscription on the active organization and
fail with `Automations require the Pro plan.` otherwise. Provide `--prompt` or
`--prompt-file`; if both are present, the inline `--prompt` value is used. A `--project` or `--workspace`
must exist on the target host; the CLI verifies this before creating the
automation. Omit both for **session mode**: each run creates a project-less
session workspace on the target host.
Every run's created workspace carries the automation's tags, which group it
into the matching sidebar folders. By default automations are tagged
`automation`, so their runs collect in an **automation** folder per project;
pass `--tag` to file runs elsewhere.
```bash
superset automations create \
--name "Weekday triage" \
--project prj_… \
--workspace ws_… \
--rrule "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=9;BYMINUTE=0" \
--prompt-file ./prompts/triage.md
```
Update an automation's metadata (name, schedule, agent, host). All flags
optional. Omitting a flag preserves the existing value: `undefined` means
"no change", not "clear". Use [`automations prompt get`](#superset-automations-prompt-get-id)
or [`automations prompt set`](#superset-automations-prompt-set-id) to read or
replace the prompt body.
Print an automation's prompt body to stdout. The output is the raw prompt
with no trailing newline added, so `prompt get` and `prompt set` round-trip
byte-exactly.
```bash
# Read to a file
superset automations prompt get aut_… > prompt.md
# Verify a push landed
superset automations prompt get aut_… | diff - ./prompt.md
```
Replace an automation's prompt body. The new prompt fully overwrites the
old one.
```bash
# Write from file
superset automations prompt set aut_… --from-file ./prompt.md
# Write from stdin
cat ./prompt.md | superset automations prompt set aut_… --from-file -
```
Delete an automation.
```bash
superset automations delete aut_…
```
Pause an automation (sets `enabled: false`).
```bash
superset automations pause aut_…
```
Resume an automation (sets `enabled: true`). The API recomputes
`nextRunAt` on resume.
```bash
superset automations resume aut_…
```
Dispatch an automation immediately. Does not wait for completion.
```bash
superset automations run aut_…
```
List recent runs for an automation.
```bash
superset automations logs aut_…
```
***
### settings [#settings]
Read and update the Superset desktop app's settings on this machine:
behavior, git, notifications, terminal, terminal/editor appearance, and the
app theme. These commands work offline and don't require login.
After every write the CLI nudges the running desktop app, which refreshes
immediately, themes included, no restart (the command output confirms
with "refreshed immediately" / "applied to the running desktop app").
Without a running app (or on older app versions) settings apply on next
window focus and theme changes on next launch. Git settings
(`branchPrefixMode`, `branchPrefixCustom`, `worktreeBaseDir`) are
host-wide and written through the local host service, so the desktop app
or `superset start` must be running for those.
List every settable key with its current value, default, and allowed values.
`isSet: false` means the app is using its built-in default.
```bash
superset settings list
```
Print the effective value of one setting (falls back to the app default
when unset).
```bash
superset settings get terminalFontSize
```
Set a setting. Booleans accept `true/false/on/off/1/0/yes/no`; enums and
numeric ranges are validated the same way the desktop settings UI validates
them.
```bash
superset settings set confirmOnQuit false
superset settings set terminalFontSize 16
superset settings set defaultEditor cursor
superset settings set selectedRingtoneId ping
```
Reset a setting to the app default.
```bash
superset settings reset terminalFontSize
```
List available themes: `system` (follows OS appearance), the built-ins
(`dark`, `light`, `monokai`, `catppuccin-latte`, `solarized-light`,
`vellum`), and any custom themes imported through the app.
```bash
superset settings theme list
```
Print the active theme.
```bash
superset settings theme get
```
Export a theme's full JSON definition, the starting point for creating a
custom theme: export a built-in, edit the colors, then import it.
```bash
superset settings theme export dark --out my-theme.json
```
Import custom themes, using the same validation and normalization as the
desktop's Appearance UI (ids are slugified; missing colors are filled from
the built-in base theme; reserved ids like `dark` are rejected).
Re-importing an id replaces that custom theme.
```bash
superset settings theme export dark --out my-theme.json
# edit my-theme.json (id, name, ui/terminal/editor colors)
superset settings theme import my-theme.json
superset settings theme set my-theme
```
Remove a custom theme. If it was the active theme (or a system light/dark
mapping), that reference falls back to the default.
```bash
superset settings theme remove my-theme
```
Set the active theme and/or the system light/dark mappings. A running
desktop app restyles live; without one the theme applies on next launch.
(On app versions without live reload, quit the app first, then set, then
relaunch, or the app may overwrite the change.)
```bash
superset settings theme set monokai
superset settings theme set system --system-light light --system-dark monokai
```
***
### completion [#completion]
Shell completion for bash and zsh, generated from the installed version's
command tree, so it never drifts from what the binary accepts.
Prints the script to stdout, byte for byte, in every output mode: `--json`,
`--quiet` and agent environments do not wrap it. The script completes command
names at every level and walks through an alias already typed
(`superset ws cr`), each command's flags and their aliases, enum values
for flags (`--priority=u` included) and arguments, and the global
options.
```bash
# This shell session
source <(superset completion zsh)
eval "$(superset completion bash)" # bash 3.2 (macOS's /bin/bash) cannot source a process substitution
# Every session: put the line above in ~/.zshrc or ~/.bashrc, or for zsh
# install the script on fpath so compinit autoloads it
superset completion zsh > ~/.zfunc/_superset # with fpath=(~/.zfunc $fpath) before compinit
```
### schema [#schema]
Prints every command, option and argument as JSON, for tooling that must not
parse `--help`. Commands hidden from this run (internal-only, or unavailable
in a cloud workspace) are left out, as they are from `--help`. Commands and
options are sorted and absent fields are omitted, so the output of two
versions diffs cleanly.
```bash
superset schema | jq '.commands[] | select(.path == ["terminals"]) | .commands[].path'
```
```ts
{
name: "superset";
version: string;
globalOptions: SchemaOption[];
commands: SchemaCommand[];
}
// SchemaCommand
{
path: string[]; // e.g. ["terminals", "read"]
description?: string;
aliases?: string[];
options: SchemaOption[];
args: SchemaArg[];
commands: SchemaCommand[]; // empty for a leaf command
}
// SchemaOption
{
name: string; // flag name without the dashes
aliases: string[];
type: "string" | "number" | "boolean";
required: boolean;
description?: string;
default?: unknown;
enum?: string[];
variadic?: true;
int?: true;
min?: number;
max?: number;
env?: string; // environment variable that can supply the value
}
// SchemaArg
{
name: string;
required: boolean;
description?: string;
enum?: string[];
variadic?: true;
}
```
### config [#config]
Inspect the CLI's local config file: `config.json` under `~/.superset`, or
under `$SUPERSET_HOME_DIR` when that is set.
Validates the file before a hand edit or a bad restore surfaces as a
confusing auth failure: JSON syntax, the shape of `auth`, `apiKey` and
`organizationId`, an expired token, and keys this version does not read.
An error exits 1; a warning does not. A missing file is not an error, it
only means nobody has logged in yet.
```bash
superset config check
superset config check --json
```
```ts
{
path: string;
exists: boolean;
valid: boolean; // false when any issue is an error
loggedIn: boolean; // the file holds a usable credential
issues: { severity: "error" | "warning"; message: string }[];
}
```
***
## Output modes [#output-modes]
**JSON mode** (`--json`): raw payloads. Lists print arrays, get/create/update
print objects, delete prints summary objects. No `{ "data": ... }` wrapper.
Empty results print `null`.
**Quiet mode** (`--quiet`): IDs only. Arrays of objects with an `id` field
print one ID per line; single objects print their `id`; everything else
falls back to JSON.
When `CLAUDE_CODE`, `CLAUDECODE`, `CLAUDE_CODE_ENTRYPOINT`, `CODEX_CLI`,
`GEMINI_CLI`, `SUPERSET_AGENT`, or `CI` is set to a non-empty value, output
defaults to JSON unless `--quiet` is provided.
---
# Environment variables
Source: https://docs.superset.sh/cli/env-vars
Complete reference for environment variables that control Superset CLI behavior.
The Superset CLI supports the following environment variables to control
its behavior. Set them in your shell before running `superset`, or
export them from your shell profile (`~/.zshrc`, `~/.bashrc`) or your
CI environment to apply them across every session.
| Variable | Description |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SUPERSET_API_KEY` | API key (`sk_live_…` / `sk_test_…`) used in place of stored OAuth login. Equivalent to `--api-key`. |
| `SUPERSET_HOME_DIR` | Directory the CLI uses for `config.json` and the host server tree. Default: `~/.superset`. Shared with the desktop app. |
| `GH_TOKEN` / `GITHUB_TOKEN` | Read by the `gh` CLI the host server shells out to for PR checkout and metadata. Set this for sandboxes or CI instead of running `gh auth login` interactively. |
The standalone install script also reads:
| Variable | Description |
| ------------------ | --------------------------------------------------------------------------------------------------- |
| `SUPERSET_HOME` | Install root for the standalone CLI and host binary. Default: `~/superset`. |
| `SUPERSET_VERSION` | Release tag to install. Default: `latest`, which resolves through the rolling `cli-latest` release. |
---
# Getting Started
Source: https://docs.superset.sh/cli/getting-started
Install the Superset CLI, sign in, and run your first commands.
The CLI is currently in Beta. Commands and flags are still evolving. Make sure you're on the latest version of the CLI if you run into issues.
The Superset CLI (`superset`) is a single static binary that drives the same
backend as the desktop app. Use it to manage workspaces, tasks, automations,
and the local host server from your terminal or from CI.
## Install [#install]
### Desktop app [#desktop-app]
The desktop app includes the Superset CLI. When the app launches, it writes
an app-managed shim at `~/.superset/bin/superset`, and Superset terminals
prepend `~/.superset/bin` to `PATH` automatically.
To use the bundled CLI from a normal shell, add the directory to your shell
profile:
```bash
export PATH="$HOME/.superset/bin:$PATH"
```
### Standalone install [#standalone-install]
```bash
curl -fsSL https://superset.sh/cli/install.sh | sh
```
The script auto-detects your platform (macOS on Apple Silicon or Intel, Linux on
x64 or arm64), installs Superset under `~/superset` by default, and adds
`~/superset/bin` to your shell `PATH`.
### Homebrew [#homebrew]
```bash
brew install superset-sh/tap/superset
```
## Sign in [#sign-in]
```bash
superset auth login
```
The CLI starts a loopback callback server on `127.0.0.1:51789` (or `51790`
through `51793` if earlier ports are busy), opens your browser to the
consent page, and stores a session token at `~/.superset/config.json`.
If you belong to multiple organizations, you'll be prompted to pick one. To
skip the prompt and pick directly:
```bash
superset auth login --organization acme
```
For CI or other non-interactive environments (where there's no browser to
complete the OAuth flow), use an API key instead. You can either store it
once with `auth login --api-key`:
```bash
superset auth login --api-key sk_live_…
superset auth whoami
```
…or set `SUPERSET_API_KEY` per-invocation without writing anything to disk:
```bash
export SUPERSET_API_KEY=sk_live_…
superset auth whoami
```
API keys are issued from the **Settings → API Keys** page in the desktop app.
## Verify your session [#verify-your-session]
```bash
superset auth whoami
```
```text
Signed in as Satya Patel (you@example.com)
Organization: Acme
Auth: Session (expires in 32 min)
```
## Explore interactively [#explore-interactively]
Bare `superset` in a terminal opens an interactive command browser:
arrow-key through the commands, read their flags, and fill in required
inputs with guided prompts. The confirmation screen shows the exact
command before running it. `superset --help` prints the same catalog as
static, grouped help. Agents and CI always get static help; the browser
never opens there.
## Run your first commands [#run-your-first-commands]
List the projects in your organization:
```bash
superset projects list
```
If your repo isn't there yet, register it on this machine. Clone from a
Git URL or import an existing checkout:
```bash
# Clone from a URL
superset projects create --name "my-app" --local \
--clone https://github.com/org/my-app.git \
--parent-dir ~/code
# Or register an existing local checkout
superset projects create --name "my-app" --local --import ~/code/my-app
```
If the project already exists in your org but isn't on this machine,
attach to it instead of creating a duplicate:
```bash
superset projects setup --local --parent-dir ~/code
```
Then create a workspace against it:
```bash
superset workspaces create \
--project prj_… \
--name "fix-login-bug" \
--branch fix/login-bug \
--local
```
Trigger an automation immediately:
```bash
superset automations list
superset automations run aut_…
superset automations logs aut_…
```
## Output modes [#output-modes]
Every command prints a TTY-friendly view by default. Two flags switch the
shape of the output for scripting:
| Flag | Output |
| --------- | ------------------------------------------------------------------------------------------- |
| `--json` | The data payload as formatted JSON. No envelope. |
| `--quiet` | One ID per line for arrays of objects with `id`; the ID for single objects; JSON otherwise. |
```bash
superset tasks list --status in_progress --json | jq '.[].title'
superset workspaces list --quiet | xargs -L1 superset workspaces archive
```
When the CLI detects an agent or CI environment (`CLAUDE_CODE`,
`CLAUDECODE`, `CLAUDE_CODE_ENTRYPOINT`, `CODEX_CLI`, `GEMINI_CLI`,
`SUPERSET_AGENT`, or `CI` set to a non-empty value), it defaults to JSON
output unless you pass `--quiet`.
## Local vs. remote hosts [#local-vs-remote-hosts]
Commands that touch a host accept `--host ` to pick which host handles
the request, or `--local` for this machine. Local-targeted calls go
straight to the host server over loopback (offline-friendly); remote
calls route through the cloud API and the relay.
```bash
superset hosts list
superset workspaces list # this machine
superset workspaces list --host h_… # another host
```
Every host-scoped command targets exactly one host. Reads
(`workspaces list`, `projects list`) default to this machine; mutating
host commands (`projects create`, `projects setup`, `workspaces create`)
require an explicit `--host` or `--local`; there's no default. There is
no org-wide listing; the desktop app is the cross-host view.
## Where state lives [#where-state-lives]
```text
~/.superset/config.json # auth, active organization
~/.superset/host//manifest.json # host server endpoint + token
~/.superset/host//host.db # local host server DB
```
`SUPERSET_HOME_DIR` relocates the whole tree, matching the desktop app.
## Next steps [#next-steps]
Continue to the [CLI reference](/cli/cli-reference) for every command,
flag, and output shape.
---
# Host Server
Source: https://docs.superset.sh/cli/host-server
Set up the daemon the CLI and desktop app talk to when targeting the local machine.
The `superset start` command runs a headless HTTP server that any Superset desktop app or CLI can communicate with.
It manages workspaces, ports, and agent runs on the machine it's running on. The desktop app starts it automatically; on a CLI-only or headless machine you start it yourself.
If you installed the desktop app, it already includes the CLI and installs a
`~/.superset/bin/superset` shim on app launch. Superset terminals prepend
that directory to `PATH` automatically. On a headless machine, use the
standalone installer from [Getting Started](/cli/getting-started).
## Prerequisites [#prerequisites]
`git` and `gh` need to be on your `PATH`. `git` handles clone, worktree, and branch ops; `gh` handles PR checkout and metadata.
```bash
gh auth login
```
The host server reuses your existing `gh` auth. For sandboxes or CI, set `GH_TOKEN` (or `GITHUB_TOKEN`) instead of running `gh auth login`. `gh` picks it up automatically.
### Agent CLIs (optional) [#agent-clis-optional]
If you plan to run AI agents inside workspaces, install whichever agent CLIs you want available. The host server launches them based on which are on your `PATH`:
| Agent | Install |
| ------------ | ------------------------------------------------ |
| Claude Code | `npm install -g @anthropic-ai/claude-code` |
| Codex | `npm install -g @openai/codex` |
| Cursor Agent | install via Cursor's website |
| Amp | `npm install -g @sourcegraph/amp` |
| Gemini CLI | `npm install -g @google/gemini-cli` |
| OpenCode | see [opencode.ai/docs](https://opencode.ai/docs) |
None are required to start the host server or create workspaces. Install only what you plan to run.
## Authenticate the Superset CLI [#authenticate-the-superset-cli]
The host server starts under your Superset session. If you haven't already:
```bash
superset auth login
```
See [Getting Started](/cli/getting-started) for the full sign-in flow,
including API-key auth for CI.
## Start the host server [#start-the-host-server]
```bash
superset start --daemon
```
Spawns the daemon in the background and writes a manifest at
`~/.superset/host//manifest.json` so other clients can find
it. Binds to `127.0.0.1` only.
Verify it's healthy:
```bash
superset status
```
### Keep it updated [#keep-it-updated]
Automatic updates are off by default. To turn them on, start the host with
`--auto-update`:
```bash
superset start --daemon --auto-update
```
* `--auto-update` requires `--daemon`.
* The first check runs one hour after start, then every hour. A newer release
installs, and the host restarts with its health check and rollback.
Terminals reconnect after the restart.
* Updates never downgrade the host. A release that fails its health check is
skipped on later automatic checks; `superset update` can still install it.
* The flag applies to a new start only. To change it, stop the host and start
it again.
If an update fails with a permission error on `superset.update-lock`, the host
user cannot write the directory that contains the install. The error names the
install path, the lock path, and the user. Give that user ownership of the
install and its parent directory, or reinstall as that user.
### Run it under systemd [#run-it-under-systemd]
On a server, let systemd start the host server at boot and restart it on
failure. Run `superset start` without `--daemon` so systemd tracks the
process:
```ini
# /etc/systemd/system/superset-host.service
[Unit]
Description=Superset host server
After=network-online.target
Wants=network-online.target
[Service]
User=
ExecStart=/home//superset/bin/superset start
Restart=on-failure
KillMode=process
[Install]
WantedBy=multi-user.target
```
Keep `KillMode=process`. Other kill modes stop the terminal daemon, and with
it every terminal and agent, whenever the service stops or restarts. The
terminal daemon keeps running after the service stops, so the next start
picks up the same terminals.
This setup needs a CLI released after 1.30.2. With 1.30.2 and older,
`systemctl restart` hangs until systemd kills the CLI, and the old host
keeps running.
```bash
sudo systemctl daemon-reload
sudo systemctl enable --now superset-host
```
To end every terminal and agent too, stop the unit first, then stop the
terminal daemon. If you run `superset stop` while the unit is active,
systemd starts the host again.
```bash
sudo systemctl stop superset-host
superset stop --terminals
```
## Getting started [#getting-started]
### Create or adopt a project [#create-or-adopt-a-project]
A workspace branches off a project: a repo registered with Superset.
Each repo gets one cloud project record, shared across the organization.
The first machine to register the repo runs `projects create`; every
machine after that uses `projects setup` to attach to the existing
project instead of creating a duplicate.
Start by checking what's already in your org:
```bash
superset projects list
```
#### First machine: `projects create` [#first-machine-projects-create]
If the project doesn't exist yet, clone a remote repo or import an
existing local one:
```bash
# Clone from a Git URL
superset projects create \
--name "My Project" \
--local \
--clone https://github.com/org/repo.git \
--parent-dir ~/code
# Or import a repo that's already on disk
superset projects create \
--name "My Project" \
--local \
--import ~/code/existing-repo
```
The host server clones (or registers) the repo, creates the cloud project
record, and ensures the main workspace.
#### Subsequent machines: `projects setup ` [#subsequent-machines-projects-setup-id]
If a previous machine of yours already created the project, adopt it
instead of running `create` again: `create` would register a second,
unrelated project for the same repo. Projects are host-owned, so pick the
ID from a machine that has it (`projects list --host `), then:
```bash
# Clone the project's repo onto this machine
superset projects setup 47c31b04-… --local --parent-dir ~/code
# Or attach to an existing local checkout
superset projects setup 47c31b04-… --local --import ~/code/repo
```
The URL for clone mode comes from the cloud project record, so `setup`
doesn't need `--clone `. `setup` is idempotent: re-running against a
project that's already set up here is a no-op.
### Create your first workspace [#create-your-first-workspace]
```bash
superset projects list
superset workspaces create \
--project prj_… \
--name "fix-login-bug" \
--branch fix/login-bug
```
The host server clones the project (if it isn't already on disk), creates
a git worktree at the chosen branch, and registers the workspace.
You can also create a workspace from a pull request number:
```bash
superset workspaces create \
--project prj_… \
--name "review-pr-123" \
--pr 123 \
--local
```
## Stop the host server [#stop-the-host-server]
```bash
superset stop
```
Your terminals and agents keep running in the terminal daemon, and the next
`superset start` picks them up. To end them as well:
```bash
superset stop --terminals
```
## Shared state [#shared-state]
State lives under `~/.superset/host//`:
```text
~/.superset/host//manifest.json # endpoint + auth token
~/.superset/host//host.db # local host server DB
```
A host server started by the desktop app is visible to the CLI and
vice-versa. `SUPERSET_HOME_DIR` relocates the whole tree.
## Command details [#command-details]
For full flags, exit codes, and output shapes:
* [`superset start`](/cli/cli-reference#superset-start)
* [`superset status`](/cli/cli-reference#superset-status)
* [`superset stop`](/cli/cli-reference#superset-stop)
---
# Advanced Usage
Source: https://docs.superset.sh/sdk/advanced
Real-world recipes that combine the SDK's primitives (webhooks, triage scripts, and on-demand agents).
The SDK is in early alpha. It is not meant for production use and may be removed in the future. Stay on the latest version (`@superset_sh/sdk@latest`) while we iterate.
The SDK's individual methods are simple. The interesting part is what you compose them into. These are end-to-end recipes you can copy as starting points.
## Sentry webhook → agent on the bug [#sentry-webhook--agent-on-the-bug]
When Sentry fires an alert, file a task and spawn an agent to investigate, all in two SDK calls. (In production, verify the Sentry signature header before trusting any payload. That part is omitted here for clarity.)
```ts title="sentry-webhook.ts"
import { Hono } from 'hono';
import Superset from '@superset_sh/sdk';
const app = new Hono();
const client = new Superset();
// reads SUPERSET_API_KEY + SUPERSET_ORGANIZATION_ID from env
const TARGET_HOST_ID = process.env.SUPERSET_TARGET_HOST_ID!; // see hosts.list()
const PROJECT_ID = process.env.SUPERSET_PROJECT_ID!; // see projects.list()
app.post('/webhooks/sentry', async (c) => {
const event = await c.req.json();
const { title, web_url: sentryUrl, culprit, short_id } = event.data.issue;
const slug = `sentry-${short_id.toLowerCase()}`;
// 1. File a task so the bug shows up in the dashboard
const task = await client.tasks.create({
title: `[Sentry] ${title}`,
description: `Triggered by ${culprit}\n\nSentry: ${sentryUrl}`,
priority: 'high',
labels: ['sentry', 'bug'],
});
// 2. Spin up a worktree on a developer's machine and dispatch an agent
// inside it. The SDK creates the worktree, then runs the agent with
// your prompt; you don't manage the dispatch loop.
const result = await client.workspaces.create({
hostId: TARGET_HOST_ID,
projectId: PROJECT_ID,
name: slug,
branch: slug,
agents: [
{
agent: 'claude',
prompt: [
`A Sentry alert just fired:`,
` Title: ${title}`,
` Culprit: ${culprit}`,
` URL: ${sentryUrl}`,
``,
`Reproduce the failure, fix it, push a branch, and update task`,
`${task.id} with what you found.`,
].join('\n'),
},
],
});
return c.json({
ok: true,
taskId: task.id,
workspaceId: result.workspace.id,
sessionId: result.agents[0]?.ok ? result.agents[0].sessionId : null,
});
});
export default app;
```
What just happened, end-to-end:
* The task lives in the cloud and shows up in the dashboard for everyone.
* The workspace is a real `git worktree` on the target machine, ready for a human to take over if the agent gets stuck.
* The agent runs inside the new workspace, with the prompt above and access to the codebase + whatever MCP servers the host has configured.
You can spawn multiple agents in parallel by adding more entries to `agents`:
```ts
agents: [
{ agent: 'claude', prompt: 'Reproduce the bug and write a failing test.' },
{ agent: 'claude', prompt: 'Investigate related Sentry issues from the last 7 days.' },
],
```
## Burn down the P0 backlog overnight [#burn-down-the-p0-backlog-overnight]
Pick up every urgent task in the queue and spawn an agent on each one in parallel. Comes back the next morning with a branch and a comment per task.
```ts title="burn-p0s.ts"
import Superset from '@superset_sh/sdk';
const client = new Superset();
const HOST_ID = process.env.SUPERSET_HOST_ID!;
const PROJECT_ID = process.env.SUPERSET_PROJECT_ID!; // see projects.list()
const p0s = await client.tasks.list({ priority: 'urgent', limit: 50 });
const dispatched = await Promise.all(
p0s.map((task) =>
client.workspaces.create({
hostId: HOST_ID,
projectId: PROJECT_ID,
name: task.slug,
branch: task.slug,
agents: [
{
agent: 'claude',
prompt: [
`Pick up task ${task.slug}: "${task.title}".`,
``,
task.description ?? '(no description; read recent changes for context)',
``,
`Investigate, make the fix, run the relevant tests, push the branch, and`,
`update task ${task.id} with a one-paragraph summary of what changed and why.`,
`If you can't make confident progress in ~30 minutes, leave a comment with`,
`where you got stuck and stop.`,
].join('\n'),
},
],
}),
),
);
console.log(`dispatched ${dispatched.length} agents across the P0 backlog`);
```
Run it from a daily cron on a beefy host and you wake up to a branch per bug. Ones the agent could fix have a PR-ready branch; ones it couldn't have a comment explaining why so a human picks up where the agent stopped.
## Sweep a refactor across every repo [#sweep-a-refactor-across-every-repo]
Internal API rename, dependency bump, lint rule rollout. Anything that has to land identically in dozens of repos is a one-loop, fan-out problem:
```ts title="sweep-rename-getUser.ts"
import Superset from '@superset_sh/sdk';
const client = new Superset();
const HOST_ID = process.env.SUPERSET_HOST_ID!;
const projects = await client.projects.list({ hostId: HOST_ID });
const wave = await Promise.all(
projects.map((p) =>
client.workspaces.create({
hostId: HOST_ID,
projectId: p.id,
name: `rename-getUser-${p.name}`,
branch: 'refactor/rename-getUser',
agents: [
{
agent: 'claude',
prompt: [
`Rename every caller of \`getUser()\` to \`fetchUser()\` across this repo.`,
``,
`1. Find call sites with grep.`,
`2. Update each one and re-run the test suite.`,
`3. If green, push the branch and open a draft PR titled`,
` "refactor: rename getUser → fetchUser".`,
`4. If a repo doesn't actually use getUser, exit cleanly with a note.`,
].join('\n'),
},
],
}),
),
);
const totalAgents = wave.reduce(
(n, result) => n + result.agents.filter((agent) => agent.ok).length,
0,
);
console.log(`launched ${totalAgents} agents across ${projects.length} repos`);
```
Same loop works for "bump TypeScript to 5.7", "swap Sentry SDK for the new one", "add a `lint:strict` script to every package.json". Anything you'd otherwise farm out to a long Slack thread.
## On-demand agent dispatch from your tools [#on-demand-agent-dispatch-from-your-tools]
If you've already created a recurring automation in the dashboard, the SDK can fire it off-schedule from anywhere (a Slack slash command, a CI job, an internal admin panel):
```ts
const run = await client.automations.run('');
console.log(`dispatched run ${run.runId} for automation ${run.automationId}`);
```
The automation's pinned host has to be online and tunneling. The SDK will surface a `503 Host not connected` error if it isn't, so you can retry later or page someone.
---
# Getting Started
Source: https://docs.superset.sh/sdk/getting-started
Drive Superset programmatically from any TypeScript or JavaScript codebase.
The SDK is in early alpha. It is not meant for production use and may be removed in the future. Stay on the latest version (`@superset_sh/sdk@latest`) while we iterate.
The Superset TypeScript SDK lets you create and manage your workspaces, tasks, projects, and automations from code. Anything you can do in the dashboard, your scripts and services can do too.
A few things you might use it for:
* **Bulk task management**: script the creation, triage, or cleanup of tasks across one or many projects.
* **Integrations**: sync tasks to/from your CRM, issue tracker, or internal tools.
* **Provisioning**: spin up workspaces on a developer's machine when an issue is opened, a PR is reviewed, or a customer ticket lands.
* **On-demand agents**: kick off a recurring automation off-schedule when a webhook fires.
Everything is fully typed and works in Node, Bun, and Deno. The bundle also runs in browsers, but **don't ship `sk_live_…` keys to a frontend**: they're long-lived and grant full org access. From the browser, talk to a thin server proxy that holds the key.
## Install [#install]
```bash
npm install @superset_sh/sdk
```
```bash
pnpm add @superset_sh/sdk
```
```bash
yarn add @superset_sh/sdk
```
```bash
bun add @superset_sh/sdk
```
We're under active development. The SDK follows the API as it grows, so **stay on the latest version** rather than pinning. New methods get added; existing ones don't change shape without a version bump and a note in the changelog.
## Get an API key [#get-an-api-key]
1. Open the [Superset desktop app](https://superset.sh/download) → **Settings → API Keys** → **Create**. The key starts with `sk_live_…`. Copy it now (you won't be able to see it again).
2. Note your **organization ID**. Find it in the org switcher inside the desktop app.
```bash
export SUPERSET_API_KEY=sk_live_…
export SUPERSET_ORGANIZATION_ID=…
```
## Create the client [#create-the-client]
```ts
import Superset from '@superset_sh/sdk';
const client = new Superset();
// reads SUPERSET_API_KEY and SUPERSET_ORGANIZATION_ID from env
```
That's all the setup. From here, every resource works the same way:
```ts
// Create a task
const task = await client.tasks.create({
title: 'Wire up auth',
priority: 'high',
});
// Update it
await client.tasks.update({ id: task.id, statusId: '' });
// Look one up by id or slug
const got = await client.tasks.retrieve('SUPER-172'); // returns null if missing
// Find tasks with rich filters
const urgent = await client.tasks.list({
priority: 'urgent',
search: 'auth',
creatorMe: true,
});
// Inspect what else you have: projects and workspaces are host-owned
const [host] = await client.hosts.list();
if (!host) throw new Error('No hosts registered; run `superset start` on a machine');
const projects = await client.projects.list({ hostId: host.id });
const automations = await client.automations.list();
// Trigger an automation off-schedule
await client.automations.run('');
// Create a workspace on a developer's machine
await client.workspaces.create({
hostId: '',
projectId: '',
name: 'fix-auth-bug',
branch: 'fix/auth',
});
```
See the [reference](/docs/sdk/reference) for every method, parameter, and return type.
## Configuration [#configuration]
You can configure the client explicitly instead of (or alongside) the env vars:
```ts
const client = new Superset({
apiKey: 'sk_live_…',
organizationId: '…',
timeout: 60_000, // default: 60s per request
maxRetries: 2, // default: 2 retries with exponential backoff
logLevel: 'warn', // 'off' | 'error' | 'warn' | 'info' | 'debug'
});
```
The client retries automatically on network errors and 429/5xx responses, so transient failures usually fix themselves.
## Handling errors [#handling-errors]
The SDK throws typed errors for any non-success response, so you can catch what you actually care about:
```ts
import Superset, { APIError, NotFoundError, RateLimitError } from '@superset_sh/sdk';
const client = new Superset();
try {
await client.tasks.create({ title: '' });
} catch (err) {
if (err instanceof RateLimitError) {
// 429: already retried up to maxRetries; back off further if you keep hitting it
} else if (err instanceof NotFoundError) {
// 404
} else if (err instanceof APIError) {
// anything else: err.status, err.headers, err.error (the parsed body)
console.error(`Superset returned ${err.status}:`, err.error);
}
}
```
## Next [#next]
Head to the [reference](/docs/sdk/reference) for the complete surface.
---
# Superset SDK Reference
Source: https://docs.superset.sh/sdk/reference
Method-by-method reference for the Superset TypeScript SDK.
The SDK is in early alpha. It is not meant for production use and may be removed in the future. Stay on the latest version (`@superset_sh/sdk@latest`) while we iterate.
## Client [#client]
```ts
import Superset from '@superset_sh/sdk';
const client = new Superset({
apiKey: 'sk_live_…',
organizationId: '…',
// optional:
baseURL: 'https://api.superset.sh',
relayURL: 'https://relay.superset.sh',
timeout: 60_000,
maxRetries: 2,
logLevel: 'warn', // 'off' | 'error' | 'warn' | 'info' | 'debug'
});
```
### Telemetry [#telemetry]
The SDK reports one `sdk_method_called` event per resource call: the method name (for example `tasks.list`), SDK version, runtime, whether the call succeeded, and how long it took. Request and response data are never included. The report is sent after your call settles and is best-effort, so it cannot slow down or fail a call. Set `SUPERSET_TELEMETRY=0` to turn it off.
***
## tasks [#tasks]
### `tasks.create(body)` [#taskscreatebody]
Create a task.
```ts
const task = await client.tasks.create({
title: 'Wire up auth',
description: 'See SUPER-100',
priority: 'high', // 'urgent' | 'high' | 'medium' | 'low' | 'none'
assigneeId: '', // optional
statusId: '', // optional, defaults to first backlog status
estimate: 4, // optional, story points
dueDate: '2026-12-31', // optional, ISO date
labels: ['bug'], // optional
});
```
Returns a `Task`.
### `tasks.list(params?)` [#taskslistparams]
List tasks with rich filters. All filters AND-combine.
```ts
const tasks = await client.tasks.list({
assigneeMe: true, // tasks assigned to you
creatorMe: true, // tasks you created
priority: 'high',
statusId: '',
assigneeId: '', // someone else's tasks
search: 'auth', // substring of title
limit: 50, // max 500
offset: 0,
});
```
Returns `Array`. Each row is a `Task` denormalized with `assigneeName`, `assigneeImage`, `creatorName`, `creatorImage`, and `statusName` so you don't need follow-up calls for display.
### `tasks.retrieve(idOrSlug)` [#tasksretrieveidorslug]
Look up a single task by id or slug.
```ts
const task = await client.tasks.retrieve('SUPER-172');
if (!task) throw new Error('not found'); // returns null when missing
```
Returns `Task | null`.
### `tasks.update(body)` [#tasksupdatebody]
Patch a task.
```ts
const task = await client.tasks.update({
id,
priority: 'urgent',
statusId: '',
prUrl: 'https://github.com/…',
});
```
Returns the updated `Task`.
### `tasks.delete(id)` [#tasksdeleteid]
Soft-delete a task.
```ts
await client.tasks.delete(id);
```
### `tasks.statuses.list()` [#tasksstatuseslist]
List the task statuses (workflow states) configured for the active organization, in display order. Useful for resolving status ids before [`tasks.create`](#taskscreatebody) or [`tasks.update`](#tasksupdatebody).
```ts
const statuses = await client.tasks.statuses.list();
const todo = statuses.find((s) => s.type === 'unstarted');
```
Returns `Array`. Each entry is `{ id, name, color, type, position }`.
***
## workspaces [#workspaces]
### `workspaces.list({ hostId, projectId?, search? })` [#workspaceslist-hostid-projectid-search-]
List workspaces on a host. Workspaces are host-owned. There is no org-wide
listing; enumerate hosts with [`hosts.list()`](#hostslist) and query each one
you care about.
```ts
const workspaces = await client.workspaces.list({ hostId: '' });
```
Returns `Array`. Rows include the host-served `projectName`
(`string | null`; null when the workspace's project row is missing on that
host, so don't assume it's always present).
### `workspaces.create({ hostId, projectId, name, branch?, pr?, baseBranch?, taskId?, agents?, command? })` [#workspacescreate-hostid-projectid-name-branch-pr-basebranch-taskid-agents-command-]
Create a worktree on a specific host. Provide exactly one of `branch` or `pr` (a pull request number; the host checks out the verified PR head and derives the branch). `baseBranch` picks the fork point when `branch` doesn't exist yet, and `taskId` links the new workspace to a task. Optionally spawn one or more agents inside it as soon as the worktree is ready, and/or run a one-off shell `command` in the worktree. Goes through the relay tunnel: the host must be online.
Each entry in `agents` takes a preset id (e.g. `"claude"`) or a `HostAgentConfig` instance UUID: the host service resolves it against its configured rows and copies their stored `command`, `args`, and `env`. Set `model` or `effort` to override the agent's model or reasoning effort for that launch, or omit them to use the agent's own defaults. Use [`agents.list({ hostId })`](#agentslist-hostid-) to enumerate what's installed. `command` is independent of `agents`. Pass either or both.
```ts
const result = await client.workspaces.create({
hostId: '', // see hosts.list()
projectId: '', // see projects.list()
name: 'wire-up-auth',
branch: 'feat/auth',
agents: [ // optional: spawn agents on creation
{ agent: 'claude', model: 'sonnet', effort: 'high', prompt: 'Implement the auth flow described in SUPER-100.' },
{ agent: 'claude', prompt: 'Write integration tests for the new auth flow.' },
],
});
console.log(result.workspace.id);
for (const agent of result.agents) {
if (agent.ok) console.log(agent.kind, agent.sessionId, agent.label);
else console.error(agent.error);
}
```
Returns a `WorkspaceCreateResult`:
* `workspace`: the created workspace row (`id`, `name`, `branch`, `hostId`, `projectId`, `type`, `taskId`, …).
* `terminals`: terminals opened on the host (`{ terminalId, label? }`).
* `agents`: one entry per agent in the request (empty if `agents` was omitted). Each entry is either `{ ok: true, kind: 'terminal' | 'chat', sessionId, label }` or `{ ok: false, error }`.
* `alreadyExists`: true when a workspace for that branch already existed and was reused instead of created.
### `workspaces.update(id, params, { hostId })` [#workspacesupdateid-params--hostid-]
Update fields on an existing workspace on its host. Moving a workspace to a different branch or host requires host-side orchestration and is not safe to drive directly.
```ts
await client.workspaces.update('', { name: 'wire-up-auth-v2' }, { hostId: '' });
```
Returns the updated workspace row (`id`, `name`, `branch`, `hostId`, `projectId`, `type`, `taskId`, …).
### `workspaces.delete(id, { hostId })` [#workspacesdeleteid--hostid-]
Delete a workspace on its host.
```ts
await client.workspaces.delete('', { hostId: '' });
```
***
## projects [#projects]
### `projects.list({ hostId })` [#projectslist-hostid-]
List projects set up on a host. Projects are host-owned; there is no
org-wide project registry.
```ts
const projects = await client.projects.list({ hostId: '' });
```
Returns `Array` (`id`, `name`, `repoPath`, `repoUrl`, …).
***
## hosts [#hosts]
### `hosts.list()` [#hostslist]
List developer machines registered in the org. Returns `Array` with `id` (machineId), `name`, `online`, and `organizationId`.
```ts
const hosts = await client.hosts.list();
const online = hosts.filter((h) => h.online);
```
***
## agents [#agents]
Terminal-agent rows configured on a specific host (the same rows shown in
Settings → Agents on that machine). Reads route through the relay tunnel:
the target host must be online.
### `agents.list({ hostId })` [#agentslist-hostid-]
List configured agents on a host in persisted display order. First call on a
fresh host seeds the bundled defaults. Returns `Array`.
Each row carries `id`, `presetId`, `label`, `command`, `args`, `env`, and
prompt-transport fields used to launch the agent.
```ts
const agents = await client.agents.list({ hostId: '' });
```
### `agents.create({ hostId, workspaceId, agent, prompt, model?, effort?, attachmentIds? })` [#agentscreate-hostid-workspaceid-agent-prompt-model-effort-attachmentids-]
Create (launch) an agent session in an existing workspace on its host.
`agent` accepts either a preset id (e.g. `"claude"`) or a `HostAgentConfig`
instance UUID. `model` and `effort` are agent-specific launch overrides; omit
them to use the agent's own configured defaults. Unsupported values for either
fail before launch with a message naming the supported ids.
Returns `{ kind, sessionId, label }`.
```ts
const { sessionId } = await client.agents.create({
hostId: '',
workspaceId: '',
agent: 'claude',
model: 'sonnet',
effort: 'high',
prompt: 'Audit the login flow for race conditions.',
});
```
***
## terminals [#terminals]
Terminal (PTY) sessions on a host, scoped to a workspace.
### `terminals.create({ hostId, workspaceId, command?, cwd? })` [#terminalscreate-hostid-workspaceid-command-cwd-]
Create a terminal session in an existing workspace on its host. Pass
`command` to run a one-off shell command, or omit it to open an interactive
shell. Returns `{ terminalId, status }`.
```ts
const { terminalId } = await client.terminals.create({
hostId: '',
workspaceId: '',
command: 'bun install && bun test',
});
```
***
## automations [#automations]
Recurring agent runs scheduled by RRULE. Automations are a Pro feature: `create`, `run`, and `resume` are refused with `FORBIDDEN` unless the org has a Pro or Enterprise subscription. Reading, `update`, `pause`, and `delete` stay available so a downgraded org keeps control of what it has.
### `automations.list(params?)` [#automationslistparams]
```ts
const automations = await client.automations.list();
// or filter by case-insensitive substring on name:
const triage = await client.automations.list({ name: 'triage' });
```
Each row is an `AutomationSummary`: the `prompt` body is omitted (it can be
large markdown). Fetch one with `automations.getPrompt(id)`. Each row includes
`scheduleText`, a human-readable rendering of the rrule.
### `automations.retrieve(id)` [#automationsretrieveid]
```ts
const a = await client.automations.retrieve(id);
```
Returns an `AutomationSummary` (no `prompt` body: call `getPrompt(id)`).
### `automations.create(body)` [#automationscreatebody]
Create a recurring automation.
```ts
const a = await client.automations.create({
name: 'Daily leads',
prompt: 'Find new leads from Linear and update the CRM…',
agent: 'claude', // host agent presetId, instance UUID, or 'superset' for built-in chat
rrule: 'FREQ=DAILY;BYHOUR=6;BYMINUTE=0',
timezone: 'America/Los_Angeles',
v2ProjectId: '', // one of v2ProjectId or v2WorkspaceId required
// optional:
v2WorkspaceId: '', // pin to a specific workspace
targetHostId: '', // pin to a specific host
dtstart: new Date().toISOString(),
mcpScope: ['linear', 'notion'],
});
```
### `automations.update(body)` [#automationsupdatebody]
```ts
await client.automations.update({ id, rrule: 'FREQ=WEEKLY;BYDAY=MO' });
```
### `automations.delete(id)` [#automationsdeleteid]
### `automations.run(id)` [#automationsrunid]
Dispatch immediately, off-schedule. Goes through the relay to the automation's
target host. Returns identifiers for the dispatched run, not the full run row;
use [`automations.logs(id)`](#automationslogsid-params) for status.
```ts
const run = await client.automations.run(id);
console.log(run.automationId, run.runId);
```
### `automations.pause(id)` / `automations.resume(id)` [#automationspauseid--automationsresumeid]
Toggle the `enabled` flag. A paused automation stops running on its schedule until you resume it.
### `automations.logs(id, params?)` [#automationslogsid-params]
Run history. Owner-only: returns 404 if the automation isn't owned by the calling user.
```ts
const runs = await client.automations.logs(id, { limit: 20 });
```
### `automations.getPrompt(id)` / `automations.setPrompt(id, prompt)` [#automationsgetpromptid--automationssetpromptid-prompt]
Read or replace the automation's prompt without going through the full update.
***
## organization [#organization]
### `organization.members.list()` [#organizationmemberslist]
List members of the active organization.
```ts
const members = await client.organization.members.list();
```
---
# Drive Superset from Your Agent
Source: https://docs.superset.sh/recipes/agent-driven-superset
Delegate work in parallel, then make it recurring with the automate skill, without leaving the conversation
you're mid-conversation with an agent and the next step is a Superset action (fan this work out in parallel, or make it recur on a schedule) and you'd rather say so than click through the app.
## The Idea [#the-idea]
Superset ships [skills](/skills) to your coding agents automatically, so the agent in front of you already knows how to run Superset itself. `superset:orchestrate` makes it a coordinator of parallel workers; that has [its own page](/orchestration). This recipe is about the move that follows: `superset:automate` turns anything you've asked for twice into a scheduled [automation](/automations), in the same conversation.
## Steps [#steps]
1. Delegate something splittable to the agent you're talking to: "split this migration into independent slices and run a worker on each" ([Agent Orchestration](/orchestration) covers what to ask for and how the coordination works). Review each workspace's diff as it lands.
2. When the job turns out to be recurring (a dependency sweep, a triage pass, a weekly cleanup), promote it without switching surfaces:
```text
That worked. Make it a Superset automation that runs every Monday at 7am
on this project, and walk me through the first run.
```
3. The agent writes the automation prompt, schedules it, and reviews the first run with you. From then on it's a [workspace waiting for you](/recipes/nightly-audit) instead of a task on your list.
## Variations [#variations]
* **Catch up instead of fan out**: "what did my agents do overnight?" gets you a standup digest of finished, blocked, and needs-review work
* **When Superset itself misbehaves**: "diagnose why this host shows offline" has the agent fix it instead of you reading logs
* The full list of shipped skills, and how they're delivered and updated, is on the [Skills](/skills) page
---
# Command Your Fleet from the CLI
Source: https://docs.superset.sh/recipes/command-your-fleet
Read every agent's screen and broadcast follow-ups across workspaces with two shell loops
several agents are running across workspaces (from a fan-out, a race, or a busy day) and you want status or course-corrections without clicking through panes.
## The Idea [#the-idea]
Every terminal Superset runs is addressable from the [CLI](/cli/getting-started): `terminals list`, `read`, and `send`. Compose them with `workspaces list` and one shell loop sweeps a whole project: every agent's screen in one scroll, or one instruction delivered to all of them.
Workspaces are host-owned, and these loops target the machine you run them on. If your fleet spans hosts, add `--host ` to each command to sweep a remote host's share of it.
## Read the Whole Fleet [#read-the-whole-fleet]
Print the last few lines of every terminal in every workspace of a project:
```bash
superset workspaces list --project my-app --quiet | while read ws; do
superset terminals list --workspace "$ws" --json 2>/dev/null \
| jq -r '.sessions[].terminalId' | while read t; do
echo "=== $ws / $t ==="
superset terminals read --workspace "$ws" --terminal "$t" --max-lines 5 --json | jq -r '.text'
done
done
```
`--quiet` prints one workspace ID per line; the inner loop asks each workspace for its live sessions. Raise `--max-lines` when you want more than a glance.
## Broadcast a Follow-Up [#broadcast-a-follow-up]
Send the same instruction to every running agent in the project:
```bash
superset workspaces list --project my-app --quiet | while read ws; do
superset terminals list --workspace "$ws" --json 2>/dev/null \
| jq -r '.sessions[].terminalId' | while read t; do
superset terminals send --workspace "$ws" --terminal "$t" \
--text "Status check: summarize what you have done and what remains in 2 sentences."
done
done
```
Follow with the read loop a minute later to collect the answers.
One caveat: `send` delivers to *every* terminal, including plain shells, where the text just lands at the prompt. Broadcast when the fleet is all agents, or filter by workspace name first (`workspaces list --search worker- --quiet`).
## Clean Up When You're Done [#clean-up-when-youre-done]
```bash
superset workspaces list --project my-app --quiet | xargs -L1 superset workspaces archive
```
Archives every listed workspace (the project's `main` workspace cannot be archived). An archived workspace loses its uncommitted changes. Filter with `--search` to target only the fleet you launched.
## Variations [#variations]
* **Scope by name**: prefix fleet workspaces (`worker-1`, `race-claude`) at creation, then drive only them with `workspaces list --search worker- --quiet`
* **Let an agent do this**: the [`superset:orchestrate` skill](/orchestration) runs these same loops for you; monitoring workers and delivering follow-ups is exactly how it coordinates
* **Watch continuously**: wrap the read loop in `watch -n 30` for a poor-man's fleet dashboard
---
# Fan Out a Big Refactor
Source: https://docs.superset.sh/recipes/fan-out-refactor
Split a large change into independent slices and run one workspace per slice
a refactor is too big for one PR: a rename that touches 200 files, a library migration, deleting a deprecated pattern across the codebase.
## The Idea [#the-idea]
The failure mode of big refactors is one giant branch that rots while it waits for review. Instead: delegate in workspaces, integrate through small PRs. Slice the work so each piece can merge independently, then run one agent per slice.
## Steps [#steps]
1. **Plan the slices first.** In a scratch workspace, have an agent do the survey:
```text
We're migrating from moment to date-fns. Find every usage and propose
a split into 3-6 slices that can each merge independently, in any order.
For each slice: name, files touched, and any shared prep work that must
land first. Don't change anything yet.
```
2. If the plan names shared prep (a compat helper, a codemod script), run that slice first and merge it before fanning out.
3. Press **⌘N** once per slice. Same prompt template, one slice each:
```text
Migrate the files in [slice] from moment to date-fns, per the plan below.
Only touch files in your slice. Run the affected tests before finishing.
[paste the slice plan]
```
4. Review each workspace's diff as it finishes and open a PR per slice from the diff viewer. Small PRs merge fast; that's the point.
5. Delete each workspace as its PR merges.
## Why Slices Must Be Independent [#why-slices-must-be-independent]
Two agents editing the same file on different branches means merge conflicts, and you inherit them. The planning step exists to make slice boundaries follow file boundaries. If two slices genuinely overlap, merge them into one workspace.
## Variations [#variations]
* **Race the risky slice**: if one slice is much harder than the rest, [race two agents on it](/recipes/race-agents) while the easy slices run
* **Rolling fan-out**: for very large migrations, keep 2-3 slice workspaces active and start the next slice as each PR merges, instead of opening all of them at once
* **From the CLI**: once the plan names the slices, launch every worker in one paste:
```bash
for slice in api cli web; do
superset workspaces create --project \
--name "migrate-$slice" --branch "migrate/$slice" --local \
--agent claude \
--prompt "Migrate the $slice slice from moment to date-fns, per plan.md. Only touch files in your slice. Run the affected tests before finishing."
done
```
---
# Wake Up to a Finished Audit
Source: https://docs.superset.sh/recipes/nightly-audit
Schedule an agent to audit your repo overnight and review the results over coffee
there's recurring maintenance work nobody prioritizes during the day: dependency updates, dead code, TODO triage, security sweeps.
## The Idea [#the-idea]
[Automations](/automations) run an agent session on a schedule, and the output is a real workspace you can open, review, and continue. Schedule the boring sweep for 3 AM; your morning job is just reviewing a diff.
## Steps [#steps]
1. Go to **Automations → New automation**.
2. Pick the project, this device, an agent, and a daily schedule: `FREQ=DAILY;BYHOUR=3;BYMINUTE=0`.
3. Write a prompt that produces a reviewable diff and is safe to re-run:
```text
Audit this repo's dependencies. Find outdated packages with known
vulnerabilities or major-version lag. Apply the safe minor/patch updates,
run the test suite, and revert anything that breaks it. Write a summary
of what you updated and what needs a human decision to AUDIT.md.
If a previous audit branch already covered today's findings, stop.
```
4. In the morning, open the run from the automation's detail page. Each run in "new workspace" mode gets a fresh workspace from the project's repo.
5. Review the diff, read `AUDIT.md`, commit and open a PR, or discard by deleting the workspace.
## Prompt Rules for Unattended Runs [#prompt-rules-for-unattended-runs]
* **Idempotent**: delivery is at-least-once, so a rare double-dispatch must be harmless. "Stop if already done" costs one sentence.
* **Self-verifying**: "run the tests, revert what breaks" is the difference between a reviewable diff and a mess
* **Escalate, don't guess**: anything requiring judgment goes in the summary file, not the diff
## Variations [#variations]
* **Weekly instead of nightly**: `FREQ=WEEKLY;BYDAY=MO;BYHOUR=3;BYMINUTE=0` for lower-churn repos
* **Rotate the sweep**: separate automations for deps (Monday), dead code (Wednesday), TODO triage (Friday); one prompt per automation
* **Test it now**: use **Run now** on the detail page instead of waiting for 3 AM
```bash
superset automations create --name "Nightly audit" \
--rrule "FREQ=DAILY;BYHOUR=3;BYMINUTE=0" \
--project --prompt-file prompt.md --agent claude
superset automations run
```
Or create it and fire the first run in one pipe:
```bash
superset automations create --name "Nightly audit" \
--rrule "FREQ=DAILY;BYHOUR=3;BYMINUTE=0" \
--project --prompt-file prompt.md --agent claude \
--json | jq -r '.id' | xargs -I{} superset automations run {}
```
---
# Run Three Workstreams at Once
Source: https://docs.superset.sh/recipes/parallel-workstreams
A feature, a bugfix, and a PR review in parallel without branch juggling
your day is a mix of unrelated work: something to build, something to fix, something to review. This is the everyday shape of parallel work, no racing involved.
## The Idea [#the-idea]
Each workstream gets its own workspace, so switching between them is a click, not a stash-checkout-rebuild cycle. Agents keep making progress on the streams you're not looking at.
## Steps [#steps]
1. **Feature** (⌘N → new branch): prompt an agent with the feature task and let it run.
```text
Build the CSV export button on the reports page. Match the existing
export patterns in this codebase. Stop and ask before adding dependencies.
```
2. **Bugfix** (⌘N → new branch): paste the bug report as the prompt.
```text
Users report the login form clears on validation errors. Reproduce it,
find the root cause, and fix it. Include the repro steps in your final message.
```
3. **Review** (⌘N → pull request): link the PR by number, title search, or URL. Read the diff in the **Changes** tab, run the branch locally with the **Run** button, and leave your review on GitHub.
4. Rotate your attention to whichever workspace needs you. The sidebar shows agent status, ahead/behind counts (**↑N**/**↓N**), and PR checks on hover.
5. As each stream lands: commit and push from the diff viewer, then delete the workspace.
## Tips [#tips]
* Descriptive branch names (`feature/csv-export`, `fix/login-clear`) keep the sidebar readable at a glance
* The review workspace is fully functional: if the PR needs a small fix, make it there and push rather than writing a comment
* Never work directly on `main`; the whole model assumes every stream is a branch
## Variations [#variations]
* **Interrupt-driven days**: keep one empty "incident" workspace pattern in mind. When something urgent lands, ⌘N and delegate it without disturbing the other streams.
* **More than three**: nothing special happens at four or five streams; the limit is your review attention, not the tool.
---
# Clear PR Feedback in the Background
Source: https://docs.superset.sh/recipes/pr-feedback
An agent addresses review comments on your PR while you work on something else
a PR comes back with review comments that are legitimate but mechanical: rename this, add a test for that, handle the nil case.
## The Idea [#the-idea]
Addressing review feedback is high-interruption, low-creativity work. Create a workspace from the PR, hand the comments to an agent, and stay in whatever you were doing.
## Steps [#steps]
1. Press **⌘N** and choose **Pull request**. Search by title or number, or paste the PR URL.
2. Prompt an agent to work through the feedback. The `gh` CLI is already authenticated in every workspace:
```text
Read all review feedback on this PR. `gh pr view --comments` misses inline
code comments, so also run
`gh api repos/{owner}/{repo}/pulls/{pr}/comments --paginate`
with this repo's owner/name and this PR's number.
Address each comment: make the change, or reply explaining why not.
Commit with one commit per comment, referencing it. Do not force-push.
Summarize what you changed and what you pushed back on in your final message.
```
3. Get notified when it finishes. Check the **Changes** tab to review what was done against each comment before it re-requests review.
4. Push from the diff viewer if the agent didn't, and re-request review on GitHub.
5. Delete the workspace once the PR merges.
## Tips [#tips]
* Hover the workspace in the sidebar to watch review status and CI checks without opening GitHub
* "One commit per comment" keeps the reviewer's second pass trivial
* If a comment requires a judgment call, the agent should punt: telling it to reply rather than guess is what makes this safe to run unattended
## Variations [#variations]
* **Teammate's PR**: same recipe works on any PR you can push to, not just your own
* **CI fixups**: replace the prompt with "CI is failing on this PR; read the failing check logs with `gh`, fix the failures, and push"
---
# Race Agents on One Task
Source: https://docs.superset.sh/recipes/race-agents
Run the same prompt across multiple agents and merge the best result
the task is self-contained, you're not sure which approach (or agent) will do it best, and reviewing three diffs is cheaper than iterating on one.
## The Idea [#the-idea]
Agent output varies a lot between attempts and between agents. Instead of prompting, reviewing, and re-prompting one agent serially, run the attempts in parallel on isolated branches and pick the winner.
## Steps [#steps]
1. Press **⌘N** three times. Same prompt each time, different agent each time (or the same agent three times: variance alone makes racing worth it).
2. Keep **Auto-run command** on so each agent starts immediately.
3. Write the prompt once and reuse it verbatim. End it with a self-report so comparison is fast:
```text
Add rate limiting to the public API endpoints. Use the middleware pattern
already in this codebase. In your final message, list the files you changed
and any tradeoffs you made.
```
4. Do something else. Notification sounds tell you when each agent finishes.
5. Open each workspace's **Changes** tab. Focus mode (target icon) makes stepping through a diff file-by-file fast.
6. Ship the winner: stage, commit, push, **Create PR** from the diff viewer.
7. Before deleting the losers, skim their diffs for ideas the winner missed. Select and copy any lines worth keeping.
8. Delete the losing workspaces.
## Picking a Winner Quickly [#picking-a-winner-quickly]
* Read the final messages first; disqualify anything that misunderstood the task before reading diffs
* Prefer the smallest diff that fully does the job
* Run the test suite in the winner's terminal before you push
## Variations [#variations]
* **Two agents, two approaches**: same agent, but prompt one toward each design ("use middleware" vs "use a decorator") when you're unsure which is right
* **Best-of-N on hard bugs**: for a bug that has resisted one agent, three fresh attempts beat continuing a stuck session
* **From the CLI**: write the prompt to `prompt.md`, then start the whole race in one paste, one workspace per agent with the same prompt:
```bash
for agent in claude codex opencode; do
superset workspaces create --project \
--name "race-$agent" --branch "race/$agent" --local \
--agent "$agent" --prompt "$(cat prompt.md)"
done
```