Pair

---
name: pair
description: "Pair persistently with another coding agent. Use for live peer work, inbound `[agent ...]` or `[herdr-pair control ...]` messages, and resuming a pair after context compaction."
---

# Pair

Pair two agents on one task: you are the **lead**, and the partner is one of
`claude`, `codex`, `cursor`, `grok`, or `opencode`. The transports require a
different CLI, except headless Codex can use a different account home selected
with `--identity <name>`. The helper proves home separation; separate accounts
do not themselves guarantee independent reasoning. Two different harnesses may use the
same underlying model or provider and still form a valid pair. Keep the
pair and its `sid` alive across tasks, accepted work cycles, and context
compaction, naming its `sid` in every command — one lead can run several
pairs at once. Keep protocol headers and identifiers literal.

Two backends carry the same protocol. Inside Herdr the partner is a visible
pane the user can read and interject in; outside it the partner is a persistent
headless session of the partner CLI.

## Choose the pair

Look for an existing pair before proposing one: a session recorded for this
Herdr tab, or a headless one in this repository (the backend reference names
the exact command). Before a new pair or work cycle, run the
[pool check](references/models.md#pools) and follow its rule for each state.
Resume an existing pair the check allows; for a live pair the check's
fallback is ending it, which only the user can choose. When its partner,
model, or effort differs from what the user just asked for, say so and keep
going — respawning discards the pair's whole history, and a model is changed
by ending the pair, not by restarting its pane.

With no pair to resume, run the
[catalog check](references/models.md#families) before choosing the partner.
Take every choice the user or an orchestrate unit has already made — partner,
model, effort, identity, role — as final and do not ask for it again. Fill unspecified choices from the
[roster](references/models.md) and the live pool check: the Peer seat for an
equal collaborator, the Executor seat for delegated implementation. Use
`peer` when the task leaves the role open. The seat supplies partner family,
model, and effort; for Codex, choose the available identity with the lower
`pace` (`default` is `~/.codex`, a named home is
`~/.codex-profiles/<name>`). Ask the user in plain chat text only when no
eligible route remains or their preference is ambiguous.

The role decides who holds the write leases by default:

- `peer` (default): equals. Split scopes, one lease per scope, review each
  other's `ready`.
- `executor`: the partner holds the write leases and implements; you plan and
  review. Any individual `task` still redistributes leases.

The backend records partner, model, effort, identity, and role in the session,
so a resumed pair keeps them without asking again.

## Choose the backend

Read one backend reference in full and follow it:

- Resume through the recorded backend. An explicit headless request, or an
  orchestrate unit recorded as headless, uses the [Headless backend](references/headless.md)
  even inside Herdr. For a new pair needing `latest:<family>` or a named Codex
  identity inside Herdr, offer that explicit headless route.
- `HERDR_ENV=1` → [Herdr backend](references/herdr.md). Its preconditions
  own the `herdr` CLI check: a Herdr environment missing the CLI stops there
  instead of falling through to a hidden headless session.
- Otherwise → [Headless backend](references/headless.md).

A `[herdr-pair control ...]` line identifies Herdr. An `[agent ...]` header is
shared by both transports: use the recorded session to choose its backend.
Done when the selected session and its backend agree; report ambiguous state
before sending a message.

## Protocol

Messages start with a header:

```text
[agent <from> -> <to> kind=<kind> sid=<sid>]

<body>
```

The Herdr backend adds a `[herdr-pair control seq=<n>: ...]` line under it.

Use these kinds:

- `task`: propose or update the work split and its write leases. Begin a
  mid-flight stop with `STOP — <reason>`.
- `review`: request review with file paths and a short change summary.
- `question`: ask for clarification before proceeding.
- `ready`: report changed files, validation, and residual risk.
- `accepted`: accept the partner's `ready` and advance the work cycle.
- `blocked`: name the user decision required to continue.
- `stalemate`: report the same disagreement repeated twice without movement.
- `handoff`: return control to the user in normal local output.

Send every partner message through the backend's helper. Reserve normal
assistant output for a header-free user handoff.

## Write leases

Give one agent the write lease for each file scope: owner, target files,
forbidden changes, validation, and stop point. The partner stays read-only on
that scope until handoff.

The role sets the opening distribution, and each `task` may redistribute from
there. Under `executor` the partner holds every lease until a task says
otherwise, and you review rather than edit.

Under `peer` the partners are equals: propose a scope split — one write lease per scope,
each partner implementing its own scopes and reviewing the other's `ready` —
and include enough context for independent work; the partner accepts or
counters before implementing. A task with no independent scopes takes one
lease: the holder drives while the partner reviews, and the lease alternates
across tasks.

## Broken-checkout windows

Announce every deliberate broken-checkout window. Before mutation testing,
bisect, or a deliberate revert, send a `task` naming the affected paths and
stop condition; send `ready` after the tree is restored and verified. Do not
wait for `accepted`: the notices are the protection. A partner that has seen
an open window treats that checkout's test results as unusable until the
close notice arrives, and asks rather than reports. Run an experiment that
cannot be announced, or that lasts more than a few minutes, in a separate
worktree.

## Work cycles and persistence

Continue while producing useful artifacts. Five consecutive turns with no new
code, test result, decision, or narrowed option require a `handoff`. Reset the
count on real progress. Settle a factual disagreement with one direct proof or
focused test before it can become a stalemate. Send `stalemate` after the same
judgment call repeats twice without movement.

Two `accepted` statuses complete one work cycle. The initiator gives the user a
local handoff naming the result, verification evidence, unresolved issues, and
every pair pane, worktree, or watcher still active. Both agents may idle; the
next task resumes the same pair and `sid`. The session remains active.

Session renewal is a user decision. If a fresh pair is chosen, carry continuity
in a written checkpoint in its first task.

`blocked` and `stalemate` also hand off without deleting the session. End the
session only when the user explicitly asks to end the pair; the backend
reference owns that command.