parallel-agent-worktree-skill

Experimental dangerous-workflow disclosure: this skill can coordinate multiple autonomous CLI agents, git branches, git worktrees, merge operations, test commands, backup commands, and infrastructure commands that you configure. It is provided as-is, without warranties under Apache-2.0. Use it only in repositories and environments you are authorized to modify, keep verified backups, review every generated command and diff, and assume responsibility for any data loss, downtime, credential exposure, cost, or unwanted changes caused by using or modifying it.

Generic Agent Skill for orchestrating parallel agentic tasks with any agent harness that has a CLI. Workers run in isolated git worktrees with review-gated integration, changelog requirements, deterministic Python/Bash loop generation, and backup-aware maintenance support. The package is generic; the included JSON examples use Kimi CLI only as one concrete harness mapping. Other harnesses must be mapped from their current local help output and docs before use.

Philosophy

This screenshot captures the workflow philosophy: plan, fan out, verify, integrate; changelog first, merge back last; use interactive workers when steering is needed and deterministic loops when backups, conditions, and logs need repeatable execution.

Quick Get Started

Clone the repo and copy the skill into the skill directory used by your agent harness. For a project-local install:

git clone https://github.com/TheAhmadOsman/parallel-agent-worktree-skill.git
mkdir -p .agents/skills
cp -R parallel-agent-worktree-skill .agents/skills/parallel-agent-worktree-skill

For a user-level install, copy it into your local skill root, for example:

mkdir -p ~/.codex/skills
cp -R parallel-agent-worktree-skill ~/.codex/skills/parallel-agent-worktree-skill
mkdir -p ~/.claude/skills
cp -R parallel-agent-worktree-skill ~/.claude/skills/parallel-agent-worktree-skill

Then give this prompt to your local agent:

Install and use the parallel-agent-worktree-skill from this repo.

First, read SKILL.md and README.md. Treat the workflow as experimental and do not
run destructive commands without explicit review. Confirm that git, tmux, uv,
Python 3.12+, bash, and my target agent CLI are available.

If my target agent CLI is Kimi, use the included Kimi sample mapping.
If my target agent CLI is not Kimi, convert the skill before use: run `<target-agent-cli> --help`
and any available version/config/help commands, inspect local docs, read
references/harness-portability.md and references/harness-conversion.md, create a
harness mapping JSON, run scripts/convert_harness.py into a converted skill
directory, then update README, SKILL.md, references, examples, helper scripts,
tests, poster copy, validation commands, and any generated-loop behavior for the
target harness. Do not assume Kimi flags work for Codex CLI, Claude Code, OpenCode,
Droid Factory, Pi, or any other CLI.

For my actual task: <describe the task here>.

Plan independent worker tasks, create one git worktree per worker, require every
worker to update the repo-standard changelog or write a unique changelog fragment,
run workers through interactive tmux sessions or deterministic Python/Bash loops as
appropriate, review diffs before merge, merge accepted work back into the branch
that was checked out before fan-out, run final validation, report anything missing
or blocked, and clean up safe worker sessions, worktrees, and branches.

Finish with:
› Let's unit test and integerate test comprehensively and extensively covering any
and all things + any and all possible edge cases.

What This Is

This skill captures a generic workflow for turning a large request into bounded parallel agent tasks using CLI agent harnesses. The helper scripts are generic and the process is intentionally harness-agnostic. The bundled examples cover Kimi CLI as the default sample harness and Codex as a sample conversion target.

• Interactive worker mode: spawn one CLI-agent worker per task in tmux, each inside its own git worktree, then steer workers with follow-up prompts. Configure the harness with --agent-cli and --agent-args.
• Deterministic loop mode: render a Bash or Python script from JSON, run preflight and backup gates, launch non-interactive CLI-agent workers, log every artifact, and leave integration to a review step. Configure non-interactive execution through the JSON agent block.

The skill is intentionally conservative: it treats agent output as untrusted until diffs and tests have been reviewed.

It also treats release notes as part of the work. Every parallel worker must update the repo-standard changelog or produce a per-worker changelog fragment, and the coordinator must reconcile those entries before the final merge. Accepted work should finish merged into the branch that was checked out when the run started; if that is blocked, the coordinator leaves a clear report with the branch names, blocker, current state, validation status, and exact next commands.

Contents

parallel-agent-worktree-skill/
├── SKILL.md
├── README.md
├── LICENSE
├── pyproject.toml
├── Makefile
├── uv.lock
├── examples/
│   ├── harness-codex.json
│   ├── harness-template.json
│   └── self-hosted-upgrade.json
├── references/
│   ├── implementation-log.md
│   ├── harness-portability.md
│   ├── harness-conversion.md
│   └── deterministic-loops.md
├── scripts/
│   ├── convert_harness.py
│   ├── agent_workers.py
│   ├── render_worker_loop.py
│   └── self_test.py
├── tests/
│   ├── conftest.py
│   ├── test_convert_harness.py
│   ├── test_agent_workers.py
│   ├── test_render_worker_loop.py
│   └── test_skill_package.py
└── poster/
    ├── index.html
    └── screenshot.png

