Skip to content

Home

Jump to bottom
alphaelements edited this page Jun 30, 2026 · 3 revisions

handoff-mcp Wiki

handoff-mcp is an MCP server that gives AI coding agents persistent memory across sessions. It saves session context — tasks, decisions, blockers, and file pointers — to a local .handoff/ directory so the next session can resume without a manual briefing.

This wiki is the user- and agent-facing reference: what the tools do, how to configure a project, and how the on-disk data model behaves. For installation and a quick start, see the README.

Pages

  • Tools Reference — every handoff_* MCP tool, its inputs, outputs, and behavior.
  • Configuration — the .handoff/config.toml schema: settings, calendar, assignees, milestones, effort budget, gantt view.
  • Data Model — how tasks and sessions are stored on disk, status transitions, and the session handoff fields.
  • Estimates and Capacity — required estimates, the AI-effort multiplier, metrics, and scheduling.
  • Cross-Project Referrals — sending and reading referrals between handoff-enabled projects.
  • CLI API Reference — call any MCP tool from the shell (handoff-mcp <group> <action> [--flags]). JSON output for scripting.

The core loop

Session start  →  handoff_load_context   (resume previous state)
                  ↓ session_guidance? → handoff_save_context (session_status:"active")
During work    →  handoff_update_task / handoff_check_criterion / handoff_log_time
                  handoff_update_session (decisions, notes, pointers)
Session end    →  handoff_save_context   (summary, decisions, blockers, notes)

At session start the agent calls handoff_load_context to pick up where the previous session left off. If no active session exists, the response carries session_guidance telling the agent to establish one. At session end the agent calls handoff_save_context to close the session with handoff data the next session will read.

Quick links

Clone this wiki locally