Paniolo Harness · Worktree slots

A warm checkout for every agent.

Run several coding agents on one repository without collisions or cold installs. Paniolo keeps a pool of pre-warmed Git worktrees, hands each agent its own slot, and takes the slot back only once the work is safe.

# See who holds what paniolo worktree pool status --repo my-app # Take an idle, prepared slot on a new topic branch paniolo worktree pool claim --repo my-app --owner <session-id> --branch feat/topic # Hand it back once the branch is pushed or merged paniolo worktree pool release --repo my-app --path <slot> --owner <session-id>
The cold-start tax

Fresh worktrees start from zero.

A new worktree is cheap for Git and expensive for everything else: dependencies, generated code, build caches, local certificates. Every agent task that starts cold pays for all of it again. A prepared slot keeps it.

115 s → 0.3 s

Dependency install in a fresh worktree versus a prepared slot.

85 s → 48 s

First typecheck once generated code and caches already exist.

152 s saved

Before an agent writes its first line, on every task that lands on a warm slot.

Measured on a production React and Workers app on native Windows with a populated pnpm store. These are single runs on one project, not a benchmark; your savings depend on your stack.

How it works

Claim. Work. Release.

Each agent session claims a slot under its own owner ID. The pool records every claim in one locked state file, so two agents can never be handed the same checkout.

Claim

An idle slot, ready to go

The claim reserves an idle, clean slot, fetches your base branch, reruns preparation steps only when their inputs or tool versions changed, and creates the agent's topic branch.

Work

Everything stays warm

Dependencies, build output, generated packages, and local HTTPS certificates live in the slot between tasks. The agent works in a normal Git worktree with its own branch.

Release

Back to the pool, caches intact

Release checks that the checkout is clean and the branch is pushed, then returns the slot to idle, detached at the base, with its caches kept for the next agent.

Maintain

Refresh and clean idle slots

refresh moves idle slots to the latest base and reprepares them. cleanup previews, then prunes stale build outputs and merged branches within fixed bounds.

Safe by default

Fast, without losing work.

Shared checkouts are only worth it if no agent can clobber another's work. The pool refuses rather than guesses.

No takeovers

A claimed slot belongs to its owner. The pool never resets, cleans, or reassigns another session's checkout, branch, or files.

Work is never discarded

Release refuses a dirty checkout or unpushed commits. Nothing is force-reset, and cleanup never touches a dirty tree.

Trusted preparation

Steps run as argument lists with no shell interpolation. Inputs and tool versions are fingerprinted, and required outputs are checked before a slot counts as ready.

Visible failures

A failed step leaves the slot marked failed, with the phase and path that broke, instead of half-ready and silently reused.

Windows-aware

When a running process holds a file, the pool names the file and the Windows error. It never kills processes or schedules deletes on reboot.

Git-locked slots

Slots are locked Git worktrees, so git worktree prune cannot sweep them away along with their warm caches.

Configure once

Declare the pool in your harness.

Each pool lives under its repository in the harness paniolo.config.json, so your product repository carries no agent-specific files. init previews and then creates the slots; adopt imports worktrees you already have.

"my-app": { "path": "repos/my-app", "worktreePool": { "root": "repos", "slots": [".dev-worker-my-app-01", ".dev-worker-my-app-02"], "baseRef": "origin/main", "hostOs": "windows", "minFreeBytes": 1073741824, "preparation": [{ "name": "pnpm", "program": "pnpm.cmd", "args": ["install", "--frozen-lockfile"], "versionPrograms": ["node"], "inputs": ["pnpm-lock.yaml", "package.json"], "requiredOutputs": ["node_modules/.modules.yaml"], "timeoutSeconds": 900 }] } }
New in 0.5.100

Spot abandoned claims at a glance.

Agents crash, sessions end, and claims get left behind. Status makes that visible, and nothing frees a claim unless its work is provably safe.

Stale claims

Claim age and last activity

Status shows when each claim began and the time of its newest commit or file change. --stale-hours 24 lists only claims with no activity for a day.

Resume

Pick up an existing branch

claim --from origin/feature prepares a slot on a branch that already exists, such as an open pull request, and sets it to track the remote.

Recovery

Failed claims come back

A claim that broke before creating its branch returns to the pool when its owner retries or an operator runs refresh --retry-failed, but only if the checkout is still clean.

Side-by-side review

Every slot gets its own ports

Declare slotPorts once and slot 7 serves on 5107, slot 3 on 5103. Review five agents' branches in five tabs, and run e2e on separate ports without killing anyone's dev server.

Clear reasons

Unusable slots say why

A checkout owned by another account is reported by name instead of failing the command, and status lists worktrees under the pool root that the config does not manage.

Since 0.5.101

Free the safe ones

