cd /news/developer-tools/worktrunk-takes-the-friction-out-of-… · home › topics › developer-tools › article
[ARTICLE · art-154406] src=madewithlove.com ↗ pub= topic=developer-tools verified=true sentiment=↑ positive

Worktrunk takes the friction out of Git worktrees

Worktrunk, a command-line tool that wraps Git worktrees, addresses three recurring friction points in parallel development: cold starts, port collisions, and leftover Docker containers and volumes. The tool replaces worktree commands with `wt switch --create`, `wt list` and `wt merge`, and runs lifecycle hooks configured in a single committed `.config/wt.toml` file so behavior is identical across a team. The author, writing on the madewithlove blog, reports using Worktrunk on two projects, with hooks that copy gitignored files via `wt step copy-ignored`, assign each branch a stable port through a `hash_port` filter, and run `docker compose down --volumes` before a worktree is removed.

key takeaway

Worktrunk's post-start and pre-remove hooks let each Git worktree copy gitignored files in milliseconds, derive a stable per-branch port via the hash_port filter, and tear down its Docker stack and volumes on removal, eliminating cold starts, port collisions and leftover containers.

by read3 min views39 publishedOct 7, 2026
Worktrunk takes the friction out of Git worktrees
Image: Madewithlove (auto-discovered)

A while ago I wrote about how I parallelise myself with Git worktrees. I still do. But after a few months of it, the friction started to add up. Worktrees make parallel work possible. They don't make it pleasant.

The friction #

Three things kept getting in the way.

Every worktree starts cold. The code is there, but the app won't run. No environment variables, no vendor files, nothing that's gitignored. It's like cloning a blank project and running the whole setup again.

Ports collide. Spin up a Docker stack in a second worktree and it tries to grab the same database port as the first one. You fix it by hand, or you let Claude fix it. Either way, it takes a while.

Worktrees leave junk behind. Remove a worktree and its containers and volumes stay. After a few weeks, you have a machine full of Docker containers nobody needs anymore.

None of these is a big deal on its own. But when you're running several agents in parallel, you hit all three many times a day.

Worktrunk #

Worktrunk is a small CLI that wraps Git worktrees. There are other tools that do something similar, but this is the one we've been using on two projects, and it's been very useful.

First, it replaces the worktree commands you never remember with a few that make sense:

wt switch --create my-feature   # new branch and worktree in one go
wt list                         # everything you have open
wt merge                        # merge it and clean up

The real power is in the hooks. Worktrunk runs shell commands at points in the worktree lifecycle, such as after a worktree starts or before it's removed. You configure them in a single file committed to the repository, so it works the same for everyone on the team.

The hooks we use #

Here's a simplified version of our config. It's just a few lines of shell. Nothing fancy, easy to read and easy to tweak.

[[post-start]]
copy = "wt step copy-ignored"

[[post-start]]
port = "echo APP_PORT={{ branch | hash_port }} >> .env"

[pre-remove]
cleanup = "docker compose down --volumes"

A warm start. After a worktree is created, we copy over the gitignored files: the environment file, vendor directories, everything you'd otherwise rebuild. Copying takes milliseconds. Running a full dependency install and filling in an env template does not.

A port per branch. The hash_port filter turns the branch name into a port number, and we write that into the environment. The same branch always gets the same port. So every worktree has its own port and its own database, and you can tear it down and spin it up again later without thinking about it.

A clean exit. Before a worktree is removed, we bring the Docker stack down and delete its volumes. No more leftovers.

What it looks like in practice #

Create a worktree and everything is there. If it's a change that needs the app running, spin up the stack. If it's a small documentation fix, don't bother. List your worktrees whenever you lose track. Merge, and everything is cleaned up.

It's a small thing. But small friction compounds, especially when your job has shifted to orchestrating instead of typing.

TL;DR #

If you use Git worktrees for parallel work, give Worktrunk a try. One config file in the repository, and every worktree starts warm, gets its own port and cleans up after itself.

Your disk will thank you.

── more in #developer-tools 4 stories · sorted by recency
── more on @worktrunk 3 stories trending now
sponsored brought to you by zahid.host 4,200+ EU-deployed projects
reading about agents? ship yours in a single git push.

Run your AI side-project on zahid.host

EU-based hosting, git-push deploys, automatic HTTPS, no cold starts. Free tier with a custom domain — perfect for shipping the agent you just read about.

$git push zahid main
→ Live at https://your-agent.zahid.host ✓
Get free account → Pricing
from €0/mo · no card required
LIVE [news/worktrunk-takes-the-…] indexed:0 read:3min 2026-10-07 · —