codex-subagent-plugin

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 <text>: task text; repeat per task.
• -T, --task-sandbox-mode <read-only|workspace-write>: optional; defaults to read-only.
• -d, --task-cd <path>: required; per-task working directory. Must be an absolute path.
• -p, --parallel <n>: max concurrent subagents; defaults to task count.
• --heartbeat-secs <n>: 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:

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 <text>: task description aligned with sessions.
• -s, --session <id>: session ID per task (required).
• -T, --task-sandbox-mode <read-only|workspace-write>: optional; defaults to read-only.
• -p, --parallel <n>: max concurrent subagents; defaults to task count.
• --heartbeat-secs <n>: print a short heartbeat to stderr every n seconds while waiting (default: 30). Set 0 to disable.
• Output format: same JSON as run.

Example:

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.