aibris

README

aibris

AI + debris. A small CLI for cleaning up the filesystem leftovers from AI coding sessions: worktrees, logs, node_modules, and build caches.

AI tools are productive, but they shed a lot of temporary state while they branch, build, test, and retry. aibris scans the places that debris tends to collect, shows a readable cleanup plan, and only deletes after filters, confirmation, and path safety checks.

Who is this for?

• Developers who use AI coding tools (Codex CLI, Claude Code, Cursor, Windsurf)
• Teams sharing development machines where worktrees accumulate
• Anyone who wants to reclaim disk space from node_modules and build caches
• AI assistants that need structured scan output before cleanup

What it cleans

Category	Examples	Default clean
AI worktrees	Codex, Claude, generic project worktrees	Yes
Dependencies	project node_modules directories	Yes
Build caches	Go, npm, Gradle, Cargo, Xcode	Yes
Python caches	pip and uv cache directories	Yes
AI logs	Codex, Claude, Cursor, Windsurf logs	Only with --risky

Install

curl -fsSL https://raw.githubusercontent.com/sungjunlee/aibris/refs/heads/main/install.sh | bash

Install from the current main branch when you want unreleased changes:

curl -fsSL https://raw.githubusercontent.com/sungjunlee/aibris/refs/heads/main/install.sh | bash -s -- main

Install a specific release:

curl -fsSL https://raw.githubusercontent.com/sungjunlee/aibris/refs/heads/main/install.sh | bash -s -- 0.4.0

The installer downloads GitHub Release binaries and verifies checksums.txt. The default install path uses GitHub's releases/latest/download URLs for prebuilt binaries. main builds from source with Go.

By default, aibris installs to ~/.local/bin and does not require sudo. If that directory is not on your PATH, the installer prints the exact command to add it for your shell. For a system-wide install, pass an explicit prefix:

curl -fsSL https://raw.githubusercontent.com/sungjunlee/aibris/refs/heads/main/install.sh | bash -s -- --prefix /usr/local/bin

Usage

aibris scan                    # discover what's taking space
aibris scan --json             # machine-readable output (see docs/JSON_SCHEMA.md)
aibris scan --root ~/workspace # limit scan to a home subdirectory

aibris clean --dry-run         # preview without deleting
aibris clean                   # delete with confirmation
aibris clean --root ~/workspace --dry-run
aibris clean --age 7d          # older than 7 days (default)
aibris clean --age 30d         # older than 30 days
aibris clean --age 1mo         # older than 30 days (month shorthand)
aibris clean --age 1y          # older than 365 days
aibris clean --interactive     # confirm each item
aibris clean --category node_modules   # only node_modules
aibris clean --tool codex,claude       # only specific tools
aibris clean --risky           # include ai-logs
aibris clean --include-active-worktrees # include active worktrees
aibris clean --force           # skip confirmation prompt

See docs/DOGFOOD.md for real local scan transcripts used to validate release behavior.

Example

$ aibris scan

scan
  roots  ~

  scanned  7 sources   4 items   3.2 GB

summary
  found       4 items
  reclaimable 3.2 GB

by category
  node_modules    1   1.8 GB
  build-cache     2   1.3 GB
  worktree        1   96.0 MB

largest
    1.8 GB  node_modules  dashboard    -                  24d
  842.0 MB  build-cache   go-build     global             9d
  512.4 MB  build-cache   npm          global             18d
   96.0 MB  worktree      b7f4c2       aibris             active today

next
  aibris clean --dry-run
  aibris scan --json

Preview before deleting anything:

$ aibris clean --category worktree --age 7d --dry-run
clean
  roots  ~

  using cached scan from 8s ago

  matched  1 candidate   96.0 MB

clean plan
  mode     dry-run
  targets  1 item   96.0 MB

targets
      size  category      name         project            age/status     action
   96.0 MB  worktree      b7f4c2       aibris             orphaned 12d   remove-path
    ~/.codex/worktrees/b7f4c2/aibris

[DRY-RUN] No files were removed.

Confirm before deleting anything:

$ aibris clean --category node_modules --age 7d
clean
  roots  ~

  scanned  7 sources   4 items   3.2 GB

  matched  1 candidate   1.8 GB

clean plan
  mode     delete
  targets  1 item   1.8 GB

targets
      size  category      name         project            age/status     action
    1.8 GB  node_modules  dashboard    -                  24d           remove-path
    ~/workspace/dashboard/node_modules

Proceed? [y/N]:

scan writes a short-lived snapshot under the user cache directory. A following clean reuses it for 5 minutes when the scan roots and cache schema match. If the cache is stale, missing, or for different roots, clean falls back to a live scan with progress output.

So the common loop is fast and visible:

aibris scan
aibris clean --dry-run
aibris clean

When stdout is an interactive terminal, scans use a single-line spinner while providers run. In non-interactive logs, progress falls back to plain scanning / found lines.

Safety

• Default --age 7d avoids very recent work
• Human age units support h, d, w, mo, and y
• --dry-run previews before deleting
• --interactive confirms each item
• Target plan before final confirmation shows category, size, project, age/status, path, and cleanup command when applicable
• Recent scan reuse skips a repeated scan when clean can use a fresh compatible snapshot, while still re-checking target paths
• --risky must be explicitly set to delete AI logs
• Active worktrees are excluded by default; use --include-active-worktrees only when you intentionally want age-based cleanup for valid worktrees
• Home-scoped roots: default scanning starts at $HOME; --root can narrow scope to one or more existing directories under $HOME
• Pruned scan directories for project-style walks include .Trash, Library, Applications, Pictures, Movies, Music, .git, vendor, and nested node_modules; Desktop and Downloads are scanned
• Official cache cleanup commands are preferred for supported caches (go clean -cache, npm cache clean --force, uv cache prune). If the owning command is missing, aibris falls back to the existing safe path removal behavior; if the command runs and fails, aibris does not fall back silently.
• Confirmation prompt on every clean (use --force to skip)
• isSafePath validation rejects deletions outside known-safe directories
• Negative age rejection prevents accidental full-scope deletion

How It Works

aibris scan  → discovers worktrees, caches, node_modules, logs under scan roots
aibris clean → filters by age/category/tool → deletes safely

AI tools leave debris in predictable locations. aibris scans $HOME by default, prunes high-noise system and media directories while walking project-style debris, measures disk usage, and cleans only after filters and safety checks. Judgment about what should be removed stays with a human or an AI assistant using scan --json.

New tools can be added by implementing the DebrisProvider interface.

Agent Workflow

aibris scan --json
aibris scan --root ~/workspace --json
aibris clean --category worktree --tool codex --age 7d --dry-run
aibris clean --category worktree --tool codex --age 7d

The intended agent flow is: scan, summarize by project/category/age, ask the user what to remove, run a dry-run, ask again, then execute.

Contributing

See CONTRIBUTING.md and AGENTS.md for architecture and development guidelines.

License

MIT — see LICENSE.