worktree

name	worktree
description	Manage git worktrees with their own dev ports, symlinked .env files, playground, and simulations. Use when the user asks to create, set up, list, enter, or remove a worktree.

Worktrees

Run ./rh worktree $ARGUMENTS from the repo root. Why worktrees must go through this command at all — and how the WorktreeCreate hook routes EnterWorktree into it — is in AGENTS.md; this skill is the command surface.

If the user gave no arguments, ask which operation they want:

Command	What it does
./rh worktree <name>	Create a worktree branching from current HEAD, with its own dev ports
./rh worktree --init	Give an existing worktree the same setup — run it from inside that worktree
./rh worktree <name> --load	Launch a shell in the worktree
./rh worktree <name> --remove	Remove the worktree, its dev containers and volumes, and its branch
./rh worktree --list	List all worktrees

./rh worktree help prints the same list with per-flag detail.

--init on an existing worktree

For a worktree made with a bare git worktree add, or one the hook only partly set up. Run it from inside the worktree — it locates the main checkout itself:

cd ~/worktrees/rhesis/<name> && ./rh worktree --init

From the main checkout, name the target instead: ./rh worktree <name> --init.

It allocates a free port block into .rhesis-ports, symlinks playground/, simulations/, domain.local/, the .env files and the Claude config, then copies apps/backend/.env and apps/frontend/.env.local and shifts their ports. It's idempotent — re-running reports what's already linked and leaves it alone.

Two things it won't do: run in the main checkout, or touch a directory git doesn't list as a worktree. Both exit with an error rather than provisioning the wrong tree.

If the worktree's branch predates the --init flag, its own ./rh won't have it. Run the main checkout's copy instead — it resolves the target from your current directory, not from where the script lives:

/path/to/main/rh worktree --init

Notes

• A worktree outside ~/worktrees/rhesis/ gets provisioned fine, but --load and --remove can't find it by name — remove it with git worktree remove after ./rh dev clean inside it.
• --remove deletes the branch too, and only deletes it if it's fully merged.
• After creating or adopting one, ./rh dev status inside it shows the ports it actually got.