Run hcom Agents

Write and run hcom scripts that launch, coordinate, and manage multiple AI coding agents.

Mandatory preflight

Before using any reference script or launching a headless agent:

1. Verify the CLI and target tool are installed.
2. Run hcom status and confirm hooks are installed for every backend you plan to use (claude, codex, gemini, opencode).
3. If hooks are missing, run hcom hooks add <tool>, restart that tool, then re-run hcom status.
4. If hcom hooks add <tool> fails or hcom status still does not show installed hooks, stop. Capture hcom status output and do not proceed to launch scripts.
5. After launching any headless agent, wait for a ready signal before sending messages. For Codex this usually means hcom events --wait 30 --idle "$codex_name"; for other tools, use the same check when launch/binding looks uncertain.
6. If one agent's startup prompt sends to another agent, launch the recipient first. Examples: reviewer before worker, judge before contestants, Codex engineer before Claude architect.

Decision tree

1. User wants to write a new hcom script → Use the Script Template below
2. User wants a specific pattern (review loop, ensemble, etc.) → Read references/patterns/tested-patterns.md