Skip to content

handoff

Transfer knowledge between AI agent sessions — local SQLite, no cloud, no server, no configuration.

Every AI coding agent operates inside a finite context window. When that window fills up, the session ends and everything accumulated during it — decisions made, architecture discussed, progress tracked, gotchas discovered — is gone. The next agent starts from zero.

handoff solves this. Before the window closes, the agent stores a structured markdown summary to a local SQLite database. The next agent retrieves it and resumes work with full context, instantly.

handoff flow diagram — Session A stores to handoff.db, Session B retrieves from handoff.db

Quick start

Session A — store context before the window fills:

echo "## Current State
Auth is complete. Working on task CRUD.

## Next Steps
1. Finish PATCH /tasks/:id
2. Add pagination to GET /tasks" | handoff store --name "api-state" --ttl 7d

a3f9c12e

Session B — fresh agent retrieves it immediately:

handoff retrieve a3f9c12e
# or by name:
handoff retrieve --name "api-state"

The full context is written to stdout. The agent reads it and picks up where the last session left off.

How it fits together

  • Local SQLite

    All data lives in ~/.handoff/handoff.db on your own machine. Nothing leaves your system. No accounts, no API keys, no internet connection required.

  • Auto-expiry

    Every package has a TTL. Packages expire silently in the background — old context never accumulates. Default TTL is 7 days.

  • Single binary

    Pure Go, no CGO, no runtime dependencies. One executable that works the same on macOS, Linux, and Windows.

  • Works with all major agents

    Ready-made instruction files for Claude Code, GitHub Copilot, Cursor, and OpenAI Codex. Drop one file into your project and the agent handles the rest.

Supported agents

handoff ships instruction files for every major AI coding agent:

Agent Supported
Claude Code Yes
GitHub Copilot Yes
Cursor Yes
OpenAI Codex Yes
Any agent with terminal access Yes

See Agent Setup for installation instructions.

Explore the docs

  • Install

    Homebrew, go install, or build from source.

    Install

  • Commands

    Full reference for store, retrieve, list, and gc.

    Commands

  • Agent Setup

    Wire handoff into your agent's instructions in one curl command.

    Agent Setup

  • Workflow

    The recommended handoff pattern and knowledge package format.

    Workflow

  • How It Works

    Database schema, ID generation, TTL, garbage collection, and design principles.

    How It Works