Superset

https://github.com/superset-sh/superset
Admin
Superset orchestrates CLI-based coding agents across isolated git worktrees, with a built-in...
Tokens:1,300,335
Snippets:9,312
Trust Score:8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Node.js setup command example

Source: https://github.com/superset-sh/superset/blob/main/apps/desktop/src/renderer/routes/_authenticated/_dashboard/components/DashboardSidebar/components/V2SetupScriptCard/setup-script-prompt.md

Minimal Node.js example showing only the setup command. It installs dependencies with bun and copies the .env file from the repository root.

```json
{ "setup": ["bun install", "cp \"$SUPERSET_ROOT_PATH/.env\" .env"] }
```

--------------------------------

### Full config.json example with setup, teardown, and run

Source: https://github.com/superset-sh/superset/blob/main/apps/desktop/src/renderer/routes/_authenticated/_dashboard/components/DashboardSidebar/components/V2SetupScriptCard/setup-script-prompt.md

Shows the full structure of the .superset/config.json file with setup, teardown, and optional run commands. The setup command installs dependencies and copies the .env file, teardown stops Docker containers, and run launches a dev server script.

```json
{
  "setup": ["bun install", "cp \"$SUPERSET_ROOT_PATH/.env\" .env"],
  "teardown": ["docker-compose down"],
  "run": ["./.superset/run.sh"]
}
```

--------------------------------

### superset projects setup command examples

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/cli/cli-reference.mdx

Examples of adopting an existing project onto a host by cloning it or registering an existing local checkout.

```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
```

--------------------------------

### Docker setup and teardown example

Source: https://github.com/superset-sh/superset/blob/main/apps/desktop/src/renderer/routes/_authenticated/_dashboard/components/DashboardSidebar/components/V2SetupScriptCard/setup-script-prompt.md

Docker example that starts services with docker-compose up -d, runs database migrations, and tears down with docker-compose down -v. The -v flag removes volumes.

```json
{
  "setup": ["docker-compose up -d", "bun run db:migrate"],
  "teardown": ["docker-compose down -v"]
}
```

--------------------------------

### Manual installation steps

Source: https://github.com/superset-sh/superset/blob/main/packages/cli/DISTRIBUTION.md

Manual installation: download the tarball, extract to ~/.superset/bin, add to PATH, login, and start the host service as a daemon.

```bash
# Download
curl -LO https://github.com/user/superset/releases/latest/download/superset-darwin-arm64.tar.gz

# Extract
mkdir -p ~/.superset/bin
tar -xzf superset-darwin-arm64.tar.gz -C ~/.superset/bin

# Add to PATH
export PATH="$HOME/.superset/bin/bin:$PATH"

# Login
superset auth login

# Start host service
superset start --daemon

```

--------------------------------

### Setup workspace and run dev

Source: https://github.com/superset-sh/superset/blob/main/DEVELOPMENT.md

Sets up a workspace and starts the development servers. Run `setup.local.sh` in every new worktree before `bun run dev`.

```bash
./.superset/setup.local.sh
bun run dev
```

--------------------------------

### Skip setup entirely configuration

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/setup-teardown-scripts.mdx

Example JSON configuration that sets empty arrays for setup and teardown to skip those phases.

```json
{ "setup": [], "teardown": [] }
```

--------------------------------

### Lifecycle Setup Script

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/using-monorepos.mdx

A JSON configuration for the setup script, including dependency installation and environment file copying.

```json
{
  "setup": [
    "bun install",
    "cp \"$SUPERSET_ROOT_PATH/.env\" .env"
  ]
}
```

--------------------------------

### Install and verify Browser Use 3.0 CLI

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/browser.mdx

Use uv to install the Browser Use CLI globally and verify the installation by displaying the help menu.

```bash
uv tool install browser-use
browser-use --help
```

--------------------------------

### Calling a setup shell script

Source: https://github.com/superset-sh/superset/blob/main/apps/desktop/src/renderer/routes/_authenticated/_dashboard/components/DashboardSidebar/components/V2SetupScriptCard/setup-script-prompt.md

Shows how to call a shell script from the setup command for non-trivial setup logic. The script should be created and committed with the .superset directory.

```json
"setup": ["./.superset/setup.sh"]
```

--------------------------------

### Custom setup script configuration

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/setup-teardown-scripts.mdx

Example JSON configuration that uses custom setup and teardown scripts from the user override directory.

```json
{
  "setup": ["~/.superset/projects/<repo-path>/setup.sh"],
  "teardown": ["~/.superset/projects/<repo-path>/teardown.sh"]
}
```

--------------------------------

### Install plugins

Source: https://github.com/superset-sh/superset/blob/main/plugins/superset/skills/plugins/SKILL.md

Install a plugin, update to the latest marketplace version, or specify a marketplace when names collide. Install records the plugin on the account and materializes skills locally.

```bash
superset plugins install linear
superset plugins install linear --update      # move to the marketplace's current version
superset plugins install linear@superset      # when two marketplaces carry the same name
```

--------------------------------

### Install host service via systemd/launchd (stretch goal)

Source: https://github.com/superset-sh/superset/blob/main/packages/cli/DISTRIBUTION.md

Stretch goal command to install the host service: writes a systemd unit or launchd plist, enables and starts the service, and ensures it runs on boot.

```bash
superset host install   # writes systemd unit or launchd plist
                        # enables + starts the service
                        # host service runs on boot

```

--------------------------------

### Run script example with npm install

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/setup-teardown-scripts.mdx

This JSON configuration shows a `run` field that defines commands to start a dev server or other long-running processes. Run commands are on-demand, restartable, and run in a dedicated terminal pane.

