Automation recipes

The bundled sc CLI drives scripts, agent instructions, and terminal workflows while the Superconductor app runs. Commands target the live app through the local API.

Check the current worktree

Run this from a Superconductor-launched terminal:

sc worktree status --json

Use it when a script or agent needs the current branch, target branch, worktree path, or changed-file counts.

Summarize the diff

Request a machine-readable diff summary before an agent reviews its own work:

sc worktree diff-summary --json

For one file:

sc worktree diff-summary --file src/content/docs/docs/cli-local-api.md --json

Build a review checklist

Run the review checklist command when an agent or script needs a structured review starting point:

sc worktree review-checklist --json

Example prompt:

Run sc worktree review-checklist --json, inspect the changed files, and list the three highest-risk review items.

Create a chat session

List available providers:

sc chat providers

Create and activate a chat session:

SESSION_ID=$(sc chat new --provider codex --reasoning medium --activate)

Send a prompt and watch the response:

sc chat send "$SESSION_ID" "Summarize the current diff." --watch

Send a prompt from a file:

sc chat send "$SESSION_ID" --stdin --watch < prompt.txt

Watch session events

Stream events when a script needs to observe a live session:

sc chat events "$SESSION_ID"

The local API emits structured events for messages, turn lifecycle, tool activity, usage, plans, and heartbeats.

Set tab titles

Set the current tab title from an agent or shell script:

sc tab title "Docs Review"

This command requires a Superconductor-launched session, which exports SUPERCONDUCTOR_TERMINAL_ID so the app can identify the calling tab.

Open a workspace from a script

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

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

To open and target in one step, pair --worktree PATH with --open-if-needed on a layout or agent command:

sc layout run views --worktree /Users/example/project --open-if-needed \
  --ui terminal --provider codex --prompt "Start the review."

Fan out parallel agents

The orchestration and coordination recipes below (and the --open-if-needed layout example above) require Settings → Experimental → Agent orchestration; with it off, the sc layout, sc agent(s), and sc coordination-state commands return a feature_disabled error.

Create several labelled agent sessions across split views and map a prompt to each:

sc layout run views --ui terminal --provider codex \
  --label implementer --prompt "Implement the change. Keep edits focused." \
  --label reviewer --prompt "Review the diff for regressions and missing verification." \
  --output json

Use views for top-level splits, tabs for tabs in a view, and panes for panes in a tab.

Send a follow-up to a running agent

Send another prompt to an existing target by selector or label:

sc layout send --to label:implementer --prompt "Address the review findings." --output json

Read stable targets first with sc agents list --output json, then target id:<stable_target_id> or label:<label> for durable follow-ups.

Coordinate a review loop

Group roles, broadcast a prompt, wait for idle, and share machine-readable state across agents:

sc agents group create review-team --agent label:reviewer --agent label:validator --output json
sc agent send --to group:review-team --prompt "Return only actionable findings." --queue --output json
sc agent wait --group review-team --idle --timeout-ms 120000 --output json
sc coordination-state set review/status '{"round":1,"open_findings":3}' --output json

Bound the loop and state the stop condition before it starts: continue until the reviewer reports no actionable findings, a max-round limit is reached, the user stops the loop, or the budget is reached.

Rename setup branches

Rename a worktree branch:

sc worktree rename-branch feat/docs-review

Script behavior

For automation:

• Pass --json for parsing on chat, worktree, and tab commands.
• Pass --output json for orchestration and coordination commands (sc layout run/send, sc agents ..., sc agent ..., sc coordination-state ...); these reject --json.
• Run worktree commands from inside the worktree, since the CLI sends the current directory as worktree_path.
• Run sc status before assuming the app is available.
• Treat chat session IDs as live app IDs; closed sessions drop out of sc chat list.
• Run sc tab title only from a Superconductor-launched terminal.