Cleanup

Project Cleanup

Audit and clean the project workspace across 7 categories. Every action follows the same safety protocol: scan first, preview changes, confirm with user, then execute.

Before Starting

Read these files for context:

• CLAUDE.md — Project structure, tech stack, protected patterns
• .gitignore — Existing ignore rules
• references/protected-paths.md — Common paths that must never be modified or deleted

If the project has a local .claude/skills/cleanup/references/known-temp-patterns.md, read that too for project-specific temp file patterns.

Safety Protocol

These rules are non-negotiable and override any user request:

Invocation

/cleanup [category] or /cleanup all

If no category specified, present this menu using AskUserQuestion (multiSelect: true):

Run categories in this order (rationale in parentheses):

1. security (highest priority)
2. temp (quick wins, free space)
3. git (committing untracked files affects what appears unused)
4. deps (after git, so committed files are visible)
5. dead-code (after deps, for accurate analysis)
6. build (clear stale caches)
7. quality (last — lint against clean state)

Category: security

Find exposed secrets, credential files outside protected directories, and missing gitignore rules.

Scan

# Check common auth/secret directories are gitignored
for dir in .auth .secrets .credentials; do
  [ -d "$dir" ] && git check-ignore -v "$dir" 2>&1
done

# Find credential-like files in project (max depth 3)
find . -maxdepth 3 \( -name "client_secret*" -o -name "credentials.json" -o -name "token.json" -o -name "*.pem" -o -name "*.key" -o -name "service-account*.json" -o -name ".env" \) -not -path "./node_modules/*" 2>/dev/null

# For each found file, check if gitignored
# git check-ignore -v <file>

# Scan for hardcoded secrets in source code (adapt paths to project)
grep -rn "sk-[a-zA-Z0-9]\{20,\}" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.mjs" --include="*.py" . 2>/dev/null | grep -v node_modules
grep -rn "Bearer [a-zA-Z0-9]\{20,\}" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.mjs" . 2>/dev/null | grep -v node_modules

Preview Format

## Security Audit

| # | Issue | File | Severity | Action |
|---|-------|------|----------|--------|
| 1 | .auth/ not in .gitignore | .gitignore | HIGH | Append to .gitignore |
| 2 | Credential file in root | client_secret_*.json | MEDIUM | Move to secure dir |

Execute

For gitignore additions — append to .gitignore (never replace). For file relocations — mv to a gitignored directory. NEVER delete credential files — only relocate or gitignore them.

Category: temp

Detect and remove temporary files that accumulated from one-off tasks.

Scan

Adapt scans to the project. Common patterns:

# Screenshot artifacts in project root
ls -la *.png *.jpg *.jpeg *.gif 2>/dev/null

# Debug/extraction JSON files in root (exclude config files)
ls -la *.json 2>/dev/null | grep -v -E 'package|tsconfig|eslintrc|\.mcp|composer'

# Temp directories
du -sh .auth/*/ tmp/ temp/ .tmp/ 2>/dev/null

# Log files
ls -la *.log 2>/dev/null

# Core dumps, heap snapshots
ls -la core.* *.heapsnapshot 2>/dev/null

Also check for project-specific patterns:

• Build tool temp dirs (.turbo/, .parcel-cache/, .vite/)
• Browser automation caches (.auth/*/, playwright-data/)
• One-off script outputs in root

Preview Format

## Temp Files Audit

| # | File/Dir | Size | Origin | Action |
|---|----------|------|--------|--------|
| 1 | screenshot.png | 136K | Debug output | Delete |
| 2 | .auth/browser-cache/ | 81M | Playwright cache | Delete |

**Total reclaimable: ~XX MB**

Execute

Only delete user-approved items via rm -f (files) or rm -rf (directories).

Category: git

Review untracked files, stale branches, and uncommitted work.

Scan

# Untracked files
git status --short | grep "^??"

# Modified but unstaged
git status --short | grep "^ M\|^M "

# All branches (local + remote)
git branch -a

# Large untracked items
git status --short | grep "^??" | awk '{print $2}' | xargs -I{} du -sh {} 2>/dev/null

# Check for merge conflict markers
grep -rn "<<<<<<< " --include="*.ts" --include="*.tsx" --include="*.js" --include="*.py" . 2>/dev/null | grep -v node_modules

Preview Format

Split untracked files into two groups:

## Git Hygiene Audit

### Untracked — Likely to Commit
| # | Path | Type | Size | Suggestion |
|---|------|------|------|------------|
| 1 | src/new-feature/ | Feature | 8K | Commit |

### Untracked — Likely Temp/Artifacts
| # | Path | Type | Size | Suggestion |
|---|------|------|------|------------|
| 1 | debug-*.png | Screenshot | 900K | Delete (or run `temp` category) |

### Modified but Unstaged
| # | File | Status |
|---|------|--------|
| 1 | README.md | Modified |

### Branches
| # | Branch | Suggestion |
|---|--------|------------|
| 1 | remotes/origin/old-feature | Check if merged → delete |

Execute

