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, default agent.log.
• agent.timeout_seconds: per-worker timeout in generated Python.
• preflight: commands that must pass before backups and tasks.
• backups: commands that must pass before tasks when their conditions are true.
• tasks: worker definitions. Each task needs exactly one of prompt or prompt_file.
• verify: per-task commands executed from that task's worktree.
• postflight: commands run after all tasks pass.
• rollback: commands recorded into rollback.sh if a task fails.

See references/deterministic-loops.md for backup patterns, condition examples, concurrency rules, and edge cases.

Architecture

• SKILL.md: compact runtime workflow for agents. It stays focused on when to fan out, how to prompt workers, how to verify, how to merge, and how to clean up.
• scripts/agent_workers.py: interactive tmux worktree worker manager. It is generic and takes --agent-cli, --agent-args, and --session-prefix.
• scripts/render_worker_loop.py: deterministic Python/Bash loop renderer. It reads the JSON agent block and emits auditable runners with preflight, backup, concurrency, log, rollback, and verification behavior.
• scripts/convert_harness.py: first-pass package specializer for a target harness. It renames helper files, rewrites defaults, copies docs/tests/examples, and writes a conversion report for mandatory human or agent review.
• scripts/self_test.py: dependency-light package self-test for users who do not want to install pytest before checking a downloaded skill.
• tests/: primary portable test suite for a standalone repo. These tests avoid imports from any host project.
• Host repo adapter test: only checks that the host skill parser discovers this package while it is embedded inside another repository.

Harness Portability Contract

This package does not claim that every agent CLI has Kimi-compatible syntax. The default examples are made for Kimi CLI because that was the original working setup. For every other harness, the parent agent must resolve the target command surface at runtime before using the skill:

• Run the target executable's current help and version commands.
• Inspect local target-harness docs, config, auth state, permissions, and sandbox policy.
• Decide whether the harness supports interactive tmux use, non-interactive use, or both.
• Map prompt delivery explicitly: stdin, prompt argument, prompt file, or unsupported.
• Map worktree execution explicitly: a work-dir flag or running from the worktree cwd.
• Map approval, sandbox, network, model, resume/session, logging, exit-code, and cleanup behavior.
• Fill a harness mapping JSON, run scripts/convert_harness.py, then patch and test the converted output before publishing or using it.

If the target harness cannot run safely in parallel, cannot receive prompts deterministically, shares a single mutable session lock, or has unclear approval bypass semantics, do not use deterministic parallel loops. Use interactive workers with manual approval, reduce max_parallel to 1, write a wrapper script that normalizes the interface, or stop and report the blocker.

See references/harness-portability.md for the full runtime mapping checklist.

Tool Mention Justification

• Kimi appears only because examples/self-hosted-upgrade.json is the bundled sample harness mapping and the default script constants mirror that sample. It is not part of the core architecture; pass --agent-cli, edit the agent JSON block, or run scripts/convert_harness.py to use another harness.
• Codex appears only as a sample conversion target in examples/harness-codex.json, converter tests, self-tests, and documentation showing that the generic package can be specialized for a different CLI.
• uv, pytest, ruff, pyright, ty, and make appear as validation tooling for the standalone package. uv is the preferred runner because it gives repeatable project-local commands without requiring global installs.
• tmux, git, and bash are runtime requirements for the workflow: tmux for interactive steering, git worktrees for isolation, and bash for generated shell loops and preflight/backup commands.

Convert To Another Agent Harness

You can ask any capable local parent agent to specialize this generic package for your favorite agent harness. The agent should inspect the target harness' current help output, map the equivalent commands, and update this skill recursively: README, SKILL.md, references, examples, helper scripts, generated-loop behavior, tests, poster copy, and validation commands. Do this for Codex CLI, Claude Code, OpenCode, Droid Factory, Pi, or any other harness instead of assuming Kimi CLI flags work.

Runtime prompt:

Use the parallel-agent-worktree-skill skill as the source. Convert it to <target harness>.
First run `<target harness> --help` and inspect any existing docs or config in this repo.
Create a harness mapping JSON, run scripts/convert_harness.py into a new skill directory,
then comprehensively update README, SKILL.md, references, examples, scripts, tests, and
poster copy with the target harness equivalents. Cover interactive mode,
non-interactive mode, approval bypass, work-dir semantics, prompt delivery mode,
logging, cleanup, failure modes, auth requirements, sandboxing, and edge cases. Run
validation and report anything that still needs target-specific manual confirmation.
Finish with:
› Let's unit test and integerate test comprehensively and extensively covering any
and all things + any and all possible edge cases.

Deterministic first-pass converter:

uv run python .agents/skills/parallel-agent-worktree-skill/scripts/convert_harness.py \
  --config .agents/skills/parallel-agent-worktree-skill/examples/harness-codex.json \
  --output-dir /tmp/codex-worker

