amirfish1/claude-command-center/handoff

Handoff packages the current session's state into a structured file, then spawns a single fresh successor CCC session that reads the package, verifies its claims against the actual repo, and continues the mission from a clean context. The point is a clean successor session on the kanban with all the load-bearing knowledge intact — not a lossy in-place compaction. It builds on the spawn/report_to mechanics in the ccc-orchestration skill — read that first for the full Spawn/Inject/Ask API.

Cost

1 spawned session. Each spawn is a real billed session on the user's kanban — tell the user the count before spawning. Do not hand off if the work is nearly done (just finish it), and note that plain compaction already handles pure context-length pressure for free. Reach for handoff when you specifically want a clean successor session on the kanban — a fresh start that still knows why every decision was made.

Setup

CCC_URL="$(cat ~/.claude/command-center/port.txt 2>/dev/null || echo "${CCC_URL:-http://127.0.0.1:8090}")"
curl -sf --max-time 2 "$CCC_URL/api/version" >/dev/null 2>&1 || CCC_URL="http://127.0.0.1:8090"
curl -sf --max-time 2 "$CCC_URL/api/version" >/dev/null 2>&1 || CCC_DOWN=1

• (a) Run every CCC curl with the network sandbox disabled — the Bash

sandbox blocks loopback and fails spuriously even when CCC is up.

• (b) URL-encode `repo_path` in query strings (+ → %2B, space → %20).
• (c) Resolve your own session id: $CLAUDE_SESSION_ID, else the newest

*.jsonl under ~/.claude/projects/<slugified-cwd>/ (see ccc-orchestration).

Step 1 — write the handoff package to a file

Write it to handoffs/<yyyy-mm-dd>-<slug>.md in the repo (or a path the user names). Note it may belong in .gitignore if the mission is private. Required sections, each of which earns its place:

• MISSION — the original goal and the current definition of done.
• DECISIONS — each decision with its WHY. Decisions without whys get

relitigated by the successor from scratch; the why is the whole point.

• STATE — done / in-flight / next, each item tagged with the file paths

it touches.

• FILE MAP — the files that matter and why each one matters.
• GOTCHAS — dead ends already tried, environment quirks, things that look

wrong but aren't.

• OPEN QUESTIONS — what's genuinely undecided.

Hard rule: every STATE claim must be verifiable against the repo — the successor checks git, it does not trust prose. If you can't point a claim at a commit, a file, or a test, it's a guess, not state.

Step 2 — spawn the successor

Resolve your session id, then POST one spawn against the same repo, report_to you:

curl -s -X POST "$CCC_URL/api/sessions/spawn" -H "Content-Type: application/json" -d @- <<'JSON'
{
  "prompt": "You are taking over from a previous session. Read the handoff package at /abs/path/to/repo/handoffs/<yyyy-mm-dd>-<slug>.md fully. Then VERIFY its STATE claims against reality: git log, git status, and run any tests it names — trust the repo over the prose, and note every discrepancy you find. Report back: TAKEOVER-ACK, what you verified, any discrepancies found, and your first planned action. Then continue the MISSION described in the package.",
  "repo_path": "/abs/path/to/repo",
  "report_to": "<your-session-id>"
}
JSON

Omit "model" and "reasoning_effort": the server spawn defaults (Settings → Spawn defaults) apply. Pass either explicitly to keep cost down, with "engine" alongside it, since both are validated per engine (see ccc-orchestration § 2 for the per-engine effort ladders). CCC appends the return-address footer (report_to), so the successor injects its ack back to you when it's read and verified the package.

Step 3 — waiting for the ack, then hand off

After spawning, end your turn. Tell the user a successor is taking over and give its session id. The ack arrives by injection (report_to) — do not poll or sleep-loop. If it never arrives, check GET /api/sessions/spawned for whether the successor is still alive.

When the ack arrives: relay it to the user, hand them the successor's session id, and stop working the mission in this session — the successor owns it now, and the user closes this one.

Dry run

If the arguments contain dry-run, print the exact plan — session count (1), the handoff file path, the section list you'll write, and the full successor prompt — and POST nothing (and don't write the file either).

When CCC is down

If CCC_DOWN=1 or the spawn curl returns connection refused (exit 7), still write the package — it's valuable on its own. Tell the user to start a fresh session pointed at the package path. Never pretend the successor spawn ran.

What this is not

• Not compaction — that's lossy, unstructured, and stays in the same session.

Handoff is structured and starts a clean one.

• Not a group chat — this is a baton pass, not collaboration; the old

session steps aside.

• Not fleet-lane-dispatch — that fans out new missions to many lanes. Handoff

continues one mission in a fresh session.