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

- Author: canxin121
- Repository: canxin121/codex-subagent-plugin
- Version: 20260106192310
- Stars: 9
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/canxin121/codex-subagent-plugin
- Web: https://mule.run/skillshub/@@canxin121/codex-subagent-plugin~codex-subagent-plugin:20260106192310

---

---
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:
```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 <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:
```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`.