For committing — git add <paths> then git commit -m "chore: ...". For branch cleanup — git branch -d <branch> (safe delete, only if merged), git remote prune origin.

Category: deps

Find unused, outdated, or duplicate dependencies.

Scan

Detect package manager and run appropriate tool:

# Preferred: knip (comprehensive — works with npm, yarn, pnpm)
npx knip --dependencies 2>/dev/null

# Fallback: depcheck (npm/yarn projects)
npx depcheck 2>/dev/null

# Outdated packages
npm outdated 2>/dev/null || yarn outdated 2>/dev/null || pnpm outdated 2>/dev/null

Preview Format

## Dependency Audit

### Unused Dependencies
| # | Package | Type | Confidence | Action |
|---|---------|------|------------|--------|
| 1 | some-package | production | High | Uninstall |

### Outdated (major versions behind)
| # | Package | Current | Latest | Breaking? |
|---|---------|---------|--------|-----------|
| 1 | some-lib | 2.0.0 | 4.0.0 | Yes — review changelog |

Execute

Uninstall unused packages with the project's package manager. For outdated — only suggest, do not auto-update without explicit per-package approval.

Category: dead-code

Find unused files, exports, types, and components.

Scan

# Preferred: knip (comprehensive — unused files, exports, types)
npx knip 2>/dev/null

# Fallback: manual checks for TypeScript projects
# Unused exports
grep -rn "export type\|export interface\|export function\|export const" --include="*.ts" --include="*.tsx" . 2>/dev/null | grep -v node_modules

# Orphaned components (imported in 0-1 files) — adapt glob to project
# for f in components/**/*.tsx; do ...

Preview Format

## Dead Code Audit

### Unused Exports
| # | Export | File | Confidence |
|---|--------|------|------------|
| 1 | SomeType | types/index.ts | High |

### Unused Files
| # | File | Last Modified | Confidence |
|---|------|---------------|------------|
| 1 | src/old-util.ts | 30 days ago | Medium |

Execute

Before removing dead code, ALWAYS offer:

Create safety stash before removing dead code? (recommended) [y/n]

If yes: git stash push -m "cleanup: pre-dead-code-removal backup"

Then remove approved items only.

Category: build

Clear build caches and generated output directories.

Scan

Detect framework and check common cache locations:

# Common build caches
du -sh .next/ dist/ build/ output/ .turbo/ .parcel-cache/ .vite/ node_modules/.cache/ __pycache__/ .pytest_cache/ target/ 2>/dev/null

Preview Format

## Build Cache Audit

| # | Directory | Size | Gitignored | Action |
|---|-----------|------|------------|--------|
| 1 | .next/ | 331M | Yes | Delete (rebuilds on dev) |
| 2 | node_modules/.cache/ | 50M | Yes | Delete (rebuilt automatically) |

**Total reclaimable: ~XXX MB**

Execute

Delete approved directories. After clearing, remind user how to rebuild (e.g., npm run dev, npm run build).

Category: quality

Lint issues, TODO/FIXME comments, console.log statements, and type errors.

Scan

Detect available linting tools and run:

# Lint (detect tool)
npm run lint 2>&1 || npx eslint . 2>&1 || echo "No linter configured"

# TODO/FIXME comments in source (exclude node_modules, .git, build dirs)
grep -rn "TODO\|FIXME\|HACK\|XXX" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" --include="*.py" . 2>/dev/null | grep -v node_modules | grep -v ".next/"

# console.log in production code
grep -rn "console\.\(log\|debug\|warn\)" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" . 2>/dev/null | grep -v node_modules | grep -v ".next/"

# TypeScript errors (if tsconfig exists)
[ -f tsconfig.json ] && npx tsc --noEmit 2>&1 | head -50

Preview Format

## Code Quality Audit

### ESLint Issues
| # | File | Line | Rule | Message |
|---|------|------|------|---------|
| 1 | src/app.tsx | 12 | no-unused-vars | 'x' defined but never used |

### TODO/FIXME Comments
| # | File | Line | Comment |
|---|------|------|---------|
| 1 | src/api/route.ts | 45 | TODO: refactor |

### Console Statements
| # | File | Line | Statement |
|---|------|------|-----------|
| 1 | src/api/route.ts | 23 | console.log(...) |

### TypeScript Errors
[from tsc --noEmit output]

Execute

For ESLint auto-fixable: npx eslint --fix <file>. For console.log removal and TODO resolution — handle manually per item after user approval.

Final Summary

After all selected categories complete, present:

## Cleanup Summary

| Category | Found | Fixed | Skipped | Space Freed |
|----------|-------|-------|---------|-------------|
| security | 2 | 2 | 0 | — |
| temp | 5 | 4 | 1 | 84 MB |
| git | 10 | 8 | 2 | — |
| deps | 1 | 1 | 0 | — |
| dead-code | 0 | 0 | 0 | — |
| build | 2 | 2 | 0 | 400 MB |
| quality | 4 | 3 | 1 | — |

**Total space freed: XXX MB**
**Security issues resolved: X**

### Remaining Items (manual follow-up)
1. [ ] Item requiring manual attention
2. [ ] ...