reclaim releases another owner's stale claim, but only when its branch is merged or pushed and the tree is clean. Anything else is refused with what would be lost: "1 unpushed commit on codex/topic."

paniolo worktree pool status --repo my-app --stale-hours 24 { "slots": [{ "path": "repos/.dev-worker-my-app-02", "state": "claimed", "owner": "codex-sessio", "branch": "codex/topic", "clean": false, "unavailableReason": "worktree is dirty", "claimedAt": 1793900000, "lastActivityAt": 1793912345, "inactiveSeconds": 162000 }] }
The research behind the pool

Why slots, and why one agent.

The workload case for warm slots starts with where agent sessions actually spend time. The session-level FreeInference analysis (roughly 12,000 sessions, 1.19 million model requests, 1.21 million tool calls across 13 agent harnesses) puts tool execution at 21.7% of session time and user idle at 50.3%; in their simulation, halving tool time bought a 1.38x speedup while halving model generation bought only 1.16x. TraceLab's trace of about 4,300 real Claude Code and Codex sessions shows the same thing from the tail: tool calls over a minute were 4.9% of calls but 92% of tool time. Rare, slow calls own the budget, and a warm second slot is where that blocked time goes.

Nixon, Tian, Zheng, Yang, Gunawi — FreeInference, 2026, systems.seas.harvard.edu/blog/agentic-traces-freeinference · dataset 10.5281/zenodo.23903440 Zhu, Jacob, Ma, Pan, Wang, Krishnamurthy, Kasikci — TraceLab, arXiv 2026, arxiv.org/abs/2606.30560

The "one agent" half has the sharper evidence. CooperBench (Stanford and SAP) gave pairs of agents 652 coding tasks across 12 open-source libraries: the pairs succeeded about 30% less often than the same agents doing both tasks alone, communication reduced textual merge conflicts without improving cooperation, and the largest failure category at 29.7% was divergent architecture, meaning incompatible decisions that lost work even under a clean merge. Cognition's writing lands in the same place: their 2026 follow-up narrows what survives multi-agent to patterns where intelligence is parallel but writes stay single-threaded. That is the slot model's shape: several waiting hands, one deciding head.

Khatua et al. — CooperBench, arXiv 2026, arxiv.org/abs/2601.13295 Yan — Cognition, 2025 and 2026, cognition.com/blog/dont-build-multi-agents · cognition.com/blog/multi-agents-working

Two cautions the design takes seriously come from further back. Brun, Holmes, Ernst, and Notkin's FSE 2011 study of 5,355 merges found a third of the 399 merges version control reported as clean still broke the build or tests, which is why a slot's branch gets rebased once and gated once instead of trusted on a green merge. And the practitioner playbooks converge on the same shape we use: the Stackness parallel-worktree guide prescribes per-worktree ports and databases, two to four worktrees as the practical range, and a pairwise git merge-tree trial merge before either branch lands. Their coordination layer is still peers passing intent files; the evidence above is why ours is a single context.

Brun, Holmes, Ernst, Notkin — FSE 2011, dl.acm.org/doi/10.1145/2025113.2025139 Stackness, Oct 2026 — stackness.dev/blog/running-coding-agents-in-parallel-git-worktrees-and-the-merge-check

Slots isolate files and caches; they do not schedule the machine. For the other half of the problem, host queues keep heavy gates from colliding on shared hardware. More of the research behind the Harness lives on the harness research page, and every digested paper is listed in the paper index.

Honest answers

Before you ask

Which coding agents can use it?
Any agent that can run a command: Claude Code, Codex, Cursor, Devin, Copilot, or a script. Each session claims under its own owner ID. A Codex session-start hook can show the current claims, and status gives the live view.
Is this a replacement for git worktree?
No. Slots are ordinary Git worktrees. Paniolo adds the ownership, preparation, and safety checks around them, so you can always inspect a slot with plain Git.
What about my own checkout?
It stays yours. Agents work in slots, not in your main checkout. If an agent must use the primary checkout, an opt-in advisory lease records who is there, though it cannot stop a human edit.
Should my harness repository get slots too?
No. A harness that contains its satellite repositories is validated against them, and a worktree of it has an empty repos/, so its gates check nothing real. Keep one checkout of the harness, slot 00, and let agents take turns there on topic branches, handing it back on main. The slots are for the repositories inside it.
Does it work on Windows?
Yes, natively, and on Linux. Each pool declares its host OS; a Windows slot never falls back to WSL, so its caches stay valid for the toolchain that built them.
Will it free a slot an agent abandoned?
Not on its own. Taking over a claim could destroy someone's unpushed work, so the pool only reports likely abandoned claims. A person decides, saves the work, and releases the slot.
What does it cost?
Worktree slots are part of the Paniolo CLI and need no account. See pricing for the Harness plans.

Give every agent its own lane.

paniolo worktree pool init --repo my-app

Read the docs