parallel-subagents

Parallel Subagents

The native host can run parallel Codex workers for you. You cannot spawn processes yourself (the sandbox forbids it) — instead you write job files into a queue directory and poll for result files. Each worker is a full Codex agent confined to the files you assign it.

1. When to use

Use this when ALL of these hold:

• The task splits into ≥ 2 independent slices: different files, or different sections of one file (use the scatter-gather workflow in §5).
• Slices do not depend on each other's output.
• Each slice is small enough to finish in a few minutes.

Do NOT use it (work sequentially yourself instead) when:

• Slices are deeply cross-referenced and must be edited together.
• There are fewer than 2 real slices.
• The handshake file below is missing or not ready.

1b. Explicit scope — the iron rule

Every job's task MUST state its exact working scope, and scopes MUST NOT overlap:

• multi-file job: name the file(s) and what inside them is in scope;
• single-file slice job: name the section (\section{...} title) and quote the slice's exact first and last source lines. Never write two jobs whose scopes could touch the same text. If you cannot state a slice's boundaries precisely, do that slice yourself instead.

2. Handshake

Read .codex-overleaf-subagents/broker.json. If it is missing or its status is not ready, the broker is off — do everything yourself. Respect maxWorkers, maxJobsPerRun, and perWorkerTimeoutMs (size each job to finish well inside it).

3. Write jobs

One job per slice. Each job OWNS its files exclusively — no file may appear in two jobs. Write atomically: create a temp file, then mv it to its final .json name.

cat > .codex-overleaf-subagents/jobs/.tmp-ch3 <<'JSON'
{
  "id": "ch3",
  "title": "Polish chapter 3",
  "task": "Polish sections/ch3.tex for grammar, flow, and concision. Keep all math and citations intact. Follow the shared style notes: <paste the style guidance here>.",
  "files": ["sections/ch3.tex"],
  "readOnlyContext": ["main.tex", "macros.tex"]
}
JSON
mv .codex-overleaf-subagents/jobs/.tmp-ch3 .codex-overleaf-subagents/jobs/ch3.json