DevBroom

DevBroom is a small cross-platform utility for reclaiming disk space from development dependencies.

It scans a directory, finds removable folders such as node_modules and Python virtual environments, shows their estimated size, and lets you clean them through either:

• a Tkinter desktop UI
• a headless CLI mode for remote or Linux server workflows

Installation

pip install devbroom

Requires Python 3.10 or newer.

On Linux, Tkinter may need to be installed separately before the GUI will open (see Quick Start → Linux below).

Upgrade

pip install --upgrade devbroom

Run from source

If you prefer to clone the repo instead:

git clone https://github.com/Sandhu93/devBroom.git
cd devBroom
pip install -e .

Interface Preview

Why This Project Matters

Developer machines and shared workstations tend to accumulate large dependency folders that are safe to rebuild but expensive to keep. DevBroom focuses on that narrow but common cleanup problem: identify heavyweight development artifacts quickly, show the likely reclaimable space, and let the user clean them without touching real application code. The result is a small, practical tool that demonstrates filesystem traversal, cross-platform behavior, GUI/CLI dual-mode design, and safety-oriented cleanup logic in one project.

Architecture

flowchart TD
    A[main.py] --> B[devbroom.app.main]
    B --> C{CLI mode?}

    C -- No --> D[DevBroomApp Tkinter UI]
    C -- Yes --> E[run_cli]

    D --> F[Load settings]
    D --> G[User actions]
    G --> H[Start scan]
    G --> I[Preview or export visible results]
    G --> J[Delete selected results]
    G --> K[Manage ignored paths and theme]

    E --> F
    E --> L[scan_targets]
    E --> M[Console report]
    E --> N[Optional JSON export]

    H --> O[iter_scan_targets]
    L --> O

    O --> P[scanner.py]
    P --> Q[Detect node_modules]
    P --> R[Validate virtualenv folders]
    P --> S[Apply ignored-path pruning]
    P --> T[Estimate folder sizes]

    D --> U[ui.py]
    E --> V[cli.py]
    J --> W[cleanup.py]
    F --> X[settings.py]
    P --> Y[models.py]
    V --> Y
    U --> Y

What A User Should Know First

• Problem solved: developer machines accumulate large dependency folders that are safe to rebuild but expensive to keep.
• Primary value: quickly find and remove disk-heavy dependency directories without touching application source code.
• Supported targets: node_modules and real Python virtual environments.
• Supported environments: Windows and Linux.
• Interfaces: GUI for local desktop use, CLI for headless use.
• Safety posture: conservative detection, ignored-path support, confirmation before deletion, symlink protection, and partial-failure reporting.

Quick Start

After pip install devbroom, the devbroom command is available system-wide.

Windows

devbroom          # opens the GUI
devbroom --help   # show all CLI options

Tkinter is included with the standard Python installer from python.org, so the GUI works out of the box.

Linux

Some Linux distributions do not include Tkinter by default. Install it before using the GUI:

# Debian / Ubuntu
sudo apt install python3-tk

# Fedora
sudo dnf install python3-tkinter

Then:

devbroom          # opens the GUI
devbroom --help   # show all CLI options

How To Use The Application

GUI Workflow

1. Start the app with devbroom (no flags).
2. Choose the root directory you want to scan.
3. Click Scan.
4. Review the discovered cleanup candidates.
5. Optionally filter, preview, export, or ignore folders.
6. Select the rows you want to delete.
7. Click Delete Selected.

CLI Workflow

Basic scan:

devbroom --cli --path /path/to/projects

Skip saved ignore paths for one run:

devbroom --cli --path /path/to/projects --no-settings-ignores

Export results to JSON:

devbroom --cli --path /path/to/projects --json-out scan-report.json

Preview what would be deleted without removing anything:

devbroom --cli --path /path/to/projects --dry-run

Delete all discovered targets (with confirmation prompt):

devbroom --cli --path /path/to/projects --delete

Delete all discovered targets without a confirmation prompt:

devbroom --cli --path /path/to/projects --delete --yes

Include targets that are not inside a git repository (e.g. when scanning an entire drive):

devbroom --cli --path /path/to/scan --include-non-project

Only show targets that have not been modified in the last N days:

devbroom --cli --path /path/to/projects --older-than 90

This is useful for skipping active projects. A node_modules or virtualenv that has not had packages installed or removed in 90 days is a much safer deletion candidate than one that was touched yesterday.

CLI output includes:

• matching folders sorted by size (largest first)
• estimated sizes and age of each target
• live progress indicator while scanning
• total reclaimable size
• optional JSON export

Core Features

