Create a Worktree
Create a worktree from a new branch, existing branch or pull request, copy ignored local files, finish setup and submodules, and start an agent with its first task.
Creating a Worktree
Open the Create worktree dialog from the + button in the sidebar header (Create new worktree), with Command-K, then Command-N Control-K, then Control-N Control-K, then Control-N , from the action palette, or by right-clicking empty space in the sidebar and choosing New worktree…. The dialog creates a worktree on a new branch or on an existing local branch; opened from a pull request, it checks out that PR's branch instead.
The form has three sections. Branch carries the New branch / Existing branch toggle in its header. Destination is the worktree's folder. Setup holds what happens once the worktree exists: the linked issue, the environment, the recipe, and an agent to start. A line beside the buttons says what the form is about to do (the branch it will create and its base), or what is still missing, so pressing Create worktree early names the missing field rather than doing nothing. Command-Enter Control-Enter Control-Enter submits from anywhere in the dialog.
The dialog closes as soon as you submit. A placeholder card holds the new worktree's place in the sidebar while Git works, and turns into the real card when the checkout exists. Closing the dialog with something filled in asks first: Discard changes?
Once you have added a remote host, the dialog also has a Host row listing this machine and your hosts, with hosts that aren't connected grayed out and a suggestion for the least loaded one. Choose another machine and a Create on studio-02… button appears beside it, in place of the usual create button, which brings the project across first and then creates the worktree there. With a cloud provider account connected, the row also offers New machine · Boat (or the account's name), which creates the worktree here and then a machine of its own for it; see Run a New Worktree on Its Own Machine. See Create a Worktree on Another Host.
New Branch
This is the default mode. Its fields:
- Base: a searchable picker with fuzzy matching and a Recent band. Each branch shows when it was last committed to, and a branch already checked out in another worktree reads in use, followed by that worktree's name when it differs from the branch. Defaults to the current branch, then
mainormaster, then the first available branch. Below it, Create from remote branch bases the worktree on the remote tracking branch; it is checked automatically when the chosen base is remote. - 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/andwip/. Aliases are normalized:featbecomesfeature,fixandhotfixbecomebugfix. A name that already exists gets a numeric suffix (feature/login-1) and the hint Renamed to avoid a conflict with an existing branch. - Path, under Destination: generated from the branch name using the project's path pattern (Project Settings > Worktree setup > Worktree path pattern), which falls back to the global default in Settings > Worktree. Edit it by hand or use the folder picker. A path that already exists gets the same numeric suffix and the hint Renamed to avoid a conflict with an existing directory.
- Issue (optional), under Setup: a searchable issue selector, shown when the project's forge provides one (the built-in GitHub provider does; GitLab does not). 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 andfeaturewhen neither says. Once an issue is linked and the forge knows who you are, an Assign to @{login} checkbox appears under it. The checkbox is remembered across sessions, and after creation an Issue assigned notice offers Undo for five seconds. - Environment: Local plus one choice per configured resource environment. Picking one adds the line Provisions the {name} environment after setup. The whole row is hidden when the project has no environments. See Remote Compute.
- Recipe: the layout to open in the new worktree: Clone current layout, No recipe, or one of the project's recipes. It starts on the recipe you picked last time in this project, otherwise the project's default recipe, otherwise Clone current layout. The row is shown when the project has saved recipes or an agent is chosen below; with neither, the current layout is cloned. See Recipes.
- Agent and Prompt: an agent to start in the worktree once it is ready, with an optional first task. See Starting an agent.
~ ^ : ? * [ \, no .., @{ or //, no leading -, no leading or trailing /, no trailing . or .lock, and no path segment that starts with .. Windows device names such as CON or NUL are refused as segments too. The dialog checks the full name with the same rules the backend applies, and shows the problem under the field.Existing Branch
Use this for a branch that already exists locally: resuming interrupted work, or picking up a branch created outside Daintree. The base picker and the name input collapse into one 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 clears the branch selection and any validation errors.
PR Checkout
Create a worktree straight from a pull request with the Create worktree action on a PR in the Code Forge panel. The dialog opens in PR checkout mode: the title becomes Check out PR branch, the mode toggle is hidden, a banner shows the PR number and title, the issue row is gone, and the button reads Check out.
Daintree resolves the PR's branch in order: an unambiguous exact remote tracking branch (<remote>/{headRefName}), then the local branch, then a fetch of the PR's head ref from the forge's remote (pull/{number}/head on GitHub), then a re-check for the now-local branch. The fetch runs on its own; you don't need to type any git commands. Pull requests from forks are supported and are not filtered out of the PR list or the bulk-create plan.
If the branch still can't be resolved, the dialog says so and won't create anything, rather than quietly building the worktree from a different branch:
{headRefName} didn't come down from the remote. Run git fetch origin, then reopen this dialog.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.namewhen the worktree is created, slugs it to lowercase, and prepends it asalice/. - 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
Problems the form can see before submitting appear under the field they belong to: a missing base, an empty or invalid name, a missing path. A branch list that failed to load says so under the picker.
A failure after you submit lands on the placeholder card in the sidebar, since the dialog has already closed. The card turns into Couldn't create {branch} with Git's error underneath and two buttons: Retry reopens the dialog with the branch name, recipe, agent and prompt filled back in, which is where a conflict such as a branch already checked out elsewhere gets fixed; Dismiss clears the card. See Placeholder cards during creation.
Copying Local Files Into a New Worktree
A worktree is a fresh checkout, so files Git ignores, such as .env, local certificates or editor settings, are not there. List them in a .worktreeinclude file at the project root, using .gitignore syntax, and Daintree copies the matching files from the main checkout into every new worktree, keeping their relative paths:
# .worktreeinclude
.env
.env.local
certs/*.pem A file is copied only when it matches a pattern and Git ignores it, so tracked files never come across. Git itself evaluates the patterns, so gitignore semantics hold exactly. The copy never overwrites a file that already exists in the new worktree, skips symlinks and anything that resolves outside the repository, and never touches .git.
The include list is meant for small local config, not dependency trees, and is capped at 10 MB per file and at 100 MB and 1,000 files per worktree. Anything past a cap is skipped and logged. A .worktreeinclude over 64 KB, or one that is missing or can't be read, copies nothing and never fails the worktree. For node_modules and other installs, use a setup command in lifecycle scripts instead.
Starting an Agent in the New Worktree
The Agent row in the dialog's Setup section starts an agent in the worktree once it is ready to work in. Choose one of your installed agents, or No agent. With an agent chosen, a Prompt box appears for an optional first task (First task for the agent); leave it empty to start the agent without one. The choice of agent is remembered per project.
The agent waits for the worktree's setup to report ready, for up to five minutes, then launches with your prompt as its first turn. If setup fails, times out, is still running at five minutes, or is waiting for you to approve its commands, the agent is not started. Instead a notice above the panel grid reads Agent not started, says why, and keeps your prompt: its Start {agent} button launches it when you are ready, waiting again for setup still in progress. The same notice appears if the agent itself fails to launch.
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. Bulk creation is part of the built-in GitHub provider. 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 reduces repeated startup work when several worktrees use the same layout.
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.
Cancel stops queued work and further steps. Worktree creation itself has no abort API: an already-started Git request can still finish and leave a worktree on disk. Completed work is retained, and cancellation reports the resources created so far. Check the resulting worktrees before starting another batch.
Setup and Submodules
Creation first returns the Git checkout, then finishes setup in the background, in this order:
- Copy the project's
.daintree/directory into the worktree, without overwriting anything already there. - Copy the files listed in
.worktreeinclude. - Initialize submodules.
- Run the project's setup commands from its lifecycle scripts.
- Provision the resource environment, when one was chosen.
A worktree appearing in the sidebar does not mean those steps have finished.
Setup commands that come from the repository, rather than from your own user-level config, run only after you approve them. Until then, setup stops before running anything, and the card shows Setup is waiting for you to approve its commands with a Review commands button. The dialog lists the exact commands, file by file; Approve and run setup approves those lines and finishes the setup. Approval covers the exact command text, so any later change to it asks again. See lifecycle scripts.
By default, a new worktree initializes the direct submodules already initialized in the source checkout. Programmatic creation also supports submoduleInit policies all and none. Initialization runs before setup scripts; a failure is recorded while the remaining setup still runs, and the setup then reports failed rather than ready. Check the final setup state before starting builds that depend on submodules.
The Assistant’s worktree.waitUntilReady action, which the dialog's agent start also uses, waits for that setup result. It reports a setup failure, a timeout or a pending approval rather than treating the presence of the directory as readiness. See the workspace creation implementation and lifecycle script reference.