handoff-mcp
alphaelements/handoff-mcp
MCP server that gives AI coding agents persistent memory across sessions
Instalação
npx convez-ai alphaelements/handoff-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
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/ │ Loading... │
│ │──────────────────>│ │
│ save_context │ tasks/ │ load_context │
│ - summary │ sessions/ │ - tasks │
│ - decisions │ config.toml │ - decisions │
│ - blockers │ │ - blockers │
│ - tasks │ │ - git state │
└──────────────┘ └──────────────┘
At session end, the agent calls handoff_save_context to persist what matters. At session start, it calls handoff_load_context to pick up where things left off.
Installation
npm (recommended)
npm install -g handoff-mcp-server
Build from source
git clone https://github.com/alphaelements/handoff-mcp.git
cd handoff-mcp
cargo build --release
Setup
Add to your Claude Code MCP configuration:
Global (~/.claude/.mcp.json) — available in all projects:
{
"mcpServers": {
"handoff": {
"type": "stdio",
"command": "handoff-mcp",
"args": []
}
}
}
Per-project (.mcp.json in project root):
{
"mcpServers": {
"handoff": {
"type": "stdio",
"command": "handoff-mcp",
"args": []
}
}
}
Quick Start
-
Initialize a project:
The agent calls
handoff_initwith your project name. This creates a.handoff/directory:.handoff/ ├── config.toml # Project settings ├── sessions/ # Session history (TOML files) └── tasks/ # Task tree (directories + TOML files) -
Work normally — create tasks, track progress, make decisions.
-
Save context at session end — the agent captures a summary, decisions, blockers, and references.
-
Load context at next session start — the agent reads back everything and resumes.
Add
.handoff/to your.gitignore— it contains local working state, not code.
Tools
| Tool | Purpose |
|---|---|
handoff_init | Initialize .handoff/ directory for a project |
handoff_load_context | Load session context, tasks, and git state at session start |
handoff_save_context | Save session summary, decisions, blockers, and references |
handoff_list_tasks | List tasks with optional status filter |
handoff_update_task | Create, update, or move tasks in a hierarchical tree |
handoff_get_config | Read project configuration |
handoff_update_config | Update project configuration |
handoff_dashboard | Overview of all handoff-enabled projects |
Task Management
Tasks are stored as a directory tree, supporting hierarchical structures:
tasks/
├── 01-todo--implement-auth/
│ ├── task.toml
│ ├── 01.1-done--design-schema/
│ │ └── task.toml
│ └── 01.2-in_progress--write-handlers/
│ └── task.toml
└── 02-blocked--deploy-staging/
└── task.toml
Statuses: todo | in_progress | review | done | blocked | skipped
Each task can have:
- Priority (
low/medium/high) - Labels
- Done criteria (checklist items)
- Links to issues, MRs, or docs
- Notes
Session Context
When saving context, the agent can record:
- Summary — one-line description of what happened
- Decisions — what was decided and why, with confidence levels (
confirmed/estimated/unverified) - Blockers — what's preventing progress
- Checklist — items for the next session
- Handoff notes — categorized as
caution,context, orsuggestion - References — links to files, issues, MRs, wiki pages, or URLs
- Context pointers — specific files and line ranges the next session should look at
- Git state — current branch, recent commits, and dirty files (captured automatically)
Dashboard
handoff_dashboard scans directories for projects with .handoff/ and shows a summary:
## my-project (3 tasks)
- [in_progress] Implement auth (high)
- [todo] Add tests (medium)
- [blocked] Deploy staging (medium)
## other-project (1 task)
- [review] Update README (low)
Configuration
.handoff/config.toml:
[project]
name = "my-project"
description = "Project description"
[settings]
history_limit = 20 # Max closed sessions to keep
done_task_limit = 10 # Max completed tasks to show
auto_git_summary = true # Capture git state automatically
[dashboard]
scan_dirs = ["~/pro/"] # Directories to scan for dashboard
MCP Resources
| URI | Description |
|---|---|
handoff://sessions | Active session data (JSON) |
handoff://config | Project configuration (TOML) |
Recommended CLAUDE.md Setup
Add the following to your project's CLAUDE.md so the agent uses handoff consistently:
## Session Handoff
This project uses handoff-mcp for session continuity.
- **Session start**: Call `handoff_load_context` to load previous session state.
If not initialized, call `handoff_init` with the project name.
- **Session end**: Call `handoff_save_context` with a summary, decisions, and blockers.
- **During work**: Use `handoff_update_task` to track progress.
Mark tasks `in_progress` when starting, `done` when complete.
- **Decisions**: Record decisions with confidence levels as they are made,
not just at session end. Use `confirmed` for verified facts, `estimated`
for reasonable assumptions, `unverified` for unknowns.
Skill File (Optional)
This repository includes a skill file at skills/handoff/SKILL.md that makes handoff behavior automatic in Claude Code. Copy it to your user skills directory:
cp -r skills/handoff ~/.claude/skills/
This teaches the agent to automatically load context at session start, track tasks during work, and save context at session end.
Compatibility
- Claude Code — fully supported (stdio transport)
- Other MCP clients — any client supporting the MCP stdio transport
License
MIT