# How laundry keeps your Git tidy

_Paper · 27 October 2026 · the lab · Version 1.0_

Version 1.0, 27 October 2026. Replaced by version 1.1, 3 November 2026.

Laundry ran 52 times in 15 of the lab's repositories over two months, archived and removed 196 branches, left 36 more archived in place, refused 403, and lost nothing. The refusals are the finding.

- 52 washes, one run of laundry each
- 196 branches archived, then removed
- 36 archived, left in place
- 403 branch refusals
- 0 commits lost

## By month

The tool's own meter, one row per run, rolled up by month, 26 August 2026 to 25 October 2026.

- Removed and refused: 196 removed, 403 refused, in all.
- Refusals by reason: 403 refusals, by the reason Laundry printed. Each one is a branch left in place.

| Month | Runs | Examined | Removed | Refused | Seconds |
|---|---:|---:|---:|---:|---:|
| August | 8 | 77 | 33 | 56 | 107 |
| September | 10 | 119 | 27 | 92 | 100 |
| October | 34 | 422 | 136 | 255 | 353 |

## Why we built it

Every developer knows the pause before `git branch -D`. Is this the branch that merged, or the one with Tuesday's fix? Most of us answer by leaving it. Then there are hundreds.
A lab that works with agents makes branches faster than a person can read them. By October 2026 the lab's repositories held hundreds: feature branches, agent sessions, a plan, a spike, a worktree that was never cleaned. So the branches stay, and every survey, every clone and every agent that reads `git branch -a` pays for them.

## Where other tools stop

`git branch --merged` lists a branch only when its tip sits inside the branch you are on. A squash merge writes a new commit, so a branch that has landed still looks unmerged, and a careful person keeps it. GitHub can delete a pull request's branch when it merges, but only on GitHub; every clone keeps its copy. A script that pipes one into `git branch -D` deletes on a guess, and a guess that is wrong once loses work nobody can get back.

## Why safety came first

A lost commit is not a number on a dashboard. It is an afternoon of someone's thinking. We wanted a tool an agent could run without a person watching, which meant it had to be safe to be wrong: prove before it removes, archive before it deletes, and when it cannot prove, refuse and say why. Laundry is that tool, and a run of it is a wash. This paper is its record: what it did in the lab's own repositories from 26 August to 25 October 2026, counted by the tool itself.

## What it saves

Branches cost attention long before they cost disk. A person facing hundreds of them reads each name and decides, one at a time, what is safe. Laundry does that reasoning once, writes it down, and hands back only the branches it refused, each with its reason. The person reads a short list instead of a long guess.
An agent pays the same cost in tokens. Every `git branch -a` it reads and every `git worktree list` it runs carries every branch nobody cleaned, and a branch with no recorded reason sends the agent to rebuild the reasoning from `git log`. We did not measure those tokens: the meter sees the tool, not the agent that ran it. The saving we can name is where it comes from: fewer branches to read, and a printed reason in place of one to work out again.

## What laundry does

Laundry surveys every local and remote branch in a repository and sorts each one into a classification: merged by ancestry, merged by a pull request, squash-merged, superseded, held by a worktree, protected, current, open on a pull request, or unmerged. For each branch it can prove safe, it writes a snapshot ref, verifies the ref points at the exact commit, and only then removes the branch. Anything it cannot prove, it refuses, and says why.
It never deletes. A removed branch is restorable to the exact commit with one command: `--restore <run>` brings back everything a run archived, `--restore-branch <name>` one branch. There is no model and no network call; it reads git, and `gh` when it is present.
Every run writes one row to the repository's own git directory: when, which version, how long, how many git calls, how many branches examined, planned for removal and refused, each refusal's reason, each step's outcome. That row is the data in this paper. Nothing here was reported by an agent from memory.

## What the record shows

