Sweepito

Safely clean caches and build artifacts across languages, frameworks and tools.

Why Sweepito?

Every ecosystem leaves its own clutter behind: __pycache__/, .next/, Cargo target/, Gradle build/, .terraform/, .ipynb_checkpoints/, and many more. Cleaning them by hand means remembering each tool's quirks, and the usual shortcuts are risky: rm -rf build happily deletes a committed build/ folder, and git clean -fdx removes everything untracked, including your .env.

Sweepito is one tool for all of it, built around a simple rule: it only removes paths that Git already ignores and does not track, and only when the project's own marker files prove what the folder is. A build/ directory is a candidate beside a CMakeLists.txt or pom.xml, never because of its name alone.

What you get

• 17 technology profiles and 97 rules, detected automatically from marker files (Cargo.toml, pom.xml, package.json, ...). Repositories with several technologies and nested projects are handled per project.
• Conservative by default. Only safe caches are cleaned. Build output is opt-in, and dependency directories such as node_modules/ need an explicit flag as well.
• Previews you can trust. scan shows exactly what clean would remove, with sizes and the reclaimable total.
• One config format for every language, with custom cleanup rules and profiles.
• Git hooks: post-commit cleanup through the pre-commit framework or a native hook, silent when there is nothing to do.
• Machine-readable output (--json) and meaningful exit codes for automation.
• Small and cross-platform: Python 3.11+, two dependencies (pathspec, rich), with a CI matrix covering Linux, macOS and Windows.

Safety model

Built-in rules never target application data, infrastructure state (*.tfstate), secrets (.env*) or IDE settings.

Install

Requires Python 3.11 or later and Git.

pipx install sweepito          # or: uv tool install sweepito
uvx sweepito scan              # run without installing
pip install sweepito           # into the current environment

Quick start

sweepito scan                              # what would be removed (safe rules only)
sweepito scan --risk configurable          # include build output
sweepito clean                             # remove, asking first
sweepito clean --enable rust.target --yes  # also remove Cargo target/, no prompt
sweepito rules                             # list every rule and its risk
sweepito init                              # write a starter sweepito.toml

Example:

$ sweepito scan --risk configurable
Project: /home/dev/myapp   profiles: common, node, python, rust
                    Cleanup candidates
┌────────────────┬──────────────────┬──────────┬──────────────┐
│ Rule           │ Path             │     Size │ Risk         │
├────────────────┼──────────────────┼──────────┼──────────────┤
│ python.pytest  │ .pytest_cache/   │   3.2 KB │ safe         │
│ python.pycache │ src/__pycache__/ │  87.8 KB │ safe         │
│ node.next      │ web/.next/       │ 210.0 MB │ configurable │
│ rust.target    │ engine/target/   │   1.8 GB │ configurable │
└────────────────┴──────────────────┴──────────┴──────────────┘
4 candidate(s), 2.0 GB reclaimable.
Nothing deleted. Run 'sweepito clean' to remove them.

Output is rendered with Rich (tables, panels, colour). Add --json for plain machine-readable output, or --no-color to turn colour off.

Profiles

The full list of targets, markers and risk levels is in docs/profiles.md.

Risk levels

Use

Selection options work the same for scan, clean, check and report:

sweepito clean -p python -p node                       # only these profiles
sweepito clean --risk configurable -x dist/            # build output, but keep dist/
sweepito clean --enable node.modules
sweepito clean --disable python.hypothesis
sweepito scan --json | jq '.total_bytes'               # for scripts
sweepito check --quiet                                 # exit 1 if anything is left

Configuration

Create sweepito.toml (or a [tool.sweepito] table in pyproject.toml). The format is the same for every language, so non-Python projects need no pyproject.toml.

[defaults]
profiles = ["auto"]            # or ["python", "node"]
risk = "safe"                  # custom | safe | configurable | high-impact

[clean]
enable  = ["rust.target", "node.next"]
disable = ["python.hypothesis"]
exclude = ["dist/", "build/keep-me/"]   # gitignore syntax; always wins

[hook]                         # applies to hook runs only
quiet = true

[[rule]]                       # custom cleanup
id = "custom.test-output"
paths = ["test-results/", "tmp/e2e/**"]

Rules you write yourself always run and are shown as custom, so there is no risk level to choose. Precedence is command line, then config file, then profile defaults, then built-in defaults. Custom rules follow the same safety gates, so a target must still be inside the project, untracked and git-ignored (or opt out of the ignore check per rule with allow_untracked = true, which never applies to tracked files). Details are in docs/configuration.md.

Command line

Run sweepito <command> --help for every option, or read docs/cli.md.

Git hook setup

With the pre-commit framework, add to .pre-commit-config.yaml:

repos:
  - repo: https://github.com/coldsofttech/Sweepito
    rev: v0.1.0
    hooks:
      - id: sweepito-clean     # post-commit cleanup
      # - id: sweepito-scan    # report-only at pre-commit

pre-commit install --hook-type post-commit

Without the framework, run sweepito hook install (add --stage pre-commit for the report-only variant). It writes .git/hooks/post-commit, appends to an existing hook instead of replacing it, and sweepito hook uninstall removes only its own block.

Hooks read the same sweepito.toml and honour the [hook] section. A post-commit hook cannot fail a commit; if cleanup fails, it prints a message to stderr.

Output, logs and exit codes

Sweepito does not write log files. Results go to standard output and problems to standard error, so you can redirect them yourself.

• --json prints one JSON document with the candidates, skipped paths (and why), removed and failed items, and freed bytes.
• -v explains why paths were skipped, and -q prints nothing unless something needs attention. Hook runs are quiet when there is nothing to clean.
• sweepito doctor shows the environment, the config in use and installed hooks.

Development setup

git clone https://github.com/coldsofttech/Sweepito
cd Sweepito
uv sync                       # uses Python 3.11, the minimum supported version
uv run pre-commit install
uv run pytest -n auto
uv run ruff check . && uv run ruff format --check .

See docs/development.md and docs/architecture.md.

Documentation

CLI · Configuration · Profiles and rules · Architecture · Development · Changelog

Contributing

Contributions are welcome, especially new technologies and rules. Please read CONTRIBUTING.md first; every change keeps the safety invariants and comes with tests. Everyone taking part is expected to follow the Code of Conduct.

Security

Because Sweepito deletes files, a bug that removes tracked files, anything outside the project or follows a symlink is a security issue. Please report it privately as described in SECURITY.md and do not open a public issue.

License

MIT