handoff-mcp

An MCP server that gives AI coding agents persistent memory across sessions.

When you close a Claude Code session and start a new one, the new session has no idea what the previous one was doing. handoff-mcp solves this by saving session context — tasks, decisions, blockers, and file pointers — to a local .handoff/ directory that the next session can load automatically.

The Problem

AI coding sessions are stateless. Every new session starts from zero:

• "What was I working on?" — the agent doesn't know
• "What decisions were made?" — lost with the previous context window
• "What's left to do?" — you have to re-explain everything

This gets painful fast on multi-session projects.

How It Works

Session 1                          Session 2
┌──────────────┐                   ┌──────────────┐
│ Working...   │   .handoff/       │ load_context │
│              │──────────────────>│  ↓ guidance  │
│ save_context │   tasks/          │ save_context │
│  - close     │   sessions/      │  (active)    │
│  - summary   │   config.toml    │  ↓ work...   │
│  - decisions │                   │ save_context │
│  - blockers  │                   │  (close)     │
└──────────────┘                   └──────────────┘

At session start, the agent calls handoff_load_context to pick up where things left off. If no active session exists, the response includes session_guidance prompting the agent to establish one via handoff_save_context with session_status: "active" — this creates a persistent .active.json that survives interruptions. At session end, the agent calls handoff_save_context (defaulting to session_status: "closed") to close the session.

Installation

Codex CLI plugin (recommended for Codex users)

Install the Handoff binary, add the GitHub marketplace, install the Codex Task Loop plugin, and register the Handoff MCP server:

npm install -g handoff-mcp-server
codex plugin marketplace add alphaelements/handoff-mcp
codex plugin add handoff-task-loop-codex@handoff-mcp-marketplace
codex mcp add handoff -- handoff-mcp

Confirm the plugin and MCP server, then begin a new Codex session:

handoff-mcp --version
codex plugin list
codex mcp get handoff

Use $handoff-session-loop only when you want to explicitly run ready Handoff tasks through the Codex developer, tester, and reviewer loop. For regular session continuity, use the Handoff MCP tools and this repository's AGENTS.md guidance.

Local checkout: replace alphaelements/handoff-mcp with the absolute path to this repository in the marketplace command. Reinstall the plugin after an update and start a new Codex session so it reloads the bundled skill.

Direct MCP alternative: users who do not need the task loop can install the binary and run only codex mcp add handoff -- handoff-mcp. This supplies the Handoff tools but not $handoff-session-loop.

For a controlled non-interactive loop, permit Handoff MCP writes for that one invocation; otherwise codex exec can cancel task-state changes:

codex exec -c 'mcp_servers.handoff.default_tools_approval_mode = "auto"' \
  --sandbox workspace-write '$handoff-session-loop <scoped task request>'

Updating: run codex plugin marketplace upgrade handoff-mcp-marketplace, then reinstall with codex plugin add handoff-task-loop-codex@handoff-mcp-marketplace. Update the binary separately with npm install -g handoff-mcp-server@latest or cargo install handoff-mcp --force.

Claude Code compatibility: Codex uses $handoff-session-loop; Claude Code uses /session-loop and /research-loop. The Codex plugin does not execute Claude commands, agents, or Workflow DSL.

Claude Code Plugin (recommended)

The easiest way to install handoff-mcp is as a Claude Code plugin.

# 1. Install the binary (required — the plugin calls it)
npm install -g handoff-mcp-server
# or: cargo install handoff-mcp

# 2. Add the market