cleanup

name	cleanup
description	Clean up temporary files and session artifacts after completing a task. Use when user says "cleanup", "clean", "tidy up", "清理", or before committing / open-sourcing. Identifies: one-off node_modules, MCP session logs (.playwright-mcp), generated documents (demo.docx), empty npm scaffolding, Python __pycache__, OS junk files (.DS_Store, Thumbs.db), Claude Code artifacts (tmpclaude-*, .claude/plans/), and other disposable build/test artifacts. Optionally invokes darwin-skill for self-evolution after each cleanup.
author	Claude Code
version	1.0.0
date	"2026-05-03T00:00:00.000Z"
allowed-tools	["Bash","Read","Write","Edit","Grep","Glob","AskUserQuestion"]

Cleanup — Session Artifact Cleaner

A Claude Code skill that scans, confirms, and removes temporary files generated during coding sessions — safely and transparently.

When to Use

YOU MUST invoke this skill when the user says: "cleanup", "clean", "tidy up", "清理", "删掉临时文件", "提交前清理", "开源前清理".

Also invoke proactively after completing a complex multi-step task that likely generated scaffolding, test documents, or one-off dependencies.

Core Principles

• Safety first: when in doubt, keep it and ask the user.
• Checkpoint-driven: user confirmation before deletion, self-check after.
• Transparent: every deleted file is explained — what it was and why it's safe to remove.

---

Step 1: Scan & Catalog

Scan the current directory and list all candidate files for deletion, grouped by category. For each file, explain its purpose and why it's disposable.

Scan Categories

