Project Workspace Cleaner
Run a read-only scan over repositories in a workspace root and rank cleanup chores by severity.
Inputs
- Optional CLI overrides:
- --workspace - --min-mb - --stale-days - --max-findings - --config - --json
- Config precedence:
1. CLI flags 2. config/customization.yaml 3. config/customization.template.yaml 4. script defaults
Workflow
- Resolve settings using the documented precedence.
- Run
scripts/scan_workspace_cleanup.py. - Record skipped paths when traversal or stat operations fail, then continue scanning remaining accessible paths.
- Rank findings by severity, score, size, repo, and directory.
- Return the ranked findings plus repo-level totals.
- If there are no findings and no skipped paths, report the user-facing clean result.
Output Contract
Each finding includes:
severityrepodirectorycategorysize_humanscorewhy_flaggedsuggested_cleanup- Repo summary includes total flagged size and finding counts per severity.
- JSON output includes
partial_resultsandskipped_paths. - For user-facing clean runs, output exactly
No findings. - If any path is skipped, return a partial-results warning and list skipped paths instead of using the clean-run message.
Guardrails
- Never run destructive commands.
- Never remove artifacts automatically.
- Never write into scanned repositories.
- Provide recommendations only.
References
references/config-schema.mdreferences/customization.mdreferences/automation-prompts.mdreferences/patterns.md