Use Lookout
Worktrees
Give a chat its own branch and folder, merge its work back into your project, and reclaim old worktrees' disk with Free space.
A worktree gives a chat its own git branch in its own folder, apart from your checkout and other chats' work. Use one when several chats work on the same project at once, or when you want to read the work before it reaches your branch.
Start a chat in a worktree
Lookout creates a branch such as lookout/chat-720db589 (the start of the chat's ID) and checks it out in a folder
under ~/.lookout/worktrees/. The chat's tools, its
checkpoints and Changes all work in that folder.
The branch starts from the fetched tip of the branch your checkout tracks (the remote's default branch when the
checkout is detached or tracks nothing) when your checkout has no commits of its own past it, so a chat on a stale
checkout still starts current. A checkout with its own commits past that tip keeps them: the branch starts from its
HEAD, as does a checkout whose remote cannot be fetched. Pass base to start from a branch, tag or HEAD of your
choosing instead.
A brand new folder holds only what is committed: files such as .env and installed dependencies are not there until a
setup command brings them. When an earlier chat's worktree of the project was removed, Lookout
reuses its folder instead: it switches that folder to the new branch, so only the files that differ are written, and
installed dependencies and build output git ignores there are still in place. Every other file the earlier chat left,
such as its .env, is deleted first, and so are environment, key and Terraform state files inside build output. The setup command runs either way. Worktree can't be turned on for Scratch, which isn't a git
repository.
A worktree or clone you made yourself is not a new project either: open its folder and the chat starts in the project of its repository, working in that folder (Open a folder). Lookout neither merges nor removes it; that checkout stays yours.
Two chats in one folder
When two chats change files in the same checkout within ten minutes of each other, each is told once: which chat it
is, the files it changed, and how to message it, so neither undoes the other's work in progress. A shell command
counts only when it can change files git keeps in that checkout: a log written outside it or into a folder git ignores
doesn't, and a command that names the files it writes (a redirect, a copy, sed -i) has them named. A chat and its own
subagents are told only when both changed the same file. Edits made in place merge, so a file both sides only edited
in place isn't named, and when that is all that changed, nobody is told. The chat shows it as one row, Another chat changed files in this checkout, which opens on those files
and Open chat. Nothing is stopped or locked. A chat an agent or an orchestrator starts in a project folder another chat
is changing gets its own worktree, and the agent's answer says why, unless it asked for the folder itself (worktree
off, or a folder named). A chat you start yourself stays where you start it.
Land the work
The branch chip under the message box says where a worktree chat's work stands: Landed once your branch holds it, Conflicts while merging it into your branch would conflict, with the files in its tooltip.
Lookout commits what the chat left uncommitted in its worktree first: changed files and new ones, never the files git
ignores, build output such as node_modules, or a file holding a credential (the landing stops and names the file).
Then it works out the merge with your project's branch before anything moves, makes a merge commit, and moves the
branch only from the commit it merged onto. Your checkout follows by a fast-forward, which git refuses where your own
edits in it would be overwritten: then nothing lands, and the toast names the files. A toast reads Landed in and
your branch's name, or Already in when the branch holds the work already.
When the merge would conflict, nothing changes. The chat gets the conflicting lines and is told to merge your branch into its worktree, keep both sides, and commit. It starts on that at once; land it again once it says it is resolved.
Land and push lands on the remote's tip of your branch and pushes it, never forced. A branch behind the remote lands there and follows it; one with commits the remote lacks pushes them too. When someone pushed in between, Lookout lands again on what they pushed. The push uses this machine's own git credentials.
A chat working in your project folder, not in a worktree, lands the files it changed there as one commit on your branch. A file another chat is changing at that moment stops it.
An agent can land a chat when asked: it reads the chat's changes, lands it, and its chat shows a Merged row with your branch's name. The worktree and its branch stay either way; archiving the chat removes them.
When a chat's worktree was removed with commits not merged yet, Changes offers Land and Discard for them. Discard lets them go.
Run a setup command in each new worktree
Setup runs in each new worktree before the chat starts, and its output shows in the chat as Worktree setup. If it fails, Lookout doesn't send your message: it stays in the box, and the error says why. A chat an agent or another app starts answers at once, before its worktree is made: its first turn waits for the worktree and its setup, and if either fails the chat ends failed with the reason, its message kept. Teardown runs when Lookout removes the worktree.
Each command runs with sh -c in the worktree, counts as failed after 10 minutes, and gets these variables:
| Variable | Value |
|---|---|
LOOKOUT_BASE_REF | the branch, or HEAD, the worktree started from |
LOOKOUT_CHAT_ID | the chat's ID |
LOOKOUT_MACHINE | the name of the machine the chat runs on |
LOOKOUT_WORKTREE | the worktree's folder |
Lookout's own settings and a model provider's sign-in stay out of the command's environment.
A setup that copies your project's .env into the worktree and installs dependencies:
cp "$(git rev-parse --git-common-dir)/../.env" .env && bun installInstall dependencies in the worktree itself rather than linking your checkout's node_modules into it: through such a
link, the project's own workspace packages load from your checkout, not from the worktree's branch.
A project without a setup command
Without a setup command, a new worktree has no dependencies installed. When your project's folder holds a lockfile, Lookout says so and names the command that installs from it:
Lookout runs nothing until you set it.
| Lockfile | Command |
|---|---|
bun.lock, bun.lockb | bun install --frozen-lockfile |
pnpm-lock.yaml | pnpm install --frozen-lockfile |
package-lock.json | npm ci |
yarn.lock | yarn install --immutable, or yarn install --frozen-lockfile when the folder has no .yarnrc.yml (Yarn 1) |
uv.lock | uv sync --frozen, after the JavaScript command when there is one |
The worktree file
Lookout saves these commands in .lookout/worktree.json in your project. Commit it, and a clone on another machine has
the same commands, which run there once you approve them. The file can also set what the
shell gets in every chat of the project, worktree or not:
{
"setup": "bun install",
"teardown": "docker compose down",
"path": ["node_modules/.bin"],
"env": { "NODE_ENV": "development" },
"requires": ["bun", "docker"]
}| Key | What it does |
|---|---|
setup, teardown | the commands above |
path | folders put in front of PATH for the project's shell commands and hooks: ~/ is your home folder, a relative folder sits in the chat's folder |
env | variables for the project's shell commands and hooks. The file is committed, so never put a secret here. It can't set PATH or a LOOKOUT_ variable |
requires | commands the project needs: lookout doctor names the missing ones |
While the file has an error, a new worktree chat doesn't start, and the error says what to fix.
Approve a worktree file
Lookout runs a worktree file's setup, teardown, path and env on a machine only once you approve exactly what the
file holds there. What you save in Project settings is approved as you save it. A file that came with a clone, or
changed since you approved it (a pull, an edit outside Lookout), waits:
From another app, lookout_projects shows the file's trust and fingerprint under worktree, and
lookout_configure_project with approveWorktree set to that fingerprint approves it. Only you, or an app acting
for you, approves or writes the file this way: a chat's agent, from its shell, can't.
Remove a worktree
Archiving a chat removes its worktree's folder and its branch when nothing in the folder is uncommitted: no uncommitted
changes or untracked files. When the branch has commits not merged into your project's branch or its remote's default
branch, Lookout first parks them: the chat's ref refs/lookout/cs/<chat id> points at its last commit, with a reflog
entry for each commit it ever held, so the folder and the branch can go and nothing is lost. The next message to the
chat makes the folder again on them (When a chat's worktree is gone), and
lookout_worktrees shows the chat as parked. A commit landed by rebase or cherry-pick counts as merged when its change
is there (git cherry shows no +). Dependency and build output such as node_modules or __pycache__ doesn't count
as untracked. When the folder holds uncommitted work the worktree stays
and the archive's answer says why. Lookout checks such a worktree again every hour by the same rule, and removes it
once it is safe; archiving the chat again tries at once. The archive prompt's Keep it leaves the worktree and its
branch where they are, and the hourly check leaves it too. So does a worktree archived before Lookout recorded why an
archive kept it: it stays until you restore its chat from Settings › Archive and archive it again, or until
lookout worktrees reclaim removes it. Deleting a chat asks Remove the worktree? and removes it by
the same rule; its unmerged commits stay parked under the deleted chat's ref. An agent archiving a chat it
owns follows the archive's rule too (an agent can't keep one the rule would remove). An agent's archive answers at once
and the check runs after it: a worktree that goes shows in the archived chat as Worktree teardown, and the agent
hears in one notice each chat whose worktree stayed and why, and each whose worktree went: its folder, and its branch
at the commit removed and where that commit was merged, or the ref that parks it.
The check judges the commit the branch points to when it starts. If the worktree changes while it runs (a new commit,
a rebase, an edit) or a rebase, merge or cherry-pick is under way in it, the worktree and its branch stay and the
answer says so; a branch that moved after the check stays too. From its last look at the worktree to the removal,
Lookout holds the worktree's git index lock, so a commit or rebase started in it right then fails with git's own
index.lock message and changes nothing, and what Lookout removes is the commit it judged.
A worktree folder that is no longer a checkout (its .git went with the worktree git removed) counts as gone:
archiving marks it removed and deletes the folder when it holds only Lookout's own .lookout state. A worktree
whose branch was deleted is judged by its checkout's own commit instead.
Removing a project also removes its chats' worktrees that are safe to remove, and leaves the others on disk. Lookout
removes a chat's worktree at no other time than these, the hourly check of archived chats and
lookout worktrees reclaim.
A removed worktree's checkpoints go with it, so its chat's turns can no longer be reviewed or
restored. The chat itself stays readable. Its files are gone too: the chat's Files tab and
lookout files say the worktree was removed rather than show or change the project's checkout,
until a message makes it again (When a chat's worktree is gone).
A removed worktree's folder waits in ~/.lookout/worktrees/<project>/.pool/ for the project's next worktree chat,
which takes it over (Start a chat in a worktree). Lookout keeps up to six such folders per
project, deletes one after three days, never reuses one while a process is still running in it or while it has changes,
and deletes them all when you remove the project. Moving a folder into the pool or out of it rewrites that worktree's
own git links only, never another worktree's. Set LOOKOUT_WORKTREE_POOL to another number of folders, or to 0 to
delete every removed worktree's folder at once.
On a Mac the pool also keeps .seed, a checkout no chat works in. When no removed worktree is free, a new one is a
copy-on-write clone of it: its files take no disk space of their own until a chat changes them. Set
LOOKOUT_WORKTREE_SEED to 0 to have git write out every file instead.
Free the space archived chats' worktrees hold
When a disk fills up, archived chats' worktrees are often what holds it. Run lookout worktrees reclaim --dry-run
first: it lists every worktree an archived chat still has on this machine, with the space it takes, and removes
nothing. Add --on MACHINE for another of your machines. Then run it without --dry-run: each worktree goes by the
archive's rule above, its unmerged commits parked under the chat's ref, so the chat's next message makes its folder
again on them. A worktree with uncommitted work, one whose checkout is on another branch than its chat's, one whose
chat is running, and one you kept with Keep it stay, each with its reason, and the dry run names the same ones.
The folders it removes are deleted at once rather than kept in the pool. The space is
what du counts, so on a Mac, where a worktree shares blocks with the project by copy-on-write, less may come back.
--json prints the list for a script.
In the Mac app, Free space in Settings › Devices does the same for a device under 5 GB free, and for this Mac whenever its Disk space row shows: it makes the dry run, asks Remove 7 archived chats' worktrees? with the space they take and how many stay, then removes them and says on the row what went.
When a chat's worktree is gone
A chat outlives its worktree, whether an archive removed it or something outside Lookout did (a landing script that deletes the folder and branch it ran in, say). The next message to it (yours, an agent's Steer, a Delegate into its lane, or a Retry) makes the worktree again at the same folder before its turn runs, with the project's setup command: on its branch when the branch still exists in the repository or on its remote, or when its commits are parked under the chat's ref (the branch is made again on them), else on a branch from the base a new chat would get. The answer to the message says where and on what, and the chat's agent is told the old folder was removed, whether the branch's last commit is in the base, and that files that were never committed went with it. Lookout never runs the chat in the project's own checkout instead.
Something that wakes a chat without a message (a background command ending, a watch, a subagent finishing) does the same: the worktree is made again and the woken turn runs there, so a chat whose landing script removed its folder still reports how the landing went. A background command that ended while the folder was gone has its output file written back where the chat's notice says it is. Until its next turn, the chat's lane reads worktree removed in Sessions. Continuing a subagent of such a chat is refused until a message has made the worktree again.