worktree checkout

Check out an existing remote branch into its own worktree.

Usage

worktree checkout <remote-branch>
worktree checkout <remote-branch> --agent "<prompt>"

If omitted, worktree checkout will show an interactive branch picker. A non-interactive run has no picker: without the argument it exits 2 with worktree: no default for the branch to check out; pass <branchName>.

Examples

worktree checkout feature/fix-login-timeout
worktree checkout origin/feature/fix-login-timeout
worktree checkout feature/fix-login-timeout --agent "find the cause of the timeout"

This creates a local tracking branch and worktree directory for that branch.

Agent Dispatch

--agent (short: -a) works exactly as it does on worktree branch: the checked-out worktree is handed to the agent configured as agent.command, with the flag’s value as its prompt and the worktree as its working directory. The worktree is opened as usual: in Herdr the agent is the one Herdr starts in the space and the prompt is submitted to it, otherwise agent.command is launched detached. There is one agent per worktree either way. checkout has no --agent-file, --agent-stdin, --no-agent or --no-open; an empty or over-131,071-byte prompt is rejected, as on branch, and so is a prompt no configured agent would take (see branch), both before the worktree is created.