If you are experimenting with AI coding agents, or maybe you are just trying to work with many feature branches at the same time, you probably found this big problem. It is very hard to start local environments for multiple git worktrees in the exact same repository.
What usually happens? You try to run the project and you get that terrible error: bind: address already in use.
When multiple agents or developers try to run different stacks at the same time, they conflict with each other. The ports are the same, the database state gets messy, and your automated workflow turns into a big headache.
To solve this, I developed something called Worktree Wizardry.
What is it exactly?
Worktree Wizardry is a public starter kit for creating isolated per-worktree environments that uses Docker Compose. It is designed specifically for AI-assisted workflows where each worktree can run and test a different stack without collisions.
It is basically a skill. It is simply a public repository that allows people to run agents to create for them a worktree sandbox. This makes it possible for them to test multiple worktrees at the same time without worrying with port numbers and other environment conflicts.
Main Features
- Isolated Port Allocation: Every worktree gets a different port automatically. No more conflicts!
- Shared Git State: It safely manages the shared state in the git common dir while keeping the execution isolated.
- Smart Integrations: It comes with optional lifecycle hooks for AI tools like Conductor and Superset.
- Custom Scripts: Repo-specific setup and archive behavior is controlled via simple bash hook scripts.
How to use it
It is very easy to start. You just use the template/ folder as the starting point for your new or existing repository.
1. Copy the template into your target repo:
bash install.sh /path/to/target-repo
2. Customize your environment:
In the target repo, you just need to edit these files for your app:
worktree-wizardry/config.envworktree-wizardry/hooks/setup.shworktree-wizardry/hooks/archive.shdocker-compose.worktree-wizardry.yml
3. Run the magic:
It is one setup command per worktree:
bash scripts/worktree-wizardry-setup.sh
# And to clean up later:
bash scripts/worktree-wizardry-archive.sh
If you want to see an example, the repository has a demo/ folder that shows a concrete adapter. It runs Postgres on port + 1 and an Nginx demo app on port + 2, generates the .env.local files automatically, and cleans up everything in the archive step.
Try it out!
If you are building tools for agents or just want a better way to test multiple worktrees locally, please take a look.
Top comments (0)