Git Worktrees for Parallel Agents

In Cloudroom ($ROOM_THREAD_ID is set)

Never run git worktree add yourself. Cloudroom only deletes worktrees it made, so hand-made ones pile up in ~/code forever.

• New task: start the thread with New worktree instead.

• Move this thread to its own worktree: fork it into a Cloudroom-managed worktree. Cloudroom makes the branch and deletes the folder once its last thread is archived (after the worktree retention setting, default 21 days).

  room-cli thread fork "$ROOM_THREAD_ID" --new-environment worktree --title "<task>" \
    --prompt "You now run in a new worktree. Copy the gitignored .env files from <primary checkout> into it, then stop and wait for the user."
  

  It branches from main, so uncommitted edits stay behind; commit them first or pass --base-branch <ref>. Then tell the user to continue in the new thread and archive this one. Skip the rest of this skill.

Start here

Detect where you are before editing:

[ "$(git rev-parse --path-format=absolute --git-dir)" = "$(git rev-parse --path-format=absolute --git-common-dir)" ] \
  && echo "primary checkout" || echo "worktree"

• Primary checkout → create a task-named worktree, complete the setup below, and cd into it before editing.
• Worktree (including one created by Cursor) → proceed with the task.

Working model

Worktrees have separate working files and branches but share Git history, stashes, config, and refs.

• One task = one worktree = one agent session. Never share a working directory between agents.
• Keep the primary checkout on main, only for review, merging, and pushing.
• Nothing auto-merges. The human reviews each diff before merging or discarding the worktree.
• Keep task branches local and short-lived. Push only main unless the user explicitly asks to push a task branch.
• Merge one worktree at a time. If main moved, rebase the task branch before merging.

Creating and removing