```json
{
  "setup": ["npm install"],
  "run": ["./.superset/run.sh"]
}
```

--------------------------------

### Setup existing project with superset projects setup

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/cli/getting-started.mdx

Attach to an existing project in your organization that is not yet present on your local machine.

```bash
superset projects setup <id-from-projects-list> --local --parent-dir ~/code
```

--------------------------------

### Install jq

Source: https://github.com/superset-sh/superset/blob/main/DEVELOPMENT.md

Installs `jq`, a prerequisite for development.

```bash
brew install jq
```

--------------------------------

### Install @superset_sh/sdk with bun

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/sdk/getting-started.mdx

Install the SDK using bun. The SDK is in early alpha, so stay on the latest version.

```bash
bun add @superset_sh/sdk
```

--------------------------------

### superset projects create command examples

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/cli/cli-reference.mdx

Examples of creating a project by cloning from a Git URL or importing an existing local repository.

```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
```

--------------------------------

### Configure workspace scripts in .superset/config.json

Source: https://github.com/superset-sh/superset/blob/main/README.md

Example configuration for workspace setup, teardown, and run scripts in .superset/config.json. See full documentation at https://docs.superset.sh/setup-teardown-scripts.

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

--------------------------------

### Install @superset_sh/sdk with pnpm

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/sdk/getting-started.mdx

Install the SDK using pnpm. The SDK is in early alpha, so stay on the latest version.

```bash
pnpm add @superset_sh/sdk
```

--------------------------------

### superset start command and output

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/cli/cli-reference.mdx

Start the local host server daemon. Returns server details or existing instance info.

```bash
superset start --daemon
```

```ts
// Freshly started
{
  pid: number;
  port: number;
  organizationId: string;
}

// Already running
{
  pid: number;
  endpoint: string;
}
```

--------------------------------

### Install @superset_sh/sdk with npm

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/sdk/getting-started.mdx

Install the SDK using npm. The SDK is in early alpha, so stay on the latest version.

```bash
npm install @superset_sh/sdk
```

--------------------------------

### Manual setup with real services

Source: https://github.com/superset-sh/superset/blob/main/DEVELOPMENT.md

Manual setup for pointing at real Neon or third-party services instead of the local Docker stack. Requires filling in real credentials in `.env`.

```bash
cp .env.example .env             # fill in real Neon, Stripe, etc. credentials
bun install
bun run dev
```

--------------------------------

### Start Docker daemon and compose up

Source: https://github.com/superset-sh/superset/blob/main/docs/cloud-sandbox-mismatches.md

Defines the start command for an environment whose repository needs containers. It starts the Docker daemon in the background, waits until it is ready, then runs docker compose up.

```json
{ "start": ["sudo dockerd >/var/log/dockerd.log 2>&1 &",
            "until docker info >/dev/null 2>&1; do sleep 0.2; done",
            "docker compose up"] }
```

--------------------------------

### Install Animation Logic

Source: https://github.com/superset-sh/superset/blob/main/apps/desktop/docs/mockups/updates-sidebar.html

Handles the ASCII-based progress bar and spinner animation during the installation process.

```javascript
/* ASCII install: braille spinner + terminal progress bar, then the row retires */ const SPIN_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]; const BAR_CELLS = 12; function startInstall(inst) { const slot = inst.el.querySelector("[data-slot]"); const note = inst.el.querySelector("[data-note]"); note.textContent = "▸ live — installs, then the row retires"; const spinEl = slot.querySelector("[data-ascii]"); const barEl = slot.querySelector("[data-ascii-bar]"); let f = 0, t1, t2; const started = performance.now(); const DURATION = 3400; const cells = Number(barEl?.dataset.cells || BAR_CELLS); const iv = setInterval(() => { f++; const p = Math.min((performance.now() - started) / DURATION, 1); const filled = Math.round(p * cells); if (spinEl) spinEl.textContent = SPIN_FRAMES[f % SPIN_FRAMES.length]; if (barEl) barEl.textContent = `[${"#".repeat(filled)}${"·".repeat(cells - filled)}]`; if (p >= 1) { clearInterval(iv); if (spinEl) spinEl.outerHTML = `<svg class="done-check check-draw" viewBox="0 0 24 24" fill="none" stroke="currentColor"><path d="M4.5 12.5l5 5L20 6.5" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round"/></svg>`; const label = slot.querySelector(".label"); if (label) label.textContent = "Updated"; if (barEl) barEl.textContent = `v${VERSION}`; t1 = setTimeout(() => { const spot = slot.querySelector("[data-retire]"); if (spot) spot.classList.add("retire"); t2 = setTimeout(() => { slot.innerHTML = ""; note.textContent = "▸ up to date — row retires until the next update"; for (const b of inst.el.querySelectorAll(".seg button")) { b.classList.remove("on"); } }, 700); }, 1300); } }, 80); inst.stop = () => { clearInterval(iv); clearTimeout(t1); clearTimeout(t2); }; }
```

--------------------------------

### Install @superset_sh/sdk with yarn

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/sdk/getting-started.mdx

Install the SDK using yarn. The SDK is in early alpha, so stay on the latest version.

```bash
yarn add @superset_sh/sdk
```

--------------------------------

### Superset CLI Installation and Usage

Source: https://github.com/superset-sh/superset/blob/main/apps/marketing/content/changelog/2026-05-18-teams-slack-sdk-workspaces.mdx

Commands to install the Superset CLI, authenticate via OAuth, and initialize a project workspace.

```bash
# install
curl -fsSL https://superset.sh/cli/install.sh | sh
# or: brew install superset-sh/tap/superset
# or: it's already bundled with the desktop app at ~/.superset/bin/superset

