Worktrees

One session per git worktree, and one prompt fanned out to several agents at once.

A git worktree is a second checkout of a repository on its own branch. It is a good place to put one agent: it has its own files and its own branch, and it shares nothing with your working copy. TUIOS makes the worktree and a session inside it with one command, and the rail groups every such session under its repository, labelled by branch.

Creating one

Run this inside a repository:

tuios worktree new feat/retry

Created branch feat/retry in /home/u/.local/share/tuios/worktrees/api/feat-retry.
Created session 'api-feat-retry'.

• A branch that does not exist is created from --base, or from HEAD.
• The worktree goes under $XDG_DATA_HOME/tuios/worktrees/<repo>/<branch>.
• The session is named <repo>-<branch>, with every / turned into -. --name picks another name.
• The session attaches at once. --detach (-d) creates it without attaching.
• --repo points at another repository instead of the current directory.

--agent starts an agent CLI in the session instead of a shell. Name it the way you type it:

tuios worktree new feat/retry --base main --agent claude --detach

A session you start by hand inside a worktree is recognised too. The daemon reads the directory, so it never runs git to find out.

From the rail

(Added in v0.9.3)

1. On the session rail, right-click the header of a repository, or the row of a worktree session.
2. Select New worktree....
3. Type the branch.
4. Optionally, type a session name. With no name, TUIOS makes one from the repository and the branch.

TUIOS makes the worktree and its session, and attaches to it. The dialog does not ask for a folder. The worktree goes under the worktree folder of the daemon: TUIOS_WORKTREE_DIR in the environment of the daemon, or $XDG_DATA_HOME/tuios/worktrees. A notification shows where the worktree is.

Listing and comparing

tuios worktree ls
tuios worktree ls --repo api

Each row shows the session, repository, branch, the agent state inside it, how many uncommitted changes it holds, and its pull request and checks once tuios ship pr opened one. A row marked gone is a session whose worktree directory was removed. The session is kept, so what the agent printed can still be read.

Merged worktrees

(Added in v0.10.0)

The MERGED column shows into <ref> when the branch is merged. A branch is merged when it has commits of its own and its base already holds them. tuios checks the base, then the upstream of the base, such as origin/main, as git last fetched it. tuios does not fetch.

• A merge commit, a fast-forward, a rebase and a squash merge all count.
• A new branch with no commits is not merged.
• A branch that only fast-forwarded to its base is not merged.
• A commit and its revert are not merged.

tuios worktree ls --json gives merged and merged_into. tuios does not remove a merged worktree. Use worktree rm to remove it.

tuios worktree diff api-feat-retry
tuios worktree diff api-feat-retry --stat

worktree diff prints the commits the session made on top of its base, then its uncommitted changes, then its untracked files.

Removing one

tuios worktree rm api-feat-retry

This runs git worktree remove and kills the session. A worktree with uncommitted changes is refused and nothing is removed. Choose what happens to the changes:

Flag	Effect
--stash	Move the changes into the repository's stash as tuios: <branch>, then remove
--force	Discard the changes. The only option that throws work away
--keep-session	Remove the worktree and leave the session running

Removing a worktree also deletes the checkpoints taken in it.

Note

Branches are never deleted

Every commit made in a worktree stays in the repository. TUIOS never deletes a branch and never runs git worktree prune.

Fan-out: one prompt, several agents

tuios fan starts the same prompt in several agents at once, each in its own worktree. When they finish, compare the results and keep the best one.

tuios fan 3 --agent claude 'Add a retry with backoff to the HTTP client.'

Started 3 agents on fan/add-retry-backoff-http. Each prompt is sent when its agent is ready.
  api-fan-add-retry-backoff-http    fan/add-retry-backoff-http    ...
  api-fan-add-retry-backoff-http-2  fan/add-retry-backoff-http-2  ...
  api-fan-add-retry-backoff-http-3  fan/add-retry-backoff-http-3  ...

