codex-subagent-plugin

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).

⭐4stars🔀0forks📁View on GitHub🕐Updated Jan 6, 2026⬇️1downloads

When & Why to Use This Skill

The Codex Subagent Plugin is a high-performance orchestration tool designed to run multiple Claude subagents in parallel within secure, isolated sandboxes. It enables developers to scale complex workflows by executing independent tasks simultaneously—such as concurrent code reviews, testing, and documentation—while maintaining strict permission controls (read-only vs. workspace-write). By supporting session resumption and real-time heartbeat monitoring, it optimizes agentic efficiency, ensures process stability, and reduces token consumption for long-running operations.

Use Cases

  • Parallel Development Workflows: Simultaneously run one subagent to generate unit tests in a workspace-write sandbox while another performs a read-only architectural review of the codebase.
  • Multi-Directory Project Management: Execute documentation updates and code refactoring across different absolute paths in parallel, ensuring each subagent operates within its designated workspace.
  • Token-Efficient Task Resumption: Use the resume command to continue interrupted or long-running subagent sessions using their Session IDs, avoiding redundant API calls and reducing costs.
  • Secure Permission Isolation: Enforce security by running sensitive analysis tasks in read-only mode while granting write access only to specific subagents tasked with file modifications.
  • Automated CI/CD Pre-checks: Orchestrate multiple sub-tasks to check for security vulnerabilities, linting errors, and API compatibility in parallel before a final merge.
namecodex-subagent-plugin
descriptionRun 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.