/ccc-orchestration

name: ccc-orchestration
description: Spawn, inject into, and ask questions of persistent sibling sessions via Claude Command Center (CCC).
allowed-tools: Bash

Interact with long-running peer sessions via the CCC HTTP server. **Use only for persistent tasks** (e.g., "marketing assistant", "deploy watcher") that need to show on the user's kanban. **For one-shot subtasks, use the built-in `Task` tool instead.**

1. Setup

Port and Path Discovery

Find the CCC URL. DO NOT try to start CCC yourself.

CCC_URL="$(cat ~/.claude/command-center/port.txt 2>/dev/null || echo "${CCC_URL:-http://127.0.0.1:8090}")"
# port.txt can be stale — a now-dead secondary server may have left it pointing
# at a refused port (OPS-41). Verify liveness; fall back to the canonical 8090
# if the recorded URL doesn't answer, so live checks don't hit a dead port.
curl -sf --max-time 2 "$CCC_URL/api/health" >/dev/null 2>&1 || CCC_URL="http://127.0.0.1:8090"
REPO_PATH="${CCC_REPO_PATH:-$(pwd -P)}"

1.2 Network Sandbox Constraint

**CRITICAL:** The Bash sandbox blocks loopback connections. All CCC curls from the Bash tool can fail purely due to network sandboxing, not because CCC is down. **You must run all CCC curls with the network sandbox disabled (localhost IPC).** Ensure your tool execution options disable sandboxing for these requests.

Identifying Your Own Session UUID

If you need to know your own session UUID (e.g. to register yourself in a chat or trace your own session) and `$CLAUDE_SESSION_ID` is empty or unset in your Bash shell: 1. Locate the project directory under `~/.claude/projects/` corresponding to your slugified current working directory (e.g., `/Users/me/Apps/Notes+Tasks` becomes `~/.claude/projects/-Users-me-Apps-Notes-Tasks`). 2. Find the newest `*.jsonl` file in that directory; because you are actively executing, your active session transcript is the most recently modified. 3. The basename of that file (without the `.jsonl` extension) is your session UUID.

2. API Operations

All operations (except List) use `curl -s -X POST "$CCC_URL<endpoint>" -H "Content-Type: application/json" -d '<json>'`.

URL-Encoding repo_path

**CRITICAL:** Any parameter or payload value for `repo_path` must be properly URL-encoded (especially `+` to `%2B` and spaces to `%20`).

• *Example:* `/Users/me/Apps/Notes+Tasks` must be sent as `/Users/me/Apps/Notes%2BTasks`.
• Failure to URL-encode characters like `+` will result in HTTP 400 Bad Request because `+` is decoded as a space by the server.

Avoiding Slow List Calls

• **List endpoints can be slow:** `/api/sessions?all=1` and `/api/sessions?repo_path=...` can exceed 15s on repositories with many transcripts.
• **List is skippable:** You only need List as an anti-double-spawn guard. If you already have the target `session_id`, do not call List; proceed directly to **Inject** or **Ask**.
• If List is genuinely needed, use a generous timeout (e.g. `curl --max-time 30`).
• **Lightweight Health Probe:** Do not run `/api/sessions?all=1` to check if CCC is alive. Use `/api/version` instead, which is lightweight and fast.

Operations

• **Lightweight Health Check (GET):** `/api/version`

*Returns the version of CCC. Use this to quickly verify CCC is up and running.*

• **List Current Repo (GET):** `/api/sessions?repo_path=<URL-encoded abs path>`

*Returns the unified session list for one repo. Always check if a session for your topic exists before spawning!*

**Resolving a session by name:** rows have **no `name` or `title` field** — matching those silently misses every session. The canonical name is **`display_name`** (the server already resolves custom title → spawn-time name → AI title → first message into it); fall back to substring-matching `first_message` if needed. Use the matched row's `session_id` for Inject/Ask.

  curl -s --max-time 30 "$CCC_URL/api/sessions?repo_path=$ENC_REPO" | python3 -c '
  import json,sys
  q=sys.argv[1].lower()
  for r in json.load(sys.stdin):
      hay=((r.get("display_name") or "")+" "+(r.get("first_message") or "")).lower()
      if q in hay:
          print(r["session_id"], "|", r.get("display_name")); break
  ' "marketing assistant"

• **List Spawned Runs (GET):** `/api/sessions/spawned`

*Returns recent CCC-owned spawns with `spawn_id`, `session_id`, `parent_session_id`, `engine`, `model`, `reasoning_effort`, `repo_path`, `cwd`, and `spawned_at`. Use this if a spawn response has `session_id_pending: true`, or to confirm which engine/model/effort a spawn actually resolved to.* *Dedupe fields:* rows also carry `task_key` (the caller's dedupe token), `task_summary` (first 200 chars of the RAW prompt — `command_summary`/`prompt` is the WRAPPED prompt and starts with boilerplate, so grep this instead), `prompt_hash`, and `display_name` (the AI/enriched title, present only once the session has an archive row). Filters: `?engine=`, `?task_key=` (exact), `?parent=<sid prefix, ≥8 chars>`, `?q=` (case-insensitive substring over name/display_name/task_summary/task_key/prompt), `?include_finished=1` (adds rows from spawned-history.json with `ended_at`/`exit_code` — `exit_code` is null for worker-owned and sweep-dropped rows).*

• **List All (GET):** `/api/sessions?all=1` (optional `&engine=codex|antigravity|claude`)

*Returns cross-repo sessions plus the spawned-run registry.*

• **Spawn:** `/api/sessions/spawn`

*Payload:* `{"prompt": "...", "repo_path": "/abs/repo", "engine": "claude|codex|antigravity", "model": "...", "reasoning_effort": "low|medium|high|xhigh|max"}`. `repo_path` (or `cwd`) is required. `engine`, `model`, and `reasoning_effort` are optional; when omitted, CCC uses the server-side defaults from **Settings → Spawn defaults…**. Legacy `gemini` maps to `antigravity`. **When unsure of a model id, omit `model` entirely** rather than guessing — a made-up id can spawn a broken session. If you do need to see valid ids, `GET /api/engines/models` returns `{"engines": {"codex": ["