Skip to main content
Glama

OpenHandoff

Portable, local-first context handoffs between AI coding agents.

CI License: MIT Python

OpenHandoff keeps the durable project truth in two small files:

  • CONTEXT.md for people and Obsidian;

  • context.json for 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 .context

For 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 4000

MCP server

The dependency-free MCP server exposes load_handoff, save_checkpoint, search_handoff, and pack_context over stdio:

openhandoff-mcp

For 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 .context

Codex 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

  1. Cursor and Windsurf transcript adapters.

  2. File and commit citations in task-specific context packs.

  3. Obsidian and GitHub sync with secret scanning and review gates.

Project health

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 tools
load_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

    B3/5.0

    Scored across 4 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides 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 npm
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI coding assistants to store and retrieve project-aware context as plain Markdown files locally, with no cloud or vector database required.
      1
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables 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 npm
      MIT