Session Pack

Move a Claude Code session between users or machines at full fidelity: the real transcript travels, so claude --resume restores the conversation exactly as it was.

Everything environment-specific is tokenized into named binding slots at pack time and re-bound from the receiving environment at unpack time. Secrets are never transported — only the slot and a redacted hint travel; the receiver's own env var supplies the value.

The bundled script is scripts/ccpack.py (Python 3.9+, no dependencies). Always invoke it by absolute path from this skill's directory.

Two user-facing entry points wrap this skill. Prefer pointing the user at them: /pack (skill pack) and /unpack (skill unpack). They are disable-model-invocation, so only the user can trigger them — this skill is the auto-discoverable one and holds the shared script and reference material.

Packing (sender)

1. Identify the session. If the user didn't name one, list candidates by recency: ~/.claude/projects/<cwd with every non-alphanumeric replaced by '-'>/<sessionId>.jsonl. The current session id is in the transcript's sessionId field.
2. Build the bundle:

   python <skill-dir>/scripts/ccpack.py pack <sessionId> -o <name>.ccpack --with-files

   • --with-files snapshots files under the project root that the transcript actually touched, found via file_path / notebook_path / path tool inputs. Include it unless the receiver already has the repo — without it, the conversation will reference files that do not exist on the other side.
   • --deep-files additionally harvests paths appearing in tool results (Grep, Glob, Bash output) — files the model reasoned about but never opened directly. Broader and noisier; use when the conversation did a lot of searching.
   • --max-files N caps collection (default 200). Anything dropped is counted and reported, never silently truncated.
   • --with-history also carries ~/.claude/file-history/<id> (undo versions). Rarely needed.
   • --no-generic disables the key = value heuristic if it is producing false positives.
   • --lean turns on token-saving mode (below). Ask the user which they want before packing — it is their call, and the two produce genuinely different bundles.
3. Review REPORT.md in the bundle and show its slot table to the user. Tool results are inlined verbatim in transcripts, so pattern matching is best-effort. Tell the user to confirm nothing proprietary remains before sending. This step is not optional.
4. Relay the file counts. pack reports packed / missing / skipped / truncated. Missing means the transcript references a file that no longer exists even on the sender's machine — the receiver will hit the same gap, so say so rather than letting it surface later as a confusing failure.

Token-saving mode (--lean)

Resuming a bundle replays the whole transcript into the receiver's context, so a packed session is billed again on every turn after the resume. Most of a transcript is not conversation: file bodies inside Write/Edit inputs, tool results the model already summarized in prose, reasoning from turns that are long settled. --lean replaces those with a marked [ccpack lean: N chars omitted] gap and leaves what was said alone. Measured on two real sessions (2,239 and 514 records): -1723% / -5971% / -71~77% of the replayed context at the three levels, with the conversation itself untouched at all three. A resume of the smaller one cost $0.92 full-fidelity and $0.31 at balanced. The figure depends on what the session did - pack prints the real one every time.

Report the before/after numbers the command prints — context ~X -> ~Y tokens (-Z%) — and the per-category table. They are the point of the mode, and REPORT.md and the receiver's inspect both repeat them, so the bundle is never quietly abridged.

Why an abridged transcript still resumes:

• Records are trimmed in place, never removed, so the parentUuid tree and every tool_use/tool_result pair survive untouched. file-history-* records are the one exception — they carry no uuid and take no part in the message tree.
• The tail is protected. The last --lean-keep-tail records are byte-for-byte identical, and thinking blocks are kept for the whole final turn: that is the turn the API replays verbatim when a resume lands mid tool-loop, and a missing block there is a hard error, not a lost detail.
• pack runs the abridged transcript through verify before writing it and falls back to full fidelity if it would not pass. A bundle that fails at resume time, on someone else's machine, is worse than a large one.

Pair it with --with-files: the file bodies cut out of Write/Edit inputs are exactly what files/ carries, so the content is still in the bundle — and the gap marker says so.

Do not use it when the record itself is the deliverable: an audit, an incident review, or a conversation someone will later sync into a repository. Continuous mode is append-only, and an abridged transcript is not a valid continuation of the full one — sync says so out loud if it finds lean markers in the transcript it is about to commit.