52 washes in 15 repositories, 2026-08-26 to 2026-10-25, across 8 versions from 1.0.1 to 1.7.0-dev.5. The tool examined 618 branches. It planned 232 removals, wrote a snapshot ref for every one, and completed 196 of them. The other 36 were archived and left in place. It refused 403 branches. Of the 232 snapshot refs, 146 were pushed to the remote.
Use grew with trust. August had 8 runs and 33 removals. September had 10 and 27. October had 34 runs and 136 removals, more than the two months before it together.
A run is short: the median is 5.2 seconds, the ninetieth percentile 30.4, the longest 55.2.
The refusals are the finding. Of 403, the reasons were: unmerged work 102, a protected branch 99, the head of an open pull request 66, a pull request marked merged that no proof on the target confirmed 59, a branch held by a worktree 45, the current branch 12, and the rest under a goal's scope or a keep rule. Each of those is a branch a tired person, or an eager agent, would have deleted. Laundry left every one in place and printed the reason.
45 of 52 runs completed. 3 ended partial, 3 failed, 1 stopped for a human. All 33 failed steps across those runs share one cause: git refused the delete because it could not see the branch as merged, and laundry did not force it. In every case the snapshot ref had already been written, so the branch was archived and left in place. One run on 25 October did this 22 times and ended partial, saying so. The tool would rather fail a step than force a delete git refused.
Zero commits were lost. That is a claim, not a count: a meter cannot prove a negative. It rests on the snapshot that precedes every removal, on 199 smoke cases passed and 3 skipped with printed reasons on 27 October, and on 25 invariant attacks that try to make the tool lose a commit.

## What we learned

A refusal is worth more than a removal. The 403 refusals are what let the lab run laundry from an agent without a person watching, and the reasons are the part people read.
The tool's own meter is the only honest source, and even the meter needs reading. The first draft of this paper said 232 branches were removed, because the meter's counter counts removals planned. A second pass against the step log found 36 of them ended archived and in place. The paper counts completed deletes; the data file now carries both numbers.
Failing a step beats forcing it. Every failed step in two months was git saying no. The 1.7.0 line adds exact proofs for the cases where the refusal was git's caution and not a real divergence; the cases that remain are left for a person.

## Limits

One user, one lab. Every run was in the lab's own repositories, by the founder or by agents working for him. No outside team has run laundry yet; the counts above are a first user's record, not a field study.
The meter counts the tool's own work. It cannot see the tokens or the tool calls of the agent that invoked it; only the harness can.
Examined, removed and refused are the meter's own counters and are not expected to sum: a branch can be counted under more than one reason. Some runs were made from a worktree and count toward the repository that holds it.

## Try it

Laundry is at household.dev/tools/laundry. Clone the repository, run it with no flags to see the survey, and read the refusals before anything else. It is Apache-2.0.
Questions about one line of this record go to hello@household.dev.

## Sources

Counted by the tool itself, one row per run, read from every repository on the founder's machine. Exact on this page. Nothing here is reported by an agent about itself.

- The data: Exact counts in data/tool-usage/laundry.json: One JSON row per run, written by the tool itself to its repository's own git directory, read from every repository on the founder's machine.
- 199 smoke cases passed, 3 skipped with printed reasons: laundry-smoke.sh, run 2026-10-27
- 25 invariant attacks, all held: invariants/test_laundry_invariants.py, 25 tests, run 2026-10-27
- 22 branches in one run were archived and left in place: one repository's .git/laundry/log.jsonl, run 2026-10-25T0916Z-6fdd
- 33 failed steps across 6 runs, one cause: every .git/laundry/log.jsonl on the founder's machine, read 2026-10-27
- 8 versions of the tool: data/tool-usage/laundry.json, versions
- git branch --merged lists a branch only when its tip is reachable from the branch you are on, so a squash-merged branch looks unmerged: git-scm.com/docs/git-branch (--merged), read 2026-10-28
- GitHub's automatic branch deletion removes the head branch on GitHub after a merge; local clones keep theirs: docs.github.com, Managing the automatic deletion of branches, read 2026-10-28

Questions about one line of this paper go to hello@household.dev.

## For agents

- [llms.txt](https://www.household.dev/llms.txt)
- [tools/index.json](https://www.household.dev/tools/index.json)