• The count is 1 to 16.
• The branches are a stem, then stem-2, stem-3 and so on. The stem is fan/ plus the first words of the prompt, or --name.
• --agent is required. Name the agent the way you type it, arguments included: claude, "codex --model o5", or any program. Several, separated by commas, are cycled across the sessions, so --agent claude,codex,gemini with a count of 3 starts one of each.
• --prompt, given once per session, gives each session its own prompt. The count is then how many there are.
• --env NAME passes your value of a variable to every agent, and --env NAME=VALUE sets one. PATH is always sent.
• --base sets the ref every branch starts from.
• --grants says what every agent may do through TUIOS. See What a pane may do.
• The prompt is not typed the moment the agent starts. TUIOS waits until the agent is at its prompt, then types it, so it never lands in a start-up screen. An agent that has not shown its prompt after 30 seconds, most often because it asks a first-run question such as whether to trust the folder, puts a question in the Inbox asking you to look at its pane. Its prompt is typed as soon as it is ready.
• --wait makes the command return only when every prompt has been sent or given up on.
• --host runs the fan-out on another machine. See Remote Hosts.

Follow the run:

tuios worktree ls --group fan/add-retry-backoff-http
tuios wait-for agent-state --select 'group:fan/add-retry-backoff-http' --until idle,done --every --timeout 3600000

The --group listing shows whether each prompt is pending, sent or not_sent.

Comparing and keeping one

fan compare shows every attempt on one line: its agent and state, the files and lines it changed against the fan's base (committed or not, untracked files included), and its last check.

tuios fan compare api-fan-demo

fan/demo in api, 2 attempts against main
  api-fan-demo    bash  none  0 files  +0 -0  no check yet
  api-fan-demo-2  bash  none  2 files  +2 -0  no check yet
Keep one with 'tuios fan keep <session>'. Compare two with 'tuios fan diff A B'.

fan verify runs one check in every attempt, in a window named verify in each session, and says which passed. It always runs the command you give, never one read from the repository, and the window holds no grants. A window whose check passed closes. One whose check failed stays open so you can read the output. The command exits 1 when any check failed.

tuios fan verify api-fan-demo -- 'test -f b.txt'

Running "test -f b.txt" in 2 attempts of fan/demo.
  api-fan-demo: failed, exit 1 in 0s. Its verify window is open with the output
  api-fan-demo-2: passed in 0s
1 of 2 passed.

fan compare then shows each check's result in its last column. fan diff shows what one attempt did differently from another, and tuios review shows one attempt's changes with notes you can send back to its agent. See Reviewing an agent's changes. The review overlay's compare view (Ctrl+B v, then w) does all of this from the keyboard.

tuios fan diff api-fan-demo api-fan-demo-2 --stat
tuios review api-fan-demo-2

Keep one and remove the others:

tuios fan keep api-fan-add-retry-backoff-http-2 --stash

The session you name is untouched. Each sibling is removed the way worktree rm removes it. A sibling with uncommitted changes is left in place unless you pass --stash or --force.

To land the kept attempt too, add --merge:

tuios fan keep api-fan-add-retry-backoff-http-2 --merge --squash

--merge first merges the kept attempt's branch into its base in the main checkout, as tuios ship merge does. --squash, --ff-only and --into choose how. When the merge conflicts or is refused, it is undone and no sibling is removed. Uncommitted changes in the kept worktree are not merged, so commit them first with tuios ship commit.

Work from another machine

worktree new --host and fan --host run on a machine from the [hosts] table, and so does start-agent -s HOST:SESSION. The repository is the one the current directory is in, found on the host by its origin URL under the host's repos_root, and --clone clones it there when the host has none. The agent must be installed on that machine.

worktree pull brings the work back:

tuios worktree pull build:api-fan-add-retry-2
tuios worktree pull build:api-fan-add-retry-2 --branch try/retry-build --detach

The session's commits come across as a git bundle into a new branch here, and its uncommitted work, untracked files included, as a patch applied in a new worktree on that branch. Nothing on the other machine changes. A branch that already exists here is refused, so nothing is overwritten.

From a script

The commands are wrappers over the new-worktree, list-worktrees, remove-worktree, fan, compare-fan, verify-fan and keep-fan verbs. --json on each command gives the result as JSON.

{"id":1,"verb":"fan","params":{"count":3,"agent":"claude","prompt":"Add a retry.","repo":"/src/api"}}

See Control Protocol and tuios list-verbs fan.

Related

• Ship: Commit, merge, push and open a pull request from a worktree
• Checkpoints: Read and undo what one turn changed
• Agents: The agent state each worktree session reports
• Agent Messaging: Let the agents talk to each other
• Session Rail: Worktree sessions grouped under their repository
• Sessions: What a session is and how it persists