port of sting25/claude-code-handoff

The next Claude Code session doesn't have to start blind.

A Cowork-installable port of Christopher Chadwick's claude-code-handoff. Snapshot session state on exit; auto-load it on the next session start. Plus /handoff at clean boundaries. Nothing to remember; nothing to copy-paste.

Credit where it's due. The original idea, snapshot logic, transcript appender, and /handoff skill are by Christopher Chadwick (@Sting25). This site is about a packaging port. Visit the upstream project.

View on GitHub Install User manual Discuss

The problem

Claude Code sessions hit context limits. When they do, the next session starts blind — you re-explain the project, the in-flight track, the decisions you made twenty minutes ago, all from memory. The model has no continuity. You become the continuity.

Christopher Chadwick wrote claude-code-handoff to fix this for the standalone Claude Code CLI. This repo ports that work to the Cowork desktop app, where users install plugins through a UI rather than running shell scripts — and where the host-side shell on Windows (MSYS Git Bash) is missing two dependencies the upstream relies on.

What it does

On session exit: snapshots HEAD, branch, recent commits, working tree, and in-flight .md docs to <repo>/.claude/handoff_current.md.
On next session start: reads that file and injects it as context. No prompt to remember.
After every turn: appends the new transcript lines to a raw-dump backup at .claude/handoff_backups/handoff_raw_<session_id>.md. Saturated-context restart-from-thin-curated-notes failure mode goes away.
On /handoff: trigger the snapshot manually at clean boundaries. The assistant appends a curated ## Notes from this session block and prints a loud banner telling you to start a new session.

All four behaviors are upstream's design. This port packages them for Cowork.

Install

Open the Cowork desktop app.
Sidebar → Customize → Browse plugins → Add marketplace.
Paste: https://github.com/scottconverse/claude-code-handoff-cowork
Install claude-code-handoff from the marketplace.
Start a fresh Code-tab session in any git repo. The /handoff skill appears in the / menu.

For the standalone Claude Code CLI (Linux/macOS terminal, no Cowork app), use Sting25/claude-code-handoff directly. Its install.sh is the right path there.

Which tabs does it work in?

The Cowork desktop app has three tabs and they run different runtimes.

Tab	/handoff	SessionStart auto-load	SessionEnd auto-write	Stop per-turn dump
Code	✓	✓	✓	✓
Cowork	✓	✗	✗	✗
Chat	no shell	✗	✗	✗

The Cowork-VM-tab issue is upstream Anthropic bugs #27398 and #40495 — affects every marketplace plugin with hooks. The /handoff skill still loads there; use it manually.

Verified end-to-end

Tested on Windows 11 + MSYS Git Bash + Claude Code 2.1.87 with a real claude -p headless run against a real git repo and a real Anthropic API turn. All three hooks fired in sequence:

[2026-05-12T19:47:40Z] event=SessionStart
[2026-05-12T19:47:43Z] event=Stop
[2026-05-12T19:47:44Z] event=SessionEnd

Both artifacts written. The raw-dump file contained the actual model conversation:

## Turn at 2026-05-12 19:47:43 UTC

**User:**     Reply: ok
**Assistant:** ok

Full receipts including probe-log captures and commit SHAs: VERIFICATION.md.

What's port-specific (vs upstream)

Snapshot logic, output format, skill spec, HANDOFF_* env vars, substrate pattern — all unchanged from upstream. This port adds packaging and platform portability:

Plugin + marketplace manifests so the Cowork app's UI can install it.
Declarative hooks/hooks.json wiring with ${CLAUDE_PLUGIN_ROOT}, replacing upstream's install.sh settings.json patcher.
jq replaced with a Perl JSON::PP helper — same parse, no install dependency (Perl ships everywhere; jq doesn't on MSYS Git Bash).
flock replaced with an atomic mkdir-based lock — same serialization, works on every platform.
Three-tier session-info fallback in the Stop hook (JSON stdin → CLAUDE_ENV_FILE → encoded ~/.claude/projects/) so the plugin works in headless mode as well as interactive.
CLAUDE_PROJECT_DIR-preferred repo resolution because Cowork's Code tab shells in .klodock, not the user's project.
bin/probe_hook.sh diagnostic logger wired ahead of every hook. Writes to ~/handoff_probe.log. When something doesn't work, that's the first place to look.

See ARCHITECTURE.md for the full per-piece breakdown with sequence diagrams.

Honest caveats

Things I want you to know before you install this.

Final interactive Cowork-app verification isn't on file yet. Headless claude -p testing on the same binary the Cowork app spawns is the strongest signal short of a real Cowork session. The diagnostic probe is deployed; the first real Cowork session run after install writes a definitive trace to ~/handoff_probe.log.
The Cowork-VM tab silently degrades. Skill works; hooks don't. Not a port issue (upstream Anthropic bugs); but if you live in the Cowork-VM tab, this plugin gives you the skill only.
Standalone Claude Code CLI users should use the upstream install path. This port adds packaging the upstream doesn't need. Different tools for different surfaces.

Credit, again, plainly

Christopher Chadwick (@Sting25) wrote this. The idea is his. The snapshot script is his. The transcript appender is his. The /handoff skill spec is his. The substrate pattern is his. The HANDOFF_* env-var interface is his.

This repo is packaging and portability shims around his work. If claude-code-handoff is useful to you, his repo is where to file enhancements to the logic, send a thank-you, or follow upstream development.