# sign in (opens a browser, or prints a code for a second device)
superset auth login

# scaffold a project and open a workspace
superset projects create
superset workspaces open
```

--------------------------------

### Sign in and start host server

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/remote-access.mdx

On the machine to add to the relay network, sign in and start the host server in the background. `superset start --daemon` runs a small HTTP server and registers the machine with the relay.

```bash
superset auth login
superset start --daemon
```

--------------------------------

### Install Superset CLI via standalone script

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/cli/getting-started.mdx

Downloads and runs the official install script, which auto-detects your platform and installs Superset under ~/superset by default.

```bash
curl -fsSL https://superset.sh/cli/install.sh | sh
```

--------------------------------

### New Workspace Setup Modal UI

Source: https://github.com/superset-sh/superset/blob/main/docs/design/v2-host-project-paths.md

Visual representation of the setup modal displayed when a project path is missing or not configured.

```text
┌─────────────────────────────────────────┐
│  Set up "my-project" on this device     │
│                                         │
│  ○ Use existing directory               │
│    [~/work/my-project        ] [Browse] │
│    ✓ Matches github.com/org/my-project  │
│                                         │
│  ○ Clone repository                     │
│    [~/.superset/repos        ] [Browse] │
│                                         │
│           [Set Up & Create]             │
└─────────────────────────────────────────┘
```

--------------------------------

### Install dependencies

Source: https://github.com/superset-sh/superset/blob/main/docs/tickets/desktop-invite-member.md

Command to install the required project dependencies using bun.

```bash
bun install
```

--------------------------------

### Install Superset CLI via Homebrew

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/cli/getting-started.mdx

Installs the Superset CLI using the Homebrew tap.

```bash
brew install superset-sh/tap/superset
```

--------------------------------

### Launch development environment

Source: https://github.com/superset-sh/superset/blob/main/apps/desktop/plans/20260319-1400-keep-chat-drafts.md

Command to start the development server for manual testing.

```bash
bun dev
# Desktop app opens
```

--------------------------------

### Configure project lifecycle setup commands in .superset/config.json

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/troubleshooting.mdx

Add setup commands to your .superset/config.json file to ensure dependencies like node_modules and .env files are correctly initialized in new workspaces.

```json
{
	"setup": ["bun install", "cp \"$SUPERSET_ROOT_PATH/.env\" .env"]
}
```

--------------------------------

### Setup project on subsequent machines

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/cli/host-server.mdx

Attach to an existing project on additional machines instead of creating a duplicate.

```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
```

--------------------------------

### Install Bun

Source: https://github.com/superset-sh/superset/blob/main/DEVELOPMENT.md

Installs Bun, which is required for development. The version is pinned in `.bun-version`.

```bash
curl -fsSL https://bun.sh/install | bash
```

--------------------------------

### Git Submodules Setup Script

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/using-monorepos.mdx

Updated setup script configuration to include initializing and updating git submodules.

```json
{
  "setup": ["git submodule update --init --recursive", "bun install"]
}
```

--------------------------------

### Install gh

Source: https://github.com/superset-sh/superset/blob/main/DEVELOPMENT.md

Installs the GitHub CLI (`gh`), a prerequisite for development.

```bash
brew install gh
```

--------------------------------

### Install Superset SDK with npm or bun

Source: https://github.com/superset-sh/superset/blob/main/packages/sdk/README.md

Install the @superset_sh/sdk package using npm or bun. The bun command is provided as an alternative.

```bash
npm install @superset_sh/sdk
# or: bun add @superset_sh/sdk
```

--------------------------------

### Install Superset CLI via curl or Homebrew

Source: https://github.com/superset-sh/superset/blob/main/README.md

Install the Superset CLI standalone. The first command uses curl to pipe the install script to sh; the second uses Homebrew. The CLI also comes bundled with the desktop app.

```bash
curl -fsSL https://superset.sh/cli/install.sh | sh
# or
brew install superset-sh/tap/superset
```

--------------------------------

### Start desktop app in dev mode

Source: https://github.com/superset-sh/superset/blob/main/apps/desktop/plans/20260411-v1-terminal-resize-simplification.md

Command to start the desktop app in dev mode for manual verification.

```bash
bun dev
```

--------------------------------

### Setup and verification commands for marketing-localized-urls

Source: https://github.com/superset-sh/superset/blob/main/apps/marketing/plans/done/20260829-1230-localized-urls-seo.md

Commands to set up the branch and run typecheck, lint, tests, dev server, and a curl smoke check for the localized URL.

```bash
cd /path/to/repo
git checkout -b marketing-localized-urls origin/main
# M1 file moves via git mv, then:
bun run --cwd apps/marketing typecheck
bunx biome check apps/marketing
bun test packages/i18n     # rsc-seeding ratchet still enforces
cd apps/marketing && bun run dev
curl -s localhost:6542/ja/pricing | grep -E 'lang="ja"'
```

--------------------------------

### Install via curl | sh (planned)

Source: https://github.com/superset-sh/superset/blob/main/packages/cli/DISTRIBUTION.md

Planned one-liner installer that detects platform/arch, downloads the tarball from GitHub Releases, extracts to ~/.superset/bin/, and prints PATH instructions.

```bash
curl -fsSL https://get.superset.sh | sh

