Handover

Shared, versioned context that humans and AI agents can review and continue.

Documentation

Handover MCP

Move active work between Claude Code, Codex, Cursor, Gemini CLI, people, and service agents without losing decisions, files, history, or authorship.

Handover provides shared, versioned context for humans and AI agents through a hosted Model Context Protocol server, a dependency-free CLI, and four open Agent Skills. This repository is the public source, discovery, installation, and connection record for those interfaces.

Handover product interface

See a complete handoff

The public continuation demo shows the same workflow from both sides: an interactive human view and an agent-readable record. It includes Markdown, SQL, JSON, a visual artifact, three attributable revisions, a human review note, and the next agent's resolution. No account is required.

Connect

The canonical Streamable HTTP endpoint is:

https://handover.sh/api/mcp

The endpoint exposes its MCP handshake and tool schemas without an account so clients and directories can verify compatibility before connecting. Tool calls remain protected and return Handover's OAuth resource challenge when no valid human or service credential is present.

Use a named, scoped service credential created by a Handover workspace owner with generic MCP hosts. Gatana and other explicitly configured clients can use per-user Google OAuth. Handover does not yet expose first-party dynamic OAuth registration for arbitrary MCP clients.

Configured interactive clients open Handover's sign-in flow in a browser. Sign in with your own Google account and the client records your human identity. Generic hosts use the named service agent supplied in their configuration and do not open a human sign-in page.

For the complete setup, identity check, two-agent continuity test, and troubleshooting flow, see CONNECTING.md.

Codex

export HANDOVER_TOKEN='hnd_tok_...'
codex mcp add handover \
  --url https://handover.sh/api/mcp \
  --bearer-token-env-var HANDOVER_TOKEN

Claude Code

claude mcp add --transport http --scope user \
  --header "Authorization: Bearer $HANDOVER_TOKEN" \
  handover https://handover.sh/api/mcp

Gemini CLI

gemini mcp add --transport http --scope user \
  --header "Authorization: Bearer $HANDOVER_TOKEN" \
  handover https://handover.sh/api/mcp

Cursor

Export HANDOVER_TOKEN, then add this to .cursor/mcp.json:

{
  "mcpServers": {
    "handover": {
      "url": "https://handover.sh/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:HANDOVER_TOKEN}"
      }
    }
  }
}

Command-line client

The dependency-free Handover CLI supports the same durable workflow from a terminal:

npm install --global handover-sh
handover login
handover doctor
handover search "billing migration"
handover pull <slug-or-url> --out ./continued-work
handover publish ./report --title "Weekly report"

The published package source and metadata live in cli/. The audited direct installer remains available when npm is not appropriate:

curl -fsSL https://handover.sh/install.sh | sh

Package releases are built from this public repository. The bootstrap and trusted-publishing process is documented in RELEASING.md.

handover doctor is a read-only connection check. It verifies the configured endpoint, server-resolved identity, workspace, role, scopes, and one protected context request without printing the credential or changing a handover. Use the complete verification checklist before an agent's first write.

Agent Skills

Install reusable Handover workflows into a compatible coding agent with the open Agent Skills format:

npx skills add 44-pixels/handover-mcp --list
npx skills add 44-pixels/handover-mcp --skill handover-publish

The public collection includes skills for publishing context, resuming work, reviewing revision-anchored feedback, and governing agent access. Browse the catalog at skills.handover.sh or inspect the source in skills/. The collection is also indexed in the Skills.sh directory. The catalog organizes skills by handoff phase, includes a plain-language starting request for each workflow, and exposes the exact MCP tools and CLI commands through its machine-readable index.

The runtime is independently listed as sh.handover/handover in the official MCP Registry.

The Agent Skills and MCP guide explains the boundary between portable workflow instructions and authenticated runtime capabilities. Its raw end-to-end workflow is designed for direct agent retrieval.

For host-specific installation, use the tested Claude Code, Codex, Cursor, and Gemini CLI guide. Its raw verification checklist separates file installation from host discovery, skill activation, authenticated MCP identity, read-back, denied access, and cross-host continuation.

To publish a workflow that uses Handover, start with the contributor contract and the starter skill. Community submissions keep their publisher and source attribution; catalog inclusion does not widen Handover access or replace source review.

Open continuity benchmark

The AI Handoff Continuity Benchmark tests whether a successor model can recover the objective, current state, decisions, evidence, constraints, next action, owner, and open questions from a transcript, compressed memory, or structured handoff.

The first two-system pilot scored structured handoffs at 79.45, conversation transcripts at 76.67, and compressed memory at 45.00. It is a small authored pilot rather than a model leaderboard. The public benchmark/ directory contains the dataset, answer key, dependency-free scorer, strict submissions, deterministic results, limitations, and all 18 raw response bodies.

cd benchmark/v1
node run.mjs --validate-scorer
node run.mjs --prompts ./prompts

What agents can do

Connected agents can:

verify the active identity, organization, workspace, and scopes with handover.whoami;
search company or personal context;
inspect an exact immutable revision;
read attached Markdown, HTML, SQL, JSON, code, images, and other files;
retrieve discussions and revision-anchored annotations;
create a new handover or continue an existing one;
add, edit, resolve, and respond to review comments;
preserve the authenticated human or service identity in the audit history.

The server never asks an agent to provide an author identity in tool input. Authorship comes from the authenticated credential.

Verify the connection

Ask the connected host to perform these calls before real work:

Call handover.whoami with no arguments and confirm the returned person or named service agent, organization, workspace, role, and scopes.
Call handover.search with { "query": "" } and confirm it returns only context that identity should be able to access.
Read one known handover and artifact before creating or continuing work.

A working connection lists Handover's tools without a JSON or sign-in error, preserves the intended identity as author, and immediately stops working when the service credential is revoked.

Service agents

Workspace owners create service agents in Handover and grant only the scopes that actor needs. Store the credential in HANDOVER_TOKEN; do not put it in a repository or MCP configuration committed to source control.

export HANDOVER_TOKEN='hnd_tok_...'
codex mcp add handover \
  --url https://handover.sh/api/mcp \
  --bearer-token-env-var HANDOVER_TOKEN

Discovery and documentation

Source and support

The hosted Handover application source is maintained in a private repository. This public repository contains the MCP connection record, setup documentation, and the source of the dependency-free CLI, not the hosted service implementation.

Report connection or documentation problems through GitHub Issues. Report security concerns using the process in SECURITY.md.