- Home
- Skills
- DevOps & Cloud
- Worktree Shield: stop parallel agents colliding
More screenshots
Works with the AI Agents you already use
Worktree Shield: stop parallel agents colliding
Finds the ports, databases, Docker Compose projects and paths your Git worktrees share, before parallel coding agents collide.
Free
Worktree Shield: stop parallel agents colliding
Example session with this skill installed
Two other agents are working in parallel worktrees of this repo. Before you start the dev server here, check whether we'd collide.
- Read your context and instructions
- Compiled the worktree shield
Summary
Ran uvx worktree-shield scan --strict --scope static (the project's conflicting-worktrees example: three worktrees made from one branch). It exited 1, because one collision fails the policy, so I haven't started the server.
| Code | Status | Shared by all 3 worktrees | Where |
|---|---|---|---|
| WTS-PORT-001 | FAIL | port 5173 | .env.example:1 PORT=5173 |
| WTS-DB-001 | WARN | Postgres database app_dev on localhost:5432 | .env.example:2 DATABASE_URL |
| WTS-DOCKER-001 | WARN | Compose project app | compose.yaml:1 name: app |
It follows that the Docker volume app_pgdata is mounted in all three too (WTS-DOCKER-003).
Suggested fixes (from worktree-shield plan)
- Give each worktree its own port in its
.env: 5174 for app-billing, 5175 for app-login. - Give each its own database:
app_dev_app_billing,app_dev_app_login. - Give each its own Compose project name:
app-billing,app-login.
That is six lines across the .env files of app-billing and app-login. Want me to write them? Afterwards I'll run worktree-shield scan --strict --include-env to confirm it exits 0.
Connects securely to your tools. The creator never sees your data.
About this skill
Running several coding agents in parallel Git worktrees? Each gets its own checkout, but they still share port 8000, the app_dev database and the Docker Compose project name. One agent's migration changes another's data, and docker compose up in one worktree takes over the other's containers.
This skill makes your agent run a read-only preflight with the open-source worktree-shield CLI before it starts servers or migrations. It works on the worktrees you already have, however they were made.
What it does
- Finds every port, database, Compose project name and absolute path that two or more worktrees share
- Reports each one with the file and line it comes from, and how certain the collision is
scan --strictexits 1 on a real collision, so the agent stops before it breaks somethingplanproposes one change per worktree (for example its own port and database name in.env), applied only after you agree--scope staticreads configuration only, for CI and shared machines
Safety
Read-only: nothing in the repository is run, changed or locked. The skill tells your agent to apply plan changes only with your yes, and to read .env files (--include-env, which keeps only ports, database servers and paths) only when you agree.
Network
The first run downloads worktree-shield from PyPI through uvx. The tool itself is offline.
MIT licensed. Source and docs: https://github.com/BhuwanJoshi-01/worktree-shield
Requires Python 3.11+, Git, and uv/pipx. Only detects resources in files or running processes. Will not apply changes without user confirmation.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before any payment.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Free forever
No account required to browse
Trust & safety
Security scan
Security scan passed 11 days ago
- Free with an Agensi account
Requires
Permissions
Runs the read-only worktree-shield CLI in the terminal. It reads the repository's worktrees and their configuration files (compose files, .env.example, and .env only with --include-env), and by default lists the ports running processes listen on. Network: one package download from PyPI through uvx.