v0.1.1 Open Source  ·  MIT Go

handoff

Transfer knowledge between AI agent sessions.

When context fills up, accumulated project knowledge is lost. handoff keeps it alive.

brew tap Radixen-Dev/tap && brew install handoff
On Windows? See all install options ↓

The Problem

Context windows
have a limit.

Every AI agent has a finite context window. As a project grows, you accumulate decisions, constraints, architecture notes, and task history. When that window fills, one of two things happens: the agent starts forgetting earlier context, or you start a fresh session and spend the first ten minutes re-explaining everything.

Neither is acceptable. Repeating yourself is friction. Lost context means lost decisions, re-tread ground, and subtle mistakes.

The Solution

One command.
Nothing lost.

handoff stores a structured knowledge package locally and hands it to the next session. No cloud. No config. No re-explaining.

A Session fills up
"Our context is getting large. Do a handoff."
✓ Done. Stored as a3f9c12e
The agent runs handoff store internally
B New session, instant context
"Retrieve knowledge package a3f9c12e."
✓ Session restored. We were working on the JWT auth flow. Ready to continue?
The agent runs handoff retrieve internally

How It Works

Simple by design.
Solid in practice.

Local SQLite database

All knowledge packages live in a single file at ~/.handoff/handoff.db. Nothing leaves your machine. You own it entirely.

Stdin / Stdout interface

handoff store reads from stdin. handoff retrieve writes to stdout. Composable with pipes, scripts, and any agent that can run shell commands.

Packages expire automatically

Each package has a time-to-live. Run handoff gc to manually sweep expired entries. The database stays clean without intervention.

No server. No cloud. No config.

One binary. One environment variable if you want a custom DB path. That's it. There is no config file, no account, no network dependency.

Works with any agent

Claude Code, GitHub Copilot, Cursor, OpenAI Codex — drop in an instruction file and the agent handles handoffs automatically, responding to phrases like "do a handoff".

macOS, Linux, Windows

Pre-built binaries for all platforms. Install via Homebrew, go install, or download a release binary directly.

Installation

Up in
thirty seconds.

All platforms Go install
bash 
$ go install github.com/Radixen-Dev/handoff@latest

Requires Go 1.26+. Installs the latest release to your $GOPATH/bin.

macOS & Linux Homebrew
bash 
$ brew tap Radixen-Dev/tap
$ brew install handoff

Recommended for macOS and Linux. Keeps handoff updated with brew upgrade.

Windows Pre-built binary

Download the pre-built .zip from the releases page, extract it, and place handoff.exe in a directory on your %PATH%.

Releases page

Commands

Five commands.
That's all.

The full interface. Agents use store and retrieve automatically. You only need the others when you want to inspect or clean up.

handoff store
Read content from stdin and save it as a named knowledge package. Returns the package ID.
Agent-facing
handoff retrieve <id>
Fetch a package by ID and write its content to stdout. The agent reads this directly into context.
Agent-facing
handoff list
List all non-expired packages in a table with ID, name, size, and expiry time.
User-facing
handoff gc
Manually delete all expired packages. Runs automatically over time, but this forces an immediate sweep.
User-facing
handoff completion
Generate a shell completion script for bash, zsh, fish, or PowerShell.
User-facing
All commands share a single database at ~/.handoff/handoff.db (macOS/Linux) or %USERPROFILE%\.handoff\handoff.db (Windows). Override with HANDOFF_DB.

Agent Setup

Drop one file.
Done.

Two ways to set up your agent. Pick what fits.

GitHub Copilot

Drop an instruction file into your repo. Copilot reads it on every session automatically.

bash 
$ curl -fsSL https://raw.githubusercontent.com/Radixen-Dev/handoff/main/instructions/copilot-instructions.md -o .github/copilot-instructions.md
Claude Code

Place a CLAUDE.md file at your project root. Claude picks it up at the start of every session.

bash 
$ curl -fsSL https://raw.githubusercontent.com/Radixen-Dev/handoff/main/instructions/CLAUDE.md -o CLAUDE.md
OpenAI Codex

Add an AGENTS.md file to your repo. Codex loads it automatically as part of its context.

bash 
$ curl -fsSL https://raw.githubusercontent.com/Radixen-Dev/handoff/main/instructions/AGENTS.md -o AGENTS.md
Cursor

Add a .mdc rule file to your project. Cursor applies it as a persistent background rule.

bash 
$ curl -fsSL https://raw.githubusercontent.com/Radixen-Dev/handoff/main/instructions/cursor.mdc -o .cursor/rules/handoff.mdc
GitHub Copilot

Place the skill file in your VS Code user prompts folder. Copilot loads it when referenced in chat.

bash 
$ curl -fsSL https://raw.githubusercontent.com/Radixen-Dev/handoff/main/skills/copilot-skill.md \
    -o ~/Library/Application\ Support/Code/User/prompts/handoff.prompt.md
Claude Code

Add as a slash command. Type /handoff in any Claude session to trigger a knowledge transfer.

bash 
$ curl -fsSL https://raw.githubusercontent.com/Radixen-Dev/handoff/main/skills/claude-skill.md \
    -o ~/.claude/commands/handoff.md
OpenAI Codex

Reference the skill inline. Ask Codex to "load the handoff skill" at the start of any session.

bash 
$ curl -fsSL https://raw.githubusercontent.com/Radixen-Dev/handoff/main/skills/codex-skill.md \
    -o ~/.codex/instructions/handoff.md

Get It

Open source.
Free forever.

MIT licensed. No tracking, no accounts, no cloud. Your context, your machine.

View on GitHub Documentation