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.

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

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