handoff automatically captures what your AI coding agent does in every project and keeps a lossless, human-readable handoff document — so your next session, in Claude Code or Cursor, picks up exactly where the last one stopped.
AI coding agents forget everything between sessions. You close the terminal, come back tomorrow (or switch from Claude Code to Cursor), and you re-explain what you were doing, what's done, and what's left. handoff fixes that. It runs as a set of agent hooks and, for every directory you work in, maintains:
- a lean, human-readable
…-handoff.mdyou can read without any AI, and - an append-only history that grows forever and is never compressed or deleted.
When a new session starts, the prior context is injected automatically and you see a line like:
📋 Handoff loaded:
Users-you-myapp-handoff.md| resumed prior session a1b2c3…
- 🧠 Cross-session memory — resume any project exactly where you left off.
- 🔀 Cross-agent — Claude Code and Cursor write the same per-directory file. Start in one, continue in the other.
- 🗂️ One file per project —
~/.handoff/{dir}-handoff.md, plus a{dir}-history/folder. - 🛟 Lossless & crash-safe — every action is an append to a JSONL event log (the source of truth); the Markdown is a render of it. Atomic writes + file locks, no corruption, no lost updates.
- 🔒 Secret redaction built in — API keys, tokens, JWTs, and
Bearer/password=values are masked before anything touches disk. - ⚡ Zero-dependency Go binary — no Node, no Python, no
jq. Starts in milliseconds, so it never slows your session. - 📜 Readable history — append-only daily logs you can grep, diff, and keep forever.
- 🩺 One-command install +
handoff doctorto verify.
# Install the binary
curl -fsSL https://raw.githubusercontent.com/rosehgal/handoff/main/scripts/install.sh | bash# …or do the FULL install: binary + auto-wire Claude Code and Cursor
curl -fsSL https://raw.githubusercontent.com/rosehgal/handoff/main/scripts/install.sh | bash -s -- --fullbrew install rosehgal/tap/handoff
handoff install # wire into Claude Code + Cursor/plugin marketplace add rosehgal/handoff
/plugin install handoff@handoff
The plugin downloads the right binary from Releases on first run — nothing else to do.
handoff doctorDownloads: prebuilt binaries for macOS & Linux (arm64/amd64) and Windows (amd64/arm64) are on the Releases page.
| Platform | Direct download |
|---|---|
| macOS (Apple Silicon) | handoff_darwin_arm64.tar.gz |
| macOS (Intel) | handoff_darwin_amd64.tar.gz |
| Linux (arm64) | handoff_linux_arm64.tar.gz |
| Linux (amd64) | handoff_linux_amd64.tar.gz |
| Windows (amd64) | handoff_windows_amd64.zip |
agent hook (Claude Code / Cursor)
│ event JSON on stdin
▼
handoff <session-start|record|stop>
│
├─▶ append-only event log (JSONL) ← source of truth: atomic, lossless
└─▶ rendered {dir}-handoff.md ← human view + {dir}-history/
| Event | Claude Code | Cursor | What handoff does |
|---|---|---|---|
| Session start | SessionStart |
beforeSubmitPrompt |
Load prior context (+ git-conflict & CLAUDE.md checks), start a session |
| Each action | PostToolUse |
afterFileEdit / afterShellExecution / afterMCPExecution |
Append to Work Done, capture writes & milestone commands |
| Session end | Stop |
stop |
Mark completed, write a conversation summary |
Because the JSONL log is the source of truth and the Markdown is just a projection, "trimming" the main file never loses anything — older entries are exported to the append-only …-history/ folder and the lean handoff stays readable.
# Session Handoff — /Users/you/myapp
**Session ID:** a1b2c3… **Status:** active
## Project Context # cwd + detected stack + history pointer
## Work Done # chronological tool actions (recent kept inline)
## Current State # last activity + counts
## Important Context … # files written + milestone commands (tests/builds/deploys)
## Conversation Summary # written at session endhandoff install [--client=all|claude|cursor] # wire up the hooks (idempotent)
handoff uninstall [--client=…] # remove them
handoff doctor # verify the installation
handoff status # list tracked projects
handoff render [--cwd=DIR] # rebuild Markdown from the log
handoff version| Setting | Default | How |
|---|---|---|
| Data directory | ~/.handoff |
set HANDOFF_DIR |
Everything lives under the data dir:
~/.handoff/
├── {dir}-handoff.md # lean, human-readable handoff per project
├── {dir}-history/ # append-only logs (INDEX.md + work-YYYY-MM-DD.md)
└── .events/{dir}.jsonl # source-of-truth event log
handoff writes tool activity to disk, so it redacts secrets before storing them: OpenAI/Anthropic keys (sk-…, sk-ant-…), AWS keys (AKIA…), GitHub tokens (ghp_…, github_pat_…), Slack tokens, JWTs, PEM private keys, and api_key= / token: / Authorization: Bearer … style assignments are replaced with ***REDACTED***. Redaction happens on the event before it is ever written to the JSONL log or the Markdown. Found a gap? Please open an issue.
Does it slow down my agent?
No. It's a tiny static Go binary (ms cold start); record and stop run async, and session-start is bounded by a short timeout.
Is my data sent anywhere?
No. Everything stays local under ~/.handoff. handoff makes no network calls except the first-run binary download (plugin/installer).
Does it work with both Claude Code and Cursor? Yes — that's the point. Both write the same per-directory file, so you can switch tools mid-project.
How is this different from Claude Code's built-in memory? Built-in memory stores facts and is Claude-only. handoff is a per-directory work journal that is cross-agent and human-readable, focused on resuming work.
Where are my old sessions?
In ~/.handoff/{dir}-history/ — append-only, never deleted.
git clone https://github.com/rosehgal/handoff
cd handoff
go build -o handoff ./cmd/handoff
./handoff installIssues and PRs welcome. Run go build ./... && go vet ./... && go test ./... before submitting.
MIT © Rohit Sehgal
Keywords: Claude Code session handoff · Cursor handoff · AI agent memory · persistent context across sessions · resume AI coding session · cross-session continuity · Claude Code plugin · Cursor hooks · developer productivity
If handoff saves you context-switching pain, please ⭐ the repo.