--- name: codex-subagent-plugin description: Run Codex subagents in parallel. Main sandbox can be read-only \/ workspace-write \/ danger-full-access; children stay read-only or workspace-write and each requires an absolute working dir (workspace-write children must stay under the main cwd unless main is danger). --- # Codex Subagent Plugin ## Binary Cli Tool location `__BINARY_PATH__` ## Command: run Start new subagent tasks (options align by order). - `-t, --task `: task text; repeat per task. - `-T, --task-sandbox-mode `: optional; defaults to read-only. - `-d, --task-cd `: required; per-task working directory. Must be an absolute path. - `-p, --parallel `: max concurrent subagents; defaults to task count. - `--heartbeat-secs `: print a short heartbeat to **stderr** every n seconds while waiting (default: 30). Set 0 to disable. - Output format: prints JSON with: - `success`: overall boolean. - `results`: array per task: - `task`, `success`, `SESSION_ID` (when present), `agent_messages`, `error` (optional on failure). - Working directory tip: if a task needs a new directory, create it in the main session first and pass its absolute path via `-d\/--task-cd`. Example: ```bash codex-subagent-plugin run \ -t "Review docs" -T read-only -d \/tmp\/docs \ -t "Add tests and PR" -T workspace-write -d \/home\/user\/app \ -p 2 ``` ## Command: resume Continue existing subagent sessions in order. - `-t, --task `: task description aligned with sessions. - `-s, --session `: session ID per task (required). - `-T, --task-sandbox-mode `: optional; defaults to read-only. - `-p, --parallel `: max concurrent subagents; defaults to task count. - `--heartbeat-secs `: print a short heartbeat to **stderr** every n seconds while waiting (default: 30). Set 0 to disable. - Output format: same JSON as `run`. Example: ```bash codex-subagent-plugin resume \ -t "Add tests and PR" -s abc123 -T workspace-write \ -t "Review docs" -s def456 -T read-only \ -p 2 ``` ## Multi-subagent guide (important) - Timing(very important): the tool always returns a JSON result, but long-running child tasks can make the CLI appear to “hang” until they finish—wait for completion rather than retrying prematurely. Do **not** press Ctrl+C unless the run has been quiet for at least 10 minutes; subagents poll and will still return on their own. - Heartbeat: by default a heartbeat line is printed to stderr every 30s with elapsed time and task counts; use `--heartbeat-secs 0` to turn it off. - When to use: (1) 2+ loosely coupled tasks can run in parallel; (2) you need permission isolation (read-only vs workspace-write); (3) you want to resume existing Codex sessions to save tokens. - Sandbox & working-dir rules: main session may be read-only \/ workspace-write \/ danger-full-access. Never give a child more privilege than the main session: - Main = read-only: children must be read-only; working dir can be anywhere. - Main = workspace-write: children may be workspace-write or read-only; workspace-write children must stay within the main session’s current directory or its subdirectories. Read-only children can use any directory. - Main = danger-full-access: children may be workspace-write or read-only; workspace-write children can use any directory. - Working-dir tip: if a task needs a new folder, create it in the main session first and pass its absolute path with `-d\/--task-cd`. - Output handling: command prints JSON; check each `success`, `SESSION_ID`, and `agent_messages`. If missing, read `error` to decide retry or fall back to single-agent. - Best practices: 1) Default children to read-only; only use workspace-write when a task must modify files and the main session permits it. 2) Keep `-p` ≤ CPU cores \/ platform limits. 3) Choose sensible `-d\/--task-cd` paths so tasks can read\/write what they need. 4) Save every `SESSION_ID` for future resume in the same order as `-t`.