Unpacking (receiver)

1. Dry-run first — never unpack blind:

   python <skill-dir>/scripts/ccpack.py inspect <bundle>.ccpack --cwd <target project root>

   Report to the user: CLI version delta, unknown record types, which slots resolve automatically, which need --bind, plus the two compatibility sections below.

   Capabilities. inspect diffs every tool, MCP server, subagent type and skill the transcript called against what this environment provides.

   • MISSING — an MCP server or agent the transcript used that does not exist here. Resuming will produce dead tool calls. Offer to install the agent definition or configure the MCP server before resuming.
   • CHECK — not found on disk but possibly built-in or plugin-provided. Usually benign.

   Files. inspect compares carried file hashes against the target and reports to restore / differ locally / already missing at pack time. A DIFFERS file is never overwritten without --force; ask the user which copy should win.

2. Fill unresolved slots. Slots with strategy env:NAME read the receiver's environment variable; prompt slots need an explicit value. Ask the user for each one rather than guessing, then pass --bind SLOT=VALUE (repeatable). Leaving a slot unbound is allowed — it stays a literal placeholder in the transcript.
3. Install:

   python <skill-dir>/scripts/ccpack.py unpack <bundle>.ccpack --cwd <target> [--bind ...] [--strip-unknown]

   Add --strip-unknown only when inspect flagged record types this CLI does not know. Add --force only to overwrite existing project files, and say so before doing it.
4. Hand off the resume command printed by the script. Do not try to resume for the user — --resume is interactive and must run in their own terminal:

   cd <target>
   claude --resume <new session id>

What unpack adjusts

Memory (memory/), CLAUDE.md, and project .claude/agents|skills|commands are placed into the target; referenced file snapshots are restored only where the file is missing. Memory travels through the same tokenizer as the transcript — it is prose about the sender's environment — and unpack re-binds it to the receiver's values.

Continuous mode: a conversation tracked in git

pack/unpack hand a session over once. init/sync/adopt keep one in a repository, so several people work the same conversation the way they work the same code. Same tokenizer, different plumbing: git clean/smudge filters bind on checkout and canonicalize on commit, so every participant's copy shows their own paths while the committed blob shows slots.

Two remotes are required before offering this mode — check git remote -v before running init:

1. A code remote (origin, or any dedicated remote) — continuous mode exists so other people can read, adopt, or fork a conversation, which only works if the code it points to is fetchable by someone besides the current machine. No remote at all (local-only repo, or not a repo yet): don't start continuous mode. Tell the user it needs a remote repository first, and offer to help them create one and run git remote add origin <url> — a project of its own, never the shared hub below (a code branch pushed there collides with every other orphan project doing the same thing, since hub refs are collision-proofed only for conversations, not for refs/heads/*). If they don't want to set one up, use pack/unpack instead — it carries the files themselves and needs no remote.
2. A hub remote (optional, recommended for teams) — every conversation is published here too, regardless of which repo it came from. If git remote -v shows no hub entry, ask the user for their team's hub URL and add it:

   git remote add hub <hub-repo-url>

   Teams that standardize on one hub should pin its URL right here in this file, so the remote can be added without asking. If the user has no hub, skip the hub publish step — origin alone is a complete setup.

ccpack init --name token-grace          # link this session to a conversation ref
ccpack sync --all --publish -m "..."    # origin: code + conversation, pushed atomically
ccpack sync --publish --remote hub      # hub: same conversation commit, no code

# on the other machine
git clone <url> && cd <repo>
ccpack init                             # no local session needed - read mode
ccpack branches                         # what conversations exist
ccpack adopt alice/token-grace          # -> ~/.claude/projects/...; prints the resume command
ccpack render alice/token-grace         # or just read it
ccpack why src/auth.py:42               # which conversation produced this line

The conversation never enters your working tree. It lives only under refs/ccsession/<you>/<name>, so main carries code and nothing else. That is the default (--sidecar), and it is what makes this cheap:

--on-main selects the old layout: the transcript becomes a tracked file, visible in PR diffs at the cost of every clone carrying it and every git status paying the filter. Reasonable for a small team where the conversation is the documentation; it does not scale.

Reading a conversation

