Create a Worktree

Create a worktree from a new branch, an existing local branch, or a pull request: the dialog fields, branch prefixes, path patterns, name collisions, bulk creation from issues, and what each error state means.

Reviewed Aug 18, 2026

Creating a Worktree

Open the New Worktree dialog from the + button in the sidebar, with Command-K, then Command-N Control-K, then Control-N Control-K, then Control-N , or by right-clicking any worktree card and choosing New Worktree. The dialog has three creation modes: start a new branch, use an existing local branch, or check out a pull request branch.

New Branch

This is the default mode. Its fields:

Link Issue (optional): a searchable issue selector. Pick an issue and Daintree generates the branch name as {type}/issue-{number}-{slug}, with the type prefix taken from the issue's labels or title keywords.
Base Branch: a searchable picker with fuzzy matching and a Recent band. A branch already checked out in another worktree carries an in use badge; selecting it selects it, rather than closing the dialog and discarding what you had typed. Defaults to the current branch, or main/master when there is none.
New Branch Name: a freeform input. As you type, an autocomplete popover suggests known type prefixes: feature/, bugfix/, chore/, docs/, refactor/, test/, release/, ci/, deps/, perf/, style/ and wip/. Aliases are normalized: feat becomes feature, fix and hotfix become bugfix. An existing name gets a numeric suffix (feature/login-1) and a hint saying so.
Worktree Path: generated from the branch name using the path pattern in Settings > Worktree. Edit it by hand or use the folder picker. A path that already exists gets the same numeric-suffix treatment.
Create from remote branch: bases the worktree on the remote tracking branch. Checked automatically when the chosen base is remote.
Assign to me: shown when an issue is linked and a forge account is configured. Remembered across sessions.
Environment: a radio group of Local plus one button per configured resource environment. The whole control is hidden when the project has no environments. See Remote Compute.
Run Recipe (optional): a recipe to run once the worktree exists, defaulting to the project's default recipe. See Recipes.

Tip

Branch names can't start with . or -, can't end with a space or ., and can't contain \, : or ... The prefix is validated separately from the rest of the name.

Existing Branch

Use this for a branch that already exists locally: resuming interrupted work, or picking up a branch created outside Daintree. The base-branch picker and the name input collapse into one Select Branch picker listing local branches that aren't checked out anywhere else. Remote-only branches and branches in use are left out.

Selecting a branch generates the worktree path, with the same numeric suffix if it already exists. On submit Daintree uses the branch as-is rather than creating one. Switching between the two modes resets the branch selection, the search query and any validation errors.

Tip

A branch missing from the list is either checked out in another worktree or exists only on the remote. For a remote branch, switch to New Branch mode and select it as the base.

PR Checkout

Create a worktree straight from a pull request with the Create Worktree button in the Code Forge panel. The dialog opens in PR Checkout mode: the title becomes Checkout PR Branch, the mode toggle is hidden, and a banner shows the PR number and title.

Daintree resolves the PR's branch in order: the remote tracking branch (origin/{headRefName}), then the local branch, then a fetch of pull/{number}/head, then a re-check for the now-local branch. The fetch runs on its own; you don't need to type any git commands.

If the branch still can't be resolved, creation is not blocked. An amber banner explains what happened and the worktree is created from the fallback branch instead:

Warning

Could not fetch branch {headRefName} from the remote. The worktree will be created from the fallback branch instead. You can try running git fetch origin manually and reopening this dialog.

Pull requests from forks are supported and are not filtered out of the PR list or the bulk-create plan.

Branch Prefix

Daintree can prepend a namespace prefix to every new branch name. Set it in Project Settings > Worktree Setup > Branch Prefix:

None (default): no prefix.
Username: reads git config user.name, slugs it to lowercase, and prepends it as alice/.
Custom: any string, such as myteam/.

A live preview shows the result. The namespace prefix is separate from the type prefix that comes from issue labels or the autocomplete popover, and the two stack: a username prefix of alice/ plus a type prefix of feature/ produces alice/feature/issue-42-add-login. The prefix is per-project; there is no global option.

Error States

A failed creation shows a banner in the dialog with a plain-language message:

Condition	Message
Branch already checked out elsewhere	"This branch is already open in another worktree." An Open Worktree button navigates to it.
Directory creation failed	"Cannot create directory. Check permissions or available disk space."
Invalid branch name	"The branch name contains invalid characters."
Worktree path conflict	"A worktree already exists at this path."

Any other git error shows its raw output. Where the plain-language message differs from the raw error, a "Show details" disclosure holds the full git output.

Bulk Worktree Creation

Selecting several issues or pull requests in the Code Forge panel and clicking Create Worktrees makes a worktree for each in one pass. Selection, the numeric search syntax and the skip badges are documented with the forge panel; what matters here is how the batch executes.

Each item moves through creating the worktree, spawning terminals when a recipe is selected, assigning the issue when that's enabled, and verifying terminal health. Recipe fanout admits as a single bounded batch rather than one cold spawn at a time, which is what took 20 concurrent creates from about 19 seconds to under one.

Daintree keeps up to three creation requests in flight. The real throttle is the backend's leaky-bucket limiter; the small fan-out cap exists so the producer side doesn't fight it. Transient errors (git lock contention, rate limits, network timeouts) retry on their own with exponential backoff from 3 seconds to a 30-second cap, bounded by a five-minute per-item ceiling. Permanent errors fail immediately.

Tip

Retry Failed resumes each item where it stopped. A worktree already on disk isn't recreated; only the failed step re-runs. Retrying a half-finished batch never produces duplicates.

Cancelling stops the in-flight items too. Cancel bumps the run's abort signal and clears the queue, and every item checks that signal immediately before it creates anything, so a cancelled item does not leave a worktree on disk. Items that already completed stay.