Use Grok Build worktrees for isolated parallel agents

A worktree session runs in an isolated copy of your repository so parallel agents keep separate files. Official Build worktrees docs: worktrees need a git repo, live under ~/.grok/worktrees/<repo>/<id>/, and start from your current HEAD, including uncommitted changes. Subagents can request worktree isolation when the parent delegates parallel work.

Start a worktree session

grok -w
grok --worktree=feat "refactor module X" # = keeps the prompt out of the name
grok -w --ref main "fix the flaky test"  # clean checkout of the ref
grok -w -r <session-id>                  # resume in a fresh worktree

In the TUI:

• /fork --worktree forks the current session into a worktree
• Ctrl+W on the welcome screen opens the New Worktree dialog
• Ctrl+W in the Agent Dashboard dispatches new agents into worktrees

Whether /new and /fork offer a worktree is configurable in TOML. A worktree is a real git checkout, detached at its base commit; land changes with ordinary git.

Housekeeping

Worktrees persist until you remove them. Ending or deleting a session leaves its worktree in place. gc runs only when you invoke it.

Command	What it does
grok worktree list	List tracked worktrees
grok worktree show <id>	Show details for one worktree
grok worktree rm <ids...>	Remove worktrees (--dry-run to preview)
grok worktree gc	Remove entries whose directory is gone; --max-age 7d also expires idle worktrees not in use by a running process

When to use one

Use a worktree when two agents edit the same tree at once, when you want a clean checkout of a ref, or when you resume a session without touching the main working copy. For a single linear edit path, stay in the normal session — see Start a Grok Build session and Use Plan Mode.

Pitfalls

• Worktrees require git. Outside a repo, the flags will not create an isolated checkout.
• Uncommitted changes from HEAD copy into the new worktree unless you pass --ref for a clean checkout.
• Clean up with grok worktree rm or grok worktree gc so ~/.grok/worktrees/ does not grow forever.
• CLI install: Install the Grok Build CLI.