convez.ai
SkillAutomaçãoAvançado
OpenMOSS

Claude ↔ Codex Handoff

OpenMOSS/claude-codex-handoff

Colaboração assíncrona entre agentes de IA via protocolo de handoff em arquivos

Ver no GitHub
BomPluginScore · de 0 a 100

Protocol assíncrono baseado em arquivos para colaboração entre dois agentes de IA (Claude Code e Codex) no mesmo repositório. Usa um diretório .handoff/ compartilhado com sistema de mensagens append-only, locks atômicos e cursores por sessão — sem servidor ou daemon necessário.

Instalação

$npx convez-ai OpenMOSS/claude-codex-handoff

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
43
Forks
2
Acompanhando
0
Saúde
50%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Orquestração de múltiplos agentes de IA trabalhando no mesmo projeto
  • Automação de pipelines de desenvolvimento com passagem de contexto entre agentes
  • Implementação de workflows colaborativos sem infraestrutura adicional

Veredito

Solução técnica robusta para orquestração assíncrona de agentes sem overhead de servidor. Bem adequada para times que buscam integrar múltiplos modelos de IA em fluxos de desenvolvimento, mas exige familiaridade com protocolos de sistema de arquivos e lógica de sincronização.

README

A tradução para o português deste README ainda está na fila.

Claude ↔ Codex Handoff

A drop-in kit that lets two AI coding agents — for example Claude Code and Codex — collaborate asynchronously inside one repository. They talk through append-only files: one message stream per direction, atomic leases, and per-session cursors with legacy shared cursor anchors. No server, no daemon. Each side wakes on a timer, processes unread messages, optionally hands work back, and exits.

It installs as a single .handoff/ folder in your project, shared by both agents. There is no separate global "skill" copy to keep in sync — Claude Code and Codex read the same files.

Install (into your project)

From your project root, clone this repo as .handoff/, then run setup:

cd your-project
git clone https://github.com/OpenMOSS/claude-codex-handoff.git .handoff

# macOS / Linux / WSL:
bash .handoff/setup.sh
# Windows:
powershell -ExecutionPolicy Bypass -File .handoff\setup.ps1

Don't want to type the shell command yourself? Open the project in Claude Code or Codex and ask the agent to run .handoff/setup.sh (Windows: .handoff\setup.ps1) — it can see the script in your tree and will run it for you. Setup is what copies CLAUDE.md / AGENTS.md into your project root; after that the agents have an entry file, so saying 启动协作 (or costart) kicks off the actual collaboration — see Quick start below. (Before setup runs, a bare 启动协作 won't work: with no root entry file yet, the agent has no way to know .handoff/ exists.)

setup creates .handoff-runtime/ (live state) and copies PROJECT.md / CLAUDE.md / AGENTS.md to your project root if they're absent. From then on Claude Code (via CLAUDE.md) and Codex (via AGENTS.md) both read the same .handoff/. Update later with git -C .handoff pull.

Git note. .handoff/ is itself a git clone. Always add .handoff-runtime/ to your project's .gitignore. For .handoff/ itself, either keep it as an updatable dependency (add .handoff/ to .gitignore, git -C .handoff pull to update) or vendor it into your repo (rm -rf .handoff/.git, then commit the files).

Layout

your-project/
├── .handoff/                       # this repo — protocol + helper + templates (shared, one copy)
│   ├── PROTOCOL.md                 # the spec — source of truth
│   ├── setup.ps1 / setup.sh
│   ├── tools/send.py               # protocol-safe JSONL sender (stdlib only)
│   ├── tools/archive.py            # consumed-stream archive helper
│   ├── tools/doctor.py             # read-only runtime diagnostics
│   ├── tools/poll-gate.py          # deterministic wake/idle pre-gate (no model call)
│   ├── project-files/              # PROJECT.md / CLAUDE.md / AGENTS.md templates
│   └── prompts/                    # cron-prompt.md (Claude) / codex-heartbeat-prompt.md (Codex)
├── .handoff-runtime/               # message streams, per-session cursors, claims, notes (gitignore)
├── PROJECT.md                      # shared scope + task boundaries (fill the <FILL_IN>s)
├── CLAUDE.md                       # Claude-side entry
└── AGENTS.md                       # Codex-side entry