render is how a conversation reaches a person. By volume a transcript is reasoning blocks and tool results; by meaning it is what the two of you said, so rendering drops roughly 95% of the bytes on purpose and rewrites canonical slots into readable paths — nobody reviewing a pull request has a reason to know what __CCPACK_PROJECT_ROOT_ESC__ is.

ccpack render                                   # this repo's conversation
ccpack render alice/token-grace --turns 3       # someone else's, last 3 exchanges
ccpack render <ref> --since HEAD~1 --format md  # just this commit's turns, for a PR comment

--since is the one that matters for review: it emits only the turns a given commit added, so a 3.5MB session still produces a comment a person will read. Rendered blocks carry their record index (· r12), so a specific turn can be quoted and found again.

The reverse link: ccpack why

sync --all attaches a note (refs/notes/ccsession) to each code commit it creates, naming the conversation ref and the record range that produced it. Notes attach after the commit exists, so the commit hash never changes, and they live on their own ref - nothing in the worktree, opt-in like everything else.

ccpack why src/auth.py:42       # blame -> commit -> note -> those turns, rendered
ccpack why src/auth.py          # last commit touching the file

init installs the notes fetch refspec (to refs/notes/<remote>/ccsession, so a fetch never overwrites notes you have not pushed), and --publish pushes the notes ref - outside the atomic pair, merging first if someone else published notes in between. Commits made without ccpack sync --all carry no note; why says so rather than guessing.

When two people continue the same conversation

ccpack sync -m "..."                    # -> "diverged 6 record(s) in", refuses
ccpack sync --fork sidequest -m "..." --publish
ccpack branches                         # yours and everyone else's
ccpack render main sidequest            # the fork, side by side: shared prefix once,
                                        # then what each line did after it
ccpack gc --dry-run                     # refs already contained elsewhere

Conversations are never merged - a 3-way merge fabricates an exchange nobody had - so render <refA> <refB> is how diverged lines rejoin: in the reader, not in storage.

The ref lifecycle

ccpack log                          # how this conversation grew, sync by sync
ccpack tag v1.0                     # immutable: this conversation produced v1.0
ccpack promote token-grace          # participant line -> refs/ccsession/shared/<name>
ccpack archive old-experiment       # dead line -> refs/ccsession/archive/<who>/<name>

tags/, shared/ and archive/ are reserved namespaces with their own rules: a tag is never rewritten, promote is fast-forward only (rewinding the team line is a human decision), and branches hides archive/ unless asked (--archived). None of them are ever gc candidates - a tag points at an old commit on purpose, which is exactly what gc's "contained elsewhere" test would otherwise condemn.

For a PR bot, why --commit <sha> skips the file/blame step - a bot iterates commits. examples/pr-conversation-comment.yml is a ready GitHub Actions workflow that comments each PR with the conversation that produced its commits.

