CLI and local API

Name change notice

Superconductor’s app name will be changing. During the transition, existing local paths and developer-facing names still use superconductor, including ~/.superconductor, .superconductor/config.json, the sc CLI, and SUPERCONDUCTOR_* environment variables.

Superconductor ships a local API and a bundled sc CLI for app-aware automation. The API binds to your user account and requires the Superconductor app to run.

Discovery

The app writes local API discovery data to:

~/.superconductor/local-api.json

Superconductor-launched terminals prepend the bundled CLI directory to PATH:

~/.superconductor/bin

The bundled CLI installs at:

~/.superconductor/bin/sc

Common commands

Check app connection:

sc status

List chat providers:

sc chat providers

List chat sessions:

sc chat list

Create and activate a Codex chat session:

sc chat new --provider codex --reasoning medium --activate

Send a message and watch output:

sc chat send "$SESSION_ID" "Summarize this repository." --watch

Inspect the active worktree from a Superconductor terminal:

sc worktree status --json
sc worktree diff-summary --json
sc worktree review-checklist --json

Set the active tab title:

sc tab title "Review Auth Fix"

Open a workspace

Open a project or worktree as a workspace in the running app:

sc workspace open /Users/example/project
sc workspace open /Users/example/project --activate --json

--activate focuses the workspace after it opens. --json prints structured output.

Layout orchestration

The layout orchestration and agent-coordination commands in this section and the next require Settings → Experimental → Agent orchestration. While that toggle is off, they return a feature_disabled error (agent orchestration is disabled). sc workspace open and the chat, worktree, and tab commands above do not need it.

sc layout run creates agent sessions across visible layout slots and maps prompts to them. Use views for top-level splits, tabs for tabs in a view, and panes for panes in a tab:

sc layout run views --ui terminal --provider codex \
  --prompt "Review auth" --prompt "Fix tests" --output json
sc layout run tabs --ui terminal --provider codex --prompt "Open a Codex tab here"
sc layout run panes --ui terminal --provider codex --prompt "Left task" --prompt "Right task"

Send a follow-up prompt to an existing target with sc layout send:

sc layout send --to tab:2 --prompt "Continue here" --output json

Targets use a selector grammar — view:N, tab:N, pane:N, joined with /, 1-based and in visual order (for example view:2/tab:1). Selectors are volatile if the layout changes. For durable targeting, read stable IDs from sc agents list --output json and target id:<stable_target_id> or label:<label>.

Target a workspace that may not be open yet by pairing --worktree PATH with --open-if-needed:

sc layout run views --worktree /Users/example/project --open-if-needed \
  --ui terminal --provider codex --prompt "Review auth"

--open-if-needed also works on sc layout send, sc agent send, and sc agent wait.

Coordinate agent teams

For multi-agent work, label roles, group them, broadcast prompts, and share machine-readable state across agents:

sc agents list --output json
sc agent send --to label:reviewer --prompt "Review the current diff." --queue --output json
sc agent wait --to label:reviewer --idle --timeout-ms 120000 --output json
sc coordination-state set review/status '{"round":1,"open_findings":3}' --output json

The orchestration, observe/control, and coordination commands (sc layout run/send, sc agents ..., sc agent ..., sc coordination-state ...) take --output json and reject the older --json flag.

Worktree targeting

Worktree and tab commands resolve the target worktree from the CLI process’s current directory. Run them from the live worktree root when possible.

Limits

• The Superconductor app must run.
• The local API controls native API-chat sessions.
• Native chat commands (sc chat ...) target API-chat sessions only. Terminal-backed agents are addressable through layout orchestration when the layout response returns a tracked selector.
• Event replay stays in memory and process-local.
• The first local API release omits uploads and user-input answer submission.