Skip to content

Worktrees

View Markdown~3,900 tokens

A git worktree is another checkout of the same repository, with its own branch and its own directory. Caudra treats every checkout of a repository as one project. They share memory notes and plans, and a session can move from one checkout to another. /worktree creates, opens and removes worktrees from inside a session.

Inside a Herdr pane, Herdr creates and removes the worktrees and opens each one in a workspace grouped with the repository. Inside an Orca terminal, Orca does the same for repositories you added to Orca. Everywhere else, Caudra runs git itself. The commands are the same in every case.

Caudra identifies a repository by its git common directory, the .git directory that all of its checkouts share. Herdr groups workspaces by the same key. A linked worktree counts only when git records it from both ends: its .git file names an admin directory inside the repository, and that directory names the worktree back. A crafted .git file therefore cannot claim another repository's state. A separate clone is a separate project, even when it tracks the same remote.

Checkouts of one repository share memory notes and plan documents. Both live under the main checkout's project state directory. Trust in project config carries over when the content is identical, as described in Trust across checkouts.

Each checkout keeps its own sessions, scratch directory and stored permission rules. A rule can hold absolute paths, so it stays with the checkout where you granted it. To move rules deliberately, use caudra permissions rebind.

A worktree may have notes and plans of its own from an older Caudra release. The first time Caudra starts in that worktree, it copies them into the shared directory. Nothing is overwritten or deleted. A name that is already taken by different content is kept beside it as <name>.from-<branch>.

/worktree lists every checkout of the repository with its branch, its location and the number of sessions that work in it. The checkout of the current session is selected.

KeyAction
EnterOpen the selected checkout
Ctrl+NCreate a worktree
Ctrl+DRemove the selected worktree
Ctrl+RRefresh the list

/worktree new starts creating a worktree as Ctrl+N does, and /worktree new <branch> names the branch up front. /worktree close and /worktree remove both open the confirmation that closes or removes the checkout the session works in, as Ctrl+D does. The main checkout cannot be removed.

Opening a checkout outside Herdr moves every open tab into it, as /cd does. Inside Herdr, Caudra asks Herdr to open the checkout in its workspace. Herdr focuses the workspace when it is already open. Inside Orca, Caudra switches to a terminal Orca has open in the checkout, or opens one there.

Caudra first asks for the branch name. Leave it empty to have one generated. /worktree new <branch> skips this question.

Press Enter to open the form with Create worktree selected. A second Enter creates it. To change a field, select it and press Enter. Finishing an edit returns to Create worktree.

The form has these fields:

FieldMeaning
BranchThe branch to check out. An existing branch is checked out as it is. Leave it empty to have one named for you.
Start atA branch, tag or commit of the current checkout. The default is HEAD.
Carry uncommitted changesShown only when the current checkout has changes.

The session that created the worktree moves into it. It works in the same subdirectory there when that subdirectory exists, and otherwise at the worktree root. The session ID and conversation stay the same, and so does its plan, because the project state is shared. Permissions approved for the conversation and YOLO mode are detached, because they were granted for the directory the session left.

Caudra checks that the session can move before it creates anything. An active or paused workflow of the session stops the worktree. So does a pending revert of the session, or a pending file revert of another session in the same directory. The notice names that session. Unrevert there or send it a prompt, then try again.

Uncommitted changes carry over through git stash. The stash is taken in the current checkout and applied in the new worktree, so the changes leave the current checkout. Carrying works only when the worktree starts at HEAD, because that is the one commit where the changes are sure to apply. If applying fails anyway, the changes go back to the current checkout and the worktree is kept.

Outside Herdr, git creates the worktree under worktrees.directory as <directory>/<repository>/<branch>, with the branch turned into one path component. A branch named for you starts with caudra/. The process then follows the session into the worktree and reloads the project config there. See [worktrees] for the settings.

