openhandoff-mcp
Writes handoff context to a Markdown file (CONTEXT.md) formatted for Obsidian, enabling human-readable project state to be viewed and edited in Obsidian vaults.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@openhandoff-mcp pack context for the MCP adapter task"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
OpenHandoff
Portable, local-first context handoffs between AI coding agents.
OpenHandoff keeps the durable project truth in two small files:
CONTEXT.mdfor people and Obsidian;context.jsonfor agents, MCP adapters, and automation.
The first MVP is deliberately boring and inspectable: no cloud account, no hidden database, and redaction happens before the handoff is written. Future adapters can read Codex, Claude Code, Cursor, and Windsurf transcripts without forcing a vendor-specific memory format.
OpenHandoff is designed for public repositories and team handoffs: files are plain text, the MCP server is dependency-free, and secret-shaped values are redacted before persistence.
Skill pack
The repository includes three portable skills under skills/:
openhandoff-context— capture, recover, and pack context between agents.openhandoff-privacy— audit handoffs and transcripts before sharing them.openhandoff-release— prepare tested, documented, reproducible releases.
Copy a skill directory into your Codex skills directory, or install it with the Codex skill installer using this GitHub repository. The skills are deliberately narrow so they can be used independently.
Related MCP server: Memory Fabric
Quick start
python -m venv .venv
source .venv/bin/activate
pip install -e .
openhandoff init .context --title "My project"
openhandoff capture .context \
--title "My project" \
--decision "Use SQLite" \
--todo "Add the MCP adapter" \
--notes "The next agent should run the test suite first."
openhandoff show .contextFor a normal user install, use pipx install openhandoff after a release is published. Development dependencies and checks are documented in CONTRIBUTING.md.
Build a compact context slice for a specific task. Matching decisions, TODOs, and note lines are kept first, then the result is trimmed deterministically to the requested budget:
openhandoff pack .context --task "MCP adapter" --max-chars 4000MCP server
The dependency-free MCP server exposes load_handoff, save_checkpoint, search_handoff, and pack_context over stdio:
openhandoff-mcpFor a local agent configuration, use the command openhandoff-mcp with no network access. The server only reads and writes the handoff path supplied by the agent.
Example Codex configuration:
[mcp_servers.openhandoff]
command = "openhandoff-mcp"
args = []Example Claude Desktop configuration:
{
"mcpServers": {
"openhandoff": {
"command": "openhandoff-mcp",
"args": []
}
}
}Capture agent events
openhandoff-hook accepts a JSON event (or plain text) on stdin, redacts credential-shaped values, and appends the result to .context/events.jsonl:
printf '%s\n' '{"type":"agent_message","message":"finished"}' \
| openhandoff-hook --path .contextCodex can send its notify payload directly to the hook. Add this to your Codex configuration (the command receives the JSON payload on stdin):
notify = ["openhandoff-hook", "--path", ".context"]For Claude Code, wire the same executable into the command hook in your settings. The exact settings file can vary by Claude Code version; this is an illustrative example:
{
"hooks": {
"afterTurn": [
{"command": "openhandoff-hook --path .context"}
]
}
}Import a transcript
Codex and Claude Code JSONL event streams can be imported into the same format:
openhandoff import-transcript ./rollout.jsonl .context --title "Project handoff"Roadmap
Cursor and Windsurf transcript adapters.
File and commit citations in task-specific context packs.
Obsidian and GitHub sync with secret scanning and review gates.
Project health
License: MIT; see LICENSE.
Security reporting: see SECURITY.md.
Contributions: see CONTRIBUTING.md.
Release notes: see CHANGELOG.md.
Architecture: see docs/architecture.md.
Release process: see docs/releasing.md.
The project is early-stage and welcomes real-world feedback, integrations, and documentation improvements. Please do not commit chat transcripts, credentials, or private Obsidian data.
Available Tools
4 toolsload_handoffC
Load the current project handoff shared between coding agents.
Inputs: path.
pack_contextC
Build a compact, task-focused context slice for the next agent.
Inputs: task (required), path, maxChars.
save_checkpointB
Save durable project decisions, TODOs, and notes for the next agent.
Inputs: title (required), path, notes, todos, +1 more.
search_handoffB
Search decisions, TODOs, and notes in the current handoff.
Inputs: query (required), path.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool targets a distinct action: loading the handoff, saving new checkpoint data, searching within it, and packing a context slice. There is no overlap or ambiguity between these four operations.
All tools follow a clear verb_noun pattern (load_handoff, save_checkpoint, search_handoff, pack_context). The only minor inconsistency is the use of different nouns (handoff, checkpoint, context) when referring to related concepts, but the pattern remains uniform and predictable.
With only 4 tools, the server is tightly scoped for its purpose of managing agent handoffs. Every tool serves a distinct, necessary function and none feel superfluous.
The set covers core lifecycle operations: load, save, search, and context packing, which likely handles most workflows. A minor gap is the lack of a clear delete/reset operation for the handoff, but this may not be needed in the intended use case.
Maintenance
Related MCP Connectors
Project memory, documentation and controlled secret access for AI coding agents.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Shared project context for AI agents and teams: docs, tasks, and messages that stay current.
Persistent memory for AI agents. Search, store, and recall across sessions.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides AI coding assistants with persistent project memory to retain architectural decisions, code patterns, and domain knowledge across sessions. It stores data locally in a SQLite database, allowing agents to remember, recall, and manage project-specific context using full-text search.4 npmApache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables AI coding assistants to store and retrieve project-aware context as plain Markdown files locally, with no cloud or vector database required.1MIT
- AlicenseBqualityDmaintenanceProvides persistent local memory for AI coding sessions, enabling agents to save and retrieve project context across different tools and sessions.16MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI coding assistants to persistently save, search, and restore project context across sessions, including decisions, progress, file caches, checkpoints, and channel-based memory. It supports git-aware organization, batch operations, and shared memory across parallel sessions.195 npmMIT