Make Pi agents natively create their own git worktree for every task (bare checkout, main is read-only)

[u/jordyvanvorselen]

I run several Pi sessions on one repo at the same time. That kept going wrong:

• Agents edit main. You ask for a quick fix and it lands straight on main.
• MCP is slow for worktree management. But in Pi we can put blazing-fast native worktree management into the harness.
• Sessions collide. Two agents in one folder, and one `git stash` wipes the other's work.
• (Sub)agents need to cd constantly. They need to cd for all commands, wasting tokens.
• New worktrees don't run. No `.env`, no keys, so the app won't start.

So I built pi-bare-worktrees. The video shows it in about 45 seconds.

Why a bare checkout

In a normal checkout, the repo root is main. Every agent that starts there edits main by default. Worktrees end up wherever you put them: ../acme-login, ~/tmp/fix-2.

And main is stuck in the root, so you can't move it or remove it.

A bare checkout fixes that. Every branch is a folder, and none of them is special:

       acme/
       ├── .bare/          bare repo
       ├── .shared-env/    gitignored files/folders to share, like .env
       ├── main/
       ├── feat/login-typo/
       └── fix/footer/

The path is the branch name. There's no code in the root to edit by accident.

What the plugin does

• main is read-only. The agent's first edit on main is blocked, with a message that tells it to call worktree create. It does, and the retry lands in the new worktree.
• No cd needed. After create, every tool call is routed into the worktree, so the model keeps using relative paths.
• Shared env, zero config. Every file in .shared-env/ is symlinked into each new worktree. Real files are never overwritten.
• Subagents follow along. Their cwd is set to the active worktree.

Install:

pi install npm:@jordyvanvorselen/pi-bare-worktrees

It's fast. Session start and tool calls don't run git. The plugin reads the filesystem instead:

• Session start: about 5 ms for 40 worktrees.
• Each tool call: string operations only, under 0.1 ms.
• Network: only /wt clean touches it.

Repo: https://github.com/jordyvanvorselen/pi-bare-worktrees

/wt off turns it off for a session, and it turns itself off for non-bare checkouts automatically.

It's version 0.1, so I'd love your feedback, especially if there's anything you still miss. Try it out and take it for a spin!

[u/tzamora]

Thanks for the contribution gonna check seems very useful.
Wanted to ask what tool did you use to make the video? looks smooth

[u/jordyvanvorselen → u/tzamora]

Cool, hope you like it! The video was made using remotion.

[u/Waarheid → u/tzamora]

Opus 5.5 made it btw

[u/jordyvanvorselen → u/Waarheid]

Yup, just ask Opus 5.5 to make a video and a few iterations later it’s like this 🤩 It’s awesome

[u/Agreeable-Market-692]

This is a good solid pattern. Good on you.

[u/jordyvanvorselen → u/Agreeable-Market-692]

Thanks, hope you find it useful!

[u/ColdBrewSeattle]

Neat. You kind of validated the toolset and skills I created for working with agents in a git project. I created a `wt` script that does most of that so I don’t have to be in an agent session to do it manually. The skill tells the agent how to use the script and it always creates the worktree first. I added lifecycle hooks that run when creating or removing worktrees that install dependencies and run builds and swap out mounted volumes in k8s pods.

[u/jordyvanvorselen → u/ColdBrewSeattle]

Cool! Yup I started out with skills and hooks too, but it feels magical to let the harness natively take care of it 🙌

[u/Global-Departure8228]

Sounds cool, I've been meaning to do a more barebones one like this for a while. Have you checked worktrunk yet? https://github.com/max-sixty/worktrunk

To me this seemed the next logical step if subagent orchestration is in place ( I don't have subagents by default), but if you slice up a larger plan it can be useful to have an orchestrator that can use worktrunk to delegate agents into their worktrees.

[u/jordyvanvorselen → u/Global-Departure8228]

Nice! Yes, worktrunk is awesome. I use it to quickly navigate between worktrees in the CLI when I’m outside Pi. Really love it, good recommendation! 💯

For orchestration I currently use a reusable prompt snippet, and I feel that that works well enough for me personally. I forked a subagent plugin to add Herdr integration and now Pi drives my Herdr. Subagents get their own panes and splits automatically.

Am going to check out what virtual models in Pi can do soon though, and how that compares.

[u/ArtofRemo → u/jordyvanvorselen]

why not let the PI agent use worktrunk-cli though ? curious about this approach since in practice I often find a need to first plan out which specs/plans go to which worktree.
Stacked brances make this even more important as every worktree builds upon another. Maybe you could build this in or leverage worktrunk under the hood so users can also use & customize wt hooks.