Worktree Sweep

English · Français

Find the worktrees taking up disk space and the work you need to keep.

A local macOS CLI that brings paths, branches, disk sizes and Git evidence into one report. No AI model, service or forge account is needed.

[!NOTE] Read-only. Sweep prepares a cleanup review. Backup, restore and removal are unavailable; apply refuses every invocation.

Quick start · Read the result · HTML report · Assistant skill · Documentation · Roadmap

---

Why it exists

I built Sweep because I had run out of disk space. My worktrees were scattered across project folders and agent directories. Before deleting anything, I needed to know where the space went and which directories still held local work.

What you need to know	What the report shows
Where are my worktrees?	Paths and branches, grouped by Git family within the roots you choose.
Which ones take up space?	Logical and allocated sizes, shared Git storage and incomplete measurements.
Which ones deserve a cleanup review?	Integration evidence, local changes, private history and the reason for each verdict.

Size helps prioritize the review. It does not prove a worktree can be removed or predict the space recovered on APFS. A merged branch can still hold ignored files, uncommitted changes or local notes.

---

Quick start

Download the Apple Silicon alpha

Use v0.1.0-alpha.3 on macOS Apple Silicon with /usr/bin/git. Rust is not required for the downloaded binary. The Downloads directory must exist; each installation uses a new folder.

(
  set -eu
  test "$(uname -s)" = Darwin
  test "$(uname -m)" = arm64
  install_dir="$(mktemp -d "$HOME/Downloads/wt-sweep-alpha.XXXXXX")"
  cd "$install_dir"
  release_url="https://github.com/FlorianBruniaux/wt-sweep/releases/download/v0.1.0-alpha.3"
  curl --fail --location --proto '=https' --tlsv1.2 -O "$release_url/SHA256SUMS"
  curl --fail --location --proto '=https' --tlsv1.2 -O "$release_url/wt-sweep-v0.1.0-alpha.3-aarch64-apple-darwin.tar.gz"
  shasum -a 256 -c SHA256SUMS
  tar -xzf wt-sweep-v0.1.0-alpha.3-aarch64-apple-darwin.tar.gz
  cd wt-sweep-v0.1.0-alpha.3-aarch64-apple-darwin
  ./wt-sweep --version
  ./wt-sweep review --help
  printf '\nBinary: %s/wt-sweep\n' "$PWD"
)

Use the printed binary path in place of ./target/release/wt-sweep in the commands below. No global installation or permissions change is made. The archive includes licenses and MANIFEST.json with its source commit and file hashes. It is not Apple-notarized; browser-downloaded Gatekeeper behavior and older macOS versions remain unqualified. If macOS blocks execution, keep the protection and use the source-build instructions. Intel, Linux and Windows binaries are not provided.

Build from source

Use macOS and Rust. The repository is public; clone it over HTTPS.

git clone https://github.com/FlorianBruniaux/wt-sweep.git
cd wt-sweep
cargo fetch --locked
cargo build --release --locked --offline
./target/release/wt-sweep --help

The repository pins Rust 1.95.0 in rust-toolchain.toml. Skip cargo fetch when dependencies are already cached. Git is read through /usr/bin/git. No package-manager install or global configuration is required. Setup and troubleshooting.

Inspect one repository family

Run from the Sweep checkout. Enter your clone path and the full integration ref you have confirmed, such as refs/heads/main or refs/heads/develop. The command stops if that ref is absent locally.

(
  set -eu
  sweep_bin="$PWD/target/release/wt-sweep"
  printf 'Absolute clone path: '
  IFS= read -r repo_path
  printf 'Confirmed full target ref (refs/heads/... or refs/remotes/...): '
  IFS= read -r target_ref
  /usr/bin/git --no-optional-locks -c core.fsmonitor=false -C "$repo_path" \
    show-ref --verify --quiet "$target_ref"
  "$sweep_bin" review --repo "$repo_path" --target "$target_ref" \
    --summary --disk-usage --open
)

