Claude Code Handoff Plugin
Hand off your work between AI sessions and agents — without losing context.
A Claude Code plugin that writes self-instructing handoff documents any LLM agent can pick up. Built for the messy reality of multi-agent workflows: jumping from Claude Code to Codex, from Cursor to Gemini, from today's session to next week's session — without re-explaining what you were doing, what you decided, and where you left off.
The Problem
You're deep in a coding session. The context window is filling up. You need to stop for the day, switch to Codex for a specific task, or hand the work to a teammate. A few hours later, a fresh agent stares at the codebase and has no idea:
- What you were trying to accomplish
- Which constraints you'd already agreed on
- What you'd already tried (and why it didn't work)
- Where exactly to put the cursor next
So you spend 20 minutes re-explaining. The fresh agent runs off in the wrong direction. You lose the thread.
The Solution
/handoff:write produces a structured, self-instructing document the next agent reads first. The document carries its own pickup protocol — even agents that have never heard of this plugin understand exactly what to do.
You (Claude Code, session ending):
/handoff:write
→ Handoff written: /repo/.handoffs/2026-05-23-1530-auth-refactor.md
→ Depth: rich (47 turns, 6 changed files, 1 running process)
→ Mission: Refactor auth middleware to use JWT
→ Next step (Section 3): Edit src/auth.ts:142 — replace validateToken...
→ To pick up: paste the path into any agent and say "read this and continue"
You (Codex CLI, next morning):
> read /repo/.handoffs/2026-05-23-1530-auth-refactor.md and continue
Codex: I've loaded the handoff. Mission: refactor auth to JWT.
Verified env: branch matches, port-forward still running.
Next step is editing src/auth.ts:142. One constraint from
Section 4 — you said "no breaking changes for the v1 API".
Should I begin?
That's the experience. One document, any agent, no re-explanation.
Features
- 🔄 Agent-agnostic — the doc carries a literal "you are picking up work, here's how" protocol at the top. Works with Codex, Cursor, Gemini, GPT, ChatGPT, any LLM.
- 🎯 Adaptive depth — the skill measures conversation complexity (turns, file changes, env state) and picks
minimal / rich / exhaustive. Override with --depth=.
- 🔐 Secret redaction — scans the doc for API keys, tokens,
.env values, IPs before writing. Never leak credentials into a handoff.
- 📍 One concrete next step — every handoff names ONE action with file path and line number. No vague "continue the refactor".
- 💬 Verbatim constraint quotes — Section 4 preserves your exact words ("don't touch the legacy API"). The next agent can't paraphrase them into something else.
- 📊 Project + central index — handoffs live next to the code (
<repo>/.handoffs/), with a central INDEX.md for cross-project browsing.
- 🔁 Resume mode —
/handoff:resume <path> verifies env (branch, processes, dirty files) and presents status before any action.
- 📋 List & archive — browse open handoffs, archive old resumed ones, all reversible.
- 🌍 Bootstrap stays English — the agent-to-agent protocol is monolingual for maximum pickup reliability. Doc body follows your conversation language.
Install
This plugin is distributed via the aploe-tools marketplace — a small catalog repo that lists this and future plugins.
/plugin marketplace add aploe/claude-plugins
/plugin install handoff@aploe-tools
After install, four skills become available under the handoff namespace: /handoff:write, /handoff:resume, /handoff:list, /handoff:archive.
Verify
/handoff:list
You should see the central INDEX (empty on first run) and a tip about creating your first handoff.
Skills
The plugin ships four skills under the handoff namespace. Each has its own description so Claude auto-invokes the right one from natural language (e.g., "save state for next session" → write; "load that handoff" → resume).
