handoff
Compress the current Claude Code session into a portable markdown bundle the receiver can paste into a different session (same mac, different machine, claude.ai, future-you) and resume with zero conte
SKILL.md.claude/skills/handoff/SKILL.md
GitHub/handoff - session handoff bundle
Compress this Claude Code session into a single paste-anywhere markdown bundle. Receiver pastes it into a new session and resumes.
Design doc: research/dev-workflows/755-handoff-skill-design/README.md (in ZAO repos).
When to fire
- User types
/handoff - "save my context", "summarize this session", "hand off to another terminal"
- "move this work to my other laptop", "I want to pick this up later"
- About to /clear or /compact and want a portable artifact first
- Switching to claude.ai or a different agent and need to carry context
The 5-section bundle (this is the output shape - do not deviate)
The bundle is recursive-friendly: the receiver pastes the whole thing into a fresh session and the model knows exactly what to do because of the receiver preamble at the top. The receiver can ALSO /handoff again later, chaining bundles. Each bundle's "Previous handoffs in chain" pointer keeps the lineage traceable.
The chain: field has three accepted shapes (pick the most accurate one):
chain: none- first handoff for this thread of workchain: <path-to-prior-bundle>- sequential, this bundle resumes from the named onechain: sibling:<path>- parallel session, related to but not derived from the named bundle (e.g. two terminals working different facets of the same project)
Skip transient overlays in Section E "Skills invoked". List discrete /skill invocations only - omit startup-hook overlays (caveman:caveman, superpowers:using-superpowers) and ambient session-config skills that are always-on. They are noise in the cold-start map.
Always append an "Inline copy-paste block" at the very bottom of the bundle - a one-line instruction the receiver can fire instantly without scrolling through the bundle to find the path:
## Inline copy-paste block (for fast receiver paste)
Ingest the bundle at <full-path-to-this-README> and follow receiver instructions at the top. <N> tasks to absorb.
That single line is what the receiver pastes when they just want to dispatch a fresh session pointed at the bundle.
Always surface friction-source observations in Section B (decisions / why). When the session hit a sandbox block, an ENOSPC, a flaky API, a permissions gate, etc - document it explicitly so the next session does not re-discover it. Friction-source surfacing is the highest-value thing the bundle does. If you skip it, future sessions waste cycles re-learning what you already know.
# Session handoff - YYYY-MM-DD HH:MM
> from <source machine + branch> -> to <receiver, default "fresh CC terminal">
> doc: <path-to-this-bundle>
> chain: <previous-handoff-path-or-none>
## Receiver instructions (read me FIRST, then do exactly this)
You just received a handoff bundle. Do NOT start work yet. Do this:
1. Read ALL sections below (A through E) before responding to anything.
2. If section C has a diff, decide: apply it (`git apply diff.patch`) or note it for later.
3. Create TaskList entries from section A. These are the "to do" items.
4. Use section B as your "why" - do NOT re-litigate decisions captured there unless new info surfaces.
5. Use section D to know what's still running (background jobs, wakeups, subagents).
6. Use section E as your cold-start map for files, skills, memory state.
7. Once integrated, message back: "Ingested handoff <slug>. <N> tasks queued. Ready."
8. If you /handoff later, your new bundle's `chain:` field points BACK to this bundle's path so the chain is traceable.
## A. Tasks to absorb (paste these into your TODO list)
- [ ] <task 1> - <one-line context>
- [ ] <task 2> - <one-line context>
- [ ] <task 3> - <one-line context>
## B. Why - decisions + pivots + ruled-out paths
- <decision 1> because <reason>. Ruled out <alternative> because <reason>.
- <decision 2> ...
## C. Git state
- Branch: `<branch>` (ahead N, behind M, dirty K files)
- Push status: `<pushed | unpushed | merged>`
- Uncommitted diff (apply with `git apply` from repo root):
```diff
<unified diff>
- Untracked files:
<list>
D. In-flight
- Background bash jobs: <task_id - description - status>
- Subagents pending: <agent_type - task>
- Scheduled wakeups: <delaySeconds - reason>
- Open AskUserQuestion: <yes/no>
E. Cold-start map (read if you are confused)
- Files touched this session: <relative paths + brief note>
- Skills invoked:
<skill_name>- <count> - <last result> - Memory writes:
<memory_slug>- <new | updated> - <one-line> - Last-known mental model: <2-3 sentences>
- Open questions for the receiver: <items to clarify with the user>
Section order is fixed: A is task-first because most receivers are mid-work and want the actionable item, not the backstory. B-E are opt-in.
## Phase 0 - Detect repo type
Run:
```bash
bash ${CLAUDE_SKILL_DIR}/scripts/handoff-detect.sh
It prints one of:
zao- cwd hasresearch/events/andcommunity.config.ts-> ZAO OS V1 repobcz- cwd matches BCZ repos patternother-repo- inside a git repo but not ZAO -> output goes to<repo-root>/.handoffs/session-<slug>/no-repo- not in a git repo -> output goes to~/.zao/handoff/<slug>/
Output path rule:
zao->research/events/session-YYYY-MM-DD-<slug>/bcz-><repo-root>/.handoffs/session-<slug>/(or wherever the project keeps similar artifacts)other-repoorno-repo->~/.zao/handoff/session-<slug>/
Phase 1 - Gather state (mechanical, runs scripts)
1a. Git state
SKIP this step if Phase 0 detected no-repo - there is no git state to
gather, and handoff-build.sh git will hard-exit with an error outside a git
repo. Leave the bundle's git-state fields blank/omitted for a no-repo session.
bash ${CLAUDE_SKILL_DIR}/scripts/handoff-build.sh git
Outputs to /tmp/handoff-git-<pid>.txt - branch, push status, dirty file count, unified diff (capped at 500 lines; full diff goes to a sidecar diff.patch if larger).
1b. Files touched + skills invoked + memory writes
You (the model) collect these from conversation memory. The harness does not expose a tool-call audit log, so you derive them from what you actually did this session.
Format:
- Files touched: every path you Wrote or Edited. Group by directory if many.
- Skills invoked: every
Skilltool call by name + a one-line result note. - Memory writes: paths under
~/.claude/projects/.../memory/you created or edited.
1c. In-flight state
- Background bash jobs: review your conversation - any
run_in_background: trueBash calls that have NOT been marked complete in a system-reminder. - TaskList: include any tasks with status
pendingorin_progress(use TaskList tool if available, else recall from conversation). - ScheduleWakeup: any pending wakeups + their fire-time + reason.
- Open AskUserQuestion: did you ask a question that has no answer yet?
Phase 2 - Synthesize sections A + B + E (you the model write these)
These three sections are the high-value parts. Mechanical gathering can't write them - the model has to reflect on the conversation.
Section A - Tasks to absorb (3-5 bullets, the receiver's next moves)
Sources:
- Open TaskList items (pending + in_progress)
- ScheduleWakeup prompts (literal "do this later" content)
- "TODO" / "next step" Zaal said explicitly
- Background bash jobs that haven't completed cleanly
- PRs / commits / pushes the conversation flagged but didn't execute
Voice: imperative, one-line, with a colon-prefix indicating effort if known. Examples:
[ ] Re-fire bonfire for the 7 May 19-23 meetings (5 min, run bash ~/.claude/skills/meeting/scripts/bonfire-episode.sh /tmp/meeting-bonfire-episodes.json)[ ] Write recap doc 754 (~30 min, transcript already at /tmp/meeting-<id>.txt)[ ] Decide PR strategy for doc 754 - same branch as M8 or its own?
3-5 items. If more, pick the most-blocking ones. If fewer than 3 real items, that's fine - don't pad.
Section B - Why (decisions, pivots, ruled-out paths)
This is the expensive-to-reconstruct part. Source: your conversation memory. Pull:
- Explicit decisions ("we picked X because Y")
- Pivots ("tried Z first, abandoned because W")
- Ruled-out alternatives ("considered Q but skipped because R")
- Surprising findings the receiver shouldn't have to re-discover
Voice: declarative, past-tense, named-with-reason. Example:
- "Picked single-file markdown bundle (not multi-file split) because the receiver shouldn't need to know which file to grab first - friction kills the use case."
- "Decided NOT to wrap everything-claude-code:save-session - it's generic, ZAO needs Bonfire push + cowork tracker hooks that don't fit a wrapper."
5-10 items typical. Skip the obvious; capture the non-obvious.
Section E - Cold-start map
| Sub-field | How to fill |
|---|---|
| Files touched | List from Phase 1b. Group by topic if many. |
| Skills invoked | List from Phase 1b. |
| Memory writes | List from Phase 1b. |
| Last-known mental model | 2-3 sentences. "We are mid-X. Just finished Y. Next step is Z." |
| Open questions | Items the receiver should clarify with the user before resuming. Empty is fine. |
Phase 3 - Confirm with the user
Show the user the draft section A + B inline (NOT the whole bundle - too long). Ask:
Section A draft (the tasks the receiver will absorb):
- ...
- ... Section B headline (the decisions you'll explain):
- ...
Receiver context (where is this going?):
- ZOE / cowork bot, via Bonfire (default)
- Another CC session on this mac
- CC on a different machine
- claude.ai or a different agent
- Future-you, weeks later
Slug for the doc folder (default:
<auto-picked from section A>): _______ Targets to fire:
- Write the bundle doc
- DROP INTO THE HANDOFF INBOX (default) -
zao-tracker handoffso it appears in ZOE's /cockpit with NO paste (Phase 7)- Bonfire push (required when receiver is ZOE, best-effort otherwise)
- Auto-clipboard for paste (opt-in now - only if Zaal wants a paste-ready copy for himself; the inbox is the delivery path)
- Cowork tracker rows for EACH section A task (opt-in - the inbox drop is one summary row; check this to also file each task)
Wait for confirmation. Edit Section A based on feedback before writing.
Default-receiver rule: unless Zaal says otherwise, assume the receiver is ZOE via Bonfire - most /handoff invocations are "move this back to the assistant" rather than a same-mac CC-to-CC handoff. When receiver = ZOE:
- Bonfire push (Phase 6) is REQUIRED, not best-effort - if it fails (no key, network error), surface that failure to Zaal explicitly rather than silently reporting success. This is the actual delivery mechanism for a ZOE handoff, not a nice-to-have.
- One Bonfire episode per Section A task (not just one summary episode) so ZOE's queries can surface individual open items, not just a paragraph blob.
- The local bundle file (
~/.zao/handoff/session-<date>-<slug>/README.mdfor no-repo sessions) still gets written as the durable human-readable record, but the clipboard auto-copy is lower priority for a ZOE handoff than for a same-mac receiver - skip asking about it unless Zaal also wants a paste-ready copy for himself. - Still ask the Phase 3 confirmation question every time (don't skip confirmation just because ZOE is the default) - Zaal said "most of the times," not "always," so a same-mac or different-machine receiver is still a real, live option he may pick.
Phase 4 - Write the bundle
Write the bundle to the path Phase 0 picked. Use the 5-section template verbatim (the structure in the "The 5-section bundle" section above).
For a CLOUD / different-machine receiver, add two extra sections above Section A (they are noise for same-mac handoffs, so skip them there):
- "Repos to use (START HERE)" - the exact primary repo the receiver clones (owner/name + git URL + the branch/validate/PR conventions), plus one line naming any secondary/reference repos. Rule of thumb: "if unsure which repo, it is <primary>."
- "Capability boundary (cloud vs terminal)" - a boot self-check (
~/.zao/zao.envfor secrets,~/.claude/skillsfor the brain,gh auth status,$DISPLAYfor GUI) + the escalation rule: when a task needs local secrets, browser/GUI, the clipboard skill, locally-authed MCP, Zaal's real accounts, onchain writes, or a non-repo local file, the cloud session STOPS and asks Zaal to run that step in a mac terminal (or do it himself) rather than silently failing or faking it - and continues with everything it CAN do. This is what lets a cloud session know its own lane.
If the unified diff is over 500 lines:
- Write a one-line-per-file summary inline in Section C
- Write the full diff to
<path>/diff.patchas a sidecar - Note in Section C: "Full diff at diff.patch (apply with
git apply diff.patch)"
Sidecar files (only when relevant):
diff.patch- if uncommitted diff is largeinflight.json- if background jobs are running (raw state for debugging)transcript.md- if this session was processing a meeting (link to the source)
Phase 5 - Secret + PII scan
Before writing, scan the bundle markdown for secrets + PII. Use the regex set from .claude/rules/secret-hygiene.md (project-local if available, else the patterns inlined below):
Secret patterns (HIGH severity):
sk-ant-[A-Za-z0-9_-]{20,}(Anthropic key)ghp_[A-Za-z0-9]{36}(GitHub PAT)sk-(proj-|cp-)?[A-Za-z0-9_-]{30,}(OpenAI key)-----BEGIN ([A-Z]+ )?PRIVATE KEY-----(PEM)0x[0-9a-fA-F]{64}(private key / hash)[0-9]{9,12}:[A-Za-z0-9_-]{30,}(Telegram bot token)AKIA[0-9A-Z]{16}(AWS key)
PII patterns (per .claude/rules/pii-hygiene.md, in ZAO repos):
- third-party emails outside the public ZAO allowlist
- US phone numbers
- street addresses
- third-party Telegram handles
If any HIT, abort the write. Print to chat: [handoff] ABORT - secret/PII match: <pattern>. Redact + re-run. Do NOT auto-redact - that risks leaving partial leaks.
Phase 6 - Bonfire (required when receiver is ZOE, best-effort otherwise)
Build the episodes JSON at a session-specific tmp path so parallel sessions never collide and the Write tool never errors on stale files:
EPISODES_JSON="/tmp/handoff-bonfire-episodes-${slug}-$$.json"
Pattern: /tmp/handoff-bonfire-episodes-<slug>-<pid>.json. The PID makes it unique per invocation; the slug makes it human-readable when scanning /tmp. NEVER hardcode /tmp/handoff-bonfire-episodes.json - that path is a collision trap (the Write tool refuses to overwrite a stale file from a prior session and you waste a turn on rm -f + retry).
Same pattern applies to any other tmp file this skill writes: append -<slug>-$$ so each invocation gets its own filename.
Contents:
{
"episodes": [
{"name": "session:<date>:summary", "body": "<one paragraph: what was worked on, key decisions, where it ended>", "source_tag": "handoff:<slug>"},
{"name": "session:<date>:task-1", "body": "From the <date> session, <action title>. Context: <one-line>.", "source_tag": "handoff:<slug>"}
]
}
One summary episode + one per section-A task. Run:
bash ~/.claude/skills/meeting/scripts/bonfire-episode.sh "$EPISODES_JSON"
The bonfire-episode.sh script handles all env loading + secret-scanning + best-effort posting (post doc 754, it reads ~/.zao/zao.env correctly). If env is missing it prints "skipped (no key)" and exits 0.
Phase 7 - Auto-clipboard (BOOT-CLIPBOARD format - least clicks)
Zaal's standing rule: least clicks always. Do NOT dump the whole bundle markdown to the clipboard. Emit a minimal, two-block BOOT clipboard the receiver can act on without reading or scrolling. Use the clipboard-emit.sh helper directly with exactly two <pre> blocks (each gets its own one-click Copy button):
- The repo (its own labeled spot) - the exact repo the receiver opens, as a copyable clone URL. If the work spans multiple repos, this is the PRIMARY one only; name secondary/reference repos in one line of prose, not as copy blocks.
- The one paste for the terminal - a single self-contained block that does the whole boot: clone the repo, cd in, read the bundle, follow it. One copy, one paste, done. Example shape:
Clone <primary-repo-git-url> and cd into it, then read <bundle-path-relative-to-repo-root> and follow the receiver instructions at the top. <one-line mode + task count>.
cat <<'BODY' | bash ~/.claude/skills/clipboard/bin/clipboard-emit.sh "Cloud terminal boot - <slug>" "cloud-boot-<slug>"
<h2>1. The repo</h2>
<primary-repo owner/name>
<pre><primary-repo git clone URL></pre>
<h2>2. Paste this into the terminal</h2>
<pre><the one self-contained clone+read+follow line></pre>
BODY
Cloud-receiver rule (overrides "never commit the bundle"): if the receiver is a cloud terminal / different machine (i.e. it will NOT have Zaal's local filesystem), the bundle MUST be reachable from a clone - so commit it into the primary repo (a .handoffs/ path is fine; PR + merge) BEFORE writing the clipboard, and make the paste-block path RELATIVE to the repo root (not the absolute mac path). For same-mac receivers, keep it local/uncommitted and the absolute path is fine.
The full bundle still lives at its path for anyone who wants to read it; the clipboard is just the fast boot.
Phase 7.5 - Drop into the handoff INBOX (DEFAULT delivery - no paste)
This is the step that means Zaal never has to paste a handoff into ZOE. Every
handoff registers itself in the shared inbox that ZOE's /cockpit reads, so it
shows up as a HANDOFFS lane item automatically.
Run (best-effort; falls back to clipboard if it fails):
# one summary row per handoff - legacy_source "handoff:<slug>" is what the
# cockpit HANDOFFS lane (bot/src/cockpit/adapters.ts partitionHandoffs) reads.
~/bin/zao-tracker handoff "<slug>" "<one-line: what this handoff is + the top task>"
- The
<slug>matches the bundle folder slug. The summary should lead with the single most important task to pick up. - On success: report
[OK] Inbox - dropped into ZOE /cockpit (no paste needed). - If
zao-trackeris unavailable (env not loaded, network): fall back to the clipboard-for-paste path and say so - do NOT silently drop the handoff. - This REPLACES manual paste as the default. The clipboard is now opt-in (only when Zaal wants a copy for himself).
- The receiver flow: Zaal (or any terminal) runs
/cockpit, sees the handoff in the HANDOFFS lane with its slug + top task, and picks it up. No copy-paste.
Phase 8 - Report
[OK] Bundle -> research/events/session-YYYY-MM-DD-<slug>/README.md
[OK] Inbox -> dropped into ZOE /cockpit HANDOFFS lane (no paste needed)
[OK] Diff -> diff.patch sidecar (NN lines)
[--] Bonfire - skipped (no key) | [OK] Bonfire - N episodes posted
[--] Clipboard - opt-in (skipped) | [OK] Clipboard - ready to paste from ~/.zao/clipboard/session-<slug>.html
[OK] Or copy-paste this whole block into a fresh CC terminal:
<bundle markdown inline>
End with the actual bundle inline (last) so the user can long-press-copy it directly from the terminal if they don't want to open the clipboard page.
Hard rules
- Default voice: receiver is mid-work. Section A is "tasks to absorb into your TODO list", not "things you need to know." Tone is "add these to your list" not "here's the situation."
- Never include the full conversation transcript in the bundle. Section B's job is to compress it. Section E's "mental model" is 2-3 sentences max.
- Never auto-write decisions without confirming Section A with the user first. Skip this only on
--autoflag (for chained workflows). - Never push to remote git as part of
/handoff- EXCEPT the Phase-7 cloud-receiver case, where the bundle must be committed + pushed so a cloud clone can read it (see Phase 7). For same-mac/local receivers, never push. - Never commit the bundle to git for same-mac receivers. Bundles are draft artifacts. The ONLY exception is a cloud/different-machine receiver that needs the bundle reachable from a clone (Phase 7 cloud rule).
- No emojis. No em dashes. Use hyphens. Per global feedback rules.
Anti-patterns
- Do NOT wrap
everything-claude-code:save-session. Native build per doc 755 decision #6. - Do NOT write the bundle as multiple files for "easier reading" - the spec is single-file. Sidecars are only for the diff + inflight raw state, not for splitting the bundle itself.
- Do NOT post the FULL conversation to Bonfire. Only summary + section-A tasks.
- Do NOT include section-A items the user pushed back on - if they edited the draft, write what they confirmed.
Receiver flow (for documentation; not part of this skill)
Receiver gets the bundle. Two paste flows:
- Same-mac fast path: open a new CC terminal, type
/handoff-resume <path-to-bundle-README>(v2 skill, not yet shipped). - Manual path (v1): open any chat surface, paste the bundle. The receiving model reads it, integrates section A into TaskList, and reads B-E as it works.
Scripts
scripts/handoff-detect.sh- print repo type (zao/bcz/other-repo/no-repo) + suggested output pathscripts/handoff-build.sh git- emit git state + diff to a tmp file- (v2)
scripts/handoff-bonfire.sh- thin wrapper that builds the episodes JSON + calls bonfire-episode.sh
References
references/bundle-template.md- the exact 5-section markdown template (copy-paste-able)- Doc 755 (in ZAO OS V1) - design spec
- Doc 754 (in ZAO OS V1) - Bonfire push unblock that makes Phase 6 work
- Doc 717 (in ZAO OS V1) - upstream architecture context