Claude coterie

Claude Coterie

Coordinate N bounded-parallel persistent Claude Code agents around any user goal, each framed with a role tailored to make a distinct contribution. Codex is the host and orchestrator: it composes the panel and the shared context, launches the run, and reconciles the aggregated report into one coherent outcome rather than forwarding a pile of independent replies. Each role keeps its own Claude thread per project (state key role:<id>) so useful framing and project knowledge accumulate across calls. This is the mirror-inverse of codex-council with the hosts swapped.

A coterie may contain one role when one focused lens is all the work needs or the user explicitly requests one. That is a one-role panel using the same council workflow.

Step 1 — Read the actual work

Look at what the user is actually doing in the conversation and workspace. Privately ask and answer: what larger problem are they solving; which files, modules, tests, or artifacts are in flight; which bugs, risks, or ambiguities are they hunting; what are the known unknowns and possibly-wrong assumptions; is the work converging, blocked, or exploratory. Then ask the synthesis question:

What distinct contributions would move this shared goal forward and catch its work-specific failure modes?

That question, answered from the material in front of you, is the panel. Do not start from a category and pick roles to match — compose lenses from the actual work. If the user named a panel in the invocation, trust it and skip to Step 3.

Step 2 — Compose the panel

Design 2–6 sharply distinct roles by default (3 is a good default; use more only when the work genuinely has more independent lenses and concurrency allows). Each role is {id, label, instruction} — exactly those keys:

• id — a lowercase slug matching ^[a-z0-9_-]+$, derived from the lens for THIS work. A stable id resumes that role's thread across councils; a novel id starts fresh.
• label — non-empty single line, shown in the report.
• instruction — a JSON array of short strings (the script joins them into one paragraph). One sentence per item is the authoring convention that keeps file writes uncorrupted. Name the failure modes this role should hunt in the vocabulary of the task. Two properties of the joined text are validated: it must contain the phrase "nothing material" (write an item like "If nothing material, say so clearly.") and it must end with the exact sentence "Thoroughness beats speed."

Roles in one panel must be sharply distinct so a role asked outside its lens returns "nothing material" instead of overlapping a sibling. If roles mutate files, keep a single writer (pass --allow-edit) while the rest analyze.

Step 3 — Announce and launch

Write one short user-facing paragraph naming what you inferred the work to be and the roles you composed (id + one-line summary each). Do not gate on approval — the composed panel is accepted by default. Stage everything in one private per-run directory:

# 0. Run mktemp -d exactly once; the printed path is ABS_RUNDIR everywhere.
mktemp -d "${TMPDIR:-/tmp}/claude-coterie.XXXXXX"

# 1. Write ABS_RUNDIR/roles.json and ABS_RUNDIR/context.md (see below).

# 2. Pre-flight: validate the staging dir and panel.
python3 "$CODEX_HOME/skills/claude-coterie/scripts/claude_coterie.py" \
  --check-staging-dir 'ABS_RUNDIR' --skill-contract 1

# 3. Launch; with free parallel slots and no role-lock contention, a
#    council takes roughly as long as its slowest role (queueing extends it).
python3 "$CODEX_HOME/skills/claude-coterie/scripts/claude_coterie.py" \
  --roles-file 'ABS_RUNDIR/roles.json' \
  --context-file 'ABS_RUNDIR/context.md' \
  --skill-contract 1 \
  > 'ABS_RUNDIR/out.md' \
  2> 'ABS_RUNDIR/err.log'

If the pre-flight rejects the directory, abandon it — run mktemp -d again and re-write both files into the new path; never chmod or reuse the rejected one. The report and context can hold sensitive reviewed content, and a predictable world-readable path can be pre-created by another local user.

context.md is the shared decision-complete working set: the problem and immediate objective, in-flight work, active problems and hypotheses, primary evidence, durable constraints, and explicit unknowns. Never launch with an empty context file. Roles receive the identical context; their instructions differentiate the lenses.

Concurrency defaults to 6 parallel roles (override with CLAUDE_COTERIE_MAX_PARALLEL, which must be a positive integer); extra roles queue. The final ~2,000 characters of each role's transport diagnostics are relayed into err.log (role <id> stderr: ...). On normal completion, after the report is flushed to stdout, the last stderr line is the sentinel:

[claude-coterie] CLAUDE_COTERIE_DONE ok=N total=M elapsed=T.Ts exit=X

Its absence means the run was interrupted, failed validation, or could not deliver the report. Exit codes are council-level: 0 when at least one role responded, 1 only when every role failed, 2 for usage/validation errors; a cancelled run exits 128 + signal (130 for Ctrl-C, 143 for SIGTERM). Treat shell status as transport status — inspect the report Summary before deciding the council succeeded. Roles are analysis-only by default; pass --allow-edit to the orchestrator only when roles should mutate files, and then keep a single writer to avoid write races.

After the coterie responds

Reconcile rather than relay. Check the claims against the repository and your own reasoning. Combine compatible work, choose between conflicting recommendations with reasons, preserve useful dissent, and turn the panel into one actionable outcome. Then report your own read: what you accept, what you reject, what changed your assessment, and what remains uncertain. When cross-pollination would help, stage the first round's findings as fresh context and re-invoke only the relevant roles; reuse a role id only for a semantically continuous lens.