@ai-dossier/worktree-pool weekly downloads statistics

@ai-dossier/worktree-pool

Use one portable AI-agent skill across Claude Code, Codex, OpenCode, and MCP-compatible workflows.

@ai-dossier/worktree-pool is for developers and coding-agent teams that need isolated, parallel Git worktrees without repeated setup. It maintains ready-to-use worktrees so issue work can begin in seconds instead of repeating a dependency install and build for every agent.

Part of the ai-dossier ecosystem: use @ai-dossier/sched to orchestrate agents, @ai-dossier/cli to run workflows, and the ai-dossier project for the complete platform.

Works with pnpm, yarn, bun and npm — the package manager, lockfile and build command are detected from the project, or pinned explicitly in .worktree-pool.json.

Install

Or use directly with npx:

Requires Node.js >= 20.0.0.

Commands

| Command | Description |

| worktree-pool status [--json] | Show pool inventory (warm/assigned/broken counts); --json prints the whole inventory, including per-entry status, for callers. Not strictly read-only: first repairs stale worktree links of pool entries (git metadata only) | | worktree-pool replenish [--count N] | Pre-warm spares up to target count, after repairing stale worktree links | | worktree-pool claim --issue N --branch B | Claim a warm worktree, print path (repairs stale worktree links first); exits non-zero, renaming nothing, if a folder named after the branch already exists | | worktree-pool return --path P [--json] | Return worktree to pool for reuse; kills any process still running out of it first, self-checks on success, and on failure marks the entry broken and exits non-zero naming the step | | worktree-pool refresh | Fetch origin + rebuild in all warm worktrees | | worktree-pool gc [--dry-run] [--yes] | Remove stale/orphaned pool worktrees (never anything else), killing any process still running out of one first | | worktree-pool reap [--older-than H] [--dry-run] [--yes] | Kill processes orphaned by a removed or non-assigned worktree, at least H hours old (default 24) — the sweep for what return/gc already missed | | worktree-pool init | Configure pool directory for this project | | worktree-pool detect [dir] | Print the detected package-manager env as JSON |

Quick Start

How It Works

1. Replenish creates worktrees from base_ref (default origin/main) on temp branches, then runs the warm commands (install + build) 2. Claim renames a warm worktree, switches to your feature branch — instant setup (~2s) 3. Return first kills any process still running out of the worktree (see Process cleanup below), then recycles it back to pool on a fresh temp branch, then verifies the result against reality — the entry really reads warm, no tracked file is dirty, and the new pool/spare-* branch is really checked out — before reporting success. A failure at any step leaves the entry broken (never assigned, never a falsely-warm spare), leaves the directory on disk, and exits non-zero naming the step 4. GC kills any process still running out of a worktree it is about to touch, then removes broken entries and stale entries (>72h) and reconciles disk state vs pool state — only for worktrees the pool created (see Sharing the pool directory)

Claim and return only re-run the warm commands when the project's lockfile changed between the worktree's base commit and base_ref — otherwise the existing node_modules and build output are reused.

Process cleanup

A dev server, jest run, or vite server started inside a worktree by a verification step does not stop on its own when the worktree it was started in is recycled or removed. Left unaddressed, these outlive the worktree, the branch and the issue that spawned them — a real sweep on a dev host found 13 such processes across four merged worktrees, one holding open connections to a shared test database for 10 days.

• return and gc kill first. Before recycling or removing a worktree, both send SIGTERM to every process whose cwd or command line is rooted under that exact worktree path, wait up to 5 seconds, then SIGKILL anything still alive. The kill is scoped to that one worktree — a sibling worktree sharing the same pool directory is never touched — and the killed pids are printed and included in return --json's killedProcesses / gc's killedProcesses field. • reap is the sweep for what got away — a process from a worktree that was removed by something other than this tool, or that is otherwise no longer assigned:

reap never touches a worktree the pool did not create (the same ownership rule gc uses), and never a currently-registered worktree in an active pool status (assigned, recycling, creating, warming) — that is active work, not an orphan, and includes a return that is mid-flight but has not reached its own kill step yet. Run it on a schedule (a host cron/timer calling reap --older-than 24 --yes), not per-issue; return/gc already handle the common case at the moment a worktree changes hands. • The Linux discovery path (/proc/*/cwd + /proc/*/cmdline) always excludes the invoking process and its whole parent chain, so running return --path from a shell whose own cwd is inside cannot kill its own invoker. The ps-based fallback (non-Linux) can only exclude the invoking process itself — an ancestor's cwd/ppid is not determinable without /proc. return, gc, and reap all print skipped self/ancestors: whenever a match was excluded this way — routinely true for return, since its own command line contains the worktree path it was given. • return and gc refuse an unsafe kill root outright rather than silently skipping it: an empty path, the filesystem root, the git root itself, or anything outside the pool directory. Every current call site already derives a safe path, so this should never fire — it exists so a future one cannot skip the check.

Pool State

Pool state is stored in worktrees/.pool-state.json (automatically gitignored). Each worktree transitions through:

A broken entry is never handed out — claim only ever selects warm.…

Description from the npm listing.