convez.ai
SkillAutomaçãoIntermediário
jcordon5

Disk Cleaner Skill

jcordon5/disk-cleaner-skill

Libere espaço em disco com segurança via conversação natural

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill conversacional e seguro para limpeza de disco em macOS e Linux, integrado a agentes Claude. Realiza scan adaptativo, classifica riscos, apresenta dashboard local e nunca deleta sem aprovação explícita.

Instalação

$npx convez-ai jcordon5/disk-cleaner-skill

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
v0.1-alpha
Issues abertas
0
Contribuidores
1

Casos de uso

  • Liberar espaço em disco sem entender terminais ou caches
  • Analisar onde o espaço em disco foi consumido de forma visual
  • Limpar caches e arquivos regeneráveis com aprovação prévia

Veredito

Ferramenta sólida para automação segura de limpeza de disco com foco em proteção de dados e aprovação do usuário. Ainda em alpha (v0.1), mas bem testada como scanner e dashboard; recomenda-se revisar dry-run antes de deletar.

README

A tradução para o português deste README ainda está na fila.

disk-cleaner-skill

A safe, conversational disk-cleanup skill for Claude / Codex agents on macOS and Linux. Ask your assistant to free up space and it figures out where your space actually went, explains it in plain language, shows a local visual dashboard, and never deletes anything without your explicit approval.

Install

Add it to any of your agents in one line:

npx skill add https://github.com/jcordon5/disk-cleaner-skill

Then just talk to your assistant: "my disk is full, can you help me clean it up?"

Or install manually and verify it runs:

git clone https://github.com/jcordon5/disk-cleaner-skill
cd disk-cleaner-skill
python3 -m py_compile scripts/disk_cleaner.py   # sanity check (no deps)
python3 -m unittest discover -s tests            # run the safety tests

Try it risk-free

Want to see exactly what it does before pointing it at your real machine? Run the built-in demo — it scans a harmless fake home (sparse files, no real disk used) that exercises every category:

python3 scripts/disk_cleaner.py scan --demo
python3 scripts/disk_cleaner.py serve          # open the dashboard
python3 scripts/disk_cleaner.py clean --safe-only --dry-run

Status: v0.1-alpha. Solid and well-tested as a scan + dashboard + dry-run tool, and safe for cleaning your own caches with explicit approval. Review the dry-run before any real deletion, especially on someone else's machine.

What it's for

Recovering disk space without needing to understand terminals, caches, package managers, app containers, Docker, browser profiles, virtual machines, or system folders. It's adaptive — it isn't hardcoded to specific apps. It measures real disk usage on your machine, classifies what it finds by safety, and only ever touches what you approve.

What it does, in order:

  1. Scan adaptively — measures where space went, drilling only into folders that actually consume meaningful space.
  2. Classify everything by safety: safe cache · safe-to-rebuild · review required · protected.
  3. Show a local browser dashboard (no internet, nothing leaves your machine).
  4. Explain the findings in plain language and ask before deleting anything.
  5. Clean only what you approve — deleting regenerable caches directly and moving everything else to the Trash.
  6. Report how much space was recovered, with a self-contained HTML report.

Safety first

  • Nothing is deleted during discovery — scanning only measures.
  • Protected data is never offered for cleanup: SSH/GPG keys, keychains, browser logins, documents, photos, mail, cloud-sync folders, system directories — and it's refused again at delete time by an independent re-validation pass.
  • Anything that isn't a pure cache goes to the Trash, so it's recoverable.
  • Every action is written to an append-only audit log (~/.disk-cleaner/actions.log.jsonl).

Using it directly (the bundled CLI)

The assistant drives this for you, but you can run it yourself too. No dependencies beyond Python 3 — standard library only, no network access.

python3 scripts/disk_cleaner.py scan      # measure usage (never deletes)
python3 scripts/disk_cleaner.py scan --demo            # try it on a fake home
python3 scripts/disk_cleaner.py serve     # open the live local dashboard
python3 scripts/disk_cleaner.py plan      # build an approvable plan (units get ids)
python3 scripts/disk_cleaner.py clean --safe-only --dry-run    # preview pure-safe
python3 scripts/disk_cleaner.py clean --rebuildable --dry-run  # preview rebuildable
python3 scripts/disk_cleaner.py clean --id dc_003 --id dc_007  # approve by id
python3 scripts/disk_cleaner.py clean --category "browser cache"
python3 scripts/disk_cleaner.py report    # freed-now vs moved-to-trash
python3 scripts/disk_cleaner.py snapshot  # self-contained report.html (no server)

Approval is granular by design: --safe-only clears only throwaway caches/temp/ logs; --rebuildable (package/build/browser caches and downloaded AI models) is a separate opt-in because those cost time/bandwidth to get back; --all-safe is both. Review items (VMs, downloads, toolchains, large media) only ever move to the Trash, never deleted.

scan and clean also write ~/.disk-cleaner/report.html automatically — a single self-contained file (data embedded inline) you can open by double-click anytime, no server or internet needed. All state lives in ~/.disk-cleaner/ (override with the DISK_CLEANER_HOME environment variable).

The risk model

LevelMeaningAction if approved
safeRegenerated automatically, no user-visible loss (temp, logs, app caches)delete
safe, may re-downloadSafe, but costs time/bandwidth to rebuild (package/build/browser/model caches)delete
review requiredCould matter; only you can judge (VMs, games, media, downloads, big projects)move to Trash
protectedSensitive or unclassifiable (keys, documents, photos, cloud-sync, system)never touched

See references/risk-model.md for the full classification and safety details.

Layout

disk-cleaner-skill/
├── SKILL.md                  # assistant behavior & conversation flow
├── README.md
├── scripts/disk_cleaner.py   # the adaptive scanner / cleaner CLI
├── dashboard/index.html      # local-only visual dashboard
├── references/risk-model.md  # full classification & safety details
├── tests/test_disk_cleaner.py # safety tests (classification + delete-time backstop)
└── evals/evals.json          # test prompts

License

MIT

Disclaimer

This software is provided "as is", without warranty of any kind. It deletes and moves files on your system. While it is designed to be conservative — scan first, explicit approval, protected data never touched, review items sent to the Trash, and an independent re-check before every deletion — no safeguard is perfect.

You are solely responsible for deciding what to remove and for verifying the results. Always review the dry-run output before any real deletion, and keep backups of anything important. The author accepts no liability for data loss, improperly deleted files, or any damage arising from the use or misuse of this skill. By using it, you accept that you do so at your own risk.

Este software se ofrece "tal cual", sin garantía de ningún tipo. El autor no se hace responsable de la pérdida de datos, del borrado indebido de archivos ni de ningún daño derivado del uso o uso indebido de esta skill. Lo usas bajo tu propia responsabilidad: revisa siempre la simulación (dry-run) antes de borrar y mantén copias de seguridad de lo importante.

Ver o original no GitHub

Bom para

Relacionados