--open saves HTML, text and JSON under ~/Desktop/Worktree Sweep/run-*/ and asks macOS to open the HTML. Use --html to save without opening, or add --run-dir "/absolute/path/to/reports" to choose an existing directory. Reports must remain outside the inspected scope and Git directories. To try synthetic worktrees first, use the disposable demo.

Each new run-* directory contains inventory.json, review.json, report.txt, the requested report.html and the publication receipt run.json. The receipt records artifact sizes and hashes. A manifest records observations, not copies of your files.

For several project folders, start with explicit roots, then select the integration refs per family. The CLI also exposes --all; inaccessible paths and limits remain coverage gaps. A completed walk does not prove a machine-wide snapshot.

For saved inventories and detailed file manifests, follow the scan then plan workflow. Interrupted explicit-root discovery can use checkpoints.

Available in source builds after alpha.3; the alpha.3 archive is unchanged. Run in a terminal and enter the path to your saved inventory.json:

(
  set -eu
  printf 'Inventory JSON path: '
  IFS= read -r inventory_path
  ./target/release/wt-sweep plan --inventory "$inventory_path" \
    --interactive --compare-local --group-by repo --summary --open
)

Choose branch numbers or full refs for each repository, then confirm the recap with yes. Nothing is preselected. skip leaves that repository without an integration target; quit cancels. The analysis reads current evidence, keeps the captured disk measurements and opens a new HTML report. No Python script or network fetch is needed. Guided analysis.

Add --compare-local to a saved review or plan to compare local changes with your explicit integration targets. Add --compare-reference ABSOLUTE_PATH only for a different checkout in the same Git family. The report separates exact matches, differences and unexamined paths, including ignored files. It saves local-comparison.json alongside the review. Neither equality nor an incomplete zero changes cleanup eligibility. Commands and limits.

Read the result

--summary starts with disk allocation, then separates commit ancestry from cleanup verdicts. It lists the five largest measured worktrees in the selected view, their blockers and a focused retry command when the recorded path and targets can be quoted safely. Output is in English; sizes use decimal KB/MB/GB. Open report.html for the grouped view or report.txt for the full reasons.

An ancestor relationship can be known while a worktree still needs verification: local files, object availability or private history may remain unchecked. The compact recap names collection limits; --verbose adds technical timings.

Verdict	Meaning	Next step
keep	Work, a protection, an operation or another retention reason was observed.	Read what must be preserved.
verify	Required evidence is missing or inconsistent.	Inspect the gap and choose a focused check.
cleanup_candidate	The five current evidence conditions C1–C5 are satisfied.	Confirm usage; this verdict does not authorize removal.

Collection has finite entry, byte and time limits. An unread directory, an access error or a timeout remains visible; it never becomes an empty result. Partial counts are lower bounds. UNKNOWN means the evidence was not established.

Start with the default standard budget. For an unresolved row, read its gaps and consider --worktree PATH --budget thorough. Disk measurement has a separate scope and budget: use --disk-usage with --disk-root ABSOLUTE_PATH to target a registered root. Larger caps do not guarantee completion. Disk measurements and retries.

Terminal colors and icons are automatic. Add --verbose for detailed logs and phase timings, or --color never for plain output. Saved reports and JSON do not contain terminal decoration.

---

HTML report

v0.1.0-alpha.3 opens with a compact summary, recommended next checks and the worktree list. Quick filters select a status; a size shortcut shows the largest recorded entries. Show all restores the initial view. Review rows show a readable status and main reason, with full evidence folded underneath.

Expand Disk observations for captured capacity, available space and measured allocation per volume. Partial measurements stay explicit. Cmd+K / Ctrl+K jumps to a section or recorded worktree. Disk dashboard.

The offline reading guide includes a clickable workflow diagram. Each block opens its report section; Tab and Enter work too. An inventory explains which Git checks require a separate review.