```

--------------------------------

### Override setup scripts entirely

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/setup-teardown-scripts.mdx

Use a plain array to completely replace the team's setup scripts with your own custom script.

```json
{
  "setup": ["./.superset/my-custom-setup.sh"]
}
```

--------------------------------

### Publish a page with CLI

Source: https://github.com/superset-sh/superset/blob/main/plans/20260828-pages-comment-watcher.md

Example output when running the superset pages publish command.

```bash
$ superset pages publish report.html
Published "Report" v2
https://…/page/report-a1b2c3
Watching for comments · replies go to this session
```

--------------------------------

### Static ports.json Schema Example

Source: https://github.com/superset-sh/superset/blob/main/apps/desktop/plans/20260108-2251-static-ports-json.md

Example configuration file structure for defining static ports in the .superset/ports.json file.

```json
{
  "ports": [
    { "port": 3000, "label": "Frontend Dev Server" },
    { "port": 8080, "label": "API Server" },
    { "port": 5432, "label": "PostgreSQL" }
  ]
}
```

--------------------------------

### Run dev server and verify Review tab

Source: https://github.com/superset-sh/superset/blob/main/apps/desktop/plans/20260413-1600-v2-review-tab.md

Starts the desktop app in development mode and lists the expected behaviors to verify in the Review tab.

```bash
bun dev
# Expected: Desktop app opens. Create or open a v2 workspace that has
# a GitHub repo with a pull request. Click the "Review" tab in the
# right sidebar. Verify:
# - PR title, state icon, and link to GitHub are shown
# - Review decision badge (approved/changes requested/pending) appears
# - Requested reviewers are listed
# - CI checks section is collapsible, shows pass/fail/pending icons
# - Comments section shows active comments with avatars and previews
# - Hovering a comment reveals copy/resolve/link action buttons
# - Clicking resolve marks the thread as done (spinner, then updates)
# - "Mark all done" resolves all active threads
# - "Copy all" copies all comments to clipboard
# - Resolved comments appear in a separate collapsed section
# - If no PR exists, the tab shows the placeholder message
# - The tab badge shows the count of unresolved comments
```

--------------------------------

### Install and use the Superset CLI

Source: https://github.com/superset-sh/superset/blob/main/apps/marketing/content/changelog/2026-04-20-v2-workspace-brand-cli.mdx

Extract the CLI tarball, add it to your system PATH, and use commands for authentication, host management, task operations, and organization switching.

```bash
tar -xzf superset-darwin-arm64.tar.gz -C ~/superset
export PATH="$HOME/superset/bin:$PATH"

superset auth login              # OAuth PKCE + loopback
superset host start --daemon     # connects to relay.superset.sh
superset tasks list              # full task CRUD
superset org switch              # manage organizations
```

--------------------------------

### Start and verify the host server

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/cli/host-server.mdx

Spawns the daemon in the background and checks its health status.

```bash
superset start --daemon
```

```bash
superset status
```

--------------------------------

### Install and authenticate Superset CLI

Source: https://github.com/superset-sh/superset/blob/main/apps/marketing/content/changelog/2026-04-27-hosts-settings-terminal-sessions.mdx

Install the Superset CLI via curl and sign in with `superset auth login`. This is the first step to using the CLI for creating workspaces, tailing terminals, and triggering automations.

```bash
curl -fsSL https://superset.sh/cli/install.sh | sh
superset auth login
```

--------------------------------

### Quickstart: create client, workspace, terminals, agents, tasks, and delete

Source: https://github.com/superset-sh/superset/blob/main/packages/sdk/README.md

Shows the main SDK usage: instantiate Superset with apiKey and organizationId, create a workspace with an agent, poll until ready, create a terminal and agent, read terminal output, manage tasks, and delete the workspace. Requires SUPERSET_API_KEY and SUPERSET_ORGANIZATION_ID environment variables.

```ts
import Superset from '@superset_sh/sdk';

const client = new Superset({
  apiKey: process.env.SUPERSET_API_KEY,             // sk_live_…
  organizationId: process.env.SUPERSET_ORGANIZATION_ID, // required for most resources
});

// Start a cloud workspace from an environment, with an agent on first boot
const workspace = await client.workspaces.create({
  environment: 'web',          // id or name; defaults to the first with repositories
  agent: 'claude',
  prompt: 'Fix the flaky login test',
});

// Provisioning runs in the background: wait for `ready`
let current = workspace;
while (current.status === 'provisioning') {
  await new Promise((resolve) => setTimeout(resolve, 5_000));
  const next = await client.workspaces.retrieve(workspace.id);
  if (!next) throw new Error('Workspace was deleted');
  current = next;
}
if (current.status !== 'ready') throw new Error(`Workspace is ${current.status}`);

// Drive it: open a terminal, launch another agent, read its screen
const { terminalId } = await client.terminals.create({ workspaceId: workspace.id, command: 'bun test' });
const { sessionId } = await client.agents.create({ workspaceId: workspace.id, agent: 'codex', prompt: 'Review the diff' });
const screen = await client.terminals.read({ workspaceId: workspace.id, terminalId: sessionId });

// Tasks
const task = await client.tasks.create({ title: 'Wire up auth', priority: 'high' });
await client.tasks.update({ id: task.id, statusId: '<uuid>' });

