Project-local team session handoffs for Claude Code. Each dev gets their own folder under <repo>/sessions/, auto-keyed off git config user.name. When Alice clones the repo and runs /handoff save, her files land in sessions/Alice-Smith/ on their own. Zero setup for new joiners.
Claude Code's built-in /compact is lossy and keeps you in the polluted session you were trying to clean up.
Everything Claude Code ships /save-session and /resume-session, which write structured files to disk. Files land in ~/.claude/session-data/ on each dev's local machine, so if two of you are working on the same repo, your teammate can't see what you did yesterday.
/handoff fixes that. Lifts ECC's /save-session schema and prose, then stores the file in the repo under per-agent subdirs. The agent field auto-fills from git config user.name.
/compact (built-in) |
/save-session (ECC) |
/handoff (this) |
|
|---|---|---|---|
| Storage | In-conversation | Local machine | Inside the repo |
| Schema | Freeform summary | Structured sections | Structured + Agent + Branch |
| Per-user partitioning | n/a | One global folder | One folder per teammate |
| Setup for new joiners | None | None | None (auto from git config) |
| Survives crash | No | Yes | Yes |
| Teammates can see your work | No | No | Yes (if folder committed) |
One-liner:
curl -fsSL https://raw.githubusercontent.com/0ywfe/claude-handoff/main/commands/handoff.md -o ~/.claude/commands/handoff.mdOr clone:
git clone https://github.com/0ywfe/claude-handoff.git
cd claude-handoff
./install.shDrops one file at ~/.claude/commands/handoff.md. No dependencies.
In any git repo:
/handoff me Show your detected agent name
/handoff Save current session (defaults to save)
/handoff save [description] Save with an optional topic line
/handoff resume Resume your most recent session
/handoff resume Alice-Smith Pick up where a teammate left off
/handoff resume 2026-05-15 Resume by date
/handoff resume a1b2c3d4 Resume by short-id
/handoff list All sessions in this repo
/handoff list --mine Just yours
The workflow it's built for:
/handoff save state to file
/clear wipe conversation context
... new session ...
/handoff resume pick up the briefing fresh
Use it whenever you stop working. The /clear between save and resume keeps the model out of the long-context degradation zone.
After your first save, the repo looks like this:
sessions/
├── README.md auto-generated, onboards new joiners
├── 0ywfe/ your folder, from git config user.name
│ └── 2026-05-15-a1b2c3d4-session.tmp
└── Alice-Smith/ your teammate's folder, generated on her machine
└── 2026-05-15-b2c3d4e5-session.tmp
sessions/README.md gets generated the first time anyone runs /handoff save. Idempotent, so it never overwrites if your team has customised it. About 80 lines, walks through the layout and commands so a new joiner can read it and start working without external docs.
Your call. Committing makes handoffs visible to the whole team. Useful for async work, code review context, and onboarding. Combined with git log, the folder becomes a chronicle of code changes plus the reasoning behind them. Or .gitignore the folder if you want handoffs as private notes per dev.
The command doesn't pick for you and doesn't add a .gitignore line.
Auto-detected per machine. Resolution order:
$CLAUDE_AGENT_NAMEenv var (override, for people who want a different name in Claude than in git)git config user.namewhoami(fallback)
Spaces become hyphens, case preserved. Alice Smith becomes Alice-Smith. 0ywfe stays 0ywfe.
When a new dev clones the repo and runs /handoff save for the first time, their folder appears automatically. No registration, no Slack DM about conventions.
Complementary, not a replacement. Install both. ECC's /save-session works well for personal cross-project work (sessions follow you across machines via your ~/.claude/). /handoff works for team repos (sessions live where the code does).
Same schema, same briefing format. Use /save-session outside git repos, /handoff inside them.
A version of this is being proposed upstream as an ECC contribution. If that lands, the standalone repo stays as a lightweight install path for anyone who doesn't want the full framework.
- Claude Code CLI
- A git repo (otherwise the command tells you to use
/save-sessioninstead)
Built on the /save-session and /resume-session design from Everything Claude Code by Affaan Mustafa. Same file schema, same briefing format, same What WORKED / What Did NOT Work / Exact Next Step discipline. MIT-to-MIT so there's no obligation, but credit where it's due.
MIT