# Superset

Deep research completed 2026-04-08 from `github.com/superset-sh/superset`.

**Repo:** `github.com/superset-sh/superset` | **Stars:** 9,092 | **License:** Elastic License 2.0 (ELv2)

## Why it matters

Superset takes a fundamentally different approach from other coding agents:
it focuses on **orchestration** rather than terminal emulation or streaming
event plumbing. It doesn't try to understand agent output — it launches
agents in real PTY terminals, observes their lifecycle via hooks, and
coordinates via git worktrees.

- 3-person team shipping daily for 5+ months (2,100+ commits, 80+ releases)
- excellent package boundaries — host-service is deployment-agnostic,
  panes engine is framework-agnostic, sync is layered cleanly
- CLI can control the desktop app remotely via cloud DB command queue
- agent-agnostic: launches Claude, Codex, Gemini, etc. as opaque processes

## Current take

- Superset is the strongest reference for **orchestration-layer design** —
  how to coordinate multiple agents without owning their protocols.
- Their host-service extraction pattern (injectable providers, no Electron
  awareness) is worth studying for Happy's own server/CLI split.
- The Electric SQL cloud-to-local sync is a real production pattern worth
  understanding for Happy's sync story.
- Ship velocity is remarkable — they're actively doing a v2 refactor while
  shipping features daily.

## Key architectural findings

### 1. Monorepo structure (Turborepo + Bun)

**Apps (7+):**
- `apps/desktop` — Electron desktop app (primary product), React 19, xterm.js
- `apps/api` — Next.js cloud API (Neon Postgres, Better Auth, tRPC)
- `apps/web` — Next.js web dashboard
- `apps/electric-proxy` — Cloudflare Worker proxying Electric SQL shape streams
- `apps/mobile` — Expo React Native mobile app
- `apps/admin`, `apps/docs`, `apps/marketing`

**Packages (15+):**
- `@superset/host-service` — **core backend.** Hono HTTP + WebSocket. Manages
  workspaces, terminals (node-pty), filesystem, git, AI chat, PRs. Own SQLite
  DB (Drizzle + better-sqlite3). Zero Electron awareness — accepts injected
  providers via `createApp()` factory.
- `@superset/workspace-client` — React client library. tRPC + React Query
  clients pointing at a host-service instance.
- `@superset/shared` — Agent definitions, command building, task templates.
  Zero framework dependencies.
- `@superset/cli` — Bun-compiled CLI. File-based command routing via
  `@superset/cli-framework`. Commands: auth, devices, host, tasks, workspaces.
- `@superset/local-db` — Desktop-local SQLite (Drizzle). Projects, worktrees,
  workspaces, settings, plus **synced tables** mirroring cloud Postgres via
  Electric SQL.
- `@superset/db` — Cloud Postgres schema (Drizzle). Tasks, users, orgs,
  agent commands, device presence.
- `@superset/panes` — **Standalone binary-tree pane layout engine** with
  Zustand vanilla store. Framework-agnostic core + React bindings. Tabs,
  splits, drag-and-drop, resize.
- `@superset/workspace-fs` — Filesystem ops, fuzzy search (VS Code scorer
  port), watching (@parcel/watcher), resource URIs.
- `@superset/mcp` — MCP server for remote device control: create/delete
  workspaces, start agent sessions, switch workspaces, list devices.
- `@superset/chat` — AI chat runtime (client/server/shared).

### 2. Sync — three distinct layers

**Layer 1: Local SQLite** — per-device desktop state (projects, worktrees,
workspaces, settings). Schema at `packages/local-db/src/schema/schema.ts`.

**Layer 2: Electric SQL** — cloud-to-local real-time sync. The electric-proxy
Worker authenticates and proxies shape streams. Desktop uses
`@electric-sql/client` + `@tanstack/db` to subscribe and write into local
SQLite. Gives offline-capable access to org data, tasks, users.

**Layer 3: WebSocket EventBus** — real-time host-service events. Two event
types: `git:changed` (auto-broadcast on git state changes, 300ms debounce)
and `fs:events` (on-demand per-client filesystem subscriptions). Client-side
ref-counting, auto-reconnect with exponential backoff (1s–30s).

**Layer 4: tRPC** — request-response over HTTP. Host-service exposes
`/trpc/*` routes for health, chat, filesystem, git, github, PRs, workspaces.

### 3. CLI controlling the UI — cloud-mediated command queue

The `agentCommands` table in cloud Postgres acts as a **command queue**:

1. CLI/MCP tool inserts a row: `status: "pending"`, `tool`, `params`,
   `targetDeviceId`, `timeoutAt`
2. MCP server **polls** the row every 500ms waiting for completion
3. Desktop picks up pending commands (via Electric SQL sync), executes
   locally, updates status to `completed`/`failed` with result
4. MCP server sees completion and returns result

No direct WebSocket from CLI to desktop — the cloud DB is the rendezvous
point. This is elegant for remote device control.

### 4. Host-service durability

Host-service **survives app restarts**. On spawn, writes a manifest file
(`~/.superset/host/<orgId>/manifest.json`) with `{pid, endpoint, authToken,
startedAt, protocolVersion}`. On next launch, `HostServiceManager` scans
manifests, health-checks PIDs, and adopts running instances. On normal quit,
detaches without killing services.

### 5. Orchestration model — agent-agnostic

The key insight: Superset does NOT parse or understand agent output streams.

- **Workspace isolation via git worktrees** — each task gets its own worktree
- **Agent-agnostic launch** — agents are CLI command strings launched in real
  PTY terminals: `claude --dangerously-skip-permissions`, `codex --bypass...`,
  `gemini --yolo`, etc.
- **Lifecycle observation, not control** — uses notify hooks and git watchers
  to know when agents start/stop/need attention, but never injects into
  stdin/stdout
- **Task → Agent mapping** — `buildAgentCommand()` renders task metadata into
  a prompt template, writes to `.superset/task-<slug>.md`, passes via
  `--resume` or stdin
- **Pane layout as orchestration surface** — binary-tree layout (like tmux)
  with Zustand. Multiple agents in separate panes/tabs.

### 6. Agent lifecycle hooks

For Claude: merges hook definitions into `~/.claude/settings.json` that call
a `notify.sh` script → hits `GET http://localhost:<port>/hook/complete` →
Express server receives, validates, emits via `notificationsEmitter`. This
is how the desktop knows when agents need attention.

## Ship velocity

- **2,176 commits** on main in ~5.5 months (since Oct 21, 2025)
- **3 core contributors** doing 95%+ of work: Kitenite (1,300), saddlepaddle
  (460), AviPeltz (243)
- **15 releases in 17 days** (Mar 17 – Apr 3, v1.2.0 → v1.4.7)
- **67 releases** from v0.0.12 to v0.0.67 (Dec 9 – Feb 4)
- **~5–7 commits/day** with substantive features
- Currently doing a v2 architectural refactor while shipping daily

## Happy takeaways

- The host-service extraction pattern (injectable providers, zero Electron
  awareness, manifest-based durability) is directly relevant to how Happy
  structures its CLI/server split.
- Electric SQL for cloud-to-local sync is a production-proven pattern worth
  evaluating against Happy's current sync approach.
- The cloud DB command queue for CLI→desktop control is clever — no direct
  connection needed, works across networks.
- The "don't parse agent output, just observe lifecycle" philosophy is the
  opposite of what OpenCode/Claude do — worth understanding the tradeoffs.
- Pane layout as a standalone package with Zustand is a good reference for
  any layout engine work in Happy.