// Tear the sandbox down when you are done
await client.workspaces.delete(workspace.id);
```

--------------------------------

### Working directory configuration

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/setup-teardown-scripts.mdx

Example JSON configuration that sets the working directory to 'apps/web' and runs 'bun dev'.

```json
{ "cwd": "apps/web", "run": ["bun dev"] }
```

--------------------------------

### Preview email templates during development

Source: https://github.com/superset-sh/superset/blob/main/packages/email/README.md

Use this command to start the development server for email templates within the @superset/email package.

```bash
bun --filter=@superset/email dev
```

--------------------------------

### Install Cua Driver on Windows (PowerShell)

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/computer.mdx

Install Cua Driver on Windows via PowerShell, then enable and start the autostart service.

```powershell
irm https://cua.ai/driver/install.ps1 | iex
cua-driver autostart enable
cua-driver autostart kick
```

--------------------------------

### List plugins and skills

Source: https://github.com/superset-sh/superset/blob/main/plugins/superset/skills/plugins/SKILL.md

Use these commands to see installed plugins with their status, available plugins from the marketplace, and skills on the machine. The status column indicates if a connection is needed.

```bash
superset plugins list                  # installed, with status per plugin
superset plugins list --available      # everything the marketplace offers
superset skills list                   # skills on this machine, and their paths
```

--------------------------------

### Install via Claude Code plugin marketplace

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/orchestration.mdx

Claude Code users can install the skill using the plugin marketplace command.

```text
/plugin marketplace add superset-sh/superset
```

--------------------------------

### Installation config entry in ~/.codex/config.toml

Source: https://github.com/superset-sh/superset/blob/main/docs/codex-plugins-research.md

TOML entry written to config.toml when a plugin is installed; enabled=true enables the plugin, false disables it but preserves credentials.

```toml
[plugins."plugin-name@marketplace-name"]
enabled = true    # false disables but preserves credentials
```

--------------------------------

### Create a workspace or session

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/cli/cli-reference.mdx

Examples of creating workspaces using project IDs, pull requests, sessions, and tags. These commands target the local machine.

```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
```

--------------------------------

### Configure WorkspaceClientProvider

Source: https://github.com/superset-sh/superset/blob/main/plans/host-service-workspace-filesystem-plan.md

Example of wrapping a workspace screen with the WorkspaceClientProvider to establish the workspace context.

```tsx
<WorkspaceClientProvider cacheKey={workspace.id} hostUrl={hostUrl}>
  <V2WorkspaceScreen workspaceId={workspace.id} />
</WorkspaceClientProvider>
```

--------------------------------

### Example tab data model with layout and panes

Source: https://github.com/superset-sh/superset/blob/main/plans/panes-v2-data-model-redesign.md

A JSON example showing the full data model for a tab with a split layout and flat panes map. Includes panes for chat and terminal with their respective data, and the layout tree with split weights.

```json
{
  "version": 1,
  "tabs": [
    {
      "id": "tab_1",
      "titleOverride": "Chat",
      "createdAt": 1743300000000,
      "activePaneId": "pane_chat",
      "layout": {
        "type": "split",
        "id": "split_1",
        "direction": "horizontal",
        "children": [
          { "type": "pane", "paneId": "pane_chat" },
          { "type": "pane", "paneId": "pane_term" }
        ],
        "weights": [3, 2]
      },
      "panes": {
        "pane_chat": {
          "id": "pane_chat",
          "kind": "chat",
          "data": { "sessionId": null }
        },
        "pane_term": {
          "id": "pane_term",
          "kind": "terminal",
          "data": {
            "sessionKey": "workspace-123:abc",
            "cwd": "/workspace/my-repo",
            "launchMode": "workspace-shell"
          }
        }
      }
    }
  ],
  "activeTabId": "tab_1"
}
```

--------------------------------

### superset update command usage

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/cli/cli-reference.mdx

Examples of using the update command to upgrade to the latest release, check for updates, or install a specific version.

```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)
```

--------------------------------

### superset settings theme get

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/cli/cli-reference.mdx

Prints the currently active theme configuration.

```bash
superset settings theme get
```

--------------------------------

### Prompt to set up project for Superset

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/first-workspace.mdx

Use this prompt to instruct an agent to set up the project for Superset, including reading documentation and authoring a .superset/config.json file. This is useful when the 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.
```

--------------------------------

### Verify Cua Driver Installation

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/computer.mdx

Verify the Cua Driver installation and check its health. Run after installation to confirm the driver is ready.

```bash
cua-driver --version
cua-driver doctor
```

--------------------------------

### Initialize Superset SDK Client

Source: https://github.com/superset-sh/superset/blob/main/apps/marketing/content/changelog/2026-05-18-teams-slack-sdk-workspaces.mdx

Example of initializing the Superset client and running an automation. The client automatically reads SUPERSET_API_KEY and SUPERSET_ORGANIZATION_ID environment variables.

```ts
import Superset from '@superset_sh/sdk';
const client = new Superset(); // reads SUPERSET_API_KEY / SUPERSET_ORGANIZATION_ID
await client.automations.run('<automation-id>');
```

--------------------------------

### Start pty-daemon locally

Source: https://github.com/superset-sh/superset/blob/main/packages/pty-daemon/README.md

Run the daemon using bun with a specified socket path. Logs are directed to stderr.

```sh
bun run start --socket=/tmp/pty-daemon.sock
```

--------------------------------

### SDK ring evicted / host restarted / retry epoch - reset frame

Source: https://github.com/superset-sh/superset/blob/main/apps/mobile/plans/acp-vs-claude-sdk.html

Shows the reset frame for the SDK when the ring is evicted, host restarted, or a retry epoch begins. It includes latestSeq and is also fired when the cursor is ahead of the journal. retry() starts a new epoch with a fresh journal and seq restarts at 1; old subscribers get reset("session_restarted").

```json
{ "seq": 0, "sessionId": "6f0d1c2e-…", "ts": …,
  "frame": { "kind": "reset",
             "reason": "cursor_unavailable",
             "latestSeq": 57 } }
// also fired when the cursor is AHEAD of the journal.
// retry() starts a new epoch: fresh journal, seq restarts
// at 1, old subscribers get reset("session_restarted")
```