Search by path or branch, filter verdicts, sort by size and copy paths. Worktrees are grouped by Git family, with light/dark themes, sizes in Ko/Mo/Go and expandable sections. Source totals, selected rows and browser-filtered rows remain distinct.

Native capture from a disposable four-worktree demo: three keep, one cleanup_candidate. Captured on 8 October 2026, not a scan of your machine. Capture provenance.

The report and its expandable evidence work offline without JavaScript. Search, sorting and path copying use JavaScript. Review reports also link to GitHub/GitLab repositories, branches and commits from local remotes. Add --forge FILE to show associated captured PR/MR links and states. These links do not confirm publication; the CLI does not contact the server. Forge links and imports. HTML guide · Illustration and screenshot provenance

---

Use with Claude or Codex

In the HTML report, Claude prompt prepares a French prompt containing all saved entries or the current filtered selection. Inspect it before copying; nothing is sent automatically.

Starting from scratch? Give your assistant the installation and guided-review prompt (French). It covers cloning the tool and bundled skills, building the CLI, a disposable demo and your first report.

Open your assistant in this Sweep checkout and invoke /wt-sweep in Claude Code or $wt-sweep in Codex. The included skill reads reports in small batches and suggests the next checks. The CLI computes the verdicts; the assistant explains them. Native skill discovery depends on your client and project trust.

Replace the path and confirm the target ref before using this prompt. Use /wt-sweep instead of $wt-sweep in Claude Code.

$wt-sweep Review the worktrees of /absolute/path/to/repository.
The confirmed integration target is refs/heads/develop.
Measure disk usage and generate an offline HTML report.
Start with the recap, then read five worktrees at a time.
Keep the CLI verdicts and explain missing evidence. Suggest the next checks
in priority order. Do not delete anything or treat allocated bytes as savings.

The assistant guide covers an existing report, targeted retries, model/effort choices and bounded delegation. No global skill or hook installation is performed by Sweep.

---

Features

Capability	Use it for	Entry point
Repository families	Discover the main checkout, linked and detached worktrees, and missing registrations.	scan --repo PATH
Scoped discovery	Walk selected roots, including hidden, ignored and nested directories, with coverage gaps retained.	scan --root PATH
Resumable discovery	Continue a saved explicit-root traversal; reread Git families and retain separate observation intervals.	Checkpoint commands
One-command review	Discover an explicit scope and collect current review evidence.	review --repo PATH
Current local state	Compare HEAD, index and files with separate complete or partial counts.	review or plan
Local file manifests	Inspect file hashes, metadata, index entries and selected worktree administration.	scan --local
Local content comparison	Find local changes whose exact content already exists in explicit Git targets or a same-family checkout, with differences and unknowns.	review --compare-local --run-dir BASE
Git relationships	Observe identical commits, ancestry and identical trees against named refs.	plan --target FULL_REF
Offline forge evidence	Import captured GitHub/GitLab data with provenance, without contacting a forge.	forge ingerer
Human and machine output	Read the detailed report or structured console recap; retain full path bytes and OIDs in JSON.	--summary, --format json
Disk usage	Measure logical and allocated sizes, including ignored files, with partial results and inode deduplication.	--disk-usage
Offline HTML	Browse worktrees by family, search, sort and inspect captured evidence.	--open or --html
Focused collection	Spend the per-worktree allowance on one selected path after reading its gaps.

Global discovery is also available through scan --all and review --all. It uses visible mounted volumes and reports access gaps. It has been tested with injected volumes, not by scanning the development machine. Start with a repository or selected roots.

How it works

Collection reads the chosen scope; deterministic code classifies the recorded evidence. Missing information stays missing. Age, patch-id, a closed PR or a model suggestion cannot prove integration.

flowchart LR
    Review["review<br/>Explicit scope"] --> Scan["Fresh discovery"]
    Scan --> Inventory["Original inventory JSON<br/>Disk measurements if requested"]
    Inventory --> Plan["Current evidence and judgement"]
    Targets["Explicit integration refs"] --> Plan
    Forge["Captured forge export"] -. optional .-> Plan
    Plan --> Report["HTML · text · JSON<br/>Verdicts, sizes and missing checks"]