The converter copies the skill, renames the worker helper, rewrites generic defaults to target-harness defaults, and writes CONVERSION_REPORT.md. An agent must still review the converted output against the real target harness because approval flags, prompt delivery, sandboxing, session state, auth, and work-dir semantics differ across agent CLIs. See references/harness-conversion.md.

Final stage / execution:

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

Review And Integration

Do not merge based on a worker summary.

Final integration target: the branch checked out before spawning workers. Capture it as INTEGRATION_BRANCH="$(git branch --show-current)" during preflight and merge accepted work back into that branch unless a concrete blocker prevents it.

For every worker:

git -C <worker-worktree> status --short
git -C <worker-worktree> log --oneline <base>..HEAD
git -C <worker-worktree> diff --stat <base>...HEAD
git -C <worker-worktree> diff <base>...HEAD

Then run targeted verification in the worker worktree. Integrate only reviewed work:

git switch "$INTEGRATION_BRANCH"
git merge --no-ff <worker-branch>
git cherry-pick <commit-sha>

Before reporting completion, reconcile every accepted worker changelog entry into the repo-standard changelog/release notes, run the repository's final checks, and remove only the worker sessions, worktrees, and branches that are safe to delete.

If accepted work cannot be merged back into INTEGRATION_BRANCH, report that clearly: include the original branch, current branch, worker/integration branches that contain accepted work, the blocker, completed and missing items, validation already run, and the exact next commands needed to resume safely.

Screenshot Page

Open poster/index.html in a browser for a square, screenshot-ready summary page that explains the skill. The README embeds poster/screenshot.png as the publishable screenshot of the workflow philosophy.

Launch Tweet

Earlier today in the Space I tried to explain how I run parallel agents non-interactively: either ask the main agent to spin up workers (Kimi sample plan), or use deterministic Python/Bash loops with backups in separate git worktrees. Turned it into a Skill for you guys.

Implementation Log

See references/implementation-log.md for the current implementation and validation log.

Validation

Standalone package validation:

uv run ruff check .
uv run ruff format --check .
uv run pyright scripts tests
uv run ty check scripts tests
uv run python -m py_compile scripts/*.py
uv run pytest -q
uv run python scripts/self_test.py
make validate

The scripts/self_test.py path is the no-pytest fallback. It validates frontmatter, required files, script syntax, help commands, JSON examples, poster copy, and the sample Codex conversion with generated Python/Bash script checks.

While this skill is embedded inside another development repo, the root tests/test_parallel_agent_worktree_skill.py file is intentionally only an adapter check: discoverability from .agents/skills, host parser acceptance, and the description expected by this harness. Portable behavior belongs in this skill package's own tests/ directory.

Do not publish host-repo adapter tests in the standalone repo. They are useful only while this package is incubated inside another harness repository.

The two broad host-suite failures documented in the implementation log are not part of this standalone skill. Fix them in the host repo if you need a green host suite; do not copy those tests or failure notes into a published skill package.

From the embedding host repository:

uv run python -m py_compile .agents/skills/parallel-agent-worktree-skill/scripts/agent_workers.py
uv run python -m py_compile .agents/skills/parallel-agent-worktree-skill/scripts/render_worker_loop.py
uv run python -m py_compile .agents/skills/parallel-agent-worktree-skill/scripts/convert_harness.py
uv run python -m py_compile .agents/skills/parallel-agent-worktree-skill/scripts/self_test.py
uv run ruff check .agents/skills/parallel-agent-worktree-skill/scripts .agents/skills/parallel-agent-worktree-skill/tests
uv run ruff format --check .agents/skills/parallel-agent-worktree-skill/scripts .agents/skills/parallel-agent-worktree-skill/tests
uv run pyright tests/test_parallel_agent_worktree_skill.py .agents/skills/parallel-agent-worktree-skill/tests .agents/skills/parallel-agent-worktree-skill/scripts
uv run ty check tests/test_parallel_agent_worktree_skill.py .agents/skills/parallel-agent-worktree-skill/tests .agents/skills/parallel-agent-worktree-skill/scripts
uv run pytest .agents/skills/parallel-agent-worktree-skill/tests -q
uv run pytest tests/test_parallel_agent_worktree_skill.py -q
uv run python .agents/skills/parallel-agent-worktree-skill/scripts/self_test.py
uv run python .agents/skills/parallel-agent-worktree-skill/scripts/agent_workers.py --help
uv run python .agents/skills/parallel-agent-worktree-skill/scripts/render_worker_loop.py --help
uv run python .agents/skills/parallel-agent-worktree-skill/scripts/convert_harness.py --help

To validate generated scripts:

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
uv run python -m py_compile /tmp/run-agent-workers.py

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
bash -n /tmp/run-agent-workers.sh

Safety Model

• Workers run in isolated git worktrees.
• Backup and preflight failures stop generated runs before worker launch.
• Rollback commands are recorded, not auto-executed.
• Logs are durable and run-scoped.
• Integration is manual and review-gated.
• Cleanup happens only after accepted work is merged or explicitly discarded.

License

Apache License 2.0. See LICENSE.