> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Reclaim worktree disk space and restore reclaimed work

> Free the disk idle git worktrees hold on a Reliant machine, decide on the ones with unsaved work, and restore a reclaimed worktree from its capture.

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](https://docs.reliantlabs.io/deep-dives/chats-worktrees-machines.md)). Archiving a workspace in the app is a separate cleanup path, covered in [Workspaces](https://docs.reliantlabs.io/features/worktrees.md#cleaning-up).

## Before you begin

* A terminal on the machine whose disk you want to free, with the `reliant` CLI ([Installation](https://docs.reliantlabs.io/getting-started/installation.md)). 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](https://docs.reliantlabs.io/guides/machines/connect-computer-as-machine.md)).

**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:

```bash terminal theme={null}
reliant worktree reclaim scan
```

```text terminal theme={null}
mode dry-run, pass finished 2026-11-20 09:52:48: 2 worktrees; auto-safe 1 (0K), needs approval 1 (0K), held 0, reclaimed 0 (- freed)

CLASS           OUTCOME            SIZE  IDLE      PATH                    KEY                 WHY
auto_safe       would_reclaim      0K    144h0m0s  .../app-feature-done    p-dfe9d53e8fd8995f  clean, HEAD on a remote, idle 144h0m0s
needs_approval  awaiting_approval  0K    144h0m0s  .../app-feature-wip     p-8aa4c06645600a3e  dirty: 2 changed or untracked file(s): README.md, notes.txt

1 main checkouts and clones found (never reclaimed)
```

* **`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:

```bash terminal theme={null}
reliant worktree reclaim scan --capture
```

Each captured entry's **WHY** names its ref and the command that restores it into a new directory:

```text terminal theme={null}
auto_safe  would_reclaim  0K  144h0m0s  .../app-feature-done  p-dfe9d53e8fd8995f  captured at refs/reliant/reclaimed/p-dfe9d53e8fd8995f/1763632368000000000-1a2b3c4d and verified; nothing was removed. Try a restore elsewhere: reliant worktree restore refs/reliant/reclaimed/p-dfe9d53e8fd8995f/1763632368000000000-1a2b3c4d --repo /home/you/src/app/.git --to <new dir>
```

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:

```bash terminal theme={null}
reliant worktree reclaim report --class needs_approval
reliant worktree reclaim proposals
```

`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:

```text terminal theme={null}
approving a reclaim here is not available: nothing on this machine can verify the approval is a person's; approve it in the machine's Inbox item, or check its work and run `git worktree remove` yourself (keys: p-8aa4c06645600a3e)
```

`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:

```bash terminal theme={null}
RELIANT_WORKTREE_RECLAIM=on reliant daemon start
```

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:

```text logs/tools-daemon.log theme={null}
[diskwatch] Storage reaper schedule disabled (RELIANT_STORAGE_REAPER=auto runs it on managed daemons only; on enables, off disables)
[diskwatch] Worktree reclaim scheduled on its own (RELIANT_WORKTREE_RECLAIM=on) interval=6h0m0s pressure_interval=30m0s
```

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](https://docs.reliantlabs.io/guides/machines/run-agents-on-your-own-server.md)).

**5. Find a reclaimed worktree's capture**

```bash terminal theme={null}
reliant worktree reclaimed
```

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:

```bash terminal theme={null}
git -C <repo> for-each-ref refs/reliant/reclaimed
```

**6. Restore it**

Name the capture by the path the worktree had, or by its ref:

```bash terminal theme={null}
reliant worktree restore ~/src/app-feature-wip
reliant worktree restore refs/reliant/reclaimed/<key>/<time> --repo ~/src/app --to ~/src/app-wip-back
```

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**

```bash terminal theme={null}
git -C ~/src/app worktree list
git -C ~/src/app-feature-wip status --short
```

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

> [accordion] 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:
>
> ```bash terminal theme={null}
> git worktree unlock <path>
> git worktree remove <path>
> ```
>
> `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.

> [accordion] 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.

> [accordion] 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`.

> [accordion] 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

> [card] [Chats, workspaces and machines](https://docs.reliantlabs.io/deep-dives/chats-worktrees-machines.md)
>
> Why a workspace lives on one machine, and what deleting a machine releases.

> [card] [Run several daemons on one computer](https://docs.reliantlabs.io/guides/machines/run-several-daemons-one-computer.md)
>
> One daemon per checkout or account, and how to address each one.

> [card] [Workspaces](https://docs.reliantlabs.io/features/worktrees.md)
>
> Create, archive and restore workspaces in the app.

> [card] [CLI reference](https://docs.reliantlabs.io/reference/cli.md)
>
> Every `reliant worktree` flag.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.