Install Superset MCP in your client

Connect Claude, Codex, Cursor, or any MCP client and let your agent create tasks, spin up workspaces, launch agents, and run automations on your behalf.

https://api.superset.sh/mcp

Pick your agent for a one-line install, or copy the config by hand. Every client, including OAuth and API key setup, is covered in the full MCP server docs.

CAPABILITIES

What your agent can do

Tasks

List, get, create, update, and delete tasks; track status.

Workspaces

List, create, update, and delete workspaces on a host.

Agents

List agents configured on a host and launch an agent session in a workspace.

Terminals

Create, list, send input to, read the screen of, and close terminal sessions.

Automations

Schedule recurring runs, run on demand, pause, resume, and read logs.

Projects

List the projects (checked-out repos) available on a host.

Hosts

List the machines you have access to run workspaces on.

Organization

List members of your active organization.

See the available tools reference for every tool name and parameter.

TRY IT

Just ask

“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 9am”

“Pause the nightly cleanup automation”

“Show me the last 10 runs of my Linear triage automation”

AUTHENTICATION

OAuth by default, API keys for CI

Interactive clients authorize over OAuth 2.1 in your browser, scoped to your active organization. For headless environments and CI, generate an API key from Settings → API Keys in the desktop app and pass it as a Bearer token instead. Full setup, including header config for Claude Code, is in the authentication docs.

Sidebar groups (sections) can now be dragged anywhere in their project's list — above, between, and below ungrouped workspaces — instead of being stuck at the bottom.

Group membership is now explicit instead of positional.

Fixes a pre-existing drag bug from perf(desktop): cut sidebar hover and polling render fan-out #6377 where rows displaced by any sidebar drag (including plain workspace drags on main) visually vanished mid-drag.

Fixes Delete group / Ungroup context-menu actions teleporting rows to the top of the project.

Why / Context

Groups were pinned to the bottom by three interlocking behaviors: section drags could only sort against other section headers, the drop handler rebuilt the list as "ungrouped first, then sections", and membership was positional — any ungrouped row rendered below a header was silently absorbed into that group, making "group above an ungrouped row" unrepresentable.

How It Works

