trio-handoff

Bidirectional handoff bundles for two AI coding agents that review each other's work.

Built for the trio workflow (one human + two agents — Claude Code and Codex), where the agents take turns reviewing each other. The bundle format is extensible, but this repository currently ships extractors only for Claude Code and Codex session logs.

Scope note. This repo publishes the handoff bundle format and extractor. The full trio protocol itself (the CC + Codex + human triangulation workflow: reverse-PM, blind-spot scanning, who-writes / who-reviews routing) is maintained separately as a personal skill at ~/.claude/skills/trio/ — not in this repo.

Why

When agent A asks agent B to review its work, A usually hands over a diff and a one-line summary. B can't see what A already tried, what evidence A examined, or which approaches A deliberately rejected — so B keeps re-suggesting things A already ruled out.

Cognition's Don't Build Multi-Agents names the root cause: share full traces, not just messages. A compressed message can't carry the sender's decision context. trio-handoff is a precise, practical version of that principle for the review handoff.

Half-extracted, half-declared

A bundle has two sections:

Objective Evidence — auto-extracted from the agent's own session log: goal / constraints · files examined · commands + truncated outputs · files changed · current diff · current state · raw log path.

Caller Declaration — written by the calling agent, because the log can't capture it: rejected alternatives + why · why this framing / approach · unresolved questions · review focus · do-not-repeat unless new evidence.

The declared half is the valuable half. Rejected alternatives and design rationale often live only in the author's head — they never become an observable action, so no script can extract them. They must be declared. And that declared half is exactly what stops the reviewer from repeating ruled-out suggestions.

Hidden reasoning is never shared

Claude's thinking and Codex's reasoning are excluded by design. A hidden chain of thought contains discarded mid-thoughts and isn't verifiable; a reviewer should anchor on observable evidence, not the author's inner monologue. "Full trace" here means the observable work trace (what was read / run / changed) — not the raw chain of thought.

Two directions, one structure

direction	source log	reads / edits via
cc-to-codex	Claude Code JSONL session	Read / Edit / Write tools
codex-to-cc	Codex rollout transcript	exec_command (cat/sed) + apply_patch

Same bundle structure; only the extractor differs — because the two agents observe their own work differently (Claude has dedicated read/edit tools; Codex reads through shell commands and patches through apply_patch).

Usage

./trio-handoff.py                          # latest Claude session -> bundle for Codex
./trio-handoff.py --direction codex-to-cc  # latest Codex rollout -> bundle for CC
./trio-handoff.py path/to/session.jsonl    # explicit source, direction auto-detected
./trio-handoff.py --last-n 3               # only the last 3 user turns
./trio-handoff.py --include-subagents      # include subagent traces (cc-to-codex)
./trio-handoff.py --repo ~/code/project    # where to run git diff / status
./trio-handoff.py --base origin/main       # diff baseline (include committed changes)
./trio-handoff.py --out /path/bundle.md    # output path (default ~/Desktop/)
./trio-handoff.py --check bundle.md        # pre-send self-check: is the Caller Declaration still blank?
./trio-handoff.py --allow-empty            # generate even if extraction came up empty (refused by default)

"Latest session" is picked by the timestamp inside the JSONL, not file mtime (bridge/patch processes batch-refresh mtimes, making them a lottery), and Claude sessions are searched across all ~/.claude/projects/*/ subdirectories (sessions scatter by cwd). After picking, the tool prints the session's first user message so you can eyeball that it grabbed the right one — if not, rerun with an explicit source path. If extraction yields nothing (wrong source, format drift), the tool refuses to emit a hollow bundle.

Output is a Markdown bundle (default in ~/Desktop/). Fill in the Caller Declaration before sending, then run --check on the bundle — it exits non-zero while rejected alternatives is still blank. Hand the path to the reviewing agent — it reads the bundle for guidance and can drill down into the raw log path at the bottom to verify any claim, so it never has to trust the compression blindly.

The bundle opens with a review instruction:

First verify the repo anchors (run the embedded verify commands — the docs may be stale, command output isn't). Then check the Caller Declaration — if it's still a blank template, bounce the bundle back instead of reviewing half a handoff. Then extract goal / evidence / rejected-alternatives / diff and review. Don't repeat suggestions already ruled out unless you can point to new evidence.

Security boundary

Generated bundles apply best-effort redaction for common credentials, including private keys, JWTs, major provider-token shapes, credentialed URLs, authorization headers, and secret-like assignments. This is a safety net, not a complete secret scanner: inspect the generated bundle before sending it across a trust boundary.

The source JSONL is never modified or copied into the bundle; the bundle contains only its local path as a drill-down pointer. Anyone who can open that original log may still see unredacted source data. Run --check for declaration completeness, then inspect the actual bundle for sensitive content before sharing it.

Config

env	default
TRIO_CC_DIR	~/.claude/projects (scanned two levels deep; may also point at one project subdir)
TRIO_CODEX_GLOB	~/.codex/sessions/*/*/*/rollout-*.jsonl

Requirements

Python 3.8+, standard library only.

Versioning

Two version tracks (they evolve independently):

• Tool release: git tag, currently v2.5.0 — extractor / CLI behavior.
• Bundle template: currently v1.13 — the bundle's section layout. Fields carry [v1.x] markers for the template version that introduced them (e.g. repo anchors' verify lines are v1.11; falsifier and exit criteria are v1.12; the without-review baseline is v1.13; runtime surfaces and confidence are v1.10).

This repo publishes the handoff bundle format. The trio protocol itself (CC + Codex + human triangulation workflow) is maintained as a personal skill at ~/.claude/skills/trio/.

License

MIT © 2026 AliceLJY · See LICENSE. Chinese readme: README_CN.md.