The old article title promised a generic productivity win. That is the weak version of this topic. The stronger version starts with a practical failure mode: a developer asks two agents to work at once, both edit the same checkout, one rewrites shared config, the other rewrites tests, and nobody can tell which diff is safe.

parallel-agent-worktree-skill is useful because it makes that failure harder. It treats each worker as a branch with a worktree, a scoped prompt, a tmux session, logs, tests, a changelog fragment, and a review step before anything lands back on the integration branch.

Save the pattern, not the speed claim

The repo is experimental and says so directly. It can coordinate autonomous CLI agents, git branches, worktrees, merge operations, tests, backup commands, and infrastructure commands. That is powerful enough to damage a repo if the operator treats it as a shortcut.

The useful editorial frame is therefore not “run more agents.” It is “make parallel agents reviewable.” A worker that runs in its own git worktree leaves a branch, a diff, command output, and a cleanup path. A worker that runs in the main checkout leaves a mess.

Start with task boundaries

The runtime instructions say the coordinator should understand the code, tests, docs, and constraints before spawning workers. That rule matters more than the script. Split only work with disjoint ownership: one worker on API validation, one on UI copy, one on docs, one on a focused test fixture. Do not split two workers across the same migration chain, generated client, lockfile, or global config.

A useful worker brief names the task, branch, owned files, files it may read, files it must not edit, the goal, acceptance criteria, verification commands, changelog path, integration risk, and dependencies. That is what makes later review possible.

Preflight the target CLI

The README ships Kimi examples, but it warns that Kimi is only a concrete mapping. The portability guide is the important part for Codex, Claude Code, OpenCode, Cline, or any other agent CLI. Do not copy flags across tools.

For Codex, the sample mapping uses codex and records noninteractive args as exec --dangerously-bypass-approvals-and-sandbox, with a note to confirm the flag before publishing a converted package. That is the right posture: run the real help command first, then map prompt delivery, work directory behavior, approval flags, sandbox behavior, logging, exit codes, session state, and skill paths from the installed CLI.

Use interactive workers for judgment-heavy work

Interactive mode is the safer default for feature work because the coordinator can watch sessions and steer. The worker manager creates a worktree, starts a tmux session, sends the prompt, and exposes status, capture, send, and cleanup commands.

uv run python .agents/skills/parallel-agent-worktree-skill/scripts/agent_workers.py spawn api-tests \
  --base main \
  --prompt-file /tmp/api-tests.prompt \
  --agent-cli codex \
  --agent-args "exec --dangerously-bypass-approvals-and-sandbox"

uv run python .agents/skills/parallel-agent-worktree-skill/scripts/agent_workers.py status
uv run python .agents/skills/parallel-agent-worktree-skill/scripts/agent_workers.py capture api-tests --lines 120
uv run python .agents/skills/parallel-agent-worktree-skill/scripts/agent_workers.py send api-tests --prompt-file /tmp/followup.prompt

The exact --agent-args should come from current local CLI help, not this article. The point is that the worker is isolated and steerable.

Make every worker leave an audit trail

Worker output is untrusted until reviewed. The skill says the coordinator should inspect status, commit history, diff stats, and full diffs before accepting anything:

git -C "$WT" status --short
git -C "$WT" log --oneline "$BASE_REF"..HEAD
git -C "$WT" diff --stat "$BASE_REF"...HEAD
git -C "$WT" diff "$BASE_REF"...HEAD

That review is where the article becomes useful for a real Codex workflow. Do not accept a worker because its final summary sounds confident. Accept it because the diff is scoped, tests match the brief, the changelog fragment exists, and the branch can merge without hiding unrelated changes.

Use deterministic loops for stateful runs

The second mode renders a Bash or Python loop from JSON. That is for jobs where repeatability matters more than live steering: self-hosted upgrades, backup-gated maintenance, or batches of narrowly defined worker tasks. The JSON plan has explicit fields for repo, base, worktree root, max parallelism, agent settings, preflight, backups, tasks, verification, postflight, and rollback.

uv run python .agents/skills/parallel-agent-worktree-skill/scripts/render_worker_loop.py \
  --config examples/self-hosted-upgrade.json \
  --language python \
  --output /tmp/run-agent-workers.py

DRY_RUN=1 /tmp/run-agent-workers.py
RUN_ID=upgrade-2026-04-11 LOG_ROOT=/tmp/parallel-agent-worktree-skill-logs /tmp/run-agent-workers.py

The DRY_RUN=1 path should be treated as part of the workflow, not an optional rehearsal. If the backup command, preflight command, or log path is wrong, the loop should fail before agents touch the repo.

Changelog fragments are conflict control

The README requires every worker to update a changelog or fragment. That sounds bureaucratic until three workers all edit the same CHANGELOG.md block. The better pattern is a per-worker fragment such as .worker-runs/changelog/api-tests.md, then the coordinator reconciles accepted fragments during final integration.

This gives reviewers two things. First, each worker explains its change in a predictable place. Second, changelog conflicts do not become false merge conflicts that obscure the code review. The fragment is not the source of truth, but it is a cheap accountability marker.

Know when not to parallelize

The portability guide has the right stop signs. Do not use deterministic loops when the target CLI has shared mutable session state, unclear approval semantics, unreliable prompt delivery, or global config mutation. Do not use parallel workers when the repo cannot tolerate concurrent edits, when backups have not been verified, or when logs may expose secrets.

In normal app work, skip parallel workers for broad refactors that touch every import, generated SDK changes, migration ordering, package manager lockfile updates, or any task where two agents will fight over the same files. A single slower agent with a clear review path is better than three fast branches that cannot merge.

The Codex use case

For Codex teams, this skill is most useful as a coordinator checklist. Before spawning workers, run git status --short --branch, confirm the integration branch, verify uv, tmux, and codex --help, then write one prompt per worker with file ownership and verification commands.

After the workers run, merge nothing from tmux transcripts alone. Inspect each branch, run the tests in the main tree after each accepted merge, reconcile fragments, and clean up worktrees only after accepted work is merged or rejected work is deliberately discarded. That keeps the operator, not the agent swarm, responsible for the final repo state.

Save this article as a worktree orchestration guide. The idea is valuable when it isolates agent workers and forces review; it becomes dangerous when teams treat approval-bypass flags and automatic loops as a substitute for ownership.

Practical takeaway

Use parallel-agent-worktree-skill only after you can write disjoint worker briefs. Verify the selected CLI with its current help output, spawn each worker into its own branch and git worktree, require tests plus a changelog fragment, inspect diffs before merging, run main-tree validation after each accepted merge, and reserve deterministic loops for runs with tested preflight, backup, log, and rollback paths.