OpenHandoff

面向 AI 编码代理的可移植、本地优先的上下文交接。

OpenHandoff 将持久的项目事实保存在两个小文件中：

• CONTEXT.md 供人类和 Obsidian 使用；

• context.json 供代理、MCP 适配器和自动化使用。

首个 MVP 刻意保持简单且可检查：无需云账户，没有隐藏数据库，脱敏在交接写入之前完成。未来的适配器可以读取 Codex、Claude Code、Cursor 和 Windsurf 的转录记录，而无需强制使用特定供应商的记忆格式。

OpenHandoff 专为公共仓库和团队交接而设计：文件为纯文本，MCP 服务器零依赖，类密钥的值在持久化之前会被脱敏。

技能包

该仓库在 skills/ 下包含三个可移植技能：

• openhandoff-context — 在代理之间捕获、恢复和打包上下文。

• openhandoff-privacy — 在共享之前审计交接和转录记录。

• openhandoff-release — 准备经过测试、有文档、可复现的发布。

将技能目录复制到你的 Codex 技能目录中，或使用此 GitHub 仓库通过 Codex 技能安装器安装。这些技能刻意保持范围狭窄，以便可以独立使用。

Related MCP server: ai-cortex

快速开始

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

对于普通用户安装，请在发布后使用 pipx install openhandoff。开发依赖和检查记录在 CONTRIBUTING.md 中。

为特定任务构建紧凑的上下文切片。匹配的决策、TODO 和注释行会优先保留，然后结果会被确定性地裁剪到请求的预算范围内：

openhandoff pack .context --task "MCP adapter" --max-chars 4000

MCP 服务器

零依赖的 MCP 服务器通过 stdio 暴露 load_handoff、save_checkpoint、search_handoff 和 pack_context：

openhandoff-mcp

对于本地代理配置，使用 openhandoff-mcp 命令，无需网络访问。服务器只读写代理提供的交接路径。

Codex 配置示例：

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

Claude Desktop 配置示例：

{
  "mcpServers": {
    "openhandoff": {
      "command": "openhandoff-mcp",
      "args": []
    }
  }
}

捕获代理事件

openhandoff-hook 接受 stdin 上的 JSON 事件（或纯文本），对类凭据的值进行脱敏，并将结果追加到 .context/events.jsonl：

printf '%s\n' '{"type":"agent_message","message":"finished"}' \
  | openhandoff-hook --path .context

Codex 可以直接将其 notify 负载发送到该钩子。将此添加到你的 Codex 配置中（该命令在 stdin 上接收 JSON 负载）：

notify = ["openhandoff-hook", "--path", ".context"]

对于 Claude Code，将相同的可执行文件接入你设置中的命令钩子。确切的设置文件可能因 Claude Code 版本而异；以下是一个示例：

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

导入转录记录

Codex 和 Claude Code 的 JSONL 事件流可以导入为相同的格式：

openhandoff import-transcript ./rollout.jsonl .context --title "Project handoff"

路线图

1. Cursor 和 Windsurf 转录适配器。

2. 任务特定上下文包中的文件和提交引用。

3. Obsidian 和 GitHub 同步，带密钥扫描和审查门禁。

项目状态

• 许可证：MIT；参见 LICENSE。

• 安全报告：参见 SECURITY.md。

• 贡献：参见 CONTRIBUTING.md。

• 发布说明：参见 CHANGELOG.md。

• 架构：参见 docs/architecture.md。

• 发布流程：参见 docs/releasing.md。

该项目处于早期阶段，欢迎真实世界的反馈、集成和文档改进。请勿提交聊天转录记录、凭据或私有 Obsidian 数据。