codex-subagent-plugin

中文Readme

Run Codex sub-tasks in parallel.

Prerequisites

• Codex CLI is installed and codex exec ... runs directly in your terminal.
• ~/.codex/config.toml (or the directory pointed to by CODEX_HOME) already exists as the security config source.
• Building requires the Rust toolchain (cargo). If you already have a prebuilt binary, you can skip the build step.

Build

cargo build --release

The binary will be at target/release/codex-subagent-plugin.

Installation

Build first, then install.

Option A: Use the script (recommended)

Linux / macOS

bash scripts/install.sh [--scope user|project] [--project <path>] [--bin-dir <bin_dir>] [--no-build]

Windows (PowerShell)

pwsh scripts/install.ps1 [-Scope user|project] [-Project <path>] [-BinDir <bin_dir>] [-NoBuild]

Options:

• --scope / -Scope: install to user-level ~/.codex/skills (default) or project-level <project>/.codex/skills.
• --project / -Project: project root when scope=project; defaults to the current directory.
• --bin-dir / -BinDir: an existing binary directory to search first; if omitted the script looks in target/release or bin/ and builds if missing.
• --no-build / -NoBuild: do not auto-build when the binary is not found.

The scripts call the plugin's built-in install subcommand, resetting any existing install directory to keep skill metadata and security settings in sync.

Uninstall

Scripts:

bash scripts/uninstall.sh [--scope user|project] [--project <path>]

pwsh scripts/uninstall.ps1 [-Scope user|project] [-Project <path>]

Use in Codex

Describe your needs directly in chat; Codex will pick this plugin automatically—no manual command needed. Examples:

• "Run 3 parallel sub-tasks: write README examples, add tests, summarize unstaged changes."
• "Resume the testing task from last time."

If you need to run the binary manually, use the full command references below.

Good use cases

• Two or more independent tasks you want to finish faster.
• Tasks require different read/write permissions or separate working dirs.
• You want to reuse previously launched tasks and continue them (resume).

Commands and options

run: start a batch of parallel sub-tasks

codex-subagent-plugin run \
  -t "task description 1" [-T read-only|workspace-write] -d /abs/path1 \
  -t "task description 2" [-T read-only|workspace-write] -d /abs/path2 \
  [-p parallelism] [--heartbeat-secs seconds]

• -t, --task: task text, repeatable.
• -T, --task-sandbox-mode: sub-task sandbox; default read-only.
• -d, --task-cd: sub-task working directory, must be absolute.
• -p, --parallel: max concurrency; default equals the number of tasks.
• --heartbeat-secs: while waiting, print a heartbeat to stderr every N seconds; default 30, set 0 to disable.

resume: continue a previous batch

codex-subagent-plugin resume \
  -t "task description 1" -s <SESSION_ID1> [-T read-only|workspace-write] \
  -t "task description 2" -s <SESSION_ID2> [-T read-only|workspace-write] \
  [-p parallelism] [--heartbeat-secs seconds]

• -s, --session: session ID to resume; order must align with -t.

Output

Both commands return JSON:

{
  "success": true,
  "results": [
    {
      "task": "write README examples",
      "success": true,
      "SESSION_ID": "abc123",    // returned for new tasks; use this in the next resume
      "agent_messages": [...]    // prompts/summaries from the sub-task
    },
    {
      "task": "add tests",
      "success": false,
      "error": "..."             // reason when it fails
    }
  ]
}

Parallelism and sandbox rules

These rules are written in SKILL.md for the AI to follow; adherence ultimately depends on the AI.

• Main session read-only: sub-tasks can only read, directories unrestricted.
• Main session workspace-write: read-only tasks anywhere; write-capable sub-tasks must work inside the current directory or its subdirectories.
• Main session danger-full-access: no restrictions on sub-task read/write paths.
• Principle: sub-task permission ≤ main session permission. Create new directories in the main session first, then pass the absolute path via -d.

Notes

• The plugin uses an isolated Codex Home for sub-tasks: ~/.codex/skills/codex-subagent-plugin/.codex (or .codex/skills/codex-subagent-plugin/.codex under a project). It copies the main session config.toml (removing MCP and approval_policy to avoid issues ending sub-task sessions). You can configure MCP or skills there; if the file already exists, installation keeps your content and does not overwrite it.