Worktree

Isolate changes in per-session Git worktrees and check them back to local branches after approval.

dsh-tauri-worktree creates an isolated Git worktree for a session. Make changes there, then choose whether to check the work back to a local branch or discard it.

Select a worktree

Work in the worktree session

Start isolated work

• The current session is in a local Git repository, and the host can run git.
• A local main branch must exist. New worktrees start from refs/heads/main, not the current branch.
• The composer shows the mode picker only for a confirmed Git repository outside a worktree.

1. Explicitly choose Worktree

   Select Worktree in the composer and send your request, or explicitly ask the Agent to use a worktree. create_worktree is for local sessions only; do not call it from an existing worktree session.
2. Create the worktree and session

   The default directory is ~/.dsh/worktrees/[hash]/[dirname]; with DSH_HOME set, its worktrees subdirectory is used. The tool hands off context after the current turn. Composer-based switching transfers the draft and attachments.
3. Change, verify, and commit

   Continue in the new directory. The composer status bar provides creation progress, logs, checkout, and discard actions.

Check out or discard

Call checkout_worktree only after a direct human user explicitly requests or approves it. Task completion, commits, a merged PR, or Agent convenience are not authorization. Ask first when needed, then wait for approval.

Action	Result
Check out	Preserves committed work, switches to your requested local branch, and removes the isolated worktree on success. It does not automatically merge into the main branch. UI checkout creates a local session with inherited context and archives the worktree session.
Discard	Deletes the isolated directory and archives the session after confirmation. Save any code you need first: archiving a session does not preserve uncommitted files.

Before checkout:

• The local main workspace must have no uncommitted changes and must not be in detached HEAD.
• The isolated worktree must have no unstaged or untracked changes; commit anything you need to retain.
• If staged changes remain in the worktree, enable carry_staged or commit them first. Otherwise checkout is rejected.
• An existing target branch must not be occupied by another worktree or contain commits absent from the isolated worktree. Matching branches can be reused; lagging branches can fast-forward.

Staged changes and tool parameters

carry_staged defaults to false and handles only changes in the Git index. Committed work does not depend on this switch.

Tool	Branch and directory parameters	With carry_staged: true
create_worktree	Adds the dsh/ prefix when branch_name omits it.	Carries source-repository staged changes into the new worktree. Unstaged and untracked content stays in the source repository.
checkout_worktree	Uses [hash]/[dirname] for worktree_hash_dirname; uses branch_name exactly as the local branch name.	Carries the worktree’s staged changes into the local target branch before removing the worktree.

The transfer uses Git binary diff/apply, not the repository’s shared stash. UI checkout has no carry_staged option: commit staged changes first, or explicitly authorize the Agent to use the tool with that parameter.

Failures and boundaries

If creation or checkout fails, inspect the status bar and logs, follow the error message, and retry. Do not manually delete a worktree directory that is still bound to a session. A failed checkout may retain the worktree, binding, and recovery information; it does not mean the session has returned to the local workspace.

Git worktrees isolate working directories, not local execution permissions. Harness and plugins can still execute local code; profiles are not operating-system sandboxes.

View source