repo-cleaner

repo-cleaner is a Go-native CLI that hunts down multi-ecosystem build artifacts, presents them in a live terminal UI, and runs safe deletes once the user approves. It also exposes its scan/clean tools via an MCP-compatible RPC over stdio with policy-driven access control.

Highlights

• Live cleanup UI: streaming scan, async metadata, a fixed control band, adaptive mode/status band, size/date sort controls, pauseable output, and immediate delete confirmation feedback.
• Workspace aware: enforces repo boundaries, respects include/exclude filters, and supports fd, find, or the built-in Go backend.
• MCP policy enforcement: the stdio toolset requires role metadata and consults an SQLite table (access_rules) to decide who (owner/admin/staff) may call scan_artifacts or clean_artifacts.
• Installation: distributed via npx repo-cleaner but also available as a compiled Go binary under cmd/repo-cleaner.

Getting started

npx repo-cleaner cleanup --fast

Key flows:

• scan: enumerate cleanup candidates, optionally with --json.
• cleanup: live TUI with streaming metadata, sort/search/paging, and immediate apply.
• clean: scripted deletes using --paths or --interactive.
• review: text-based toggle/filter workflow.
• install: builds/copies the CLI (via go build), asks to run a scan, and installs your choice of MCP client (codex or claude).
• install-tools: (macOS) adds findutils, fd, ripgrep, fzf.

Flags:

• --fast: skip byte-size math on large workspaces.
• --engine go|fd|find|auto: pick the discovery backend.
• --include/--exclude: comma-separated type filters (node,rust,go) or glob patterns.

When no root is provided, repo-cleaner treats your current working directory as the workspace root and descends into nested repositories or project folders (you can still pass an explicit root if you need to scope the scan). The mode/status band in the TUI keeps the sort, filter, and selection context visible while you work, and docs/UX.md records the flow-driven reasoning behind that layout.

• Discovery engines: auto tries fd, then find, and falls back to Go. Benchmarks in docs/perf.md show find as the fastest backend on ~/dev/repos, fd slightly slower, and the Go walker the most portable option. auto already implements the fast/fallback strategy described there, so pointing people at that doc keeps them informed without extra configuration.

Use cases

1. Quick scan: repo-cleaner scan . --fast --json feeds automation with deterministic candidate lists.
2. Interactive cleanup: repo-cleaner cleanup streams the table, lets you / search, page with PgUp/PgDn, and shows per-path deletion status when Enter applies.
3. Scripted deletions: repo-cleaner clean . --paths path1 path2 --trash for CI or scheduled cleanups where you know what to remove.
4. Review filtering: repo-cleaner review . uses text commands to filter by substring, toggle selection, and apply safely.
5. Workspace-aware scanning: repo-cleaner scan ~/dev --engine go descends into nested repos and summarizes per-project candidates.
6. Policy-driven MCP: set REPO_CLEANER_POLICY_DB, run repo-cleaner install to scan and install an MCP client, and ensure owner/admin/staff rules from the DB gate each tool.
7. MCP automation: the MCP client uses stdio and the policy database to expose cleanup tools to Codex/Claude bots.
8. Toolchain prep: repo-cleaner install-tools macos installs fd, ripgrep, fzf, and findutils.
9. Local CLI install: make install (or repo-cleaner install while developing) copies the fresh binary to ~/.local/bin.
10. Size/date prioritization: inside cleanup you can toggle sorts (1/2/3), pause refresh, and inspect aggregates before applying.

MCP setup

• Provide a policy SQLite database via REPO_CLEANER_POLICY_DB.

• Table schema:

  CREATE TABLE access_rules (
    role TEXT NOT NULL,
    tool TEXT NOT NULL,
    mode TEXT,
    allow INTEGER NOT NULL,
    PRIMARY KEY(role, tool, mode)
  );

• Example entry: (owner, clean_artifacts, trash, 1) allows owners to trash-clean selected paths.

• The MCP handlers automatically read role from each tool call and reject unauthorized requests.

Development

• Build: go build -o bin/repo-cleaner ./cmd/repo-cleaner
• Tests: go test ./...
• Format: gofmt -w ./cmd ./internal
• Install CLI locally: make install (copies the built binary to ~/.local/bin)

License

MIT