• SidebarDndItems.membership (flat workspace id → flat section id) carries explicit membership through the drag; groupInfo, commit parsing, and the ghost's predicted accent read the map instead of scanning position.
• Section drag-end collapses the flat list into top-level units (header + members move as one) and arrayMoves among units, ungrouped rows included. A dropped workspace joins the group of the row that ends up directly above it (membershipFromNeighbors); in-place drops restore the pre-drag membership so they write nothing.
• buildDashboardSidebarProjects no longer absorbs trailing ungrouped rows — interleaved orders round-trip through the existing tabOrder persistence.
• Drag-feel fixes (all rooted in the perf(desktop): cut sidebar hover and polling render fan-out #6377 collapse wrapper + the layout shift a section pickup causes):
  • The dnd translate now sits outside each row's overflow-hidden collapse wrapper (moved into SortableWorkspaceItem), so displaced rows slide instead of clipping out of view.
  • Section pickups collapse members instantly, use a live-DOM pointer collision, hide the in-list header (the DragOverlay ghost is the drag representation), and render a SectionDragSpacer that keeps the scroller's scrollHeight constant — without it, the pickup shrink clamps scrollTop near the bottom and dnd-kit's cached rects/overlay transform desync (drops landed ~member-count rows off; ghost drifted 96px from the cursor, both measured).
• deleteSection replaces the deleted group's own slot with its members; moveWorkspaceToSection(null) lands the row directly below its former group.

Manual QA

(all driven end-to-end over CDP in the dev app, real trusted input, unstaged layout)

• Group dragged above / between / below ungrouped rows, both directions — drop lands exactly at the pointer slot (verified numerically: ghost == pointer, gap adjacent, landed index exact)
• Group ↔ group reorder; collapsed-group drag; empty-group lifecycle (drain by drag, drag empty group, drop a row back in)
• Workspace into / out of a group by drag (accent + membership persist); local main row always stays on top
• Pin a grouped row by drag, reorder, unpin back into its group by drag and via context menu (returns to the same slot; sectionId retained while pinned)
• Context menus: Ungroup lands below its group; Delete group keeps members in place; New group from workspace appends at bottom
• In-place drop writes nothing (byte-identical collections before/after)
• Full reload reproduces the exact interleaved order; sidebar state survives across reloads after every scenario
• Pinned + Sessions lanes re-verified after the row-wrapper restructure (render, reorder, cross-lane drags)
• Stress battery on final code: 30 rapid random drags (8–18 ms steps), boundary oscillation with ~1 s dwells, full-sidebar autoscroll sweeps into the Pinned zone, 12 drags under induced 120 ms main-thread jank, Escape-cancels — integrity held (14 rows, no orphaned memberships), zero console errors, exact post-stress reload
• Frame-by-frame visual review of slow drags: rows part around the ghost, no vanishing rows, no double header, WYSIWYG drop

Testing

• bun run typecheck
• bun run lint
• bun test src/renderer/routes/_authenticated (371 pass; includes a new builder test for interleaved layouts)

Design Decisions

• Explicit membership map instead of positional parsing: positional absorption is what made groups-at-bottom load-bearing; the map lets ungrouped rows live below a group while keeping the drag-into-group gesture positional at drop time only.
• Live-DOM collision for section drags instead of dnd-kit's rect store: the pickup reflow invalidates cached rects and the scroll compensation double-counts; comparing the raw pointer against untransformed live rects is immune to both (transformed rects would oscillate — the known sidebar-DnD crash class).
• Spacer instead of animated collapse: keeping scrollHeight constant during the drag removes the scroll clamp entirely, which is what kept the overlay glued to the cursor; the collapse animation was cosmetic and its mid-animation re-measure was itself a source of stale geometry.

Known Limitations

• Dropping a row at the very end of a project joins the last group (row-above rule); use Ungroup or drop below another ungrouped row to leave it ungrouped — inherent to flat lists without end-of-group markers.
• SectionDragSpacer assumes the 32 px sidebar row height; if row height changes it degrades to the old clamp behavior (cosmetic), not a failure.
• Keyboard-sensor sorting shares the fixed handlers but wasn't exercised separately.

Follow-ups

• Legacy profiles that relied on positional absorption will render those trailing rows as ungrouped (their stored sectionId was always null) — this now shows the persisted truth, but counts in group headers may differ from what those users saw before.

Summary by cubic

Make sidebar groups reorderable anywhere in a project's list by replacing positional membership with an explicit map. This removes the “groups at bottom” constraint, fixes rows vanishing mid‑drag, prevents context‑action teleports, improves multiselect, and avoids stray clicks after canceled drags.

• Section drags reorder top‑level units (header + members) against ungrouped rows; grouped rows hide during drag, the in‑list header hides, SectionDragSpacer keeps scroll height constant, and collisions use dnd‑kit’s closestCenter.
• Workspace drops join the group of the row directly above the landing slot; in‑place drops restore pre‑drag membership; the ghost’s accent predicts using the same rule.
• The sidebar builder no longer absorbs trailing ungrouped rows; interleaved orders round‑trip via existing tabOrder persistence.
• Context menus: Ungroup lands directly below the former group; Delete group replaces the group’s slot with its members; no‑op when already ungrouped in the same project.
• Multiselect: the bulk‑actions toolbar is sticky; bulk Ungroup runs back‑to‑front to preserve visual order; collapsing a group prunes hidden members; stale ids drop and additive clicks re‑anchor if the previous anchor is gone.
• Drag feel: displaced rows no longer clip out of view (transform sits outside the collapse wrapper); mouse activation distance is 5 px; Escape‑canceled drags swallow the next click to prevent navigation.
• Rollout: profiles that relied on positional absorption will now show those rows as ungrouped; header counts may differ. Limitation: dropping at the very end joins the last group; use Ungroup or drop below an ungrouped row.

Summary by CodeRabbit

• New Features
  • Improved sidebar drag-and-drop for sections and workspaces.
  • Sections move with their grouped workspaces while preserving layout.
  • Added smoother collapsing, spacing, and visual feedback during drag operations.
  • Bulk actions remain visible while scrolling.
• Bug Fixes
  • Ungrouped workspaces remain correctly ordered among sections.
  • Ungrouping workspaces or deleting sections better preserves sidebar order.
  • Improved workspace transfers, stale grouping recovery, and bulk ungrouping.
  • Workspace selection now excludes hidden or unavailable items.
  • Prevented accidental navigation after canceled drag operations.

Links

• Fixes [bug] Remote/headless hosts never provision agent lifecycle hooks — sidebar status permanently blank for cloud workspaces #6254 (both defects; supersedes the spawn.ts / terminal.ts half of fix(host-service): propagate Superset home directory #6256 — happy to rebase whichever lands second)
• Related: Status indicator dots missing — SUPERSET_HOST_AGENT_HOOK_URL not set in v2 hook environment #3931, [bug] Remote host workspace sessions show a static, non-animated agent activity indicator in the sidebar #5113 (same user-visible symptom)

Summary

• Move apps/desktop/src/main/lib/agent-setup/ into a new shared packages/agent-setup and run it at standalone host-service startup, so CLI/systemd-launched hosts provision agent lifecycle hooks, PATH wrappers, shell bootstrap, and managed skills — previously Electron-only, leaving remote workspaces with permanently blank agent status.
• Give host-service a ~/.superset fallback for SUPERSET_HOME_DIR (terminal launch + shell-ready evidence) and make the CLI forward the variable to the host it spawns — without this, provisioned hooks self-disable on their own guard.
• Add a machine-shared per-agent hooks-disable state: the desktop mirrors its disabledAgentHooks setting to ~/.superset/agent-hooks.json (boot + every toggle) and headless provisioners honor it plus a SUPERSET_DISABLED_AGENT_HOOKS env override — so a machine running both converges instead of flip-flopping, and headless-only hosts get a disable mechanism at all. The login-shell merge also gained a denylist (NODE_ENV / NODE_OPTIONS / ELECTRON_RUN_AS_NODE): a dotfile exporting NODE_ENV=development would otherwise flip the host into dev-mode shutdown, killing the pty-daemon on restart.
• Merge the login-shell env/PATH into the standalone host process at startup, mirroring what the desktop's getProcessEnvWithShellPath() does for hosts it spawns, so git / gh /credential helpers resolve under systemd/cron/non-login launches.

Why / Context

Issue #6254: a CLI-only host had 18 live Claude sessions and 0 rows in terminal_agent_bindings. Two independent defects: (1) SUPERSET_HOME_DIR never reached the PTYs, and (2) nothing outside Electron ever wrote notify.sh, the managed hook entries, ~/.superset/bin, or the zsh/bash bootstrap that host-service's shell-launch.ts expects (it's an explicit read-only mirror of the desktop writers). PR #6256 addressed only (1). Fixing either alone changes nothing user-visible.

How It Works

• packages/agent-setup is the old desktop module nearly verbatim (git tracks the renames). Two things had to become lazy for a shared package: the Superset home dir (resolveSupersetHomeDir() — resolved at call time because the desktop rewrites process.env.SUPERSET_HOME_DIR during boot for dev-workspace builds) and the templates dir (setAgentSetupTemplatesDir() — bundles lose __dirname-relative assets). Templates live at the package root; each distribution copies them next to its bundle: desktop → dist/main/templates (existing vite copy plugin, new source path), CLI tarball → lib/agent-templates (+ plugin/ = repo Claude plugin), TS source → package-relative fallback.
• Host-service calls provisionAgentIntegrations() from serve.ts only — the standalone entry. The desktop uses its own host-service entry and keeps provisioning in Electron boot (it owns the per-agent disabledAgentHooks setting, which has no host-side equivalent; headless hosts provision all agents).
• Env: packages/cli spawn.ts now sets SUPERSET_HOME_DIR on the child (matching host-service-coordinator.ts), and the two host-service readers that resolved "" when unset now use the shared resolver. applyLoginShellEnvToProcess() reuses the existing terminal base-env snapshot (one login-shell probe per boot); launcher-set vars and PATH order always win, login-shell entries append.
• Dropped agent-setup/utils.ts (dead code, flagged as such by no-main-process-blocking.test.ts; its biome + ratchet allowances removed).

Manual QA Checklist

Validated end-to-end in Docker (linux-arm64, the build-dist-linux-docker.sh CI-mirror flow) simulating a systemd host: env -i stripped PATH, fresh $HOME, no SUPERSET_HOME_DIR, running the shipped superset-host:

• Repo smoke test passes on the built tarball (native addons, pty spawn, host boot)
• First boot provisions notify.sh (v8), 12 bin wrappers, zsh/bash bootstrap with OSC 133 marker, all 8 Claude hook groups, Codex/Gemini configs, managed skills — resolved from lib/agent-templates
• Full [bug] Remote/headless hosts never provision agent lifecycle hooks — sidebar status permanently blank for cloud workspaces #6254 chain: provisioned notify.sh → POST notifications.hook (200) → real row in terminal_agent_bindings (seeded terminal session)
• Unknown terminal id still 200s and records nothing (hook is deliberately unauthenticated)
• Restart is idempotent: notify.sh mtime unchanged, no duplicate hook entries
• Login-shell-only PATH dir (via .profile) merged into host process (log asserted)
• Desktop: electron-vite build copies templates+plugin to dist/main/templates ; bundles carry the provisioning + setAgentSetupTemplatesDir(__dirname/templates) wiring
• Desktop dev boot from a worktree provisions into superset-dev-data (dev-workspace SUPERSET_HOME_DIR case) and logs [agent-setup] Agent integrations provisioned
• macOS TS-source simulation (sandboxed $HOME): host-service provisioning writes all artifacts, plugin falls back to repo plugins/superset

Testing

• packages/agent-setup: bun test (109 pass; moved suites) + tsc
• packages/host-service: bun test (1089 pass, incl. no-electron-coupling) + tsc; new login-shell-env.test.ts (5 tests, verified they fail against a mutated implementation)
• packages/cli: spawn.test.ts + tsc
• apps/desktop: bun run typecheck; suites around every touched import site (terminal, terminal-host, settings/workspaces routers, bundled-cli, no-main-process-blocking) — 460+ pass
• bunx sherif, biome check on all touched files
• The headless E2E above is checked in as packages/cli/scripts/headless-e2e.sh and runs automatically in build-dist-linux-docker.sh after the smoke test (guarded behind SUPERSET_HEADLESS_E2E=1 — it wipes $HOME agent configs, so container-only). Verified end-to-end via the checked-in flow.

Design Decisions

• Shared package vs. moving into host-service: the desktop still needs the same writers (settings toggles call setupSingleAgent/teardownSingleAgent; terminal spawn uses the shell-wrapper args), so a package both depend on avoids a desktop→host-service source dependency. Host-service's no-electron-coupling test stays honest — the package has zero Electron imports.
• Provision in serve.ts, not app.ts: app.ts is shared with the desktop's host-service child, which would double-provision against the desktop's own boot call (and ignore disabledAgentHooks).
• noUncheckedIndexedAccess: false in the package tsconfig matches the desktop config the code was written under, but the five sites that leaked into stricter consumers were fixed properly — host-service compiles the package source under its own strict options.

Known Limitations

• Cross-version churn: a desktop and CLI at different versions rewrite each other's managed files at each boot (content markers differ). Both versions stay functional; writes are atomic (temp+rename), so this is churn, not corruption. Accepted.
• The full remote loop (headless host registered to a cloud org, viewed from a desktop through the relay) was verified as two halves — host side (Docker E2E: hooks → bindings) and UI side (CDP: bindings → sidebar indicator) — not as one wire; that seam is pre-existing plumbing this PR doesn't touch.

Follow-ups (surveyed, intentionally not in this PR)

Other Electron-only functionality CLI hosts miss, per the #6254-class audit: chat-v3 migrations/Claude bin absent from the CLI tarball, HOST_MANIFEST_DIR (attachments land in host/standalone), per-terminal resource metrics, serve.ts binding all interfaces without a hostname, .superset/ worktree copy.

Risks / Rollout

• Risk: provisioning now runs on hosts it never ran on; every writer is individually try/caught (one bad $HOME can't block boot) and content-gated (marker/signature checks — never touches user-owned files), the same code the desktop has shipped for months.
• Rollout: no ordering constraints; desktop and CLI halves are independently safe (env fallbacks cover version skew).
• Rollback: revert the two commits; provisioned files are inert without a Superset terminal (notify.sh exits unless SUPERSET_TERMINAL_ID is set).

Summary by cubic

Provision agent hooks, PATH wrappers, and shell bootstrap on standalone host-service startup, and merge the login-shell env. Previously only Electron-launched hosts provisioned these; headless hosts inherited a minimal env, leaving agent status blank and tools unresolved.

• Shared @superset/agent-setup: desktop sets setAgentSetupTemplatesDir(path.join(__dirname, "templates")), mirrors disabled agents via writeSharedDisabledAgentIds(), and calls setupAgentIntegrations(). Standalone host-service resolves templates from lib/agent-templates or SUPERSET_AGENT_TEMPLATES_DIR and runs provisionAgentIntegrations(); missing templates now emit one loud error.
• Shared disable state: desktop mirrors its disable list to ~/.superset/agent-hooks.json; headless hosts honor the file and SUPERSET_DISABLED_AGENT_HOOKS, so all provisioners converge on one set.
• Env: CLI forwards SUPERSET_HOME_DIR; host-service falls back to ~/.superset via resolveSupersetHomeDir() in terminal launch and shell-ready evidence. Host-service merges login-shell env/PATH at boot (launcher vars and PATH order win; missing PATH entries append), never imports NODE_ENV, NODE_OPTIONS, or ELECTRON_RUN_AS_NODE, and validates DESKTOP_NOTIFICATIONS_PORT with a 51741 default.
• Hardening: provisioning writes are idempotent and atomic via writeFileIfChanged, avoiding torn user configs under concurrent provisioners.
• Distribution/CI: CLI tarball ships lib/agent-templates/ plus the bundled Claude plugin. Linux CI installs zsh and runs a headless-host E2E that verifies first-boot provisioning, notify.sh → notifications.hook DB writes, login-shell PATH merge under a stripped env, disable/enable paths, concurrent provisioners, and restart idempotency. A per‑agent matrix dispatches through each of the 13 agents’ own artifacts and asserts host DB bindings.

Rollout

• No migration. Custom launchers must co‑locate templates next to the host bundle or set SUPERSET_AGENT_TEMPLATES_DIR. Headless hosts provision all agents; set SUPERSET_DISABLED_AGENT_HOOKS to disable specific agents.

New Features

• Added lifecycle integrations for Droid, Kimi, Mastra, and Vibe.
• Expanded coding-agent support with managed hooks, wrappers, notifications, skills, and support for 13 agents.
• Added automatic integration provisioning for desktop, standalone, and headless environments.
• Added persistent controls for disabling selected agent hooks.
• Applied login-shell environment settings more consistently to terminal sessions.
• Added configurable template and installation locations.

Bug Fixes

• Improved preservation of existing agent configuration during updates.
• Increased reliability when recovering from incomplete or invalid configuration files.
• Improved setup consistency across desktop, CLI, and host-service environments.

A Workspaces Page Built for Triage #6506

A Workspaces Page Built for Triage

The Workspaces page now groups every workspace by what needs you: Needs attention, Working, Needs review, Idle, Merged. Each row shows live agent status, diff size, PR checks progress, and last activity, so you can sweep a whole fleet of agents without opening anything.

• Sort by last activity, created, diff size, or name; sections collapse and stay collapsed
• A new All devices option in the device filter shows workspaces from every host in one view

Open Workspaces in the sidebar and pick the list view.

The Workspaces page grouping rows into Working, Needs review, and Idle sections with diff stats and PR checks

The board view walks the same buckets as columns, so the two views can never disagree. Flip between them with the toggle next to the sort control.

The Workspaces board view with Working, Needs attention, Needs review, and Merged columns of workspace cards

Edit Markdown in the Rendered Preview #6406

Edit Markdown in the Rendered Preview

Markdown files are now editable straight from the Preview view: type anywhere, click checkboxes, format with the selection menu, ⌘S to save. Saves only rewrite the blocks you touched, so bullet styles, hand-wrapped lines, front matter, and raw HTML stay byte-identical and your git diffs stay clean. The source view is still one toggle away.

Editing a markdown checklist in the rendered preview with the formatting menu open over selected text

Manage App Settings from the CLI #6402 #6418

Manage App Settings from the CLI

Desktop settings and themes are now scriptable: 35 settings across behavior, git, notifications, and typography, no cloud login needed. Changes apply to a running app instantly, themes included.

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

Typical uses: an agent adjusting your setup from a Superset terminal, dotfiles that configure the app on a new machine, or flipping a toggle without leaving your shell.

Restyling the running desktop app from a terminal: theme set, theme import, and settings reset

Sidebar Groups Go Anywhere #6514

Sidebar Groups Go Anywhere

Groups in the sidebar are no longer pinned to the bottom of a project: drag them above, between, or below ungrouped workspaces and the order sticks. The Pinned and Sessions sections also collapse now, just like Projects.

Improvements

• Host unreachable screen - when a workspace's host stops answering, you get a clear takeover screen with live reconnect status and a retry button instead of failing panes; panes stay mounted underneath, so terminal scrollback and unsaved edits survive the drop
• Folder links open in Finder - terminal folder links are now configurable under Settings → Links, with ⇧ Click bound to Open in Finder; paths outside the worktree open in Finder instead of dead-ending
• Remote Workspaces settings - the Security tab is now called Remote Workspaces, and the relay toggle also lives on your local host's page under Settings → Hosts
• Faster sidebar on big repos - gitignored build directories are excluded from file tracking, cutting background git churn, and files in ignored folders now live-reload in open editors
• Sign in with Apple - on the iOS app
• Mobile composer and sessions - the terminal composer gained dictation and attachments, terminal sessions reorder from the sessions sheet, and home is grouped by project with the active scope named on screen
• Mobile requires a paid plan - the iOS app is now Pro-only; free accounts keep home and settings
• Delete your account with a grace period - request deletion from any client and reactivate within 30 days
• Connect any agent to Superset - one-line MCP installs for Claude Code, Codex, Gemini CLI, and more at superset.sh/mcp-install

Bug fixes

• Terminal panes retry attaching after transient server errors instead of giving up
• Click the branch name to rename it, with no layout shift, and renames route to the host that owns the workspace
• Subagent activity no longer fires completion notifications, for Claude and for Codex, the latter contributed by @justinxu421
• Removed unsupported MCP transport types from generated Codex config, contributed by @lizard-kim
• Host cloud-registration failures surface the real error instead of "Not found", and workspaces resolve before being declared missing
• Agent hooks now provision on hosts created headlessly from the CLI, and hook endpoints re-resolve after a host-service restart so running agents keep reporting status
• The PR badge no longer clips in the right sidebar at mid widths, contributed by @andyst-dev
• "All tasks" and "All projects" reset the tasks-page filter dropdowns
• Mobile: saved home filters apply before the first render, and the attachments carousel no longer paints corrupted frames

Summary

• Folder links in terminal output are now settings-driven (Settings → Links → Folder links), matching how file/URL link clicks are configured. Folder-specific actions: reveal in sidebar, open in editor, open in Finder. Defaults: plain = nothing, ⇧ Click = Open in Finder (new — was unbound), ⌘ Click = Reveal in sidebar, ⌘⇧ Click = Open in editor.
• Cmd+clicking a folder that resolves outside the worktree (e.g. ~/some/dir) opens it in Finder instead of dead-ending (the sidebar reveal silently no-ops for paths outside the worktree).
• Fixes the reveal landing behind the Changes tab: the v2 WorkspaceSidebar reads its active tab from v2WorkspaceLocalState.sidebarState.activeTab, not the v2UserPreferences.rightSidebarTab that setRightSidebarTab writes.
• Fixes the hover tooltip going stale when switching modifiers mid-hover (⌘ → ⌘⇧ kept showing "Reveal in sidebar" until re-hover).

How It Works

• folderLinks: FolderTierMap on v2UserPreferences (healed for existing rows), with its own action enum (reveal | external | finder) since folders can't open in the file viewer. useTerminalFolderPolicy() resolves clicks; FolderLinkTierMapper renders the settings section (sibling of LinkTierMapper — different action typing).
• Sidebar folder rows (file tree / changes list) keep the hardcoded folderIntentFor rules — "reveal in sidebar" is meaningless there, so those surfaces aren't bound to the new map.
• revealPath keeps its contract: sidebar if inside the worktree, Finder otherwise.
• external.openFolderInFinder (main process) uses shell.openPath — opens the folder's contents, unlike openInFinder's highlight-in-parent.
• Tooltip staleness root cause: xterm's Linkifier caches the last real MouseEvent and re-fires leave + hover(cachedEvent) on every terminal render tick. Each replay re-seeded modifier flags from the stale cached event, stomping the keydown listener's update within ~one frame. Modifier flags now live in a ref owned by the key listener; hover events only seed them when the event object is genuinely new (event-identity check against the cached object).

Manual QA (all verified end-to-end over CDP against the real dev app, trusted input events)

• Baseline reproduced pre-fix: Cmd+click on ~/Downloads activated the link but opened nothing; tooltip stuck on old label when adding ⇧ mid-hover.
• ⇧+click on an in-worktree folder link → Finder opens that folder (window list [] → ["apps"]).
• ⇧+click on an out-of-worktree folder link → Finder opens it ([] → ["Downloads"]).
• ⌘+click in-worktree folder → sidebar switches to Files tab and reveals the folder expanded+selected; no Finder window.
• Settings → Links shows the new "Folder links" section; rebinding ⇧ Click → "Do nothing" through the real Select UI makes ⇧+click a no-op (and hides the hover label); rebinding back to "Open in Finder" restores it.
• ⌘-hover on an out-of-worktree folder now reads "Open in Finder" (matches the containment fallback the click takes); in-worktree still reads "Reveal in sidebar" — resolvedPath threaded through LinkHoverInfo.
• Tooltip tracks the full modifier cycle live while stationary over a link: ⌘ "Reveal in sidebar" → ⌘⇧ "Open in editor" → ⇧ "Open in Finder" → none (hidden), surviving xterm's cached-event replay ticks through ~1s dwells at each step.

Testing

• bunx tsc --noEmit, biome check clean
• bun test: terminal suite + absolute-paths + v2UserPreferences schema heal tests — 342 pass

Known Limitations

• Finder naming is macOS-centric; shell.openPath itself is cross-platform.

Summary by CodeRabbit

New Features

• Added the ability to reveal workspace files and folders directly in Finder.
• Files outside the current workspace open in Finder, while workspace items navigate to the Files view before being revealed.
• Added customizable folder-link actions for modifier-key combinations, including workspace reveal, external opening, and Finder.
• Added searchable “Folder links” settings.

Bug Fixes

• Remote workspaces are prevented from using Finder reveal actions.
• Improved cross-platform path handling and error reporting for invalid or inaccessible locations.

Terminal session tabs were locked to creation order. You can now drag sessions

into any order, and the arrangement persists per workspace across app restarts.

Where the reorder lives, and why it isn't the tab strip.

The strip's chips are ~28pt tall inside a horizontal ScrollView, so an in-strip drag competes with the scroll on the same axis — it has to be gated behind a long press, which is already bound to "Close session". I built that version first (long press to pick up, swipe up to close) and it worked, but it puts two hidden gestures on one 28pt target, makes a destructive action undiscoverable, and can't reach off-screen slots without edge auto-scroll. Safari makes the same call: you can't reorder tabs in the iPhone tab bar, only in the tab grid.

So reordering moved to a sessions sheet, opened by a new list button next to the strip's + :

• each row has its own drag handle — the drag activates on movement, no long press, nothing inferred from timing
• ✕ per row closes (same confirm alert as before), so close is visible rather than gestural
• tapping a row switches to that session and dismisses the sheet
• the strip is unchanged otherwise, including its existing long-press-to-close

Ordering rules

(orderTerminalRows): saved arrangement first, then anything it doesn't mention appended in creation order. New sessions append at the end; closed sessions drop out without moving their neighbours; a session that appears on the host while the app is away is appended rather than reshuffling the saved order. Only ids the user actually arranged are stored.

Persistence follows the existing screens/(authenticated)/stores/ pattern (zustand + persist + AsyncStorage), keyed terminal-tab-order-v1, same shape as terminalSeenStore / pinnedWorkspacesStore.

How I tested it

iOS simulator (iPhone 16e, iOS 26), driven with Maestro against a harness screen wired exactly like the sheet — same SessionList, same store, same orderTerminalRows — since a live host wasn't available in this worktree:

• drag by handle moves a row the expected number of slots (verified for moves up and down, and after the list had been scrolled); order and saved order match
• order survives a cold app restart (terminate + launch), repeatedly
• new sessions append at the end and leave the saved order untouched
• closing a session drops it out; the remaining rows keep their arrangement
• tapping a row selects it; ✕ removes it
• the list still scrolls normally with 11 rows

Two bugs the simulator caught: the width map for the first (in-strip) version only ever held the last chip's measurement, because sibling onLayout writes in the same tick can't read a shared value back; and rows were merging into one VoiceOver element, hiding the ✕ and the handle — the row is now three sibling elements with their own labels.

Terminal scrollback (asked for separately): verified good. Loaded the real generated xterm page with the same WebView props (scrollEnabled={false}, bounces={false}), filled it with 300 lines, and touch-dragged — the view moved from lines 258–300 back to 231–274 with the scrollbar visible. The outer WebView's disabled scroll view does not block xterm's own viewport. Note that in the alternate screen (Claude Code, vim, less) there is no scrollback by design — drags become mouse-wheel reports to the app, which is what the MALFORMED_MOUSE_REPORT guard in generate-terminal-html.ts handles. Same as desktop and web.

Not runtime-tested: the sheet's own data wiring (host lookup, killSession) needs a live host. It mirrors NewSessionSheet exactly, and the confirm alert it shows is the same call the strip's long-press uses, which I did verify.

bun run lint:fix and bun run typecheck pass in apps/mobile (after bun run build:types in packages/host-service).

Checklist

• PR title follows conventional commits (type(scope): subject)
• bun run lint and bun run typecheck pass (CI fails on lint warnings too)
• "Allow edits from maintainers" is checked on fork PRs (Incomplete)

Summary by cubic

Reorders terminal sessions from a Sessions sheet and persists the arrangement per workspace. Tabs were fixed to creation time; they now render in the saved order, and the active session stays attached while you reorder.

• Adds a workspace/[id]/sessions sheet (formSheet) opened by a list button next to “+”: vertical list with native drag via @expo/ui SwiftUI List.ForEach in edit mode (system grabber, edge auto‑scroll, VoiceOver), tap to switch and dismiss, in‑row ✕ to close, active tint, and an empty state. Styles the list as plain and removes custom drag/hold logic and the system delete control.
• Persists order with useTerminalTabOrderStore (zustand + persist + @react-native-async-storage/async-storage) under terminal-tab-order-v1 (device‑local). Ordering: saved ids first; unknown sessions append by creation time; closed sessions drop out; only arranged ids are stored.
• Integrates with WorkspaceScreen: derives tab rows via orderTerminalRows and pins the active session during reorders; TerminalTabs adds a manage button to open the sheet.
• Fixes: render the list as the sheet’s only layout child to avoid zero‑height cold mounts; show an alert if closing a session fails and still invalidate the host terminal query.

Summary by CodeRabbit

• New Features
  • Added a sessions screen for viewing, selecting, reordering, and closing workspace terminal sessions.
  • Added controls to manage sessions and start new ones.
  • Terminal tab order now persists separately for each workspace.
  • Added session status indicators, active-session highlighting, agent icons, and an empty state.
• Bug Fixes
  • Selecting a session no longer unexpectedly changes the visible session due to tab reordering.

Follow-up: the sheet presented empty on a real device — the wrapping View around the list hit the known formSheet cold-mount bug (flex-derived children lay out at zero height; fast refresh masks it). Fixed in 95458de: the list is now the sheet's only layout child, with the empty state inside it. Verified against a live host — the sheet lists the workspace's real sessions with handles and ✕.

Swapped the hand-rolled drag for a native SwiftUI list. @expo/ui (already a dependency) ships List.ForEach backed by SwiftUI's onMove/onDelete, so the drag, edge auto-scroll, lift animation and VoiceOver support are UIKit's — and ~200 lines of gesture arbitration, index math and hand-tuned animation timing are deleted. The list runs in edit mode: system grabber per row, leading remove control. Verified rendering, sizing and tap-to-select against a live host; the drag itself isn't scriptable (synthetic swipes don't drive UIKit's reorder control) so it wants a real finger.

CodeRabbit's two findings, addressed:

• Unhandled killSession rejection — real, fixed in 459c333. finally doesn't consume a rejection, so a failed kill closed the confirm alert and left the session running silently.
• VoiceOver can't reach the reorder action — stale: it points at SessionRow.tsx, which was deleted when the list moved to a native SwiftUI List. UIKit's reorder control is VoiceOver-operable out of the box (it exposes "Reorder", "drag" and "remove" actions in the a11y tree), so the concern is resolved by the swap rather than by a patch.

Opening the app never told you what you were looking at. The home list was scoped by organization, host, project and sort at once, and only the organization appeared anywhere on screen. Worse, two of the others resolved themselves:

• useSelectedHost falls back to whichever machine happens to be online, so a sleeping laptop silently promotes another host and the app opens onto different work.
• defaultProjectId was the project of whichever workspace was updated last, so an agent finishing overnight in another project moved your default there.

The filter icon carried no active state, and the only place a project was even implied was the empty state: "No workspaces in this project yet."

Projects are now sections instead of a filter

Every project on the host is listed, ordered by its liveliest workspace, collapsible with the state kept per host, with a count so a shut section still says what's inside. The project filter and its defaultProjectId guess are gone, along with the sheet row and route that set it. What remains of the scope — host with its presence dot, and sort— sits in a chip row under the search field, each chip opening the picker it names.

This is worth more than it sounds: on my account the host showed one project before.

It actually has seven — Boid Home, notion-clone, frontend-interview, evidence, presentations and more were invisible behind a filter nobody set.

Date group headers give way to project headers; recency survives as the section ordering.

Design exploration

options ·
interactive mock of what shipped

Two corrections made while building

• Search was never cross-host. useHostWorkspaces(host) only ever fetches the selected host's workspaces, so search escaped the project scope alone — the host predicate in the old code was a no-op. A cross-host "N more on " tail I'd planned was therefore dead code and was removed rather than shipped. Search now reports how far it reached ("N results on this host").
• projectFilter is deleted, not orphaned. It was still read by useNewChatTargets as a fallback for the composer's default target; with it gone the composer falls back to the most recently updated workspace's project, which is what a null filter already did.

How I tested it

On the iOS simulator against a live host and real projects:

• Sections render with counts; collapse toggles and survives a cold restart (terminate + relaunch), keyed per host
• Both chips open their pickers (host picker listed five machines; sort picker toggles)
• Host chip shows the live presence dot
• Search returns "2 results on this host", grouped by project, auto-expanding collapsed sections; clearing restores the full list
• A project with zero workspaces renders correctly (MASTRA-SUPERSET 0)
• Caret renders in both states — the first attempt used a rotate transform, which doesn't reach the underlying SVG and silently rendered nothing

Three rounds of layout review against the real list: headers initially out-weighed their own rows and duplicated the + ; the fix re-weights rows as children, drops my header in favour of the pre-existing row one, and puts the project mark in the same 24pt icon box the rows use so both columns share a grid.

Not exercised: the host-offline empty state.

Follow-ups (not in this PR)

• Density: projects holding only main still cost a header plus a row. Default-collapsing dormant projects would open the list on what's alive.
• useHostTerminals gates rows on host.isOnline , so a relay presence flap empties the tab strip while the terminal keeps streaming. Pre-existing, affects home too, worth its own PR.

Checklist

• PR title follows conventional commits (type(scope): subject)
• bun run lint and bun run typecheck pass (CI fails on lint warnings too)
• "Allow edits from maintainers" is checked on fork PRs (Incomplete)

Summary by cubic

Groups Home by project and makes the active scope visible. Previously, host fell back silently and a guessed project filter hid most work; now sections replace the project filter, and chips name host and sort.

• Projects become sections: headers show avatar/name/count, collapse per host via collapsedProjectsStore (keyed machineId:projectId ) and persist without flash on cold start.
• Unknown/missing projects: workspaces whose project isn’t reported fall under a “No project” section; avoids disappearing during the projects-not-yet-loaded beat.
• Scope bar: adds chips for host (with presence dot) and sort under search; chips open existing host/sort pickers.
• List/order: pinned-first then by recent activity; replaces date headers with project headers.
• Search: stays host-scoped and announces reach (“N results on this host”); empty copy is “No projects on this host yet.”
• Removed project filter: drops /filter/project , the Filter screen’s project row, ProjectFilterScreen , and projectFilter from useWorkspacesFilterStore .
• useNewChatTargets : stops reading the deleted projectFilter ; defaults to the most recently updated workspace’s project.
• UI polish: aligns project/row icons on one grid; lightens header and row weights; hides duplicate branch when it matches the workspace name.

Summary by CodeRabbit

• New Features
  • Home workspaces are now grouped by project with collapsible sections and workspace counts.
  • Added host and sort controls, host-wide search, project-based sorting, and orphan workspace handling.
  • Collapse and expand states are saved between sessions.
• Improvements
  • Updated workspace rows with clearer typography and less redundant branch information.
  • New chat targets prioritize recently updated workspaces.
• Changes
  • Removed project selection from filtering screens and controls.

Renames the Security settings tab to Remote Workspaces — sidebar label, page header, and command palette entry (route stays /settings/security ; "security" kept as a search keyword in both settings search and the palette).

Extracts the expose-via-relay toggle (paywall gate, typed confirmation dialog, optimistic update, restart toast) into a shared ExposeViaRelaySection component.

Adds that toggle to the local host's settings page (Settings > Hosts > ), rendered only when hostId === machineId, so remote workspace access can be switched on from there too.

Simplifies the toggle description and adds a "Learn more" link to docs.superset.sh/remote-workspaces.

Updates all user-facing "Settings > Security" references in automations (offline-host error, RelayOfflineNotice, HostOfflineRunDialog) to the new tab name.

Test plan

• bun run typecheck (desktop) passes
• Biome clean on touched files
• Desktop unit tests pass
• No tests referenced the old strings

Summary by cubic

Renames the Settings "Security" tab to "Remote Workspaces" and adds the relay access toggle to the local host settings. This improves discoverability without breaking links (route remains /settings/security) and preserves "security" as a search keyword.

• Sidebar label, page header, and command palette entry now show "Remote Workspaces"; command palette adds keywords ["security", "relay"].
• Extracts the relay access toggle into a shared ExposeViaRelaySection with paywall gate, typed confirmation, optimistic update, and restart toast; includes a "Learn more" link to the docs.
• Renders the same toggle on the local host page (Settings > Hosts > ) when hostId === machineId.
• Updates automation copy to reference "Settings > Remote Workspaces" in notices and dialogs.

Summary

• Adds a human-facing /mcp-install page: per-client one-line install (Claude Code, Codex, Gemini CLI, Amp CLI) and manual JSON config (Claude Desktop, Cursor), a capabilities overview, example prompts, and an auth summary — linking out to the full MCP server docs for complete details.
• Wires the page into the header nav (Product dropdown), footer, and sitemap.
• Extracts API_URL / MCP_SERVER_URL into a new client-safe apps/marketing/src/lib/api-url.ts so the client-side install-tabs component doesn't drag the fs-based blog/compare helpers from lib/llms.ts into the browser bundle.
• Deliberately at /mcp-install, not /mcp — /mcp already 307-redirects to the real MCP server (api.superset.sh/mcp) for MCP clients that guess the root-domain convention; left that redirect untouched.

Test plan

• bun run --filter=@superset/marketing typecheck
• bunx biome check on all changed/new files
• Verified in dev server: /mcp-install renders 200, /mcp still redirects (307) to https://api.superset.sh/mcp
• Verified via headless Chrome + CDP: install tabs switch correctly (CLI one-liners vs. JSON config), copy button matches existing InstallCommand behavior, header "Product" dropdown and footer both show the new MCP link

Summary by cubic

Adds a new /mcp-install page that gives one-line installs and config snippets for popular MCP clients so users can connect agents to Superset quickly. Fixes the copy button to show inline errors instead of failing silently, and moves API_URL / MCP_SERVER_URL to a browser-safe module to avoid bundling server-only code in the client.

• New route includes per-client CLI installs (Claude Code, Codex, Gemini CLI, Amp CLI), manual configs (Claude Desktop, Cursor), a capabilities overview, examples, and an auth summary with doc links.
• Adds an “MCP” link to the Header Product dropdown and Footer; includes /mcp-install in the sitemap; keeps the existing /mcp 307 redirect to https://api.superset.sh/mcp unchanged.
• Clipboard behavior: previously copy failures were swallowed; now an inline error message is shown and a success check appears on copy.
• Introduces apps/marketing/src/lib/api-url.ts; API_URL and MCP_SERVER_URL are re-exported from lib/llms.ts to prevent bundling fs consumers in client code.

Summary by CodeRabbit

New Features

• Added an MCP Server installation page with setup instructions for multiple developer tools.
• Included one-click copying for installation commands and configuration snippets.
• Added MCP capability overviews, example prompts, server URL details, and authentication guidance.
• Added MCP links to the website header and footer navigation.

Documentation

• Added the MCP installation page to the sitemap for discoverability.

A v2 workspace whose host stops answering used to degrade into failing panes or a blank frame — the durable-object/relay connection dropping was never surfaced. This adds a takeover screen wired to the real connection.

• packages/workspace-client — the shared per-host event-bus socket now tracks connecting | open | reconnecting | closed plus the last _whoowns probe, exposed as getConnectionStatus / subscribeConnectionStatus / reconnect().
• useHostReachability — reads that status, retains the bus so it keeps dialling, and reports unreachable only after 10s of sustained loss. Keyed off the real data path rather than the cloud isOnline flag, whose drift got this gate reverted twice before (fix(desktop): stop gating v2 workspace on flaky host online status #4430, revert: drop host-offline workspace gate from #4672 #4727).
• WorkspaceHostUnreachableState — revives the orphaned WorkspaceHostOfflineState left on disk by revert: drop host-offline workspace gate from #4672 #4727, with a live Reconnecting/Disconnected chip, a reason line derived from the relay probe (503 host not connected, 401/403 unauthorized, 502/504, routing, relay unreachable), and a Retry button.
• WorkspaceHostGate — overlays the screen instead of replacing the workspace, so panes stay mounted and terminal scrollback, unsaved editor documents and in-flight agent sessions survive a drop.
• WorkspaceLocalHostPendingState — replaces the blank <div> the provider rendered when the local host service has no port, with copy per hostServiceStatus and a button that restarts the service through the same coordinator call the tray menu uses.

Two fixes came out of driving the running app over CDP:

• Blank frame on a host-service restart. Losing the port set activeHostUrl to null, which unmounted the whole workspace and left ~5s of empty pane before the service returned. The provider now holds the last known local host URL through a port gap. Measured: 45s across a kill and respawn, zero blank frames.
• Recovery lagged 20.7s behind the host coming back, riding partysocket's backoff toward its 30s ceiling. The hook now re-dials every 5s while the screen is visible → 5.7s.

Test plan

• bun run typecheck (desktop) and biome check clean; packages/workspace-client tests pass (13/13)
• Normal opens and route changes never flash the screen — 189/181/286/308 samples at 100ms, zero visible frames, no console errors
• Sustained local outage: screen appears 14.1s in (≈10s after the socket closed), correct copy, one visibility transition, no flicker
• Recovery: clears 5.7s after the host is listenable again
• Host-service crash: workspace stays mounted, no blank frame
• Remote/relay path unverified — the dev stack runs no relay and every other device has zero workspaces, so the six probe-status variants are only verified as rendered components, not end to end

Screens

Captured from the running app over CDP — real host name, real host ID, not mocked.

The takeover.

Amber Reconnecting chip while the socket keeps dialling, Retry and Host settings. Note the right sidebar stays reachable outside the overlay, which is why there is no "browse workspaces" escape link.

Before — the blank frame this PR also fixes.

A host-service restart nulled the host URL, which unmounted the whole workspace and left ~5s of empty pane with no explanation. Measured 7.5s–12.7s on a plain crash.

After the host returns.

The screen lifts on its own — no reload, no navigation — 5.7s after the host is listenable again. (This workspace had no panes open, so it lands on the empty state.)

Summary by cubic

Surfaces a Host unreachable overlay for v2 workspaces to prevent blank frames and failing panes. Previously we unmounted or left panes failing; now after 10s of sustained loss we cover the workspace, keep panes mounted, and redial every 5s to cut recovery lag.

• packages/workspace-client: per-host event bus now tracks connecting | open | reconnecting | closed plus last relay _whoowns probe; adds getConnectionStatus, subscribeConnectionStatus, and reconnect(); exports HostConnectionState and HostConnectionStatus. No migration required.
• useHostReachability: retains the bus, declares unreachable after 10s, runs a 5s redial loop only while the overlay is visible, and maps probe status to user-facing detail.
• WorkspaceHostGate: overlays instead of unmounting so terminals, unsaved files, and agent sessions survive; marks covered panes inert to stop focus behind the overlay; resolves host names via the cloud list; wrapper stays mounted to avoid remount on reconnect.
• WorkspaceHostUnreachableState: shows a Reconnecting/Disconnected chip, probe-derived reason, a Retry button wired to reconnect(), and a link to host settings.
• WorkspaceLocalHostPendingState: status-specific copy before the local host service exposes a port; can restart the service via the coordinator; never prompts restart while starting/running; shows a toast if restart is clicked without an active org.
• WorkspaceProvider: caches the last local host URL across host-service restarts to avoid blank frames; shows the pending state only before any port has ever been seen; keys WorkspaceTrpcProvider on the workspace (not the host URL) so a port change swaps transport without remounting panes.

Review focus

• Event-bus status transitions, probe wiring, listener lifecycles, and retain/subscribeConnectionStatus cleanup.
• Redial loop: runs only while the overlay is visible and doesn’t fight partysocket backoff; manual reconnect() sets state correctly.
• Overlay behavior: no flicker, children never remount, and covered panes are truly inert.
• Local-host pending path: restart behavior, no restart prompt while starting/running, and toast on missing org.

Summary by CodeRabbit

• New Features
  • Added clearer workspace host connection states, including connecting, reconnecting, unreachable, and disconnected.
  • Added automatic reconnection attempts and a manual retry option.
  • Added connection-specific messaging for relay and local host failures.
  • Preserved workspace content while displaying host connectivity status.
  • Added pending-state feedback when a local host is starting or restarting.
  • Improved handling of temporary local host service restarts.
  • Kept workspace content mounted and protected it from interaction during host outages.

Why

The terminal composer was a stripped copy of the home glass pill — no voice, no attachments, and a send button that hard-popped in and out of a zero-width container instead of morphing. Two divergent copies of a fiddly SwiftUI component.

What

Both surfaces now build on one GlassComposer (screens/(authenticated)/components/GlassComposer), with slots for the surface-specific chrome (header, toolbarLeading, above). NewChatWidget and TerminalComposer are thin wrappers.
The terminal inherits the mic (dictation → recording pill → finalizing chip), the animated mic→send swap, focus-expand, and attachments. Project/branch/agent pickers stay home-only.

Also:

• Attachments sheet moved from (home)/attachments to /(authenticated)/attachments so both surfaces can open it.
• Quick keys are now SwiftUI, inside the composer's Host. As RN siblings their gap to the pill was a two-value guess (pb-[26px]/pb-2.5) at a height that varies continuously, animating on a third curve — it visibly drifted whenever the pill grew. SwiftUI now owns that spacing.
• Terminal attachments upload into the worktree's .superset/attachments/ and ride along as worktree-relative paths appended to the prompt, mirroring the desktop terminal adapter. Agent sessions only — a plain shell tries to execute the path (zsh: permission denied: …IMG_0006.HEIC), so + is gated on agentId != null.

Net −340 lines.

Notable gotchas encountered

Documented inline, since each cost real debugging time:

• The SwiftUI TextField sits outside RN's responder chain. Programmatic focus() doesn't fire onFocusChange; iOS restores first responder after a sheet dismisses without firing it either; and Keyboard.dismiss() can't lower the keyboard for it (tap-outside must call the field's own blur()).
• transitionEnd only fires on the navigator owning the animating screen — moving the attachments route to a parent stack silently killed the refocus callback.
• The liquid-glass material paints past its layout frame. onGeometryChange reports the frame accurately; the bleed still needs explicit padding inside the Host.

Verification

Driven on an iOS 26 simulator against production: expand/collapse, voice control, send insertion, tap-outside dismiss, attachment thumbnails, and an image round-tripping to Claude Code — which read the HEIC and described it correctly.

Summary by cubic

Unifies the home and terminal input into a shared SwiftUI GlassComposer, so the terminal now supports voice, attachments, animated mic→send, and consistent expand/collapse. Previously the terminal had no voice/attachments and a hard-swapping send button; now both surfaces share one component to prevent drift.

• Adds screens/(authenticated)/components/GlassComposer with header, toolbarLeading, and above slots; NewChatWidget and TerminalComposer wrap it. Exposes focus(), blur(), and clear() on a ref, plus keepExpanded, onActiveChange, onSubmit, isSending, and showAttachments.
• Moves the attachments sheet to /(authenticated)/attachments; both composers open the same sheet. Quick keys render in SwiftUI inside the composer's Host for exact spacing and native animation.
• Terminal attachments write to .superset/attachments/ via the host service and are sent as worktree‑relative paths appended to the prompt. The + button shows only for agent sessions. Adds useWriteTerminalAttachments.
• Measures composer height via onGeometryChange and pads for glass bleed to avoid keyboard clipping. onActiveChange enables backdrops/tap‑to‑dismiss in callers.

Migration

• Update any links or router.push calls to the attachments screens from /(authenticated)/(home)/attachments[...] to /(authenticated)/attachments[...].

Written for commit 6c63328. Summary will update on new commits.

Summary by CodeRabbit

• New Features
  • Added photo and screenshot attachment selection with permission guidance, previews, ordering, and multi-select support.
  • Attachments can be added to chats and terminal sessions.
  • Added voice dictation with recording controls, live levels, and transcript insertion.
  • Introduced a unified composer with attachment previews, quick actions, focus controls, and send-state handling.
  • Improved attachment presentation in authenticated mobile flows.
• Refactor
  • Standardized chat and terminal input experiences around the shared composer.

Remove the legacy type = "sse" fields from the project-scoped Codex MCP configuration.

Current Codex configures Streamable HTTP MCP servers from their url and rejects the legacy transport field. Removing it lets contributors load the bundled Superset, Expo, Neon, Linear, and Sentry MCP entries without a configuration schema error while preserving every endpoint and enabled state.

Reference: https://learn.chatgpt.com/docs/extend/mcp?surface=cli

How I tested it

• bun run lint:fix — passed
• bun run lint — passed
• Parsed .codex/config.toml with Python tomllib — passed
• Loaded the URL-only entries with codex mcp list — passed; all five remote servers were recognized
• bun run typecheck — blocked by a pre-existing @types/hast 3.0.4/3.0.5 type conflict in packages/ui
• bun run test — blocked by a pre-existing timeout in packages/workspace-fs/src/watch-pathtypes-growth.test.ts; the isolated rerun failed at the same watcher condition

Checklist

• PR title follows conventional commits (type(scope): subject)
• bun run lint and bun run typecheck pass (lint passes; typecheck has the unrelated failure documented above)
• "Allow edits from maintainers" is checked on fork PRs

Summary by cubic

Removes unsupported MCP transport declarations from the Codex project config so bundled MCP servers load without schema errors. Previously each server declared type = "sse"; now Codex infers Streamable HTTP from url and rejects type, preserving endpoints and enabled flags.

Reviewer notes

• Changed only .codex/config.toml: removed type = "sse" from superset, expo-mcp (disabled), neon, linear, and sentry.
• Validate with codex mcp list; the same five servers should appear with their prior enabled state. No migration required; omit type in new MCP entries.

Summary by CodeRabbit

• Chores
  • Updated MCP server configuration entries while retaining existing server URLs and settings.

Summary

• New superset settings command group: list / get / set / reset plus a theme subgroup (theme list/get/set) — 35 desktop settings (behavior, git, notifications, terminal, terminal/editor typography) and the app theme, all editable from any shell with no cloud login.
• Adds a superset-settings agent skill (.agents/skills/superset-settings/SKILL.md) and a CLI reference section so agents and humans can discover keys, allowed values, and propagation semantics.

Why / Context

Settings were only reachable through the desktop UI. Agents running in Superset terminals (and users scripting their setup) had no way to flip a toggle, change fonts, pick a ringtone, or switch themes. The CLI already ships on every host, so it's the natural surface.

How It Works

Three stores, routed per key by a single registry (packages/cli/src/lib/settings/registry.ts) that mirrors the desktop's validation (enums, ranges, half/tenth font steps):

• local.db (most keys): upserts the same single-row settings table the desktop writes, via drizzle over bun:sqlite. A running app picks changes up on its next window refocus (electron IPC queries have staleTime: 0 + refetch-on-focus). The CLI never creates the DB or tables — the desktop owns migrations; a fresh machine gets an actionable error instead.
• host service (branchPrefixMode, branchPrefixCustom, worktreeBaseDir): these are host-wide values the v2 Git settings page reads from host_settings, so the CLI talks to the local host service's tRPC using the manifest auth token (~/.superset/host//manifest.json) — still no cloud login. The legacy local.db columns are mirrored best-effort for v1 surfaces. settings list degrades to a (host service not running) note when it's down.
• app-state.json (theme): validated against built-ins + imported custom themes + system (with --system-light / --system-dark mappings), written atomically preserving all other app state. Applies at next launch; the command output tells users to quit first.

Deliberately excluded: exposeHostServiceViaRelay (paywalled + confirm dialog in the app), structured JSON settings (terminal presets, agent overrides), and renderer-localStorage prefs (deleteLocalBranch, diff view, hotkeys) that nothing outside the renderer can reach.

Manual QA (CDP against the dev desktop app, this worktree)

Recorded a full demo video locally (CLI command → app updating on refocus) — happy to share; each item below was verified end-to-end with before/after screenshots:

• set confirmOnQuit true / set showResourceMonitor false — General toggles flip on refocus, and back on revert
• set terminalFontSize 20, set editorFontSize 16, reset terminalFontSize — Appearance live previews resize (20px → back to 14px)
• set notificationVolume 40 — volume dropdown updates to "Low (40%)"
• set branchPrefixMode custom + set branchPrefixCustom kiet/ — v2 Git page shows "Custom prefix" + live kiet/branch-name preview (this is what caught the host-service routing requirement: writing only local.db left the UI unchanged)
• theme set light with app quit → relaunch boots in light theme; theme set dark restores
• Compiled binary (bun run build → dist/superset) exercised for all of the above, including manifest-token auth to the host service
• Error paths: unknown key, out-of-range/enum/step violations, missing local.db, host service down

Caveats verified and documented in the skill/docs:

• Force-killing the app leaves a fresh theme-storage:pending localStorage snapshot that beats app-state.json for ~5 min on next boot (reproduced both ways) — hence "quit cleanly first".
• selectedRingtoneId changes the played sound immediately (main process reads the DB) but the Notifications checkmark hydrates once at boot, so it updates after restart.
• QA refocus was triggered by dispatching window blur/focus events over CDP — the same events a real refocus fires.

Testing

• bun test packages/cli/src/lib/settings packages/cli/src/commands/settings — 31 tests (registry validation, local.db roundtrip against a schema-derived temp DB, app-state preservation, host routing fallbacks, command-level set/get/reset)
• Mutation check: broke boolean parsing → registry test fails, restored → green
• bun run typecheck (packages/cli), bun run lint (exit 0), bunx sherif (no issues)
• packages/cli has no test script wired into turbo, so CI won't run these suites automatically (pre-existing gap; ran manually)

Design Decisions

• Direct store access over new desktop IPC: the desktop has no external settings surface, and adding one is a bigger change; writing the same stores with the same validation gets full coverage today. The registry keeps key→store→rules in one reviewable place.
• skipMiddleware: true: settings are machine-local; requiring OAuth would break offline/agent use for no security gain (local.db and the host manifest are already 0600 on-disk secrets).
• Manifest-token host auth instead of --host targeting: git settings follow the UI's "This device" scope; remote-host settings can layer onto the existing resolveHostTarget later if wanted.

Known Limitations

• Theme changes need an app relaunch (the app reads app-state.json once at boot); no push channel exists for external settings changes generally — refocus refetch is the propagation mechanism.
• settings list shows host-backed git keys as unavailable while the host service is down (rather than silently showing stale legacy values).

Summary by cubic

Manage Superset desktop app settings and theme from the CLI. Previously UI-only; now superset settings (list/get/set/reset) and superset settings theme (list/get/set/export/import/remove). Theme changes apply on restart; other settings apply on next window refocus. Removes the unused terminalPersistence setting and drops the persist_terminal column from the local DB.

Highlights

• Validates values through one registry using limits from @superset/shared/settings-constraints. Local settings upsert the single settings row in ~/.superset/local.db with drizzle-orm over bun:sqlite (opened readwrite to survive WAL; reads mirror the desktop by using the first row, not id=1); rejects blank numeric input.
• Host-wide Git settings (branchPrefixMode, branchPrefixCustom, worktreeBaseDir) route through the local host service via tRPC + manifest token and mirror to legacy columns. Calls time out (5s) and map transport/auth failures to actionable errors; settings list degrades these to “host service not running” instead of failing.
• Theme commands update ~/.superset/app-state.json atomically and reuse the desktop’s parser and built-ins from @superset/shared/themes (reserved ids rejected, ids slugified, 256 KB import limit, export strips isBuiltIn, re-import replaces). Rejects arrays as app-state, drops malformed custom themes instead of crashing, and stamps imported themes with isCustom / isBuiltIn. Messages clarify when only system light/dark mappings changed; ringtone changes note immediate sound with Settings reflecting after restart.
• Consolidates ringtones and numeric constraints to @superset/shared with desktop re-export shims; adds a registry-coverage ratchet so every settings column is either exposed or explicitly excluded.

Rollout

• Launch the desktop app once so stores exist; commands otherwise return an actionable error.
• Git settings require the desktop app or superset start to be running.
• Quit the app before changing or importing themes; restart to apply.
• The local DB migration dropping persist_terminal runs at desktop boot; no user intervention required.

Summary by CodeRabbit

• New Features
  • Added CLI commands to list, view, update, reset, and validate desktop settings.
  • Added theme management for built-in, system, and custom themes, including import, export, removal, and system light/dark options.
  • Added support for Git preferences requiring the desktop host service.
  • Added Light, Dark, and Monokai themes with editor and terminal styling.
• Documentation
  • Added comprehensive CLI guidance for settings and themes.
• Tests
  • Added coverage for settings, validation, theme workflows, and host-service behavior.