---
slug: "codex-subagent-plugin"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/canxin121/codex-subagent-plugin@master/README.md"
repo: "https://github.com/canxin121/codex-subagent-plugin"
source_file: "README.md"
branch: "master"
---
# codex-subagent-plugin

[中文Readme](https://github.com/canxin121/codex-subagent-plugin/blob/HEAD/README.zh.md)

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

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

**Windows (PowerShell)**

```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
bash scripts/uninstall.sh [--scope user|project] [--project <path>]
```

```powershell
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

```bash
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

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

```jsonc
{
  "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.