# Cleanup

Reclaim disk space and prune branches left behind by AI coding agents - merged or...

- Repository: https://github.com/davepoon/buildwithclaude (3705 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add davepoon/buildwithclaude --skill cleanup -g -a claude-code -y`
Codex: `npx skills add davepoon/buildwithclaude --skill cleanup -g -a codex -y`
Cursor: `npx skills add davepoon/buildwithclaude --skill cleanup -g -a cursor -y`
Gemini CLI: `npx skills add davepoon/buildwithclaude --skill cleanup -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add davepoon/buildwithclaude`

## Description

Reclaim disk space and prune branches left behind by AI coding agents - merged or abandoned git worktrees, merged branches, stale build artifacts (node_modules, .venv, target), old archives and backups, package caches, and old agent session logs. Use when the user runs /cleanup, says the disk is full, or asks to clean up worktrees, branches, or storage.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Cleanup

Free disk space and prune branches with one scan, one confirmation, and one apply. Every deletion goes through `scripts/agent_cleanup.py` in this skill's directory. Right before acting, it re-checks each git item, artifact folder, archive and the trash, and skips anything that changed since the scan.

## 1. Scope

Choose what to scan:

- **This repo** (default): run from inside it with no `--root`. The scan covers this repo, the agent worktree folders (Codex, Cursor, Conductor, Vibe Kanban), package caches, agent logs and the trash.
- **Whole machine**: the user says disk full, all projects, or everything. Add `--root <dir>` for each folder that holds their projects. Look for the usual ones (`~/code`, `~/dev`, `~/src`, `~/projects`, `~/repos`, `~/Developer`, `~/Documents/*`). If none of them exist, ask the user.

Narrow with `--only git,artifacts,archives,caches,agents,trash` when the user asks for one kind, e.g. "just branches" → `--only git`. Add `--remote` only when the user wants merged branches deleted on `origin` too.

Done when the scan command is chosen.

## 2. Scan

```
python3 <skill-dir>/scripts/agent_cleanup.py scan --fetch [--root DIR ...] [--only ...] [--remote]
```

The scan is read-only, apart from `--fetch` updating remote-tracking refs. It prints numbered items in four classes and saves the plan:

- `REMOVE`: merged into the base branch, regenerable, or a worktree whose directory is already gone (unregistering it keeps its branch).
- `NEEDS-DECISION`: holds something unique (uncommitted or ignored files, unmerged or unpushed commits, build output, archives, old logs).
- `KEEP-ACTIVE` and `SKIP`: open PRs, recent work, long-lived branches, the main checkout, locked or rebasing worktrees, anything a running process is inside, unmounted drives. Never act on these.

`--help` lists the thresholds (`--stale-days`, `--keep-days`, `--min-size`).

Done when the plan is printed with its reclaimable total.

## 3. One confirmation

The rest: https://github.com/davepoon/buildwithclaude/blob/HEAD/plugins/all-skills/skills/cleanup/SKILL.md