mcpField
P
project-workspace-cleaner

project-workspace-cleaner

github.com/gaelic-ghostDevelopment160 installs
Repository

About project-workspace-cleaner

A read-only skill that scans repositories under a workspace root and ranks cleanup findings by severity. It reports repository-level totals and skipped paths while providing recommendations without modifying files.

Key features

  1. 01Read-only workspace repository scan
  2. 02Configurable scan thresholds and limits
  3. 03Severity-ranked cleanup findings
  4. 04Repository totals and skipped-path reporting
  5. 05Recommendations without file changes

Use cases

  1. 01Review generated or stale repository artifacts
  2. 02Prioritize cleanup across workspace repositories
  3. 03Identify large directories for manual review
  4. 04Audit scans with partial results

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/gaelic-ghost/productivity-skills --skill project-workspace-cleaner

After installing, type/project-workspace-cleanerin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

agents/
openai.yaml
config/
customization.template.yaml
references/
automation-prompts.md
config-schema.md
customization.md
patterns.md
scripts/
scan_workspace_cleanup.py
tests/
test_scan_workspace_cleanup.py

Details

From the project README

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

  1. Resolve settings using the documented precedence.
  2. Run scripts/scan_workspace_cleanup.py.
  3. Record skipped paths when traversal or stat operations fail, then continue scanning remaining accessible paths.
  4. Rank findings by severity, score, size, repo, and directory.
  5. Return the ranked findings plus repo-level totals.
  6. If there are no findings and no skipped paths, report the user-facing clean result.

Output Contract

Each finding includes:

  • severity

  • repo

  • directory

  • category

  • size_human

  • score

  • why_flagged

  • suggested_cleanup

  • Repo summary includes total flagged size and finding counts per severity.

  • JSON output includes partial_results and skipped_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.md
  • references/customization.md
  • references/automation-prompts.md
  • references/patterns.md

Comments

Markdown supported