Git Worktree Manager

Worktree setup for three parallel agents: one checkout per agent, isolated ports and databases, fixed branch names and a cleanup routine.

Directory layout

~/code/shop/            main checkout, you only
~/code/shop-wt/agent-1/ worktree, branch agent/1-<task>
~/code/shop-wt/agent-2/
~/code/shop-wt/agent-3/

Create a worktree

git worktree add ../shop-wt/agent-1 -b agent/1-checkout-refactor origin/main
cd ../shop-wt/agent-1 && pnpm install --frozen-lockfile

Per-worktree environment

Each worktree gets its own .env.local (git-ignored):

WEB_PORT=3101      # agent-2: 3201, agent-3: 3301
API_PORT=4101
DATABASE_URL=postgres://dev:dev@localhost:5432/shop_agent1
COMPOSE_PROJECT_NAME=shop_agent1

Keep one Postgres container and give each agent its own database, created by a seed script.

Branch conventions

• agent/<n>-<short-task>, always branched from fresh origin/main.
• Agents commit only in their own worktree; you merge through PRs.
• Never check out the same branch in two worktrees.

Cleanup

git worktree remove ../shop-wt/agent-1
git branch -d agent/1-checkout-refactor
dropdb shop_agent1
git worktree prune

Next steps

• Add a scripts/wt-new.sh that creates the worktree, env file and database in one step.
• Add shop-wt/ paths to your agents' allowed working directories.