handoff

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.md you 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 doctor to 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 -- --full

brew 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 doctor

Downloads: prebuilt binaries for macOS & Linux (arm64/amd64) and Windows (amd64/arm64) are on the Releases page.

 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/

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 end

handoff 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

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 install

Issues and PRs welcome. Run go build ./... && go vet ./... && go test ./... before submitting.

MIT © Rohit Sehgal