BUILD / set-worktree-prompt-modes-in-grok-build

Build

Set worktree prompt modes for /new and /fork in Grok Build

Set worktree prompt modes for /new and /fork in Grok Build

[hints] controls whether /new and /fork offer a git worktree. Official: Settings reference, Worktrees.

Keys

Key Values Default What it does
new_session_worktree_mode ask | always | never never Worktree prompt on /new
fork_worktree_mode ask | always | never ask Worktree prompt on /fork
  • ask — show the popup
  • always — create a worktree without asking
  • never — skip the worktree offer

User config (the TUI also writes these keys when you answer the prompts):

[hints]
new_session_worktree_mode = "ask"
fork_worktree_mode = "always"

Project .grok/config.toml does not own [hints] — user config only. Removing a key restores the default.

Force a worktree without the hint

CLI and slash paths still create worktrees when you ask for one:

grok -w
grok --worktree=feat "refactor module X"

In the TUI: /fork --worktree, Ctrl+W on the welcome screen (New Worktree), or Ctrl+W in the Agent Dashboard. Full lifecycle: Use Grok Build worktrees.

Pitfalls

  • Editing [hints] in project .grok/config.toml — user config only.
  • Expecting never to block grok -w / /fork --worktree — those explicit paths still create a worktree.
  • Leaving worktrees forever — clean with grok worktree rm or grok worktree gc.