--------------------------------

### ports.json schema example

Source: https://github.com/superset-sh/superset/blob/main/apps/desktop/plans/20260108-2251-static-ports-json.md

The configuration file structure for defining static ports with labels.

```json
{
  "ports": [
    { "port": 3000, "label": "Frontend Dev Server" },
    { "port": 8080, "label": "API Server" }
  ]
}
```

--------------------------------

### File a bug prompt

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/use-with-slack.mdx

Example prompt to file a bug report, including assignment instructions.

```text
@superset file a bug: the export button 500s on reports over 10k rows.
Assign to whoever owns reporting.
```

--------------------------------

### Prompt: Open Calculator and Compute

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/computer.mdx

Example natural-language prompt for the computer skill, asking the agent to operate a native app and report the result.

```text
Open Calculator, compute 27 × 14, and tell me the displayed result.
```

--------------------------------

### Verify host status

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/remote-access.mdx

Check that the host server is online after starting it with `superset start --daemon`.

```bash
superset status
```

--------------------------------

### Prepend and/or append setup/teardown scripts

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/setup-teardown-scripts.mdx

Add steps before or after the team's committed scripts using the 'before' and 'after' keys. Keys not specified pass through unchanged. The result order is 'before' → committed setup scripts → 'after'.

```json
{
  "setup": {
    "before": ["echo 'running pre-setup'"],
    "after": ["./.superset/my-post-setup.sh"]
  },
  "teardown": {
    "after": ["./.superset/my-cleanup.sh"]
  }
}
```

--------------------------------

### Preset bar layout example

Source: https://github.com/superset-sh/superset/blob/main/apps/desktop/plans/20260807-builtin-cli-preset.md

Shows the preset bar with the built-in Superset CLI preset after the user's own presets. The chip appears like any other preset with no badge or divider.

```text
[ ⌘1 claude ] [ ⌘2 codex ] [ ⌘3 run ] [ >_ Superset CLI ]
```

--------------------------------

### Development Workflow Commands

Source: https://github.com/superset-sh/superset/blob/main/apps/desktop/plans/20260318-1400-ux-polish-linear-style.md

Standard commands for type checking, linting, and starting the development environment from the monorepo root.

```bash
# After all code changes
bun run typecheck
# Expected: No errors across all packages

bun run lint:fix
# Expected: All auto-fixable issues resolved

bun dev
# Expected: Desktop app starts, all three features functional
```

--------------------------------

### Port Forwarding Sidebar Label Examples

Source: https://github.com/superset-sh/superset/blob/main/plans/done/20260824-1849-remote-port-forwarding.md

Examples of status labels displayed in the sidebar for forwarded ports.

```text
3000 · forwarded
3000 → localhost:54321
3000 · local port busy
```

--------------------------------

### Parallel agent tasks with branches and statuses

Source: https://github.com/superset-sh/superset/blob/main/apps/marketing/content/blog/working-with-worktrees-in-superset.mdx

Lists example tasks with their branches and statuses, illustrating how multiple agents run in parallel worktrees.

```text
Task 1: "Write unit tests for the auth module"
  → Branch: agent/auth-tests
  → Status: Running (Claude Code)

Task 2: "Refactor database queries to use prepared statements"
  → Branch: agent/db-refactor
  → Status: Running (Codex)

Task 3: "Update API documentation for v2 endpoints"
  → Branch: agent/api-docs
  → Status: Complete, ready for review

Task 4: "Fix the race condition in the websocket handler"
  → Branch: agent/ws-fix
  → Status: Running (Claude Code)
```

--------------------------------

### Create or register projects with superset projects create

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/cli/getting-started.mdx

Register a project by cloning from a Git URL or importing an existing local 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
```

--------------------------------

### project.setup API definition

Source: https://github.com/superset-sh/superset/blob/main/docs/design/v2-host-project-paths.md

Defines the project.setup function signature with parameters for projectId, mode, and localPath, returning an object with repoPath. The mode can be 'import' or 'clone', where localPath is an existing repo path for import or a parent directory for clone.

```typescript
project.setup({
  projectId: string,
  mode: "import" | "clone",
  localPath: string,       // import: existing repo path; clone: parent dir
})
→ { repoPath: string }
```

--------------------------------

### Mix and match: override one key, extend another

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/setup-teardown-scripts.mdx

Override the setup 'after' key while replacing the teardown scripts entirely with a plain array.

```json
{
  "setup": { "after": ["bun run my-extra-step"] },
  "teardown": ["my-custom-teardown.sh"]
}
```

--------------------------------

### Config passing before and after

Source: https://github.com/superset-sh/superset/blob/main/apps/desktop/docs/HOST_SERVICE_BOUNDARIES.md

Contrasts the old mutate-then-call anti-pattern with the recommended per-call config passing. The after example shows passing SpawnConfig directly to coordinator.start, avoiding stored mutable state.

```TypeScript
// Before (mutate-then-call anti-pattern)
manager.setAuthToken(token);
manager.setCloudApiUrl(url);
manager.setOrganizationName(organizationId, name);
await manager.start(organizationId);
```

```TypeScript
// After (pass config per-call)
await coordinator.start(organizationId, {
  authToken: token,
  cloudApiUrl: url,
  dbPath: path.join(orgDir, "host.db"),
  migrationsPath: getMigrationsPath(),
  allowedOrigins: [`http://localhost:${vitePort}`],
});
```

--------------------------------

### project.setup API definition

Source: https://github.com/superset-sh/superset/blob/main/docs/design/v2-project-create-import.md

Handles the import process for existing projects. This operation is idempotent for the same path, but throws a CONFLICT error if the project is already mapped to a different path.

```ts
project.setup({
  projectId: string,
  mode:
    | { kind: "clone";  parentDir: string }
    | { kind: "import"; repoPath: string }
}) → { repoPath: string }
```

--------------------------------

### Run development server with npm, pnpm, or yarn

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/README.md

Starts the development server for the Next.js documentation site. The comment lines indicate alternative package managers (pnpm and yarn) that can be used instead of npm.

```bash
npm run dev
# or
pnpm dev
# or
yarn dev
```

--------------------------------

### Install Amp Agent CLI

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/cli/host-server.mdx

Install the Amp CLI globally via npm to make it available for use within workspaces.

```bash
npm install -g @sourcegraph/amp
```

--------------------------------

### Create a new project

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/cli/host-server.mdx

Use this command on the first machine to register a project by cloning a remote repo or importing a 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
```