Inside Herdr, Herdr creates the worktree and a workspace grouped with the repository's own. Herdr names the branch when you leave it empty. The session continues in the root pane of the new workspace. Caudra labels that pane and its Herdr tab with the branch. Its tab closes in the current pane. When that tab was the last one, Caudra exits and the pane returns to its shell. If Herdr cannot start the session in the new pane, Caudra stays open with a fresh session and shows the command that resumes it.

Inside Orca, Orca creates the worktree and lists it in its sidebar. Orca needs a name, so Caudra generates one starting with caudra/ when you leave it empty. Orca may adjust the name it is given. The session continues in a new Orca terminal in the worktree, titled with the branch, and the current terminal behaves as it does in Herdr. When Orca does not know the repository, git creates the worktree as it does outside Orca, and the notice says so.

The new pane runs the same Caudra executable. If an upgrade replaced it while Caudra was running, the pane runs the replacement at that path. If neither file remains, the pane runs caudra from PATH.

Closing is the reverse of creating a worktree. The commits and uncommitted changes of the worktree come back to the main checkout, its sessions move there, and the worktree is removed. The confirmation for a removal lists Bring the work back to, followed by the main checkout's path, as its first choice and says what that brings back.

The commits come back by a fast-forward of the main checkout's branch to the worktree's commit. Caudra never creates a merge commit or rebases. Uncommitted changes come back through git stash, as they do when a worktree is created, and only into a clean main checkout at the worktree's commit, because that is where they are sure to apply.

Closing is not offered, and the confirmation says why, when:

  • the main checkout has commits the worktree does not have. Merge or rebase the branch first.
  • the worktree has uncommitted changes and the main checkout has changes of its own. Commit or stash the main checkout's changes first.
  • the main checkout has moved past the worktree's commit and the worktree has uncommitted changes. Commit them in the worktree first.

Sessions move back as they do for a removal, and the changes come back once they have moved. If the changes still do not apply, they stay in the worktree, the worktree is kept, and Caudra says why. The branch is kept, so git branch -d <branch> deletes it once you no longer need it. Orca deletes it itself, because a fast-forward leaves it fully merged.

Removal keeps the branch, except inside Orca. When the worktree has uncommitted changes, the confirmation offers two ways forward:

  • Stash uncommitted changes, then remove. The changes are saved with git stash. Stashes are shared by every checkout of the repository, so git stash apply brings them back in any of them.
  • Discard uncommitted changes and remove. The worktree is removed with --force.

Sessions that work in the worktree move back before it goes. They go to the same subdirectory of the main checkout when it exists, and otherwise to the main checkout root. If they cannot move, the worktree is kept and Caudra says why.

Caudra checks that every session working in the worktree can move before it stashes, merges or removes anything, as it does when it creates a worktree.

Inside Herdr, closing or removing a worktree also closes its workspace. When the current pane is in that workspace, every session open in Caudra continues in a tab of its own in the repository's workspace, or in a new workspace when the repository has none open. Each tab is labelled with its session's title, and the focused session's tab opens last, so it keeps the focus. Caudra then exits, and the removal runs in its own process, because Herdr closes the pane that started it. If a session cannot start in its tab, the worktree is kept and Caudra shows the command that resumes it.

Inside Orca, Orca removes the worktree. When the current terminal is in that worktree, every session open in Caudra first continues in a terminal of its own in the repository's main worktree, and Caudra exits. Orca also deletes the worktree's branch when it is fully merged, so removal keeps only unmerged branches.

A worktree can also be removed outside Caudra, by git worktree remove, by Herdr, or by deleting the directory and pruning. Caudra records each linked worktree while it exists, so it can still find the sessions left behind. It moves them back:

  • when Caudra starts in the repository,
  • when /sessions or /worktree opens,
  • when caudra --session <id> resumes a session from a removed worktree.