Published branches live under refs/ccsession/<you>/<name>, following Gerrit's refs/changes/* and GitHub's refs/pull/*. They are not branches: hundreds of them cost nothing in anyone's git branch -a, and init adds the fetch refspec that makes them visible to people who want them. gc drops a ref only when another ref is strictly ahead of it — never a duplicate, and never a commit.

The shared hub

refs/ccsession/* lives inside the repo it was created in by default. Publishing to the hub remote (set up per the prerequisite above) is what makes a conversation readable from one place regardless of which repo it came from — no code ever goes there:

ccpack sync --all --publish -m "..."       # origin: code + conversation, as usual
ccpack sync --publish --remote hub         # hub: conversation only

Any --remote other than origin is treated as a hub, not a second origin: the code branch and refs/notes/ccsession are dropped from that push, and the destination ref is prefixed with the source repo's path — refs/ccsession/<repo-slug>/<you>/<name> — so alice/incident-1234 from two different repos never collides once both land in the hub.

# reading from the hub — no init needed in the source repos for this
git clone <hub-repo-url> && cd <hub-clone>
ccpack init && git fetch origin 'refs/ccsession/*:refs/ccsession/*'
ccpack branches                            # <repo-slug>/<you>/<name>
ccpack render <ref>

• A ref's row in branches is only its tip. Sidecar syncs append to the same ref instead of branching, so one row can hide several past sync checkpoints. branches prints a syncs count per ref and, when any ref has more than one, a trailer telling you which ccpack log <ref> to run — always read that trailer before telling someone "there's 1 conversation up there," since the ref itself may still be several checkpoints deep.
• The hub clone has no code. adopt needs the original source repo — fetch from hub there and adopt from that checkout, not from the hub clone.
• why only works from the origin clone. The reverse-link notes are excluded from the hub push on purpose, so tracing a code line back to its conversation has to happen where the code actually lives.
• The hub mirror is a second push, not a second commit. Run sync --all --publish to origin, then sync --publish --remote hub; the second one has nothing new to commit by construction and pushes the current tip anyway. It reports "nothing new since …" followed by the published: line — both are expected.
• Append-only is enforced. sync classifies the working copy against HEAD as ahead (ordinary append), behind (pull first), or diverged, and refuses to overwrite committed turns.
• Divergence is normal, not an error. When two people both continue from the same point, sync --fork <name> branches from the commit the conversation actually left the shared line at — not from HEAD, which would carry the other person's turns underneath yours.
• Mid-turn commits are blocked. Claude Code appends while a turn runs; committing then stores a tool call whose result does not exist yet. sync waits for the file to settle (--wait, default 10s) and refuses an unfinished turn. --now overrides.
• Run sync in the background, never in the foreground. A foreground shell call is itself the trailing tool call the settle check is waiting on — its own result cannot exist until it finishes, so it can never resolve inside --wait no matter how long that is or how many turns pass; every foreground attempt fails the same way, every time. Launching that same call in the background records "started" as its own result right away, which is what settles the file — the real sync then runs against an already-quiet transcript and succeeds normally. Read the background output for the actual [ok]/[!] line before reporting success; a launched job is not a finished one. Don't default to asking the user to type a !-prefixed command instead — that's a fallback for a tool environment that genuinely cannot background a shell call, not the normal path.
• The last turns can be left out. sync --until N commits records 1-N only - for when the tail is a failed experiment. A prefix keeps append-only intact, so the next sync just appends the rest. Record numbers are the rN indices render shows. Sidecar only.
• Secrets go one way. They are tokenized on the way in and never rendered on the way out: no checkout has anyone else's key. They stay visible placeholders, and sync reports how many.
• Third-party addresses stay literal here, unlike in a bundle. Tokenizing them is irreversible, so inside a shared repo it destroys conversation content rather than protecting anyone. The account address is still tokenized — it differs per person.
• Usernames stay literal here too. They are ordinary words: when a participant is named "bob" and the conversation mentions a bob, tokenizing made the canonical form participant-dependent (false divergence) and renamed people in checkouts. Paths that carry the username are already covered by the home/project slots.
• Fetch is fast-forward only for conversation refs. A forced refspec rewound a locally-advanced ref to the remote's older commit, silently. A genuinely diverged ref (same person, two machines) is reported by fetch instead of clobbered.
• Repos grow until git gc. Every sync stores a full snapshot blob; delta compression happens at gc time (measured: 34 syncs = 5x the transcript, 95% reclaimed by one git gc). Run it occasionally, or let git's auto-gc get there.
• Each participant keeps their own local session id; __CCPACK_SESSION_ID__ is what the repo stores. .ccsession/config.json holds the local binding and is gitignored.
• ccpack verify is the pre-commit gate: conflict markers, broken parentUuid, orphaned tool_result, live secrets. A merged transcript that fails it is not resumable, and nothing downstream would notice until someone tried.

Deliberately not transported

State these to the user when relevant — they are security boundaries, not oversights:

• allowedTools / hasTrustDialogAccepted — the receiver must grant permission themselves.
• MCP OAuth tokens — only server definitions are listed in the manifest; re-authenticate locally.
• ~/.claude/.credentials.json, sessions/ — account credentials and live process registry.

Notes

• Transcript format is Claude Code's internal storage, not a supported interchange format. inspect warns on a minor-version mismatch; treat a major-version gap as unsupported.
• Write JSONL as UTF-8 without BOM and LF endings. The script does; hand-editing in PowerShell with > or Set-Content will corrupt non-ASCII text.
• parentUuid forms the message tree — never hand-trim records out of session.jsonl, or the chain breaks. Use --strip-unknown instead.