/storage-retention

name: storage-retention
description: Inspect machine storage, clean up files, and configure automatic thread archive or deletion.

Storage & retention

Enable `bb plugin enable storage-retention`. Both policies default to Never. Open the plugin's sidebar panel for machine reports and retention settings. All settings in the panel save immediately when changed. All commands return JSON. Use the owning server's normal SDK/plugin RPC transport.

bb storage retention
bb storage retention --archive-after 30 --delete-after 90
bb storage retention --archive-after 30 --delete-after 90 --save --yes
bb storage retention --archive-after never --delete-after never --save --yes
bb storage retention --delete-storage-on-archive true --save --yes
bb storage retention --delete-storage-on-archive false --save --yes
bb storage retention --delete-dev-data-on-checkout-removal true --save --yes
bb storage usage
bb storage usage --rescan
bb storage usage --machine HOST_ID --rescan
bb storage usage --machine HOST_ID
bb storage remove-orphans --machine HOST_ID --yes
bb storage clear-large-files --yes
bb storage clear-large-files --machine HOST_ID --yes
bb storage retry-worktree-cleanup --machine HOST_ID
bb storage clear-thread --thread THREAD_ID --yes
bb storage clear-archived-files --machine HOST_ID --yes
bb storage remove-dev-instances --machine HOST_ID --yes
bb storage remove-dev-instances --machine HOST_ID --instance NAME --yes

Without `--save`, retention thresholds only preview affected thread counts. Days must be whole numbers from 1 to 3650, or `never`. Unspecified settings preserve their saved values. Saved policies apply across all projects. The hourly run processes up to 50 trees per action and skips groups with pinned members. Archiving can remove worktrees including uncommitted changes. Deleting removes history and thread storage. Preview first and save only when authorized.

Delete thread storage on archive defaults to off. Set `--delete-storage-on-archive` to `true` or `false`, or use the switch in the retention panel, which saves immediately. It applies to future manual and automatic archives, including each cascaded child, while the plugin is enabled; it does not clear previously archived threads. Conversations and uploaded attachments are kept. Pinned threads are skipped. Cleanup waits for stopped threads and online persistent machines. Pending cleanup survives reloads and retries every minute; unarchiving or deleting cancels it, and turning the setting off discards pending work on the next cleanup pass. Failures are logged and retried. Threads without an environment need a completed scan to identify their storage machine, just like clear-thread.

Delete development data when its checkout is removed defaults to off and is independent of archive cleanup. Set `--delete-dev-data-on-checkout-removal` to `true` or `false`, or use its switch in the retention panel, which saves immediately. When enabled, the plugin scans online persistent machines hourly and removes missing-checkout `~/.bb-dev` entries after successful scans, including manual scans. Existing missing-checkout data is eligible too; retention previews count threads, not these folders. The host rechecks checkout absence before removal, stops servers working inside missing checkouts, and preserves entries whose source exists or cannot be identified. An environment-removal event re-measures only that machine's `~/.bb-dev`, after any running cleanup there finishes. Startup, machine reconnect, and hourly scans recover missed events from filesystem state. Offline/busy machines and failed cleanup retry on later hourly scans. Disabling the setting prevents cleanup after subsequent scans.

Scans run in the background; rerun usage to read completion, progress, or failure. `--rescan` without `--machine` scans every online machine that is not already scanning. A completed report includes `disk` (total and free bytes of the volume holding thread storage). Reports include `projectWorktrees`: counts of distinct managed worktree paths per project on the selected machine, including zero-count projects with a local source there; destroyed and removed environments are excluded, and `cleanupPendingCount` is a subset of the worktree count. Counts reflect current environment records, not filesystem measurements. Scans also measure `~/.bb-dev` on that machine. `developerStorage` is null when absent; otherwise it contains the path, total allocated bytes, and immediate folder/file sizes. Each entry includes `sourcePath`, `sourcePathState` (exists, missing, or unknown), and `threads` linked through host environment paths or a managed checkout’s thread ID. Matches cover threads known to this BB instance, including archived and hidden threads. Sources are recovered from saved launch metadata or hash-verified known/conventional checkout paths; unresolved sources remain null. Missing checkouts are cleanup candidates, not proof their development data is disposable. The UI offers missing-checkout, other-instance and unidentified-source filters. The developer section initially shows the five largest entries, grouped into linked threads, other development instances and unidentified sources, each group with its own Show N more control inside the card. Paths are hidden from rows and available through the three-dot menu’s Copy source checkout path and Copy dev data path actions. When `developerStorage` is present, the machine list totals thread and development storage with a per-kind split, and the machine page's first card adds a BB development row (instance count and size) to its category table under one total; the entry list stays in its own section. Remove-dev-instances (page: Remove instances in the Clean up section) removes `~/.bb-dev` entries the last scan marked missing. `--instance NAME` (page: the trash button on any development row, which removes immediately; different rows can run at once) removes only that entry, whatever its checkout state,