A session goes to the checkout git moved the worktree to, if it was moved rather than removed. Otherwise it goes to the same subdirectory of another checkout, or to the main checkout root. A session that another Caudra process has open stays where it is until a later pass finds it free. The usage recorded for a directory moves with its sessions once all of them have moved.

/sessions lists the sessions of the current directory first. Below them, it lists the sessions of each other checkout of the repository, one section per checkout. Opening one of those sessions outside Herdr moves the tabs into its checkout, as /cd does, and then focuses the session. Inside Herdr, Caudra opens the checkout in its Herdr workspace and resumes the session in a pane there. When another Caudra process already has the session open, only the workspace is focused. Inside Orca, Caudra resumes the session in a new terminal in that checkout. See Sessions for other ways to move sessions.

A checkout inherits trust that you granted at the same place in another checkout of the repository when the trusted content is identical. Inheritance works in both directions between the main checkout and its worktrees. It covers project permission config, project MCP servers and project workflows. Each kind compares its own digest, so an edit in one checkout needs fresh trust there and leaves the other checkouts trusted.

Grants stay on the exact path where you made them. Revoking trust in any checkout also revokes it at the same place in every other checkout, since each of them could otherwise still inherit it.

In a linked worktree, the environment block the model receives names the branch and the main checkout, for example - Git worktree: branch feature/login, linked to /work/app. The line is left out when tools run on a remote workspace.

When a session moves to another directory, the model is told the old and the new working directory once, together with the new environment. Paths from earlier in the conversation would otherwise still look valid, and in another checkout they point at the wrong files.

Inside Herdr, the herdr skill is available through the skill tool. Its content is what herdr --skill prints, so it matches the installed Herdr release. A skill named herdr on disk takes precedence. Shell commands get the variables Herdr sets in the pane, such as HERDR_ENV and HERDR_PANE_ID, so the skill's own Herdr check passes and its examples address this pane. Commands on a remote workspace do not get them. Suggested permission patterns for herdr keep three words, so approving herdr pane read w1:p2 offers herdr pane read * rather than a rule for one pane.

Inside Orca, the orca skill works the same way. Its content is what orca skills get orca-cli prints. Shell commands get the variables Orca sets in the terminal, such as ORCA_TERMINAL_HANDLE and ORCA_WORKTREE_ID. Orca's hook and launch tokens and its cloud credentials are never passed on. Suggested permission patterns for orca also keep three words, so approving orca terminal send --terminal t1 offers orca terminal send *.

Caudra detects Herdr from the environment Herdr gives every process it starts in a pane. Besides worktrees, Caudra reports to Herdr:

  • the agent state, with the prompt that blocks it, such as Permission requested: shell,
  • the title of the focused session, the model and the context usage, shown in the Herdr sidebar,
  • the command that resumes the focused session, caudra --session <id>.

Caudra also names the pane's tab after the focused session while the tab still shows its number, as Tab names describes.

After a Herdr restart, Herdr runs that command in the restored pane, so the focused tab comes back. Other tabs stay available in /sessions. A fork opens in a new Herdr tab with a Caudra of its own, as Forks in Herdr and Orca describes. See CLI for how reporting works and Notifications for how notifications change inside Herdr.

Native Herdr reporting takes precedence over OSC 7501 pane status, so Caudra does not probe for or send OSC 7501 while the native reporter is active.

Caudra detects Orca from the variables Orca sets in each terminal, ORCA_PANE_KEY or ORCA_TERMINAL_HANDLE. Herdr running inside Orca counts as Herdr. Besides worktrees, Caudra reports the agent state, the model and the label of the blocking prompt. See Notifications for what the report contains and how notifications change inside Orca. The window title carries the session title, which Orca shows on the terminal's tab until you rename it. See Tab names.

Orca cannot restore a Caudra terminal after a restart. Your sessions stay available in /sessions and through caudra --session <id>. A fork opens in a new terminal in the current worktree, as Forks in Herdr and Orca describes.

Website privacy and analytics