Worktrees

This page explains where an agent does a ticket’s work, and what happens to that work between runs. By the end you’ll know why two tickets never get in each other’s way, what carries over when you start a ticket again, and when By Dawn clears old work to free disk space.

When an agent starts on a ticket, it gets a worktree for each repo the ticket works in: a checkout of the repo on the ticket’s own branch, in a folder of its own on the machine running the agent. Every ticket gets its own, so several agents can work in the same repo at once without touching each other’s files, and your own checkout is never changed.

A ticket that works in three repos has three worktrees, one per repo, each on the ticket’s branch in that repo (Branching and CI says how that branch is named and where it starts).

Where they live

Worktrees live on the machine that runs the ticket’s agent: your own computer with the desktop app, or a remote agent your organization runs. They sit under one folder, ~/.saw/worktrees unless the machine is set up otherwise.

With the desktop app, Settings›, then You›, then This computer shows that folder as Worktree root. You don’t need to open it, though: the ticket’s Changes and Code views show what’s in its worktrees from anywhere, and its terminal opens in them.

When a worktree is made

The first time an agent starts on a ticket, the card shows it getting ready, step by step: “Claiming the ticket”, “Fetching the repository”, “Cloning the repository”, “Creating the worktree”, “Installing dependencies” and “Starting the agent”. The worktree starts from the branch the ticket’s pull request will open into, so the agent begins from the latest code there.

Starting the ticket again

The worktree stays after the agent finishes, so starting the ticket again (Start a new run, or Retry) picks up where it left off: the same worktree with every change in it, and the same conversation, so the agent remembers what it did.

Choose ⋯ next to the start button for two other ways to start:

• Start with a fresh conversation: the agent starts without its earlier conversation, but “The worktree and its changes are kept.” Use it when the agent has gone down the wrong path and you’d rather it looked at the work with fresh eyes.
• Run on any machine (starts from the base): see below.

Work that hasn’t been pushed

Changes the agent hasn’t pushed yet exist only in its worktree, on that one machine. So a new run goes back to the same machine, and the ticket says so: “This ticket’s unpushed work is on mac-mini-2, so a new run goes there.” If that machine is offline, the run waits for it.

When you’d rather not wait, Run on any machine (starts from the base) lets another machine take it. That machine builds a new worktree from the base branch, without the commits on the first one. They’re kept there until it comes back, so nothing is lost.

When By Dawn clears a worktree

Worktrees take disk space, so By Dawn clears ones that are finished with:

• When the ticket is done. Once a ticket reaches a completed column, such as Done, a remote agent clears its worktrees.
• When a machine runs low on space. The agent clears finished worktrees and old caches until there’s room again. It never touches a worktree with a live session, and never deletes files that By Dawn didn’t create.

Clearing a worktree doesn’t lose committed work. The ticket’s Changes and Code can still show what was committed, and its pull request, but nothing can be edited, and “The worktree was reclaimed” explains why Uncommitted and Whole branch are greyed out. Once the machine’s copy of the repo is gone too, the views say “This ticket’s code was cleared from its machine — reclaimed work is kept for 30 days.”

Starting a ticket whose worktree was cleared makes a new one from its pushed branch.

Disk space on remote agents

An org admin can see each remote agent’s disk in Settings›, then Organization›, then Remote agents: how much of the disk holding its worktrees is free, and Disk breakdown, which lists what’s using it, such as By Dawn’s own worktrees, caches and Docker. A machine shows Low disk space when less than 10% is free, and Disk almost full below 5% or 5 GB.

When the disk is critically full, the machine stops taking new jobs (“Paused: disk critically full”), clears space, and starts again on its own once there’s enough. Its waiting jobs move to another machine after a few minutes. If the space is taken by files outside By Dawn, clearing worktrees won’t help, and the machine says so: free space on it yourself.

FAQ

Can I work in a ticket's worktree myself?

Yes. Edit a file from the ticket’s Code view, or open the ticket’s terminal, which starts in its worktrees. The agent sees your changes on its next look.

Does starting with a fresh conversation throw away the agent's changes?

No. Only the conversation starts again. The worktree and every change in it are kept.

Two tickets change the same file. Will they clash?

Not while they work, because each has its own worktree and branch. They can conflict when their pull requests merge, like any two branches, and By Dawn brings the worker back to fix a conflict if the mission’s Keep it mergeable step is ticked (see Pull requests).