| # ACP Codex Subagents |
|
|
| This workspace turns the `idea` note into a small runnable ACP/Codex |
| orchestration layer. It uses `acpx` named sessions as the transport and keeps |
| each subagent scoped by role and file ownership. |
|
|
| `acpx` is still alpha, so this is an experimental workflow. The script defaults |
| to `npx -y acpx@latest` when a global `acpx` binary is not installed. |
|
|
| ## Quick Start |
|
|
| Check the local prerequisites: |
|
|
| ```bash |
| ./scripts/acpx-subagents doctor |
| ``` |
|
|
| Create or reuse the named Codex sessions for this workspace: |
|
|
| ```bash |
| ./scripts/acpx-subagents ensure |
| ``` |
|
|
| Send one task to one subagent: |
|
|
| ```bash |
| ./scripts/acpx-subagents send ui --no-wait "Implement the navigation fix in the owned UI files." |
| ``` |
|
|
| Send the same high-level task to all configured subagents: |
|
|
| ```bash |
| ./scripts/acpx-subagents parallel --no-wait -- "Review your owned area and report the smallest safe implementation plan." |
| ``` |
|
|
| Target another repository without moving this orchestration folder: |
|
|
| ```bash |
| ./scripts/acpx-subagents --cwd /path/to/project ensure |
| ./scripts/acpx-subagents --cwd /path/to/project send tests --no-wait "Add focused coverage for the new parser behavior." |
| ``` |
|
|
| ## Agents |
|
|
| The default agents are defined in `subagents.conf`: |
|
|
| - `ui`: frontend, templates, static assets, UI components |
| - `pipeline`: pipeline/runtime/schema/guard logic |
| - `rules`: rule packs, policy, validation rules |
| - `tests`: tests, fixtures, harnesses, test docs |
|
|
| Every prompt sent through the script gets wrapped with the agent role, ownership |
| boundaries, and collaboration rules. Agents are told not to edit outside their |
| owned paths unless the task explicitly grants that scope. |
|
|
| ## Commands |
|
|
| ```bash |
| ./scripts/acpx-subagents doctor |
| ./scripts/acpx-subagents ensure [agent...] |
| ./scripts/acpx-subagents send [--no-wait] [--file prompt.md] <agent> [prompt...] |
| ./scripts/acpx-subagents parallel [--no-wait|--wait] [agent...] -- [prompt...] |
| ./scripts/acpx-subagents sessions |
| ./scripts/acpx-subagents show <agent> |
| ./scripts/acpx-subagents history <agent> [limit] |
| ./scripts/acpx-subagents close [agent...] |
| ``` |
|
|
| Set `ACPX_BIN` if you want to pin a local or global command: |
|
|
| ```bash |
| ACPX_BIN="acpx" ./scripts/acpx-subagents ensure |
| ACPX_BIN="npx -y acpx@0.1.15" ./scripts/acpx-subagents ensure |
| ``` |
|
|
| Set `SUBAGENTS_CONFIG` to use a different Bash config file with another agent |
| list or different ownership scopes. |
|
|
| ## Integration Notes |
|
|
| `acpx` scopes sessions by git root when one exists. In a directory without a git |
| repository, sessions are scoped to the exact current working directory. For real |
| parallel implementation work, run this against the actual project repository and |
| use separate worktrees when agents will make independent changes. |
|
|
| References: |
|
|
| - https://github.com/openclaw/acpx |
| - https://github.com/openclaw/acpx/blob/main/docs/CLI.md |
| - https://github.com/cola-io/codex-acp |
| - https://agentclientprotocol.com/registry |
|
|