Quick start: start a collaboration

In each agent, open the project and say 启动协作 — or costart, or "start collaboration". That's all you type — the agents do the rest, including calling send.py themselves.

Hand over a goal in the same breath. Append a task objective after the trigger — 启动协作:检查第一章事实 / costart: review chapter 1 facts — and the agents take it as the opening task and drive it autonomously, talking it through with each other (question / handoff) as they go, looping until the goal is met. Each side weighs the other's ideas on the merits rather than just agreeing — push back, ask for evidence, offer a better option; the goal is a high-quality result, not a quick consensus. When a judgment call comes up, the two of them hash it out between themselves first instead of bouncing it back to you; they escalate to you only when they genuinely can't agree, or for anything out-of-scope / destructive per PROTOCOL.md §12 (hard limits the agents can't waive on their own). No step-by-step babysitting.

Claude side: in the project, say 启动协作. Claude reads CLAUDE.md → .handoff/PROTOCOL.md, runs setup if needed, helps you fill PROJECT.md, creates its recurring cron (prompts/cron-prompt.md), does a first poll, and sends Codex your first task.

Codex side:

Open the project in the Codex App and say 启动协作. Codex reads AGENTS.md → .handoff/PROTOCOL.md, runs setup if needed, sets up its ~10-min heartbeat automation (prompts/codex-heartbeat-prompt.md), and does a first poll.

Then it runs itself. Each side wakes on its timer, reads its inbox stream, claims and completes any task / handoff / question, replies with done, and goes quiet when there's nothing to do.

How it works

  • Two streams. claude-to-codex.jsonl (Claude writes, Codex reads) and codex-to-claude.jsonl (the reverse). Append-only; a written line is never edited.
  • Message types. task, handoff, question, done, status, error, cancel. Lease-bearing types need an atomic claim before processing; status and done are pure-consumption.
  • Per-session cursors + leases. Each running session tracks its own cursor under .handoff-runtime/cursors/; legacy .codex-cursor / .claude-cursor files are compatibility anchors. Work items are claimed via atomic file creation under .handoff-runtime/claims/. Iron law: side effects first, advance cursor last — so nothing is lost on a crash or interruption.
  • No daemons. Claude uses a recurring cron (every ~10 min); Codex uses a Codex App heartbeat. Each fire is one bounded pass; idle fires exit quietly.
  • Multi-session safe. Optional from_session / to_session labels let two same-side sessions run without stealing each other's replies; a per-side send lock serializes id assignment.

See PROTOCOL.md for the full specification.

The two sides

Claude sideCodex side
Entry fileCLAUDE.mdAGENTS.md
Wake mechanismrecurring cron (prompts/cron-prompt.md)Codex App heartbeat (prompts/codex-heartbeat-prompt.md)
Writes toclaude-to-codex.jsonlcodex-to-claude.jsonl

Sending a message

The agents use the helper themselves; you rarely call it directly:

python .handoff/tools/send.py --side claude --type task \
  --summary "review the auth refactor" --goal "list correctness risks"

python .handoff/tools/send.py --side codex --type done \
  --reply-to claude-000001 --summary "reviewed, 2 findings in notes" \
  --notes-file notes/codex-000005.md

The helper assigns ids under a lock, stamps every required field, and serializes concurrent sends. Add --dry-run to preview without writing.

Runtime diagnostics

When a collaboration appears stuck or noisy, run the read-only doctor from the project root:

python .handoff/tools/doctor.py

It checks stream JSON, local seq files, session cursors, legacy cursor anchors, claims, and unexpected runtime files. It does not modify project or runtime state.

License

MIT © OpenMOSS

Ver o original no GitHub

Bom para

Relacionados