OpenHandoff

AI 코딩 에이전트 간의 휴대 가능하고 로컬 우선인 컨텍스트 핸드오프.

OpenHandoff는 지속 가능한 프로젝트 진실을 두 개의 작은 파일에 보관합니다:

• 사람과 Obsidian을 위한 CONTEXT.md;

• 에이전트, MCP 어댑터, 자동화를 위한 context.json.

첫 번째 MVP는 의도적으로 단순하고 검사 가능합니다: 클라우드 계정이 없고, 숨겨진 데이터베이스가 없으며, 핸드오프가 작성되기 전에 편집(redaction)이 이루어집니다. 향후 어댑터는 벤더별 메모리 형식을 강제하지 않고 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의 경우 동일한 실행 파일을 설정의 command 훅에 연결하세요. 정확한 설정 파일은 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 데이터를 커밋하지 마세요.