Skip to main content
This guide frees the disk that idle git worktrees take up on one of your machines, and brings one back when you want its work again. Agents create many worktrees, each with its own node_modules and build output. Each machine’s daemon does the reclaiming, on that machine only. Before it deletes a worktree it commits everything git can see of it into a local ref, refs/reliant/reclaimed/<key>/<time>, so a wrong call costs a restore, not lost work (chats, workspaces and machines). Archiving a workspace in the app is a separate cleanup path, covered in Workspaces.

Before you begin

  • A terminal on the machine whose disk you want to free, with the reliant CLI (Installation). Run the commands there: captures are refs in that machine’s repositories.
  • To have worktrees actually removed, a daemon you start yourself (connect your computer).
1

See what a pass would reclaim

scan runs one dry-run pass now. It finds every linked worktree, classifies it and writes the report, but captures and deletes nothing:
terminal
terminal
  • auto_safe: clean, with HEAD on a remote, idle for a day. Reclaimed without asking.
  • needs_approval: holds work only it has (uncommitted changes, unpushed commits, commits on no branch), idle for about five days. Removed only after a person approves it.
  • held: kept, with the reason in WHY. A worktree a process is using is one example.
Main checkouts and clones are never reclaimed. reliant worktree reclaim report prints the last pass’s report again, and --roots path[:depth] limits the scan to the directories you name.
2

Try a capture and a restore, without removing anything

scan --capture goes one step further than a dry run. Each auto_safe worktree is captured into its refs/reliant/reclaimed/... ref, and the capture is checked against the files, exactly as a real pass does before it deletes. Nothing is deleted, and every worktree stays where it is:
terminal
Each captured entry’s WHY names its ref and the command that restores it into a new directory:
terminal
Run that restore with a --to directory that does not exist yet. The original worktree is still at its own path. When you are done, remove the trial worktree with git worktree remove <new dir> and the capture with git update-ref -d <ref>. A worktree with work only it holds is not captured, because a real pass captures one only after a person approves it. These trial captures are keyed by the worktree’s path. A chat’s workspace never applies one on its own: it was never removed, so it has nothing to put back.
3

Decide on worktrees that hold unsaved work

List the worktrees waiting on a decision, with the keys you decide by:
terminal
proposals prints JSON, including each worktree’s work, its git status. Approve a removal in the app: the Inbox item Worktrees proposed for removal has a Review button, where you choose Keep or Remove for each one and submit. The CLI refuses to approve, because nothing on the machine can prove that a person approved it rather than an agent:
terminal
reliant worktree reclaim decline <key>, run in your own terminal (an agent’s shell is refused), keeps it until it changes.
4

Turn removal on

The pass runs in dry-run by default: it reports, and approvals are refused. On a cloud machine it runs on its own every six hours, or every 30 minutes while the disk is under pressure. On your own computer a dry-run pass runs only where the storage reaper runs, which it does not by default.To have worktrees removed, start the daemon in mode on, from the checkout it serves:
terminal
Mode on runs the pass on its own schedule, every six hours or every 30 minutes under disk pressure, even with the storage reaper off. The daemon’s log says so at start:
logs/tools-daemon.log
Build-cache trimming stays off unless you also set RELIANT_STORAGE_REAPER=on. RELIANT_WORKTREE_RECLAIM takes off, dry-run or on. The idle times are RELIANT_WORKTREE_RECLAIM_CLEAN_IDLE (default 24h, at least 1h) and RELIANT_WORKTREE_RECLAIM_APPROVAL_IDLE (default 120h, at least 24h). Under a service manager, set them in the unit’s environment (run the daemon on your own server).
5

Find a reclaimed worktree's capture

terminal
It lists the captures in every repository the machine’s reclaim journal names, newest first, with each one’s path, branch, work and ref. Captures made by scan --capture are marked kept in place. Add --repo <checkout> for one repository, or use git:
terminal
6

Restore it

Name the capture by the path the worktree had, or by its ref:
terminal
It recreates a linked worktree with HEAD at the captured commit, the files as they were (untracked files untracked again), and the index as it was staged. It prints restored <ref> at <path>, then on branch <name>, or why it left a detached HEAD. The path must not exist. --branch picks another branch. The capture ref is kept.A Reliant workspace usually needs no command: when a chat in it next runs a tool, the daemon checks out its branch again and puts the capture back, as long as the branch hasn’t moved.
7

Check the work is back

terminal
The worktree is listed again, and status shows the same changes the proposal’s work field listed.

What this does not do

  • Captures stay on one machine. Nothing is pushed, and no branch is deleted. A capture is lost with that machine’s disk, so restore on the machine that reclaimed the worktree.
  • Captures never expire. Delete one by hand with git update-ref -d <ref> when you no longer need it.
  • Ignored files are not captured. A worktree whose ignored files aren’t rebuildable output is held instead of reclaimed.
  • It doesn’t run on your own computer by default. Unless you set RELIANT_WORKTREE_RECLAIM=on (or RELIANT_STORAGE_REAPER=on), only scan writes a report there.
  • It doesn’t archive workspaces. A workspace stays in the app until you archive it. reliant worktree list lists a project’s workspaces, and reliant worktree archive <name|id> archives one, as the app’s Archive does. An agent’s shell is refused archive.

Troubleshooting

Reliant locks the checkout of each of its workspaces (git worktree lock, reason reliant: worktree <id>), so plain git refuses to remove one. Archive the workspace instead: reliant worktree archive <name|id>, or Archive in the app. Its machine then removes the directory once it is clean, pushed and unused. To remove a checkout by hand anyway, first check that its work is saved, then unlock it and remove it:
terminal
git worktree remove --force --force <path> does both, and also discards uncommitted changes. The workspace stays listed in the app until you archive it there.
No pass has run on this machine. Run reliant worktree reclaim scan to write one now.
The Inbox item shows this when the machine’s mode is dry-run. Approvals are refused until the daemon runs with RELIANT_WORKTREE_RECLAIM=on.
The journal has no capture for that path. Find the ref with reliant worktree reclaimed --repo <checkout> and pass it with --repo.

Next steps

Chats, workspaces and machines

Why a workspace lives on one machine, and what deleting a machine releases.

Run several daemons on one computer

One daemon per checkout or account, and how to address each one.

Workspaces

Create, archive and restore workspaces in the app.

CLI reference

Every reliant worktree flag.