Start on a new worktree

New Worktree starts an agent in a clean git checkout of the Workspace’s repository, on its own branch. The agent works there without touching your main checkout or any other agent’s files.

Start an agent on a new worktree

1. Open the New Agent sheet and pick a Host and a Workspace inside a git repository.
2. Turn on New Worktree.
3. Type a Branch, or leave it empty for a generated name such as worktree/calm-river-3f2a.
4. Pick the agent and tap Start.

As you type a Branch, Waycar turns spaces and characters git doesn’t allow into -, and fills in the agent’s name to match until you type a different one.

Where does the new branch start?

By default, Start From Latest Main is on: Waycar first fetches origin’s default branch (usually main) on the Host and starts from its newest commit, so the worktree isn’t built on an old local copy. If the fetch fails, nothing is created and the sheet says why.

Turn off Start From Latest Main to start from the Host’s current checkout. A Base field then appears where you can type a branch or commit; empty means HEAD. Waycar remembers whether the switch is on.

What you see while it starts

The status line in the sheet shows each step, such as “Getting the latest main from origin”, “Creating the worktree” and “Opening the agent”, with the seconds spent on a slow one.

Good to know

• If you start on a branch that is already open in a worktree, Waycar opens that worktree instead: its running agent if it has one, otherwise a new tab in it.
• Tapping Start again after an error, or a slow answer from herdr, doesn’t make a second worktree. Waycar finds the one it already made and continues there.
• A Workspace that isn’t inside a git repository can’t make a worktree.

See a worktree’s details

Open an agent that runs in a linked worktree, open the More menu, and tap Worktree Details. The item only appears for agents in a linked worktree. The Worktree sheet shows the Repository, the Branch (or Detached HEAD), and the Checkout Path on the Host. If the branch can’t be read, tap Retry.

Remove a worktree when you’re done

1. Open More › Worktree Details on an agent in that worktree.
2. Tap Remove Worktree.
3. Read the confirmation “Remove worktree?” and confirm.

Removing deletes the checkout on the Host and closes its whole Workspace, ending every agent and closing every pane in it. The local branch is kept, so no commits on it are lost. The confirmation warns you when an agent is still working there. This can’t be undone.

When it’s done, you see Worktree Removed. Tap Back to Console.

If removal fails

Waycar shows Couldn’t Remove Worktree with the reason:

Message says	What to do
it “has modified or untracked files”	Commit or discard those changes on the Host, then retry.
“herdr is already changing a worktree on this Host”	Wait a moment, then retry.
“The Host is not connected.”	Reconnect, then retry.

If you see Removal Unconfirmed, the Host didn’t say whether it finished. Close the sheet, wait for the Console to refresh, then open Worktree Details again.

herdr and tmux

On herdr, each new worktree becomes its own Workspace, and the Console shows it under its repository. On tmux, the worktree opens as a new tmux session. Either way the Host needs git, and Remove Worktree works on both.