convez.ai
MCP Server
alphaelements

handoff-mcp

alphaelements/handoff-mcp

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server that gives AI coding agents persistent memory across sessions

Instalação

$npx convez-ai alphaelements/handoff-mcp

1 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

Estrelas
0
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 1 dia
Versão
v0.49.0
Issues abertas
10
Contribuidores
1

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

  1. Initialize a project:

    The agent calls handoff_init with your project name. This creates a .handoff/ directory:

    .handoff/
    ├── config.toml      # Project settings
    ├── sessions/        # Session history (TOML files)
    └── tasks/           # Task tree (directories + TOML files)
    
  2. Work normally — create tasks, track progress, make decisions.

  3. Save context at session end — the agent captures a summary, decisions, blockers, and references.

  4. 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

ToolPurpose
handoff_initInitialize .handoff/ directory for a project
handoff_load_contextLoad session context, tasks, and git state at session start
handoff_save_contextSave session summary, decisions, blockers, and references
handoff_list_tasksList tasks with optional status filter
handoff_update_taskCreate, update, or move tasks in a hierarchical tree
handoff_get_configRead project configuration
handoff_update_configUpdate project configuration
handoff_dashboardOverview 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, or suggestion
  • 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

URIDescription
handoff://sessionsActive session data (JSON)
handoff://configProject 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

Ver o original no GitHub

Relacionados