wrap-pickup

Session continuity across agents: wrap up in one, pick up in another, nothing lost between Claude Code, Codex, and Kimi.

  agent A (any client)                                     agent B (any client)
        │                                                        │
        │ /wrap                                                  │ /pickup
        ▼                                                        ▼
  ┌────────────┐   writes a receipt   ┌────────────┐   reads the receipt   ┌────────────┐
  │  session   │ ───────────────────► │  receipt   │ ◄──────────────────── │  session   │
  │  closes    │                      │   store    │                       │  resumes   │
  └────────────┘                      └────────────┘                       └────────────┘
                                   ~/.agent-handoffs/

What this is not

Single-client memory tools (project memory files, a chat history search, an embeddings index) remember things within one agent, across its own sessions. This is different: it's the handoff between agents — Claude Code closes a session, Codex or Kimi picks it up cold, with the same operational state and none of the raw transcript.

This was extracted from a working system with 390+ measured wrap/pickup runs across three clients — the numbers and the design choices below come from real, repeated cross-agent handoffs, not a clean-room spec.

How it works

A receipt is a small Markdown file with YAML frontmatter: what a session verified, what's still broken, what decisions were made and rejected, and one exact next action. /wrap writes or updates one receipt per material session, into a local store (~/.agent-handoffs/). /pickup, run in any supported client, scans that store's metadata first, matches the right receipt, cross-checks its claims against the live project (git, filesystem, running services — stronger current evidence always wins), and hands back a short brief.

Neither command trusts the other blindly. A receipt is a proposal, not ground truth; consolidating it into a project's real status doc or memory still requires a fresh ownership check on that exact target, so two live agents in the same project never silently clobber each other. See docs/ARCHITECTURE.md for the lifecycle (pending → consumed / superseded) and contract/receipt-contract.md for the full normative spec.

Compatibility

Works today with Claude Code, Codex, and Kimi Code CLI. Each client gets a thin adapter (adapters/<client>/skills/{wrap,pickup}/SKILL.md, plus debrief for Codex and Kimi) that layers client-specific mechanics — where its memory lives, what its session IDs look like — on top of one shared, client-neutral contract. Adding a fourth client means writing one more adapter against that same contract; the receipt format and lifecycle don't change.

Quickstart

git clone <this-repo> ~/wrap-pickup
cd ~/wrap-pickup

# see exactly what will be installed/preserved — no writes
scripts/install-adapters.sh plan --home "$HOME" --repo-root "$PWD"

# install: symlinks the six wrap/pickup skill dirs into each client's
# skills folder, appends one pointer block to each client's global
# instruction file, and initializes the receipt store
scripts/install-adapters.sh apply --home "$HOME" --repo-root "$PWD"

Then, in one client: /wrap to close out a session. In another: /pickup to resume it.

install-adapters.sh apply refuses to run on a machine where none of the target files are already tracked by a prior install, unless a pre-install baseline checksum manifest exists (a safety check against silently overwriting unrelated dotfiles). plan mode never writes anything, so it's always safe to run first — see the script's --help and docs/ARCHITECTURE.md for the rollback path (install-adapters.sh rollback).

What this does NOT do

• No cloud sync. The receipt store is local-only (~/.agent-handoffs/, mode 0700) unless you separately wire up a transfer yourself.
• No embeddings, no memory search, no semantic recall. This is a receipt protocol — a small, auditable file format and a lifecycle — not a memory database.
• No unattended automation. Every receipt is written by an explicit /wrap, consumed by an explicit /pickup. Nothing polls, nothing runs on a timer, nothing detects a stopped process and acts on its own.
• No secrets, credentials, or raw transcript text in a receipt — validate-receipt.sh rejects secret-shaped values outright.

Status and naming

Working name only — wrap-pickup describes the two commands, not necessarily what this should be called long-term. Renaming is an open decision for whoever maintains this next; don't read anything into the name beyond "it's the wrap and pickup thing."

Known rough edges, tracked honestly rather than hidden:

• check-conformance.sh depends on an evals/session-continuity/ fixture tree and docs/session-continuity/ install docs that are not part of this extraction. bash -n and a direct validate-receipt.sh run against a real receipt are the verified paths through the toolchain right now; the full conformance suite needs that fixture tree added back.
• install-adapters.sh apply's pre-install baseline-manifest requirement (see above) has no shipped baseline file in this repo. plan mode works out of the box; generating your own baseline before a first apply on a machine with pre-existing ~/.claude/CLAUDE.md / ~/.codex/AGENTS.md / ~/.kimi-code/AGENTS.md is on you for now.

License

MIT. See LICENSE.