#	Category	Match Pattern	Heuristic
1	npm one-off deps	node_modules/ + package.json	package.json has no real project logic (only name/version/single utility dep like docx)
2	Generated documents	*.docx, *.pptx, *.pdf	Filename contains demo, test, output, sample — generated by skills, not hand-written
3	MCP session logs	.playwright-mcp/, console-*.log, page-*.yml, network-*.json	Browser automation session artifacts — 100% disposable
4	Empty scaffolding	package.json + package-lock.json	package.json has only name/version/single dep, no scripts with real logic
5	Orphaned lock files	package-lock.json without package.json	Leftover from deleted scaffolding
6	Claude Code temp	tmpclaude-*-cwd/, nul files	Known CC bug on Windows (issue #17783)
7	Python cache	__pycache__/, *.pyc, *.pyo	Bytecode cache — regenerated on next import
8	OS junk	.DS_Store, Thumbs.db, desktop.ini	OS filesystem metadata — never part of a project
9	One-off venv	.venv/, venv/	Only if not in .gitignore and requirements.txt/pyproject.toml absent
10	Test artifacts	coverage/, .nyc_output/, htmlcov/, .pytest_cache/	Test runner output — regenerated on next run
11	Build artifacts	dist/, build/, *.egg-info/	Only if pyproject.toml/setup.py absent or this is a one-off script
12	Claude Code plans	.claude/plans/	Session plan files — regenerated per-session, not reusable
13	Empty directories	Any empty dir	Check it's not a required mount point or config path

Output Format

For each candidate, output one of:

[DEPRECATED] path/to/file  (size) — what it is, why it can be deleted
[NEEDS REVIEW] path/to/file  (size) — what it is, why unsure

Exclusion Rules — NEVER Delete

These are unconditionally protected, regardless of user request:

Protected	Reason
.git/	Version control history
.claude/settings.json, .claude/settings.local.json	Project configuration
.claude/scheduled_tasks.json	May contain active cron jobs — migrate first if needed
src/, app/, pages/, components/, lib/, utils/	Source directories
*.gitignore-listed files	Intentionally ignored = intentionally kept
README.md, LICENSE, CHANGELOG.md, CONTRIBUTING.md	Project documentation
requirements.txt, pyproject.toml, Cargo.toml, go.mod	Actual project dependency declarations
.env, .env.*	Environment files (flag if contains secrets, but never delete)
Dockerfile, docker-compose.yml	Infrastructure definitions
Makefile, Justfile	Build system entry points

---

Step 2: Confirm

Use AskUserQuestion to confirm deletions. Present options:

"Delete these files?"

Options:
- "Delete All" — remove all [DEPRECATED] files
- "Review Each" — confirm one at a time
- "Cancel" — keep everything

For each [NEEDS REVIEW] file, ask separately with an explanation of the uncertainty.

---

Step 3: Execute & Verify

Execute

rm -rf [confirmed files and directories]

For nul files on Windows (can't be deleted natively):

wsl rm -f /mnt/c/path/to/nul

Self-Check

Immediately after deletion, verify:

1. git status — no git-tracked files were deleted
2. Project integrity — if package.json remains, npm ls succeeds
3. Config integrity — .claude/ essential files still present
4. No broken imports — if source files deleted, check remaining files don't import them

Rollback

If the self-check detects a problem:

1. Report immediately: "Detected [file] was incorrectly deleted — may affect [function]"
2. Ask: "Restore from git?" → git checkout -- [file] or git restore [file]
3. If not in git, ask if the user has a backup

---

Step 4: Self-Evolution (Optional)

If darwin-skill is installed, invoke it after each cleanup to improve this skill.

4a: Log the Cleanup

Append to ~/.claude/skills/cleanup/cleanup_log.jsonl:

{
  "date": "ISO-8601",
  "project": "project-directory-name",
  "deleted": [
    {"path": "relative/path", "category": "category-name", "size": "human-readable"}
  ],
  "kept": ["files-user-chose-to-keep"],
  "user_notes": "any user feedback"
}

4b: Invoke Darwin

If ~/.claude/skills/darwin-skill/SKILL.md exists:

Skill(darwin-skill, "optimize cleanup skill. This session deleted [N] files
([categories]). User kept [M] files. Review cleanup_log.jsonl for patterns
and improve SKILL.md accordingly.")

If darwin-skill is not installed, skip this step silently.

---

Step 5: Report

Output a structured summary:

## Cleanup Report

**Before**: [total size]
**After**: [total size]
**Freed**: [delta]

**Deleted**:
- file1 (size) — reason
- file2 (size) — reason

**Kept**:
- file3 — reason kept

**Self-Check**: all-clear / issues-found
**Darwin**: optimized / skipped (not installed)

**Tip**: [any additional optimization suggestion]

---

Known Issues

Windows: tmpclaude-*-cwd and nul Files

Claude Code has a known bug on Windows where sub-agent worktrees (tmpclaude-*-cwd/) and literal nul files (from /dev/null not being translated to NUL) are left behind after sessions.

• nul files cannot be deleted by Windows native tools (reserved device name). Use WSL: wsl rm -f /mnt/c/path/to/nul
• Reference: Claude Code issue #17783
• Feature request for auto-cleanup: issue #11963

.claude/plans/ Accumulation

Plans are created per-session and can accumulate over time. They are safe to delete — Claude Code regenerates them as needed. However, if a plan was carefully crafted and may be reused, flag it as [NEEDS REVIEW] instead.

---

Pre-Deletion Checklist

Before executing any deletion, verify:

• git status reviewed — no tracked files targeted
• node_modules cross-referenced with package.json — is it a real project?
• .claude/ contents checked for active cron jobs before deletion
• package.json scripts and dependencies fields read — confirms non-project
• Generated documents confirmed not hand-written project docs
• User explicitly approved the deletion list
• Rollback path available (git or backup)

---

Examples

Example 1: After generating a Word document

Scan results:
[DEPRECATED] node_modules/ (8.9 MB) — installed only for docx generation
[DEPRECATED] package.json (294 B) — scaffolding for docx, no project logic
[DEPRECATED] package-lock.json (8 KB) — lock file for scaffolding
[DEPRECATED] demo.docx (12 KB) — generated test document
[DEPRECATED] .playwright-mcp/ (12 KB) — browser session logs

→ User confirms "Delete All"
→ Freed: ~9 MB
→ Self-check: git status clean

Example 2: Python project with cache

Scan results:
[DEPRECATED] __pycache__/ (1.2 MB) — Python bytecode cache
[DEPRECATED] .pytest_cache/ (48 KB) — pytest cache
[DEPRECATED] .DS_Store (6 KB) — macOS metadata

→ User confirms "Delete All"
→ Freed: ~1.3 MB
→ Self-check: pytest still passes