paired-agents

name	paired-agents
description	Run Claude Code and Codex CLI as a coordinated pair — one drafts, the other reviews, both check each other before anything ships. Activates when the user wants two AI agents to collaborate without manually copying messages between them. Trigger phrases include `pair with codex`, `paired review`, `draft and review`, `parallel pair`, `two-agent workflow`.

paired-agents — Claude + Codex working as one team

This skill turns two CLI agents — Claude Code and Codex — into a coordinated pair. One drafts, the other reviews. Decisions are recorded. Neither finalizes work alone. The protocol can use optional specialists such as Gemini for media extraction, but the required approval loop stays small: Claude + Codex.

When this skill activates

• You're working in Claude Code and want a second opinion on something non-trivial (auth changes, migrations, deploy plans, content for public release).
• You want to draft → review → apply → smoke without copying messages between two terminals.
• You need a record of why a decision was made, not just the final code.
• You're running unattended overnight work and want both agents to stay honest with each other.

Trigger phrases:

pair with codex
paired review of <file>
draft and review <thing>
let codex check this
two-agent workflow

What you get

1. A pair-cycle protocol that prevents single-agent groupthink.
2. File-based sync — no shared API, no daemons-talking-to-daemons. Just markdown files and a watcher.
3. Autowork mode — when you step away, the pair can keep moving on a bounded task with a safety net (AUTONOMY.md + finite phase + stop conditions).
4. Auditability — every decision lives in decisions.md, every conversation in NOTES.md, every disagreement in reviews/.
5. Agent slots — optional specialists such as Gemini can provide evidence without taking over final approval.

The five-state cycle

1. DRAFT    one agent writes a small artifact, marks it `DRAFT - pending <other> review`
2. REVIEW   other agent reads, leaves inline `<!-- review[agent]: ... -->` comments OR a file in `reviews/`
3. APPLY    author resolves comments, removes inline notes, records `v1` in `decisions.md`
4. SMOKE    when all related drafts are agreed, both run a smoke check before anything moves to runtime
5. MEMORY   record durable decisions, changed paths, smoke result, and next action

Hard rule: one file per iteration. No batched "rewrite everything." Small drafts are reviewable; big ones aren't.

How the agents see each other

You don't manually copy messages. The watcher does it:

1. Agent A finishes a draft and ends with an END marker:

   <!-- end:claude:2026-05-17T16:24:30Z -->
   

2. A shell watcher (scripts/watch-pairing.sh) polls the pair directory.
3. When it sees a new END marker from a different agent, it writes an event to .pair/events/.
4. Next time Agent B is invoked, it reads events/ first and knows there's a new draft to review.

No direct cross-agent API calls and no secret exchange. Just files. Any external messaging or bot adapter should be treated as a separate opt-in integration, not part of this skill.

What the pair won't do

• Install packages or modify system dependencies autonomously.
• Touch .env, tokens, OAuth, cookies, private keys, or browser profile files.
• Write outside the pair directory unless you explicitly extend the allow-list.
• Loop LLM calls indefinitely. Every phase has a finite checklist and stop conditions.
• Install runtime skills, plugins, or service-manager jobs without your explicit approval.

These rules live in AUTONOMY.md (see templates/AUTONOMY.md.template). Copy it into your project, fill in placeholders, and the autowork script will refuse to run without it.

Quick start

# 1. Clone the skill anywhere
git clone https://github.com/olegvasilov3-maker/paired-agents ~/code/paired-agents

# 2. Install (creates a symlink into ~/.claude/skills/)
~/code/paired-agents/install.sh

# 3. In your project, bootstrap a pair workspace
cd ~/my-project
mkdir -p .pair/events .pair/reviews .pair/.autowork
cp ~/code/paired-agents/templates/AUTONOMY.md.template .pair/AUTONOMY.md
cp ~/code/paired-agents/templates/AGENT_SLOTS.md.template .pair/AGENT_SLOTS.md
cp ~/code/paired-agents/templates/NOTES.md.template .pair/NOTES.md
cp ~/code/paired-agents/templates/decisions.md.template .pair/decisions.md
${EDITOR:-vi} .pair/AUTONOMY.md   # fill placeholders

# 4. Start the watcher (optional but recommended)
~/code/paired-agents/scripts/watch-pairing.sh codex &
~/code/paired-agents/scripts/watch-pairing.sh claude &

# 5. Use the skill from Claude Code
# Just type a trigger phrase: "paired review of src/auth.ts"

Files Claude and Codex maintain together

Inside ${PAIR_ROOT} (e.g. ~/my-project/.pair/):

File	Purpose	Who writes
AUTONOMY.md	rules for what the pair can/cannot do unattended	you (once), agents read every run
AGENT_SLOTS.md	optional specialists such as Gemini, security, QA, docs	you + agents
NOTES.md	short coordination replies, one per turn	both, with END markers
decisions.md	only things both agents said "yes" to	both, after apply
reviews/<reviewer>-<topic>-<utc>.md	long reviews of one agent's work by another	the reviewer
events/<ts>-<self>-saw-<other>-<filekey>.event	watcher-generated handoff signals	watcher only
.autowork/	logs and artifacts from background passes	autowork script

Behavior modes

Foreground (you're in Claude Code, watching)

Type a trigger phrase. Claude drafts. Then either you call Codex with the skill's helper, or Claude does codex exec --sandbox read-only -C "$PWD" "<review prompt>" via Bash. You see both outputs, decide what to apply.

Background (you're away)

~/code/paired-agents/scripts/autowork.sh \
  --pair-root ~/my-project/.pair \
  --phase phase-a-router \
  --prompt ~/my-project/.pair/prompts/router-task.md

The script:

1. Refuses to run if AUTONOMY.md is missing.
2. Runs Codex (workspace-write, sandbox to pair-root, 15-min timeout).
3. Runs Claude -p for review (4-min timeout).
4. Logs everything to .autowork/<phase>-<utc>.{jsonl,stderr,final,review}.
5. Stops. No infinite loop.

Examples

See examples/:

• 01-basic-pair.md — pair-review a single file change.
• 02-three-agents.md — add Gemini for media tasks.
• 03-custom-phase.md — define your own phase with autowork.
• 04-n-agents.md — add optional specialists without losing the pair approval rule.

Conventions and gotchas

• END markers use UTC seconds and Z suffix: <!-- end:claude:2026-05-17T16:24:30Z -->. Without Z you'll fight timezone bugs.
• One marker per record. The last marker wins for watcher purposes.
• No auto-finalization. If a file is stable for 5 minutes without a marker, the watcher writes a stale-draft event — warning, not approval. Only the pair finalizes.
• Inline review comments (<!-- review[codex]: ... -->) are temporary. Author removes them in the APPLY step.
• decisions.md is append-only. Don't edit old entries; add a new one that supersedes.
• NOTES.md lives forever. Don't truncate. If too long, summarize into WORKLOG.md and link.

What this skill is NOT

• It is not an autonomous coding agent. It coordinates two CLIs you already have.
• It is not a CI replacement. Smoke is a manual checklist, not a test runner.
• It is not a memory layer. SQLite-backed pair memory is a future extension (paired-agents-memory skill, planned).
• It is not tied to any specific runtime. The protocol works in any project where you can run claude and codex CLIs.

License

Source-available, not open source. See LICENSE before redistributing, commercialising, publishing derivatives, or rebranding this project.

Feedback

If you find a way to break the pair (e.g. one agent silently overriding the other), open an issue. Edge cases are the point.