Every AI agent session has a memory limit.
When it fills, everything accumulated — decisions, progress, context — disappears.
The next agent starts from zero.

handoff stores structured knowledge before the window closes,
so the next session picks up exactly where the last one left off.

---

Install

macOS / Linux

brew tap Radixen-Dev/tap
brew install handoff

All platforms (requires Go 1.26+)

go install github.com/Radixen-Dev/handoff@latest

Windows — download a pre-built .zip from the releases page, extract it, and place handoff.exe on your %PATH%.

Full guide — PATH setup, build from source, all platforms → Install →

---

Quick Start

Session A — context is filling up

You tell the agent:

"Our context is getting large. Do a handoff."

The agent composes a structured summary of current state — decisions made, work in progress, next steps, gotchas — and stores it:

Done — stored as a3f9c12e

Session B — fresh session, zero re-explaining

You say:

"Retrieve knowledge package a3f9c12e."

The agent fetches the full summary and resumes exactly where work left off, without any re-explaining of the project.

Note

The agent handles handoff store and handoff retrieve internally. You never need to run them yourself. See the Commands reference → for the full details.

---

Commands

handoff store         Read from stdin → save as a named package → print 8-char ID
handoff retrieve      Fetch by ID or name → write full content to stdout
handoff list          Show all live packages in a clean table
handoff gc            Purge all expired packages on demand
handoff completion    Shell completion for bash, zsh, fish, and PowerShell

All five commands share a single SQLite file at ~/.handoff/handoff.db (macOS/Linux) or %USERPROFILE%\.handoff\handoff.db (Windows).

Full command reference — flags, output examples, error tables →

---

Agent Setup

Drop one file into your project. The agent will automatically check for existing packages at session start, offer proactive transfers when context grows large, and respond to phrases like "do a handoff" or "save context".

Always-on instruction files

Loaded every session. Install once per project.

Agent	File	One-line install
Claude Code	CLAUDE.md	curl -fsSL https://raw.githubusercontent.com/Radixen-Dev/handoff/main/instructions/CLAUDE.md -o CLAUDE.md
GitHub Copilot	.github/copilot-instructions.md	curl -fsSL https://raw.githubusercontent.com/Radixen-Dev/handoff/main/instructions/copilot-instructions.md -o .github/copilot-instructions.md
OpenAI Codex	AGENTS.md	curl -fsSL https://raw.githubusercontent.com/Radixen-Dev/handoff/main/instructions/AGENTS.md -o AGENTS.md
Cursor	.cursor/rules/handoff.mdc	curl -fsSL https://raw.githubusercontent.com/Radixen-Dev/handoff/main/instructions/cursor.mdc -o .cursor/rules/handoff.mdc

On-demand skill files

Tip

Prefer this when you want handoff loaded only when the agent recognizes a handoff request, rather than on every session.

File	Agent
.claude/skills/handoff/SKILL.md	Claude Code
.github/skills/handoff/SKILL.md	GitHub Copilot
.agents/skills/handoff/SKILL.md	OpenAI Codex and others

Agent Setup guide — always-on vs. skill files, comparison and tradeoffs →

---

Configuration

handoff has exactly one setting.

Variable	Default	Description
HANDOFF_DB	~/.handoff/handoff.db %USERPROFILE%\.handoff\handoff.db (Windows)	Path to the SQLite database file

There is no config file. Set the variable or don't — either way, it works.

---

Documentation

Full documentation at radixen-dev.github.io/handoff

Install	All install methods, PATH setup, pre-built binaries, uninstall
Commands	Full flag reference, output examples, error handling
Agent Setup	Always-on vs. skill files, per-agent curl commands
Workflow	The two-session pattern, recommended package format
How It Works	SQLite schema, IDs, TTL, GC, design principles

---

MIT — see LICENSE.