# lysosome

> lysosome is the disk cleaner for the agentic coding era: an open-source (MIT) Rust CLI for macOS that finds the disk space eaten by dormant git worktrees (created by Claude Code, Cursor and parallel agents), git-ignored build artifacts, package-manager caches, local AI models, Docker and Xcode data. It labels every item by safety tier and cleans up safely. The CLI is available now. A paid native Mac menu bar app built on the CLI is coming soon (waitlist open).

## What it finds
- Agent and git worktrees: dormant worktrees are classified REMOVABLE (idle 30+ days, clean, merged or pushed), REVIEW (dirty, locked, unpushed or no remote), ACTIVE, or ORPHAN (parent repo missing). Stale worktree metadata is reported.
- Build artifacts: node_modules, target, .venv, venv, .next, .nuxt, .svelte-kit, .turbo, dist, build, .gradle, Pods, .dart_tool, .build, coverage, .parcel-cache, .expo — only when `git check-ignore` confirms they are ignored.
- Package caches: npm, pnpm, Yarn, Bun, pip, uv, conda, Cargo, Go, Gradle, Maven, Homebrew, CocoaPods.
- Local AI models: Ollama, Hugging Face hub, LM Studio, torch and whisper caches, listed by model name, size and last use.
- Docker and OrbStack: build cache, images, volumes.
- Xcode: DerivedData, iOS DeviceSupport, simulators, Archives.

## Safety tiers
- regenerable: caches and DerivedData; cheap to rebuild.
- regenerable_expensive: models, images, node_modules; costs a re-download or rebuild.
- review: archives, volumes, anything that may not be rebuildable.

## Safety rules
- Scanning never modifies anything; git runs with --no-optional-locks.
- Never removes a worktree with uncommitted changes, untracked files, a lock, or commits neither merged nor pushed.
- `lysosome clean` is a dry run by default; `--yes` applies. Items go to the macOS Trash or through each tool's own cleanup command (git worktree remove, docker image prune, brew cleanup, xcrun simctl).
- When unsure, items are labeled REVIEW, never REMOVABLE.

## Commands
- `lysosome worktrees [ROOTS...] [--days N] [--json]` (available now)
- `lysosome completions <bash|zsh|fish|powershell|elvish>` (available now)
- `lysosome scan [ROOTS...] [--json]` (next release)
- `lysosome caches` (next release)
- `lysosome clean [--worktrees] [--artifacts] [--caches] [--tier regenerable] [--older-than 90d] [--yes]` (next release)
- `--json` output is a stable, versioned contract (schema_version).

## Install (available now)
- Homebrew: `brew install lysosome-dev/tap/lysosome`
- Install script: `curl -fsSL https://lysosome.dev/install.sh | sh`
- Cargo: `cargo install --git https://github.com/lysosome-dev/cli lysosome`
- Prebuilt binaries for macOS (arm64, x86_64) and Linux (x86_64, arm64; glibc and musl): https://github.com/lysosome-dev/cli/releases/latest
- Shell completions: `lysosome completions zsh` (also bash, fish, powershell, elvish)

## lysosome for Mac (paid, coming soon)
Native menu bar app: always-on disk pressure monitoring, alerts before the disk fills, agent-aware worktree tracking, scheduled safe cleanups with rules, one-click reclaim with undo, history charts, AI model library manager. Team and fleet features later. Pricing not set (one-time or yearly license); waitlist members get early-bird pricing.

## Links
- Website and waitlist: https://lysosome.dev/
- Source code: https://github.com/lysosome-dev/cli
- Releases: https://github.com/lysosome-dev/cli/releases