--------------------------------

### Install Codex Agent CLI

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/cli/host-server.mdx

Install the Codex CLI globally via npm to make it available for use within workspaces.

```bash
npm install -g @openai/codex
```

--------------------------------

### Replace polling timer in start()

Source: https://github.com/superset-sh/superset/blob/main/plans/v2-paths-worktree-perf-fix-plan.md

Updates the start method to use GitWatcher for event-driven updates while maintaining a long-cadence safety net.

```ts
start() {
    if (this.unsubscribeFromGitWatcher) return;

    // One initial sweep so existing workspaces have correct branch/sha/upstream
    // even if no .git/ changes have happened since the last process start.
    void this.syncWorkspaceBranches();
    void this.refreshEligibleProjects();

    // Steady-state: react to real .git/ changes per workspace.
    this.unsubscribeFromGitWatcher = this.gitWatcher.onChanged((event) => {
        void this.syncOneWorkspace(event.workspaceId);
    });

    // Long-cadence safety net for events the watcher might miss
    // (overflow, fs.watch errors). 5 min, not 30 s.
    this.safetyNetTimer = setInterval(
        () => void this.syncWorkspaceBranches(),
        SAFETY_NET_INTERVAL_MS,
    );
}
```

--------------------------------

### Build desktop app

Source: https://github.com/superset-sh/superset/blob/main/DEVELOPMENT.md

Builds the desktop app and opens the release folder.

```bash
bun run build
open apps/desktop/release
```

--------------------------------

### Bootstrap desktop-latest release manually

Source: https://github.com/superset-sh/superset/blob/main/plans/release-channels-spec.md

Run once after step 1 lands to create the initial desktop-latest release from the current desktop-v1.7.2 release. Downloads the existing release artifacts and creates a rolling release pointing to the same commit.

```bash
# Run once after step 1 lands
gh release download desktop-v1.7.2 --pattern '*' --dir /tmp/desktop-bootstrap
gh release create desktop-latest /tmp/desktop-bootstrap/* \
  --title "Latest Superset Desktop" \
  --notes "Rolling pointer to the latest published desktop release." \
  --target $(gh release view desktop-v1.7.2 --json targetCommitish --jq .targetCommitish)
```

--------------------------------

### Install Gemini CLI Agent CLI

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/cli/host-server.mdx

Install the Gemini CLI globally via npm to make it available for use within workspaces.

```bash
npm install -g @google/gemini-cli
```

--------------------------------

### Install Cua Driver on macOS and Linux

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/computer.mdx

Install the default Cua Driver on macOS and Linux. Requires a shell with curl and network access.

```bash
/bin/bash -c "$(curl -fsSL https://cua.ai/driver/install.sh)"
```

--------------------------------

### Per-platform build script for Superset CLI

Source: https://github.com/superset-sh/superset/blob/main/packages/cli/DISTRIBUTION.md

Builds the CLI binary, bundles the host service, downloads Node.js, copies native addons and migrations, creates the superset-host wrapper, and packages the output into a tarball.

```bash
# 1. Build CLI binary
bunx cli-framework build --target=bun-darwin-arm64 --outfile=dist/bin/superset

# 2. Bundle host service JS (single file, native deps external)
esbuild packages/host-service/src/serve.ts \
  --bundle --platform=node --format=esm \
  --external:better-sqlite3 --external:node-pty \
  --outfile dist/lib/host-service.js

# 3. Download standalone Node.js binary
curl -O https://nodejs.org/dist/v22.x.x/node-v22.x.x-darwin-arm64.tar.gz
# extract bin/node → dist/lib/node

# 4. Copy native .node files from node_modules prebuilds
cp node_modules/node-pty/prebuilds/darwin-arm64/pty.node dist/lib/native/
cp node_modules/node-pty/prebuilds/darwin-arm64/spawn-helper dist/lib/native/
# better-sqlite3 prebuilds downloaded by prebuild-install during npm install
cp node_modules/better-sqlite3/prebuilds/darwin-arm64/better_sqlite3.node dist/lib/native/

# 5. Copy migrations
cp -r packages/host-service/drizzle/ dist/share/migrations/

# 6. Write superset-host wrapper
cat > dist/bin/superset-host << 'EOF'
#!/bin/sh
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
exec "$SCRIPT_DIR/../lib/node" "$SCRIPT_DIR/../lib/host-service.js" "$@"
EOF
chmod +x dist/bin/superset-host

# 7. Package
tar -czf superset-darwin-arm64.tar.gz -C dist .
```

--------------------------------

