# OpenHandoff

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

[![CI](https://github.com/StoneReaper/openhandoff/actions/workflows/ci.yml/badge.svg)](https://github.com/StoneReaper/openhandoff/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)

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/`](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

```bash
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](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:

```bash
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:

```bash
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:

```toml
[mcp_servers.openhandoff]
command = "openhandoff-mcp"
args = []
```

Example Claude Desktop configuration:

```json
{
  "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`:

```bash
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):

```toml
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:

```json
{
  "hooks": {
    "afterTurn": [
      {"command": "openhandoff-hook --path .context"}
    ]
  }
}
```

## Import a transcript

Codex and Claude Code JSONL event streams can be imported into the same format:

```bash
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](LICENSE).
- Security reporting: see [SECURITY.md](SECURITY.md).
- Contributions: see [CONTRIBUTING.md](CONTRIBUTING.md).
- Release notes: see [CHANGELOG.md](CHANGELOG.md).
- Architecture: see [docs/architecture.md](docs/architecture.md).
- Release process: see [docs/releasing.md](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.