Pipeline launcher for Codex CLI with staged agent networks
npm install codex-swarmPipeline launcher for Codex CLI. Provides staged, wired agent execution driven by a YAML/TOML pipeline file. Supports temp dirs, git worktree clones, built-in + user agent types, dry-run, parallel node execution within a stage, and command nodes.
Not affiliated with OpenAI.
bash
npm install -g codex-swarm
`Run (local checkout)
`bash
npm install
npm run build
codex-swarm parallel-development --dry-run -i "Build me a plan"
`Pipeline file
- Recommended format: YAML (TOML also supported).
- Top-level keys: version, name, description, directories, agent_types, stages.$3
`yaml
directories:
main:
alias: main
kind: path
path: .
scratch:
alias: scratch
kind: temp
base: /tmp/codex-swarm
worktree:
alias: worktree
kind: worktree
source: .
ref: HEAD
`
Kinds: temp (mktemp under base), path (existing path), worktree (git worktree clone; CoW). Use keep: true to skip cleanup.$3
- Resolved from layers: built-in src/builtin/agent-types.yaml → ~/.codex-swarm/agent-types.{yaml,toml} → inline agent_types in the pipeline file.
- Fields: alias, prePrompt, access (read-only|read-write), optional command/args/env defaults. Root/directories are set on each agent instance.$3
`yaml
stages:
- alias: planning
agents:
- alias: planner-1
type: planner
input: stdin
root: main
directories: [main]
- alias: implementation
agents:
- alias: implementor-1
type: implementor
input: planner-1
root: worktree
directories: [worktree, scratch]
- alias: reviewer-1
type: reviewer
input: implementor-1
depends_on: [implementor-1]
root: worktree
directories: [worktree]
`
- Nodes in a stage run in parallel when ready (dependencies satisfied).
- input: stdin (pipeline input) or another node alias; wiring resolves when dependencies are satisfied.
- depends_on: optional list of aliases that must complete before the node can run; does not provide input.
- root: directory alias to launch from; use root to run from pipeline cwd. Alias root is reserved and cannot be defined in directories. directories: aliases surfaced via template placeholder {{directories}} and env CODEX_DIRECTORIES.
- Placeholders available in prePrompt/args: {{stdin}}, {{input}}, {{directories}}, {{agent}}, {{stage}}.
- Environment: CODEX_DIRECTORIES (human list) and CODEX_DIRECTORY_MAP (JSON map of alias → path).$3
`yaml
- alias: merge
agents:
- alias: merge-winner
kind: command
input: reviewer
depends_on: [reviewer]
root: root
directories: [repo, work1, work2, work3]
command: node
args: [scripts/merge-best.mjs]
`
- kind: command runs command/args directly (no Codex agent type).CLI
`
codex-swarm [options]
-i, --input Inline pipeline input (else stdin)
--input-file Read input from file
--codex-bin Codex CLI binary (default: codex)
--dry-run Print actions without spawning agents
--verbose Extra logs
--list-pipelines List available pipelines and exit
`
Pipeline names must be provided without paths.
Pipeline resolution order: ./.codex-swarm/pipelines → ~/.codex-swarm/pipelines → packaged pipelines/.Pipelines
- pipelines/parallel-development/pipeline.yaml (parallel-development`): three parallel implementors, reviewer, and merge-winner pipeline.