review combines discovery and current evidence collection. scan and plan remain available separately. Integration refs are explicit; no default branch is guessed. Captured forge exports are optional. Architecture · Evidence contracts.

Retention reasons take priority. Only a linked worktree with complete current controls, verified integration, clean files and covered private history qualifies. A missing optional forge export does not invalidate those proofs.

flowchart TD
    Reason{"Work, protection or other<br/>retention reason observed?"}
    Reason -->|Yes| Keep["keep"]
    Reason -->|No| Proof{"All five current conditions<br/>C1-C5 established?"}
    Proof -->|Yes| Candidate["cleanup_candidate<br/>Usage to confirm"]
    Proof -->|No| Verify["verify<br/>Missing conditions listed"]
    Keep --> Report["Reasons and evidence<br/>No removal authorized"]
    Candidate --> Report
    Verify --> Report

The classification table and evidence contracts describe how to read these results.

Disk measurements include ignored files and distinguish logical size, allocated size and inode-deduplicated totals. Shared Git storage is recorded separately. HTML uses decimal Ko/Mo/Go and keeps exact bytes in the details. APFS clones prevent these figures from establishing recoverable space.

Git object bytes are checked against their full OIDs. Local checks distinguish staged, unstaged, conflicted, untracked and ignored paths. Private history and shared stashes remain part of the evidence. Commit messages and changelogs provide context, not integration proof.

On macOS, Sweep verifies that dataless-file materialization is disabled before protected reads, including Git children, or refuses the operation. Access errors and timeouts stay in the report. Observations span an interval, not an atomic snapshot.

Disk guide · Collection performance · Native read boundaries.

---

Documentation

Guide	Use it for
Hands-on tutorial (French)	Disposable trial, local tests and first real repository
Getting started	Installation and troubleshooting
CLI reference	Commands, defaults, limits and exit codes
Disk usage	Sizes, partial results and focused measurements
Assistant skill	Example prompts and progressive report reading
Documentation index	All guides, contracts, architecture and validation records

The overview is available in English and French. The tutorial, assistant and disk guides are in French; other guides retain their original language.

---

Worktrunk v0.80.0 already dispatches wt sweep to wt-sweep on your PATH. No adapter or hook is needed. The tested integration covers arguments, cwd, exit status and real scan/review results. An alias named sweep takes precedence; use an explicit Sweep path if resolution is ambiguous.

wt sweep --version
wt sweep review --help

Roadmap and validation

The read-only audit is delivered: HTML reports, targeted disk measurement, grouped Git reads and resumable discovery. The extension evaluations record what to reuse and where to stop. Worktrunk already runs wt sweep; provenance and APFS recipes remain experiments. Writer exclusion is unproven, so backup, restoration and removal remain unavailable.

The 9 October acceptance record covers one real family with 71 registered worktrees. The first review returned 10 keep, 61 verify and no candidate. Later focused observations do not turn that partial review into a complete snapshot. Five prioritized worktrees have complete disk measurements; the family-wide total remains partial.

Release validation and installation evidence are linked from the release guide. Historical test counts remain in the validation record.

Concurrent-writer exclusion, durable backup and independent restore remain unproven. Removal is unavailable. Real FileProvider placeholders, actual TCC denials and a machine-wide snapshot have not been verified. Acceptance plan · Why apply is unavailable · Remaining work.

Development and project status

v0.1.0-alpha.3 is the current read-only macOS Apple Silicon pre-release. See the release guide for installation, checksums and scope.

CONTRIBUTING.md covers local checks and disposable fixtures; CHANGELOG.md records changes. Cargo publishing remains disabled.

---

License

Functional Source License 1.1, Apache 2.0 future license (FSL-1.1-ALv2), copyright 2026 Florian Bruniaux. Third-party dependencies retain their own licenses.