### Provision EXPO_PUBLIC_RELAY_URL in setup scripts

Source: https://github.com/superset-sh/superset/blob/main/plans/local-redis-srh-for-relay.md

Adds the missing EXPO_PUBLIC_RELAY_URL environment variable to the setup scripts to prevent mobile app startup crashes.

```bash
write_env_var "EXPO_PUBLIC_RELAY_URL" "http://localhost:$RELAY_PORT"
```

--------------------------------

### Install Claude Code Agent CLI

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/cli/host-server.mdx

Install the Claude Code CLI globally via npm to make it available for use within workspaces.

```bash
npm install -g @anthropic-ai/claude-code
```

--------------------------------

### Install Peekaboo Driver on macOS

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/computer.mdx

Install the alternative Peekaboo driver on macOS via Homebrew. Requires the same Accessibility and Screen Recording permissions as Cua Driver.

```bash
brew install steipete/tap/peekaboo
```

--------------------------------

### Create the Linear wrapper script

Source: https://github.com/superset-sh/superset/blob/main/apps/docs/content/docs/use-with-linear.mdx

Save this script as ~/.linear/open-in-superset.sh and replace <your-project-id> with your actual project ID. The script uses Superset CLI commands to create a workspace and open it in the desktop app.

```bash
#!/usr/bin/env bash
# Linear custom script -> open the issue as a Superset workspace.
set -euo pipefail

PROJECT="<your-project-id>"

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"
```

--------------------------------

### PaneContent Resolver Example

Source: https://github.com/superset-sh/superset/blob/main/apps/desktop/plans/20260322-2305-pane-layout-api-and-test-plan.md

Example implementation of PaneContent as a thin resolver. It looks up the pane definition by kind, throws an error if missing, and calls renderPane with the provided arguments.

```TypeScript
function PaneContent<TPaneData>({
  root,
  group,
  pane,
  registry,
  isActive,
  isFocused,
}: PaneTabPanelProps<TPaneData>) {
  const definition = registry[pane.kind];

  if (!definition) {
    throw new Error(`Missing pane definition for kind: ${pane.kind}`);
  }

  return definition.renderPane({
    pane,
    root,
    groupId: group.id,
    isActive,
    isFocused,
  });
}
```

--------------------------------

### Read pages back with list, get, versions, and pull

Source: https://github.com/superset-sh/superset/blob/main/plugins/superset/skills/page/SKILL.md

Commands to list pages, get a page, list versions, and pull a specific version to stdout. pull writes HTML to stdout and can recover a lost source file or diff shipped content. get includes workspaceLinks showing the workspace and path each publish resolved against.

```bash
superset pages list --workspace <id>     # or omit --workspace for the whole org
superset pages get <page-id-or-slug>
superset pages versions <page-id-or-slug>
superset pages pull <page-id-or-slug> --version 2 > v2.html
```

--------------------------------

### List, set, and theme settings via Superset CLI

Source: https://github.com/superset-sh/superset/blob/main/apps/marketing/content/changelog/2026-08-16-workspaces-triage-editable-markdown.mdx

Use these commands to list all settings, set a specific setting like terminalFontSize, and switch the theme to dark. Changes apply instantly to a running app without cloud login.

```bash
superset settings list
superset settings set terminalFontSize 16
superset settings theme set dark
```

--------------------------------

### Generate session ID (ACP and SDK)

Source: https://github.com/superset-sh/superset/blob/main/apps/mobile/plans/acp-vs-claude-sdk.html

Both ACP and SDK use a random UUID for the session ID. The ACP example uses '7d1e4a02-...' and the SDK example uses '6f0d1c2e-...'.

```javascript
sessionId = randomUUID()
// acp example: "7d1e4a02-9c1f-4f7e-b1de-2f6d1a0c55aa"
// sdk example: "6f0d1c2e-4b7a-4c8e-9f21-3d5a7b9c1e0f"
```

--------------------------------

### Scenario G - restart from settings validation

Source: https://github.com/superset-sh/superset/blob/main/apps/desktop/plans/done/20260504-1200-v2-onboarding-flow.md

Commands to validate restarting onboarding from Settings for an authed user with completed onboarding. Expected to navigate to /onboarding/auth, auto-advance through providers if configured, and land at the first incomplete step or directly back at /workspace if everything is satisfied.

```bash
# Open v2 Settings → General → click "Restart setup" → confirm
# Expected: navigates to /onboarding/auth, which auto-advances since session is valid;
# /onboarding/providers auto-advances if a provider is still configured;
# user lands at the first step where state is incomplete (e.g., gh-cli or permissions),
# or directly back at /workspace if everything is still satisfied.
```

--------------------------------

### Milestone 1 acceptance commands (shell)

Source: https://github.com/superset-sh/superset/blob/main/apps/desktop/plans/done/20260504-1200-v2-onboarding-flow.md

Commands to run the desktop app and manually test the onboarding flow: sign in, navigate to /onboarding/auth, click through pages, and verify persistence on reload.

```shell
cd apps/desktop
bun dev
# Sign in, then navigate to /onboarding/auth manually
# Click Next through all 5 placeholder pages, observing the progress indicator advance
# Reload mid-flow; the same step persists
```

--------------------------------

### Configuration file paths for local state: ~/superset/*

Source: https://github.com/superset-sh/superset/blob/main/plans/cli-distribution-scope.md

Shows the exact paths where the CLI writes its local configuration state.

```text
~/superset/config.json
~/superset/device.json
~/superset/host/<organizationId>/manifest.json
~/superset/host/<organizationId>/host.db

```
Tokens:
Raw