| 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.
