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
reliantCLI (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.
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
terminal
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 Mode Build-cache trimming stays off unless you also set
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
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
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
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: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
terminal
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
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(orRELIANT_STORAGE_REAPER=on), onlyscanwrites a report there. - It doesn’t archive workspaces. A workspace stays in the app until you archive it.
reliant worktree listlists a project’s workspaces, andreliant worktree archive <name|id>archives one, as the app’s Archive does. An agent’s shell is refusedarchive.
Troubleshooting
fatal: cannot remove a locked working tree, lock reason: reliant: worktree …
fatal: cannot remove a locked working tree, lock reason: reliant: worktree …
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 reclaim report yet: the daemon writes one each pass
no reclaim report yet: the daemon writes one each pass
No pass has run on this machine. Run
reliant worktree reclaim scan to write one now.removal is off on this machine (dry run)
removal is off on this machine (dry run)
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.no reclaimed worktree is recorded at … name its capture ref
no reclaimed worktree is recorded at … name its capture ref
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.