Codex dispatch

A dispatch is one complete, self-contained prompt sent to Codex. Give it the deliverable, target files or directories, constraints, and required checks. Codex works from that prompt alone: the conversation, the reasoning behind the request, and the skills loaded in this session all stay on this side, and Codex starts with the repository, whatever its own configuration supplies, and the prompt. Put substantial prompts in a file and pass --prompt-file.

Use the companion as the contract. The companion speaks Codex app-server JSON-RPC over a socket through a persistent broker, which provides resumable threads, background jobs, and structured review output. codex exec bypasses that broker, loses those, and has no remaining advantage.

Send a dispatch

The plugin's codex:* surfaces are designed entry points the main thread reaches on its own: the codex-rescue subagent, and the review, adversarial-review, and setup companion subcommands the commands wrap. Prefer one when the task carries little session context and ergonomics beat a hand-tuned brief: setup for readiness, review or adversarial-review for a structured pass, the subagent for a quick throw-over. Author the task prompt yourself when the brief benefits from folding in the session's skills, conventions, and decisions.

The main thread writes the prompt, chooses the scope, submits the dispatch, pulls its result, and verifies the outcome. The codex:codex-rescue subagent is a pipe by design: its instructions confine it to forwarding one task call and returning stdout verbatim, and bar it from inspecting the repository, polling status, or fetching results. Treat that as its contract rather than a guarantee, and keep inspection, polling, result retrieval, and follow-up work in the main thread.

Take stock of what this session is running on before writing the brief: skills in play, conventions from instruction files, decisions already made, constraints the user set. Fold whatever shapes the work into the prompt. Knowledge carries well — voice rules, domain facts, the standard the result has to meet. Procedure tied to this harness, such as tool names, MCP servers, or subagents, reads as noise on the other side, so state the outcome it was meant to produce instead.

To hand over a skill, resolve its absolute path here and tell Codex to read it before starting, naming the entry file and any sibling reference files it needs. Reads outside the workspace succeed, so the path holds regardless of --cwd. Pass the path rather than the name, so Codex has a file to open. Then ask the result for something only that skill would produce, since a dispatch that missed it still returns finished-looking work.

Standing conventions belong in AGENTS.md, which Codex loads on its own.

Glob the installed companion version instead of naming one: