Two months ago the first four were 13 to 17 seconds each. What changed is not that the work got faster. Most of it did not.

The numbers before

Measured then on the same project, which had 66 worktrees at the time:

Look at the first row against the second. The recompute got 23% cheaper, which is a rounding error you would never feel. The read got 400 times cheaper. Those two lines are the whole thesis.

You cannot make the walk fast. You can stop putting it on the read.

Listing 95 worktrees means asking git 95 times what changed, and git status --porcelain costs 120 ms in that repository. That is 11 seconds of unavoidable work, and no amount of shell tuning removes it.

So the read stopped doing it:

• a cached list is served immediately, even when stale, with a note on stderr saying how old it is;
• the recompute runs in a detached background process that rewrites the cache for the next read;
• --refresh stays synchronous, because when you ask for fresh you are saying you will wait;
• the first run ever is synchronous too, since there is nothing to serve.

That is the trade, stated plainly: you get milliseconds and you accept that the answer may be a minute old. For “what is dirty across my worktrees” that is obviously fine. For “did my last command take effect” it is not, which is why writing metadata invalidates the cache instead of waiting for it to expire.

The instrument that lied

A serial trace blamed the wrong thing. Running the list under bash -x and counting external commands produced a satisfying culprit: 752 tr forks per list. It was real, and it was nearly free. Forks are cheap and the trace flattened a parallel loop into a serial one, so the shape of the cost was gone before I read it.

What found the real cost was comparing CPU to wall clock. /usr/bin/time -l reported 79 seconds of system time for 14 seconds of wall, which says the work is spread across cores and dominated by syscalls, not by process creation. That pointed at the filesystem, and from there at two things: the status walk running twice per row (once to render, once to decide merge status) and a git fetch costing 3 seconds on every list that missed the cache.

The same lesson arrived a second time from a different direction, when a commit message credited the startup win to the change that shipped alongside the one that actually earned it. Re-measuring meant extracting each commit with git archive and running all of them against identical state, and the credit moved. That one has its own post, including the part where the “faster” format was twice as slow on the cold path.

What actually made the recompute cheaper

Not one big thing. Six small ones, each removing repeated work rather than optimising it:

• the status walk runs once per row instead of twice, with the merge check reusing the porcelain output already captured;
• status symbols come from parsing one git status --porcelain in bash, instead of three git commands piped through wc and tr (there go the 752 forks, worth about nothing, removed anyway);
• divergence uses one --left-right --count instead of two calls;
• commit hash and age share a single git log;
• column width for ASCII answers without forking;
• the row pool became a rolling window sized to the core count instead of a batch-of-4 barrier, so a slow row no longer stalls three idle workers.

The dead end, since it was the obvious idea: widening the pool past 8 on a 12-core machine made it slower, 13.6 s against 12.7 s. git status is already multi-threaded and the contention is in the filesystem, so more workers just fight each other.

The bug that only appeared because of the fix

Serving stale caches needed tests, and the tests found something the feature introduced: list --refresh deleted the cache before regenerating it. For the seconds the recompute took, a concurrent reader saw no cache file at all, and got the slow path or an empty answer. Cache writes are now a temp file plus a rename, which is atomic, and refresh overwrites rather than unlinking.

This is the ordinary tax on caching. The moment a read can be served from a file, every writer has to think about who is reading it mid-write.

Still slow, found while writing this

pwt servers is 3 seconds today, against the 1.9 s it measured at 66 worktrees: it grew with the project, which is the signature of work that scales linearly with rows. I only looked at why because the table above embarrassed me. Same method as before, CPU against wall:

3.14 real   1.32 user   1.62 sys

CPU almost equals wall, which means one core is busy the whole time: it is serial. Counting its externals: 65 git invocations, one lsof, one ps. The snapshot work already landed there (one lsof for the whole machine instead of one per worktree, which is what took it from 11.7 s to 1.9 s), but the git calls never joined the parallel pool that pwt list uses.

So the fix is not fewer git calls, it is the same rolling pool applied to a second command. Measured, not guessed, which is the only part of this I would insist on.

Where the floor is

The cached porcelain read is 245 ms, and 62 ms of that is process startup. Tracing it shows five external commands in the whole run. The remaining time is bash walking 95 records and escaping their fields, about 2 ms per record with no forks at all.

That is worth knowing before you optimise a shell tool further: once you have stopped forking, what is left is the interpreter, and the only remaining moves are doing less work per record or not being bash. There is no third option hiding in there.

If you are auditing your own CLI

1. Time every command, not the one that annoys you. The table is the deliverable. Mine had four entries over ten seconds and I had normalised all of them.
2. Compare CPU to wall before profiling anything. Wall much greater than CPU means waiting (network, locks). CPU close to wall means serial. CPU far above wall means parallel and syscall-heavy. Each points somewhere different, and it costs one command.
3. Distrust fork counts from a serial trace. They are easy to collect and they flatten exactly the structure you are trying to measure.
4. Re-measure attributions, especially your own commit messages. Extract the commits, run them against identical state, and let the numbers assign the credit.
5. Ask whether the work belongs on the read path at all. That question beat every optimisation in this list by two orders of magnitude.

brew install jonasporto/pwt/pwt. pwt list is served from cache and tells you its age; pwt list --refresh is the one that waits (reference). If you script against it, --porcelain carries generated_at so you can decide for yourself whether the document is fresh enough.

Read the right-hand column again. Every one of them solved creation, which is the easy half, and none of them defined what makes a checkout ready. The same complaint follows each release: a fresh worktree has no .env, no dependencies, and a dev server that wants a port another worktree already took. Only one of these tools has an event you can hang setup on, and using it means taking over creation.

So configuring setup per tool means maintaining the same knowledge in four formats, three of which do not exist yet. The alternative is to define “a ready worktree” once, in the repository, and make every tool land on it. There are exactly three ways to do that, and they differ in how much cooperation they need from the tool.

Layer 1: instruct (portable, advisory)

Every agent reads a project instruction file. Put the rule there:

Worktrees in this repository are created with `pwt create <name>`, never
with `git worktree add`: creation allocates a port, writes metadata and
runs the project's setup hook. A worktree that already exists is
registered with `pwt adopt`.

One wrinkle worth knowing: Claude Code does not read AGENTS.md, the file the other CLIs standardised on. If you keep one, import it rather than duplicating it:

<!-- CLAUDE.md -->
@AGENTS.md

This layer is portable and free, and it is advice. An agent under pressure will still reach for git worktree add, because that is what its training says worktrees are.

Layer 2: enforce (mechanical, per tool)

Claude Code can refuse the command outright, in .claude/settings.json (checked in, applies to the team) or .claude/settings.local.json (your machine only):

{ "permissions": { "deny": ["Bash(git worktree add *)"] } }

Two properties make this actually hold. Deny is evaluated before allow, so no broader permission reopens the path. And compound commands are parsed per subcommand, so git status && git worktree add wt is caught too, rather than sneaking through as one string. /permissions shows every active rule and where it came from.

This is the layer that turns a convention into a guarantee, and it exists only for the tools that implement it.

Layer 3: the creation hook (Claude Code)

WorktreeCreate fires when Claude Code makes a worktree: --worktree, subagents with isolation: worktree, background sessions. The contract is narrower than it first looks, and the thread that requested the feature flagged why: your script owns the creation. Exit 0 and git is never called; exit non-zero and the whole thing rolls back.

The input arrives as JSON on stdin, not as arguments:

{ "base_path": "/repo", "worktree_path": "/repo/.claude/worktrees/session-xyz",
  "worktree_name": "session-xyz", "session_id": "abc123" }

So the script creates the checkout where the agent asked for it, and hands the rest over:

#!/usr/bin/env bash
# .claude/hooks/worktree-create.sh
input=$(cat)
base=$(jq -r .base_path     <<<"$input")
wt=$(jq   -r .worktree_path <<<"$input")

git -C "$base" worktree add "$wt" -b "$(basename "$wt")" >&2 || exit 1
pwt --no-input adopt "$wt" >&2 || exit 1    # port, metadata, setup()
exit 0

{ "hooks": { "WorktreeCreate": [ { "matcher": "*", "hooks": [
  { "type": "command", "command": ".claude/hooks/worktree-create.sh" } ] } ] } }

Two details that bite. Everything on stdout is parsed as structured output, so send your progress to stderr. And --no-input closes stdin and sets PWT_AGENT=1, so a setup step that would have asked a question fails loudly instead of hanging a session nobody is watching.

Note which command does the work: adopt, not create. The agent picked the path, usually inside .claude/worktrees/, and adopting records that real path instead of insisting on the project’s own directory. Verified on a checkout outside worktrees_dir: port allocated, setup() run, .env written with the allocated port.

Layer 4: adopt whatever arrives

The other three layers cover the tools that cooperate. This one covers everything else, and it needs no cooperation at all:

pwt adopt          # inside a worktree someone else created
pwt adopt --all    # every unregistered worktree in the directory

That is the fallback for Gemini CLI (which creates worktrees and has no hook to run anything in them), for Grok Build’s eight parallel subagents, for Codex where you did the git worktree add yourself, for a teammate, and for the worktree you made by hand last Tuesday and forgot. It is also the only layer that keeps working when a tool changes its hook format, which they will: three of the four rows above shipped their worktree support this year.

What to actually wire

Layers 1 and 4 give most of the value and depend on nothing: state the rule, and adopt the strays. Add layer 2 for the tool you use most, since it is one line and it converts “please” into “cannot”. Add layer 3 only if you are already using that tool’s worktree flag daily, because you are taking ownership of creation in exchange.

And the honest limit: none of this is worth wiring if your worktrees do not need setup. A repository with no .env, no installable dependencies and no dev server is fine with whatever the agent does on its own. The whole argument for routing creation through one tool is that the values that must differ per worktree have to be derived, and something has to own that derivation. If nothing must differ, nothing needs owning.

brew install jonasporto/pwt/pwt, and the agent-facing guide the rule above refers to is pwt skill, printable into any tool’s skills directory with pwt skill --install.

The ask that follows is always some version of “a central registry and routing for all this”. That sounds like one feature. It is two, at different layers, and every tool solves one and leaves the other, which is why nothing ever feels finished:

• Allocation decides which number a project gets. It is bookkeeping.
• Naming decides what you type in the browser. It is a proxy.

Layer 1 is bookkeeping, and scanning is not it

The registry question is “who owns 8001”. The universal answer, and the one every framework and helper script implements, is to scan: try a port, see if it is bound, take the next one if it is. devenv’s ports.<n>.allocate does a careful version of this, holding ports during evaluation to avoid races.

Scanning has one blind spot, and it is fatal for this scenario: a stopped server still owns its port. Thirty projects on a laptop are not running at once; most are asleep. Every scan looks at a machine where almost nothing is bound and concludes almost everything is free, so two projects get the same number and the collision is deferred to whichever morning you start both.

I had this exact hole in my own tool, which allocated per project and consulted the live machine. Two projects, both configured to start at 8000, nothing running:

$ # project chatapp, then project dashboard
   chatapp    feature-a    8001
   dashboard  feature-b    8001

Both correct by their own logic, both wrong. A port is a machine resource, so the record has to be machine-wide: allocation must consult what every project has already been given, whether or not anything is listening today. After the fix, on the same machine:

$ pwt ports
PORT    PROJECT     WORKTREE      STATUS
8000    chatapp     @             conflict
8000    dashboard   @             conflict
8001    chatapp     feature-a     conflict
8001    dashboard   feature-b     conflict
8002    chatapp     feature-c     -
8003    dashboard   feature-d     -
8004    chatapp     feature-e     -

Two records share a port. Fix with: pwt fix-port <worktree>

New allocations step around every other project’s numbers, and the pre-existing overlaps are reported rather than quietly inherited. That listing is the “central registry for this shit”: one command, every project, plus who is actually listening right now.

The important part is not the tool, it is the shape: a registry is a file you write to when you hand out a port, not a scan you run when you need one. Anything that only scans will keep handing out duplicates to a machine full of sleeping apps.

Repairing an old overlap has one wrinkle, and it decides whether the fix is free. Two patterns exist in the wild:

# Read at runtime: the port is whatever the tool says, today
server() { exec env PORT="$PWT_PORT" mix phx.server; }

# Baked at setup: the number is written into generated files
# .env       DEFAULT_URL=localhost:5001
#            WORKTREE_DB_SUFFIX=_wt5001
# Procfile   rails s -p 5001

Moving a project of the first kind is a metadata edit and nothing else. Moving one of the second kind leaves generated files pointing at the old number until the setup hook runs again, and when a database name is derived from the port, as in that second block, reallocating quietly points the app at a different database. Check which kind you have before repairing a port that something already generated files from.

Repairing an old overlap has one wrinkle worth knowing, and it decides whether the fix is free or not. Two patterns exist in the wild:

# Read at runtime: the port is whatever the tool says, today
server() { exec env PORT="$PWT_PORT" mix phx.server; }

# Baked at setup: the number is written into generated files
# .env         DEFAULT_URL=localhost:5001
#              WORKTREE_DB_SUFFIX=_wt5001
# Procfile     rails s -p 5001

Moving a project of the first kind is a metadata edit and nothing else. Moving one of the second kind means the generated files still point at the old number until the setup hook runs again, and if a database name is derived from the port, as in that second block, reallocating quietly points the app at a different database. Check which kind you have before you fix a port that something already generated files from.

Layer 2 is naming, and it cannot be solved by allocation

Even with a perfect registry you still have the other half of the complaint: you have to remember that the dashboard is 8003. The fixes for that live one layer up, and they are genuinely different tools:

The last row is the one people skip, and it is the right shape when the thing on the other end is not you: an OAuth callback, a webhook, a device on your network. Those store one address and have no opinion about your ports, which is its own post.

Notice that none of these rows allocate anything. A proxy routes a name to a port that something else decided. That is why the two layers keep getting conflated and nothing feels solved: tools that name (portless, Port Zero, Caddy setups) do not stop two apps from claiming 8000, and tools that allocate (devenv, per-project config) do not give you a name worth typing.

The honest scope

For a laptop with dozens of unrelated projects, the registry half is the half that pays: you need the machine to remember what it handed out, and you need to see the map. That is pwt ports, and the allocation behind it, in pwt.

The honest caveat: pwt is a git worktree manager. The port registry is real and now machine-wide, but you get it by registering a project with pwt init, which earns its keep when you also want per-worktree setup, servers and jobs. If all you want is a port broker for 35 loose folders, this is a bigger tool than the problem. What I would keep from it, whatever you use, is the rule: write down the allocation, do not scan for it.

brew install jonasporto/pwt/pwt, then pwt ports (reference).

$ lsof -nP -iTCP:5000 -sTCP:LISTEN
COMMAND         PID   USER  TYPE  NAME
ControlCenter   649  jonas  IPv4  *:5000 (LISTEN)

That is macOS itself: AirPlay Receiver, added in Monterey and enabled silently for anyone who upgraded, with Control Center holding the socket. It takes 7000 as well. Of the 156 listening sockets on this machine, those two are the only ones below 10000 owned by a system daemon, and both belong to that one process.

The Flask documentation states it outright, in the “Address already in use” section: “macOS Monterey and later automatically starts a service that uses port 5000.”

It does not just occupy the port. It answers.

$ curl -i http://127.0.0.1:5000/
HTTP/1.1 403 Forbidden
Content-Length: 0
Server: AirTunes/860.7.1

Both ports answer, both with 403, both identifying as AirTunes. That is the part every write-up about this skips, and the part that causes the expensive failures. A TCP connect succeeds. An HTTP request gets a response. Anything built on “can I reach this port” concludes your server is up.

Whether it collides with you depends on one socket option

This surprised me, so I measured it instead of assuming. Same machine, same daemon on *:5000, four attempts to bind:

Control Center holds the wildcard address. On BSD, and therefore on macOS, a socket with SO_REUSEADDR may bind a specific address while another socket holds the wildcard on the same port. Linux does not allow that. Ruby’s TCPServer sets SO_REUSEADDR for you; a raw Python socket does not.

So “does AirPlay break my dev server” has no single answer. It depends on your language’s socket defaults and on whether you bind localhost or all interfaces. It also means a real server and the daemon can be listening on the same port at the same time, which turns out to matter later.

The errors, when you do collide, measured here rather than copied:

Those are the honest failures. The interesting ones print nothing at all.

Four ways my own tool got this wrong

pwt allocates a port per worktree and reports what is running. Pointed at a machine with AirPlay on, every reporting path was wrong:

$ pwt ports
PORT    PROJECT   WORKTREE   STATUS
5000    app       feat       listening        # nothing is running

$ pwt server wait feat --timeout 600
Ready: feat (port 5000)                       # returned immediately

$ pwt info feat
  Server:  running (PID 649)                  # that is Control Center

And the one I am least proud of:

$ pwt remove feat
Error: Processes detected on port 5000:
  PID 649 (/System/Library/CoreServices/ControlCenter.app/.../ControlCenter)

Options:
  pwt remove feat --kill-port    # Kill port processes

The removal was blocked by a process nobody should be killing, and the suggested way out was kill -9 on Control Center. I found that by writing the test before the fix: run it against the old code and the output reads ✓ Port 5000 freed, right after the signal goes out.

pwt server wait is the one that actually costs you. An agent starts a server, waits for readiness, gets “Ready” instantly, and calls an endpoint that belongs to AirTunes. The 403 comes back and the failure surfaces three steps later, somewhere unrelated to the port.

Why one command got it right and the rest did not

pwt already knew how to tell a system daemon from a dev server. The check existed, correct and complete, in exactly one function, reached by exactly one command: pwt list -v printed [port 5000: system] while everything else printed listening.

That is the general shape of this bug and it deserves a name: a filter that lives in one code path is not a filter, it is a coincidence. Each later occupancy check was written by someone looking at the socket, not at the function three files away that had already solved it. No amount of care prevents that. Only a single callable place does.

What “a system process” means, mechanically

You cannot ask the kernel whether a listener is “yours”. You can ask who owns the pid:

port_pid_is_system() {
    cmd=$(ps -p "$1" -o command= 2>/dev/null) || return 1
    exe="${cmd%% *}"
    case "$exe" in /System/* | /usr/libexec/*) return 0 ;; esac
    case "${exe##*/}" in
        ControlCenter | rapportd | AirPlayXPCHelper | sharingd) return 0 ;;
    esac
    return 1
}

Two decisions in there carry weight.

A port counts as system only when every listener on it is one. This is where the SO_REUSEADDR measurement stops being trivia: a Ruby server really can hold 127.0.0.1:5000 while Control Center holds *:5000. Verified with both running at once, the port reports listening, which is correct, because one of the two listeners is a server you started.

Allocation is unchanged. A system-held port stays unavailable for new worktrees, because you cannot reliably bind what Control Center holds. The whole fix is about what gets reported, never about what gets handed out. Making 5000 allocatable again would have been the obvious next step and the wrong one: it hands a worktree a port whose server may fail to start depending on how that server opens its socket.

Cost: one ps over every listener, once per command, 40ms with 151 of them. Per-port classification instead would be a fork per worktree, which is exactly what a snapshot exists to avoid.

The options, and what each costs

Turn AirPlay Receiver off. System Settings, General, AirDrop & Handoff. It frees both ports, and you lose the ability to AirPlay to that Mac. If you never use it, do this and stop reading.

Move your port. Correct, and more expensive than it looks. On one project here the port is not just a flag: it is written into .env, into the Procfile, and the database name derives from it, so moving the port meant recreating a database. That is the argument for a tool that allocates ports and derives the dependent values, instead of copying a file that already contains a number.

Teach the tool the difference. What I shipped in 0.2.9:

$ pwt ports
PORT    PROJECT   WORKTREE   STATUS
5000    app       feat       system

system: held by a macOS daemon, not by a server of yours.
  AirPlay Receiver takes 5000 and 7000: turn it off in System
  Settings > General > AirDrop & Handoff, or move the port with
  pwt fix-port <worktree>.

pwt server wait now refuses immediately, with the reason, instead of waiting out a ten-minute timeout on a port that can never become yours.

One myth, since it is everywhere

Several popular write-ups claim Flask changed its default port to 5001 on macOS because of this. It did not. The current documentation (3.1.x) still starts the server on http://localhost:5000/ and tells you to disable AirPlay Receiver or pass --port 5001 yourself. Check the docs of whatever you are actually running before trusting a fix you read somewhere, this article included.

The rule underneath

“Something is bound to this port” and “my server is running” are different questions, and most tools answer the first while printing the second. It stays invisible until a daemon you did not start occupies exactly the port your framework defaults to, which on macOS is the default case.

brew install jonasporto/pwt/pwt, then pwt ports (reference) to see every allocation on the machine and who actually holds each one. Ports across many projects are their own post, and per-worktree allocation is here.

This is not a bug in any of those tools. git worktree add checks out tracked files, and everything that makes a checkout runnable is untracked on purpose. The difference from the usual version of this problem is who created the checkout: you did not. Your agent did, so the advice that starts with “when you create the worktree” does not apply.

What the tools give you, and where each stops

.worktreeinclude (Claude Code) copies gitignored files into the new worktree. It is the smallest possible fix and it works for secrets that are identical everywhere. It cannot derive anything: every worktree gets the same file, so the same PORT=3000 and the same DATABASE_URL. Copy a port into three worktrees and two of them will not start.

The WorktreeCreate hook (Claude Code, shipped since the feature request that collected 29 reactions) does run your script when the agent makes a worktree. It is the real answer, with one consequence the feature request thread flagged immediately: your hook is expected to create the worktree itself and print the path. You are not adding setup to Claude’s worktree handling; you are replacing it.

That is fine if you have something that already knows how to create a worktree properly. It is a lot to write from scratch.

Nothing at all is what you get from every other path: a teammate’s git worktree add, another agent tool, claude-squad (whose own issue for this is still open), or the worktree you made by hand last Tuesday.

Measured: what an agent-created worktree is missing

Three worktrees, created the way an agent creates them:

$ git worktree add ../wts/fix-login    -b fix-login
$ git worktree add ../wts/add-search   -b add-search
$ git worktree add ../wts/refactor-api -b refactor-api

fix-login:     .env MISSING
add-search:    .env MISSING
refactor-api:  .env MISSING

Copying .env into each would fix the first failure and create the next one, because all three would then hold PORT=3000.

Adopting what already exists

pwt adopt registers a checkout that someone else created: it allocates a port, writes the metadata, and runs the project’s setup() hook with $PWT_PORT bound. From inside the worktree:

$ pwt adopt
Adopting worktree: agent-feature
  Branch: agent-feature
  Port:   4001

  ✓ Metadata saved
Running Pwtfile (setup)...
  ✓ Copied: .env
  ✓ Pwtfile (setup) completed

$ cat .env
PORT=4001
API_KEY=abc

The copy came from the hook; the 4001 did not. The setup rewrote it from the port pwt had just allocated, which is the difference between copying config and deriving it.

For the pile that accumulated while you were not looking, --all takes the whole directory:

$ pwt adopt --all
Adopting: add-search
Adopting: fix-login
Adopting: refactor-api
Adopted: 3  Skipped (already registered): 0  Failed: 0

fix-login      -> PORT=3002
add-search     -> PORT=3001
refactor-api   -> PORT=3003

Three worktrees, three ports, one command, and the ones already registered are skipped rather than redone.

If you do want the hook

The hook receives a JSON object on stdin (base_path, worktree_path, worktree_name) and owns the creation: exit 0 and git is never called, exit non-zero and the whole thing rolls back. So the script creates the checkout where the agent asked for it, and hands the rest to adopt:

#!/usr/bin/env bash
# .claude/hooks/worktree-create.sh
input=$(cat)
base=$(jq -r .base_path     <<<"$input")
wt=$(jq   -r .worktree_path <<<"$input")

git -C "$base" worktree add "$wt" -b "$(basename "$wt")" >&2 || exit 1
pwt --no-input adopt "$wt" >&2 || exit 1     # port, metadata, setup()
exit 0

{ "hooks": { "WorktreeCreate": [ { "matcher": "*", "hooks": [
  { "type": "command", "command": ".claude/hooks/worktree-create.sh" } ] } ] } }

Two details that are easy to get wrong. Everything the script prints on stdout is parsed as structured output, so send progress to stderr. And --no-input closes stdin and sets PWT_AGENT=1, so a setup step that would have asked a question fails instead of hanging a session nobody is watching.

Note where the worktree lives: the agent picks the path, often inside .claude/worktrees/, and adopt records that real path rather than insisting on the project’s own directory. Verified: adopting a checkout outside worktrees_dir allocates the port and runs setup() normally.

Worth being honest about the split: the hook covers the worktrees that agent creates. adopt covers all the others, and there are always others. They are not alternatives; the hook is the front door and adopt is the one you use for everything that came in through a window.

The rule underneath

A worktree is not ready because it exists. It is ready when the values that must differ per worktree have been derived rather than copied: the port, the database name, whatever your stack keys on. Which tool created the directory is an implementation detail, and any workflow that only works when you created it will break the first time an agent gets there first.

brew install jonasporto/pwt/pwt, then pwt adopt inside the worktree your agent already made (reference). What setup() should do with the port, the database and the dependency store is its own post.

The four worktrees: 01-merged (merged normally), 02-squashed (merged with squash, the way most PRs land), 03-open (genuinely unfinished), 04-dirty (merged, but with an uncommitted file).

git branch --merged cannot see a squash merge

The canonical way to find finished branches:

$ git branch --merged main
  TICKET-01-merged
  TICKET-04-dirty

TICKET-02-squashed is missing, and its work is already in main. Squash merge replays the changes as one new commit, so the branch’s own commits are not ancestors of main and every ancestry-based check calls it unmerged. Since most teams merge PRs with squash, the list you would clean up is exactly the list of branches your workflow cannot detect. Nothing errors; you just keep the directories forever.

This one has no free lunch, and I will not pretend otherwise: pwt’s check is ancestry-based too, so it also reports 02-squashed as pending. The difference is what happens next. An ancestry check that says “pending” and therefore keeps the directory is a false negative you clean up by hand; a tool that guessed and deleted would be a false positive you cannot undo. If you want squash-merged branches detected, the reliable signal is the forge (gh pr list --state merged), not git ancestry.

git worktree remove has exactly two settings

Point it at 04-dirty, the merged worktree with an uncommitted file:

$ git worktree remove .../TICKET-04-dirty
fatal: '.../TICKET-04-dirty' contains modified or untracked files,
use --force to delete it

Correct refusal, useless suggestion. Git tells you the one flag that makes it work, so that is the flag everyone types:

$ git worktree remove --force .../TICKET-04-dirty
$ cat .../TICKET-04-dirty/notes.txt
(gone)

The uncommitted file is not in any commit, not in any stash, not in the reflog. --force is the only way past the refusal and it is unrecoverable. “Refuse, or destroy” are the two options git offers, and in a directory you already decided is finished, the refusal is the thing you are trying to get past.

The sweep, with the classification made explicit

The same repo, through pwt auto-remove (its alias is pwt cleanup), which previews by default:

$ pwt auto-remove main --dry-run
Checking worktrees merged into: main

  ✅ MERGED: TICKET-01-merged
  ⏳ PENDING: TICKET-02-squashed
  ⏳ PENDING: TICKET-03-open
  ⚠️  DIRTY: TICKET-04-dirty - merged but has uncommitted changes

[DRY-RUN] Would remove 1 worktree(s):
  - TICKET-01-merged

Would keep: 3

Three states instead of two. Merged and clean is removable. Pending is kept. Merged but dirty is its own state, and it is the one that matters: the branch is finished, so a merge-based sweep would delete it, and the uncommitted file would go with it. It is reported and kept.

Running it for real removes exactly what the preview promised:

$ pwt auto-remove main --execute
Removing: TICKET-01-merged
Done!
  Removed: 1
  Kept:    3

Two guards worth knowing. Non-interactively (an agent, a script, CI) the command refuses to do anything without an explicit --execute or --dry-run: a destructive sweep should never be what happens when nobody was watching. And the branch is left alone; removing a checkout and deleting history are different decisions, and pwt remove --with-branch is where you say you meant the second one.

When you do delete dirty work, it is recoverable

Sometimes the answer really is “yes, remove it, I know it is dirty”. That path keeps a copy:

$ pwt remove TICKET-03-open -y
?? notes.txt
Proceeding due to -y flag (changes will be LOST)
  ✓ Metadata saved to ~/.pwt/trash/TICKET-03-open_20260816_165157.trash
  ✓ Untracked files backed up to ~/.pwt/trash/..._untracked/

$ pwt restore list
Available backups:
  TICKET-03-open  2026-08-16 16:51:57  [untracked]
     Branch: TICKET-03-open

The file I “lost” is sitting in the trash directory, and pwt restore TICKET-03-open puts it back. This is the difference between --force as an escape hatch and --force as a shredder: git has no copy of an untracked file, so a tool that removes worktrees has to make one before it deletes.

The shape of the rule

Cleanup is a classification problem wearing a deletion problem’s clothes. For every finished-looking worktree there are three questions, and the usual tools answer only the first:

pwt auto-remove (alias pwt cleanup) is the sweep with those three answered: reference, brew install jonasporto/pwt/pwt. The git worktree remove refusal is still correct behaviour; it just needed a tool that treats “merged but dirty” as a real answer instead of an obstacle.

status=0
while read -r _ path; do
    (cd "$path" && ./scripts/test) || { echo "FAILED: $path" >&2; status=1; }
done < <(git worktree list --porcelain | grep "^worktree ")
exit $status

Every part of that is load-bearing, and the rest of this post is the evidence: I built a scratch project with three worktrees, broke the test in one of them, and ran the four loop variants the internet suggests. Three of the four got it wrong, each differently.

Variant 1: the pipe that reports and then lies

The most common answer pipes into while read and appends an || echo:

$ git worktree list --porcelain | grep "^worktree " | while read -r _ path; do
    (cd "$path" && ./scripts/test) || echo "failed: $path"
  done
failed: .../wts/TICKET-1102
$ echo $?
0

It tells you TICKET-1102 failed and then exits 0. The pipe runs the loop in a subshell, so nothing you record inside it survives, and the pipeline’s status is the loop’s, which succeeded. In CI this is a green build with a broken worktree. The fix is the process substitution in the version up top: the loop runs in your shell, so status=1 sticks.

Variant 2: no error handling, with and without set -e

Drop the || entirely, which is how most one-off loops get typed:

• Without set -e: the failure vanishes. Loop exits 0, nothing printed, nothing recorded.
• With set -e (a script): the first failing worktree aborts the whole sweep. In my run, TICKET-1102 failed and TICKET-1103 was never visited. You do not learn whether the rest passes, which was the whole question.

Same loop, two shells, two different wrong answers.

Variant 3: awk, until a path has a space

Plenty of answers skip --porcelain and parse the human output:

$ for path in $(git worktree list | awk '{print $1}'); do
    (cd "$path" && ./scripts/test) || echo "failed: $path"
  done
cd: .../wts/hotfix: No such file or directory
failed: .../wts/hotfix

The worktree is called hotfix urgente. Word splitting cut it at the space and the loop visited a directory that does not exist. One honest footnote: the --porcelain + read -r _ path form survives spaces, because read puts the rest of the line in its last variable; it is the unquoted $( ) and awk forms that break. Paths with newlines need --porcelain -z, at which point the loop stops fitting in a comment box.

The entry nobody filters

git worktree list includes the main checkout as its first entry. Every loop above ran the command there too. Sometimes that is what you want; often it silently is not (the command mutates state you meant to keep clean in main). Either way, the loop does not ask.

What the loop looks like as a command

pwt ships the loop as pwt for-each, with the failure handling the DIY versions kept getting wrong. Same scratch project, same broken worktree:

$ pwt for-each ./scripts/test
=== @ (main) ===
=== TICKET-1101 ===
=== TICKET-1102 ===
=== TICKET-1103 ===
✗ Command failed in 1 of 4 worktrees: TICKET-1102
$ echo $?
1

Every worktree gets a labeled header, the main checkout runs first and is explicitly marked @, the sweep continues past failures, and the exit is non-zero with the failing worktrees named. Each worktree also gets its PWT_* environment, so the command can use the things pwt already knows:

pwt for-each 'curl -s localhost:$PWT_PORT/health'   # each worktree's own port
pwt for-each migrate                                # a Pwtfile function, per worktree

The second form is the quiet superpower: if migrate is a function in your Pwtfile, for-each runs it with each worktree’s port, branch and path filled in, which is how “run the migration everywhere” stops needing any loop at all.

Full disclosure, because this blog measures its own tool by the same rules: until this week pwt for-each had variant 2’s bug. It printed a checkmark and exited 0 no matter what failed. Writing this post is what exposed it; the fix (aggregate per-worktree exit codes, name the failures, exit non-zero) shipped with tests that were first run against the old binary to prove they caught it.

brew install jonasporto/pwt/pwt, and pwt for-each is there after a pwt init (reference). The loop at the top of this post remains correct if you would rather own it yourself.

$ cd ~/Projects/pwt-ui && pwt init
✓ Configured: pwt-ui

path=/Users/jonasporto/Projects/pwt-ui
worktrees_dir=/Users/jonasporto/Projects/pwt-ui-worktrees
remote=git@github.com:jonasporto/pwt-ui.git

That output is not a summary of what happened. It is the entirety of what happened: those three lines are the complete contents of the one file pwt created, and this post is short because there is honestly not much more to it.

Where the state lives, and where it does not

Everything landed outside your repo, in ~/.pwt/projects/<name>/config, as plain key=value text. Inside the repo: nothing. No dotfile, no hook, no config edit; git status before and after are identical. The worktrees_dir was not even created yet, because it is not needed until the first worktree is.

That asymmetry is deliberate, and it makes un-registering trivial:

rm -rf ~/.pwt/projects/pwt-ui   # pwt forgets the project; the repo never knew

There is nothing to uninstall from the repo because nothing was installed into it. If you try pwt for one project and hate it, the exit is one rm of pwt’s own state.

The variant for a repo you have not cloned yet does both steps at once:

pwt init git@github.com:you/app.git   # clone + register

The part you will use fifty times a day

Registration buys you the navigation. With the shell integration active (eval "$(pwt shell-init)" in your shell rc), the project name is now a cd from anywhere:

$ pwt pwt-ui        # from any directory: cd to the repo
$ pwt pwt-ui list   # or run commands against it without cd'ing

The name is still four syllables, so give it an alias:

$ pwt alias ui
✓ pwt-ui → ui

pwt ui from anywhere in the filesystem now lands in the repo, and pwt ui <worktree> lands in a specific worktree of it. For a project you enter dozens of times a day, this is the feature that pays the registration back within the hour.

And the worktree name does not have to be the worktree name. Any unique fragment matches, which in practice means the ticket number is the whole address:

$ pwt 1234                 # worktree is TICKET-1234-fix-login
~/Projects/app-worktrees/TICKET-1234-fix-login

$ pwt 1240                 # fragment matches two worktrees
Multiple matches for '1240':
  TICKET-1240-api
  TICKET-1240-api-retry

Unique fragment: you are there. Ambiguous fragment: pwt lists the candidates and refuses to guess, which is the correct behavior at 4pm with six worktrees named almost the same thing.

What the registration unlocks later

Nothing above touched worktrees, and that is the point: registration is cheap and separate. When the project needs them, the machinery from the earlier posts is already wired to the name:

• pwt create feature-x gives the worktree a port that survives everything
• a Pwtfile in the repo root turns “set up a worktree” into code that runs on every create, including worktree-only git excludes
• pwt server --bg and pwt jobs wait give agents something better than polling

The repo in the transcript is real: pwt-ui, the terminal dashboard for pwt I am building, is now managed by the tool it fronts. Registering it took under a minute, and dogfooding it immediately caught a real bug (pwt init through the shell wrapper registered a ghost project named after an internal command; fixed, with a regression test, before this post went up). Adding your repo to the tool that manages your repos is apparently also a test suite.

brew install jonasporto/pwt/pwt, then pwt init inside the repo you use most. The alias goes in the same minute.

git config extensions.worktreeConfig true         # once per repo
git -C <worktree> config --worktree \
    core.excludesFile /abs/path/to/exclude-file   # once per worktree
echo "debug.log" >> /abs/path/to/exclude-file

The rest of this post is why the popular answers fail, measured, and the two gotchas inside the working one. Everything below was run today on git 2.39.5.

The file everyone cites is never read

Search for this and the top answers, including a dedicated guide site and well-starred gists, tell you a linked worktree has its own exclude file at .git/worktrees/<name>/info/exclude. It sounds right: that directory is the worktree’s private git dir, and info/exclude is where repo-local ignores live. Measured:

$ echo "debug.log" > .git/worktrees/wt-a/info/exclude
$ touch wt-a/debug.log
$ git -C wt-a status --porcelain
?? debug.log

Git does not read that path. Ignore patterns come from $GIT_COMMON_DIR/info/exclude, the directory all worktrees share, and git never consults a per-worktree info/ for excludes. The failure mode is the worst kind: nothing errors, the file just sits there, and you believe the pattern is active until an agent runs git add -A and commits the thing you “ignored”.

Two more non-answers, briefly. A different .gitignore per worktree does not exist as a concept: .gitignore is tracked content, so it belongs to the branch, follows every checkout of that branch, and any edit is one git add away from being committed for the whole team. And the global core.excludesFile is the opposite scope, every repo on the machine, which is its own trap.

The almost-right answer: one file for all worktrees

.git/info/exclude in the common directory works and is never committed. Its scope surprises people in the other direction:

$ echo "debug.log" >> .git/info/exclude
$ git status --porcelain; git -C wt-a status --porcelain; git -C wt-b status --porcelain
(empty)  (empty)  (empty)

One line, ignored in the main checkout and in every worktree, current and future. Before reaching for true per-worktree isolation, check whether this is actually what you need: an ignore pattern for a file that does not exist costs nothing, so the union of every worktree’s patterns in one shared file behaves identically to per-worktree files in almost every real case. You need real per-worktree scope only when the same filename must be ignored in one worktree and visible in another.

True per-worktree: worktreeConfig

When you do need it, git has it, behind an extension:

$ git config extensions.worktreeConfig true
$ git -C wt-a config --worktree core.excludesFile \
      "$PWD/.git/worktrees/wt-a/info/exclude"
$ git -C wt-a status --porcelain    # debug.log ignored here
(empty)
$ git -C wt-b status --porcelain    # and only here
?? debug.log

A nice touch: pointing core.excludesFile at .git/worktrees/<name>/info/exclude makes the internet’s mythical file real. Git still does not read it on its own; the --worktree config is what wires it in, and the path is simply a sensible place to keep the patterns, since it dies with the worktree.

Two gotchas cost me a retake each:

The path must be absolute. My first attempt used a relative path and nothing was ignored, silently: a relative core.excludesFile resolves against wherever the command runs, not against the git dir.

Per-worktree core.excludesFile replaces the outer one. The key is single-valued, so the most specific scope wins alone; it does not stack:

-- repo-level excludesFile ignores *.tmp
-- wt-a sets a worktree-level excludesFile for debug.log
$ git -C wt-b status --porcelain | grep tmp    # still ignored
(empty)
$ git -C wt-a status --porcelain | grep tmp    # resurfaced
?? x.tmp

The worktree that customized its excludes lost every pattern from the level above. If you use this, copy the outer patterns into the per-worktree file, and remember the config is machine-local state: a new clone, a teammate, a recreated worktree all start from zero.

Declaring it once, in the repo

For the common case, the shared info/exclude, pwt can own the writing. The project’s Pwtfile (which is committed) declares the patterns, and every pwt create applies them idempotently:

# Pwtfile
setup() {
    pwtfile_git_exclude "pnpm-lock.yaml" "pnpm-workspace.yaml" ".claude/"
}

pwtfile_git_exclude (pwt ≥ 0.2.2) appends each pattern to the common .git/info/exclude only if it is not already there, so the declaration is safe to run on every worktree creation, and a fresh machine converges the first time it creates a worktree. The knowledge travels in the commit; the ignore state stays out of it.

What this looks like with an agent

The honest summary of this post is “git has four ignore layers, one famous path is fake, one config key silently replaces another, and paths must be absolute”. Nobody should keep that in their head. Stated as an outcome instead:

you> ignore the generated pnpm files in every worktree,
     without committing anything
agent> runs pwt skill, reads the guide, adds
       pwtfile_git_exclude "pnpm-lock.yaml" "pnpm-workspace.yaml"
       to setup(), creates a throwaway worktree, checks git status

pwt is a git worktree manager for parallel development: brew install jonasporto/pwt/pwt. The exclude helper landed in v0.2.2, alongside the port allocation and setup hooks from earlier posts.

What I found on one machine: two global ignore files with identical content, because a conditional include (includeIf "gitdir:...") pointed work repos at a second copy. core.excludesFile is single-valued, so the second file did not add to the first; it silently replaced it. The two files matched today only because one started as a copy of the other, and nothing would have kept them matching. Together they were hiding 36 files across 10 repos, and in one repo they were hiding a directory the repo deliberately tracks ten files inside.

That last one is the real cost. Ignore rules never affect tracked files, so nothing broke. But the next intentional file of that name, in the one repo where it belongs in a commit, is born invisible: git status will not mention it, and you will not commit it, and nothing will tell you.

The four layers, and what each is for

Two facts decide everything:

Layers are additive, but core.excludesFile is one value. All four sources combine when git decides what to ignore. But the global layer is a single config key: set it again in an included config and the old file stops applying entirely. That is how machines end up with two registries and nobody noticing.

.git/info/exclude lives in the repo’s common directory. A worktree’s .git is a pointer file; the real directory, including info/exclude, is shared by every worktree of the repo. One line in that file ignores the pattern in the main checkout and in all worktrees, current and future, and can never reach a commit because git does not track its own metadata.

That second fact makes info/exclude the right home for exactly the files this post is about: repo-specific, machine-local, worktree-borne. The global file is the right home for almost nothing: the classic .DS_Store case, and even that is arguable.

The fourth layer exists but read the fine print before wanting it: per-worktree config requires extensions.worktreeConfig, and a per-worktree core.excludesFile replaces the global one for that worktree instead of adding to it. Since ignore patterns for files that do not exist are free, I have yet to find a case where the union of patterns in info/exclude is not simpler.

Migrating off the global, mechanically

The dangerous move is deleting the global first: the moment it stops applying, every file it was hiding shows up as ?? in every repo at once, and an agent running git add -A will happily commit your agent config into a work repo. So the order is: write the per-repo entries first, prove they cover everything, delete the global last.

No guessing is needed at any step. Git will tell you exactly what the global is hiding, per repo:

# what status looks like today vs. with no global ignore
diff <(git status --porcelain) \
     <(git -c core.excludesFile=/dev/null status --porcelain)

# for each path that appeared: which pattern (and which file) hid it
git check-ignore -v -- <path>

Every line the diff produces is a fact: this repo depends on that global pattern. check-ignore -v names the pattern and the file it came from, which is also how I discovered registry number two. The migration is then: append exactly those patterns to that repo’s .git/info/exclude, re-run the diff everywhere until it is empty everywhere, and only then empty the global file. I ran this across 90+ checkouts; the whole thing is an hour, most of it waiting on git status.

The repos that needed nothing got nothing, which is the point. A global pattern is a claim about every repo you will ever clone. A line in info/exclude is a claim about one repo, and it can be wrong without poisoning the others.

Making it reproducible

info/exclude has one genuine weakness: it travels with nothing. A new machine, a teammate, a re-clone all start from an empty file, and the knowledge of what to exclude lives nowhere.

So give it a source of truth that is committed, without committing the excludes themselves. As of this week, a pwt Pwtfile can declare them:

# Pwtfile - setup() runs on every `pwt create`
setup() {
    pwtfile_git_exclude "pnpm-lock.yaml" "pnpm-workspace.yaml" ".claude/"
}

pwtfile_git_exclude appends each pattern to the repo’s common .git/info/exclude, idempotently, so declaring it on every create costs nothing and a fresh machine converges on the first worktree it creates. The Pwtfile is committed; the exclude file never is. The declaration travels, the state stays local.

Running agents in your worktrees? This failure is agent-shaped on both ends: agents generate exactly the files that need excluding, and agents run git add -A without reading the status first. A pattern declared in the Pwtfile closes the loop before either happens.

pwtfile_git_exclude ships in pwt as of this week, alongside the port allocation and setup hooks from the earlier posts: brew install jonasporto/pwt/pwt.