• Scan a chosen directory recursively
• Detect node_modules
• Detect Python virtual environments such as venv, .venv, and virtualenv
• Show estimated folder sizes and age of each target before deletion
• Filter results by age with --older-than N (CLI) or the age spinbox (GUI)
• Live scan progress indicator in CLI mode
• Non-blocking deletion with live per-item progress in the GUI
• Selectively delete only the folders you choose
• Remember last scanned path and preferred theme
• Persist ignored scan paths
• Preview current visible scan results
• Export scan results to JSON or text
• Light mode and dark mode UI

Detection Rules

DevBroom scans for these targets:

• node_modules
• venv
• .venv
• virtualenv

Virtual environment candidates are only treated as real Python environments if they contain one of:

• pyvenv.cfg
• Scripts/activate
• bin/activate

This prevents deleting unrelated folders that only happen to use a common virtualenv-like name.

By default, devBroom only surfaces targets that live inside a git repository. This prevents folders bundled inside installed applications (VS Code, Arduino IDE, pgAdmin, etc.) from appearing as cleanup candidates. Pass --include-non-project to disable this filter.

The scanner also skips likely nested package locations such as:

• site-packages
• Lib
• lib
• node_modules

That reduces false positives inside installed dependencies.

Preview And Export

From the GUI:

• Preview opens a read-only view of the current visible scan results
• Export saves the current visible scan results as .json or .txt

From the CLI:

• --json-out scan-report.json exports JSON
• the console output itself serves as a plain-text preview/report

Safety Notes

• Deletion is permanent. Items are not moved to Trash or Recycle Bin.
• Symlinked directories are skipped during scanning.
• Symlink targets are not deleted.
• Read-only files are handled during deletion where possible.
• Permission errors and locked files are reported without aborting the entire operation.

Project Layout

• main.py: thin application launcher
• devbroom/app.py: app startup and CLI/GUI mode selection
• devbroom/cli.py: headless CLI scan/report mode
• devbroom/ui.py: Tkinter UI and theme handling
• devbroom/scanner.py: target discovery and size calculation
• devbroom/cleanup.py: delete helpers and filesystem cleanup
• devbroom/models.py: shared constants and ScanTarget
• devbroom/settings.py: saved preferences and ignored paths
• tests/test_scanner.py: scanner tests
• tests/test_cleanup.py: cleanup tests
• tests/test_settings.py: settings tests
• tests/test_cli.py: CLI tests

Tests

The project includes a strong non-UI unit test suite.

Run the full suite:

python -m unittest discover -s tests

GitHub Actions also runs the test suite automatically on pushes to main and on pull requests targeting main.

You can also run each file directly:

python tests/test_scanner.py
python tests/test_cleanup.py
python tests/test_settings.py
python tests/test_cli.py

Covered areas:

• target detection
• virtualenv validation
• nested-folder skip behavior
• ignored path handling
• scan cancellation behavior
• safe delete behavior
• read-only file cleanup behavior
• settings persistence
• CLI scan and JSON export behavior
• text report export behavior

The suite is intentionally strongest around non-UI logic. Tkinter widget behavior is still validated manually rather than through UI automation tests.

Known Limitations

• Scans can be slow on very large directories because folder sizes are calculated recursively.
• Locked files on Windows may still prevent complete deletion.
• Tkinter styling can vary across platforms and desktop environments.
• GUI export currently exports visible rows only, which is usually the right behavior after filtering.

Good Next Modifications

• Add CSV export for results that are easier to open in spreadsheets.
• Add a GUI toggle to include or exclude non-project targets (currently CLI-only via --include-non-project).
• Add a progress indicator showing scan depth or folders visited for large directory trees.

Contributing

Contributions, fixes, and small usability improvements are welcome.

If you want to contribute:

• open an issue for bugs or feature ideas
• keep pull requests focused and easy to review
• run the test suite before submitting

See CONTRIBUTING.md for details.

What I Would Not Add Yet

• a database
• background worker processes
• plugin architecture
• heavy UI automation for the current Tkinter surface

Engineering Decisions

• Conservative target detection over aggressive cleanup. Virtual environment folders are validated with marker files instead of trusting names alone, which reduces dangerous false positives.
• Shared scanner and reporting logic across GUI and CLI. This keeps behavior consistent and reduces duplication between local desktop use and headless server workflows.
• Lightweight JSON settings instead of a config framework or database. The project only needs a few persisted values, so a simple file is easier to inspect and maintain.
• Focused non-UI tests over brittle GUI automation. The highest-risk logic lives in scanning, deletion, settings, and reporting, so that is where the test investment provides the most value.
• Intentional feature restraint. The project avoids plugins, background services, and packaging complexity until the core cleanup workflow is more mature.