Automation recipes

The bundled sc CLI drives scripts, agent instructions, and terminal workflows while the app runs. Begin every automation with a connection check and use the installed help for exact syntax:

sc status --json
sc help worktree

Inspect the current worktree

Run these commands from an app-launched terminal in the worktree:

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

Use status for the app-owned branch, target, path, and change counts. checks refreshes PR/MR check detail when needed. Limit a diff summary to one file with --file PATH.

Read and add review comments

List open app-managed threads before an agent reviews or fixes the diff:

sc worktree review-list --status open --json
sc worktree review-get "$COMMENT_ID" --json

Add a line-range or file-level comment:

sc worktree review-add --file src/auth.ts \
  --start-line 41 --end-line 46 \
  --author "Automated review" \
  "Handle the expired-token path." --json

sc worktree review-add --file src/auth.ts --anchor file \
  --author "Automated review" \
  "This module needs an integration-level check." --json

Reply through a provider and optionally resolve the thread:

sc worktree review-reply "$COMMENT_ID" --provider codex \
  --resolve "Fixed and verified." --json

Observe the workspace tree

Get the same hierarchy the sidebar uses:

sc workspace list --json

For a long-lived dashboard, sc workspace watch --json emits a snapshot followed by JSON Lines deltas. Rows include sections, projects, worktrees, Git and PR/MR status, and nested agent sessions.

Open or select a workspace:

sc workspace open /Users/example/project --activate --json
sc workspace select "$WORKSPACE_ID" --activate --json

Organize worktrees from a script

Create manual and filtered sidebar sections:

sc section create "Mine" --manual --json
sc section create "Needs review" \
  --rule review_decision=review_required --json
sc section create "Release work" --branch-glob 'release/*' --json

Run sc section assign "Mine" --json from the worktree you want to place. Use section unassign, edit, move, and delete to maintain the workspace. Filter rules are repeatable, so one section can require both a branch pattern and failing checks.

Create or select a worktree

Creating a managed worktree requires an explicit human request. Read sc instructions worktree first.

Create an idle worktree with exact workspace and project IDs:

sc worktree create \
  --workspace "$WORKSPACE_ID" \
  --project "$PROJECT_ID" \
  --json

From a verified app-launched agent session, create a task-bearing worktree:

sc worktree create \
  --project docs \
  --from-file /tmp/docs-task.md \
  --provider codex \
  --background \
  --json

Use the supplied task for the real work; do not create a worktree merely to delegate. Select an existing row with sc worktree select "$ITEM_ID" --activate --json.

Create and observe a Chat UI session

sc chat providers --json
SESSION_ID=$(sc chat new --provider codex --reasoning medium --activate)
sc chat send "$SESSION_ID" "Summarize the current diff." --watch

Send a larger prompt from standard input:

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

sc chat events "$SESSION_ID" streams live session events. Use sc chat stop, cancel, or close according to whether you need to end the active turn or the session.

Set a tab title

From an app-launched terminal:

sc tab title "Docs Review"

The command can also target a tracked agent or nested session explicitly; see sc help tab.

Orchestrate agent teams

App-managed orchestration now has its own documentation section:

Team workflows for lead agents, durable teams, handoffs, and review loops.
Cross-provider teams for assigning providers and models by role.
Layouts and control for visible placement, monitoring, steering, and cancellation.
Coordination state for reports and versioned shared state.
Prompt patterns for adaptable natural-language ways to create and steer teams.

Script behavior

Pass --json to ordinary app commands and --output json to orchestration and coordination commands.
Run worktree and section commands from the intended worktree when possible.
Prefer IDs or stable labels over numeric layout indexes.
Treat live session IDs as ephemeral.
Use a file or standard input for multiline prompts to avoid shell-quoting errors.
Read the relevant sc instructions <topic> guide before a managed worktree, layout, orchestration, or review mutation.

See CLI automation for the complete command map and authorization boundaries.