Requirements

• uv: recommended runner for helper scripts, tests, and validation in this repo. The standalone package includes uv.lock so validation uses a reproducible dev toolchain unless you deliberately refresh it.
• Python 3.12+: required by the helper scripts.
• git: required for branches, commits, diffs, and git worktree.
• tmux: required for interactive worker mode.
• Agent harness CLI: any authenticated CLI that can run in the current worktree. The bundled sample plan requires Kimi Code CLI: kimi or kimi-cli. For Codex CLI, Claude Code, OpenCode, Droid Factory, Pi, or any other local harness, first ask the parent agent to convert this skill by inspecting that harness' current --help output and local docs.
• bash: required for generated Bash loops and shell-based preflight/backup steps.
• A git repository with a branch suitable for git worktree add.
• Optional infrastructure tools when used by a plan: Docker, Docker Compose, LXC, virsh, ssh, database dump clients, ZFS/Btrfs/LVM/restic/borg tools, cloud CLIs, or other backup and deployment utilities.
• Optional timeout: generated Bash loops use it when available; generated Python loops enforce per-worker timeouts internally.

In this repository, run helper scripts with uv run python.

Install

Project-level install:

mkdir -p .agents/skills
cp -R parallel-agent-worktree-skill .agents/skills/parallel-agent-worktree-skill

User-level install:

mkdir -p ~/.codex/skills
cp -R parallel-agent-worktree-skill ~/.codex/skills/parallel-agent-worktree-skill
mkdir -p ~/.claude/skills
cp -R parallel-agent-worktree-skill ~/.claude/skills/parallel-agent-worktree-skill

Codex, Claude Code, and similar harnesses can load skills from user-level skill directories such as ~/.codex/skills or ~/.claude/skills. Kimi Code CLI is used by the bundled sample plan and can also be pointed at a custom skill root:

kimi --skills-dir /path/to/skills

Claude Code supports additional frontmatter such as disable-model-invocation for manual-only skills. This package does not ship that Claude-specific key because the local cross-harness validator used here accepts the open skill keys only. If you want Claude Code to require explicit /parallel-agent-worktree-skill invocation, add that key in your local copy after validation.

Use The Skill

Invoke it directly:

/skill:parallel-agent-worktree-skill implement this feature by splitting safe work across parallel agents

Or let the agent discover it when a task involves parallel CLI-agent workers, git worktrees, harness conversion, deterministic worker loops, backup gates, changelog fragments, or review-gated integration.

Interactive Worker Mode

Use this when the plan may need steering.

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 kimi \
  --agent-args "--yolo"

Useful commands:

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/api-tests-followup.prompt
uv run python .agents/skills/parallel-agent-worktree-skill/scripts/agent_workers.py cleanup api-tests --branch-delete

Worker branches and worktrees default to the task name. Tmux sessions use the agent-worker- prefix unless --session-prefix is set.

Each worker prompt should include the changelog path or fragment convention for that task. If a single CHANGELOG.md would force every worker to edit the same lines, have workers write unique fragments under .worker-runs/changelog/<task>.md or the repo's standard fragment directory, then fold them into the canonical changelog during integration.

Deterministic Loop Mode

Use this when workers should be generated from conditions, inventory, or backup status. This is the better path for self-hosted service upgrades, LXC/Docker/VM maintenance, database changes, fleet edits, and other runs where a failed backup must stop every worker.

Render Python:

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

Render Bash:

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

Dry run:

DRY_RUN=1 /tmp/run-agent-workers.py
DRY_RUN=1 /tmp/run-agent-workers.sh

Run with stable paths:

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

Generated loops write prompts, agent logs, verification logs, manifests, and rollback notes under .worker-runs/<run-id>/ by default. In this example, task agent logs are named agent.log.

JSON Plan Fields

• run_name: name used in the run id.
• repo: repository root or a path inside it.
• base: base ref for new worker branches.
• worktree_root: optional worktree parent. Empty means <repo>.worktrees.
• max_parallel: worker concurrency.
• agent.cli: executable name for the selected harness.
• agent.work_dir_arg: optional worktree flag inserted before the worktree path. Use an empty string for harnesses that rely on current working directory only.
• agent.args: non-interactive harness arguments.
• agent.prompt_mode: prompt delivery mode for generated loops: stdin, argument, or file.
• agent.prompt_arg: optional flag inserted before the prompt text or prompt file path when agent.prompt_mode is argument or file.
• agent.log_name: per-task agent output file name,