Skip to main content
command CX Codex

cleanup · carlrannaberg — Claude Code command: what it does, how to install

cleanup finds disposable debug scripts, test files, and generated reports from Claude Code sessions and prompts before removing them.

MIT ★ 763 updated 2026-03-31

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/commands/cleanup.md
Open on GitHub

What cleanup does

During coding sessions, Claude Code frequently leaves behind helper scripts, *_REPORT.md summaries, and scratch directories like temp-*. The cleanup command starts a subagent to scan git status for untracked or ignored debugging remnants. When the working tree is clean, it searches for committed files matching disposable patterns such as debug-*.js or *-poc.*.

Safety is enforced strictly: the subagent prepares a detailed removal candidate list and stops. It never deletes files without explicit user approval. Root documentation like CLAUDE.md, core folders like src/, and standard directories such as tests/ or __tests__/ are excluded entirely.

Once confirmed, untracked files are cleared via rm, while committed items are removed through git rm. The tool then offers tailored .gitignore rules to block matching artifacts from accumulating in future sessions.

What it helps with

  • detect abandoned debug scripts and markdown summaries
  • safely remove temporary POC directories without touching project tests
  • purge committed scratch files from version control with git rm
  • generate .gitignore entries based on detected disposable files

Example prompts for the agent

  • /cleanup
  • Run /cleanup to review debug artifacts in this branch
  • /cleanup and suggest gitignore rules for temporary files

How to install cleanup

Manually: put the files in place

.claude/commands/cleanup.md

Call it with /cleanup. For all projects use ~/.claude/commands/

Questions about cleanup

How to install cleanup in Claude Code?

Save the command configuration to .claude/commands/cleanup.md in your project root.

Does cleanup delete files automatically?

No, it only presents a proposal with reasons for each file and waits for confirmation before deleting anything.

Which files does cleanup ignore?

It never touches README.md, CLAUDE.md, core folders like src/, or standard test folders like test/ and __tests__/.

Source text

cleanup.md · MIT
---
description: Clean up debug files, test artifacts, and status reports created during development
category: workflow
allowed-tools: Task, Bash(git:*), Bash(echo:*), Bash(grep:*), Bash(ls:*), Bash(pwd:*), Bash(head:*), Bash(wc:*), Bash(test:*)
---

## Purpose

Clean up temporary files and debug artifacts that Claude Code commonly creates during development sessions. These files clutter the workspace and should not be committed to version control.

## Context

\!`git status --porcelain && git status --ignored --porcelain | grep "^!!" && echo "--- PWD: $(pwd) ---" && ls -la && if [ -z "$(git status --porcelain)" ]; then echo "WORKING_DIR_CLEAN=true" && git ls-files | grep -E "(analyze-.*\.(js|ts)|debug-.*\.(js|ts)|test-.*\.(js|ts|sh)|.*-test\.(js|ts|sh)|quick-test\.(js|ts|sh)|.*-poc\..*|poc-.*\..*|.*_poc\..*|proof-of-concept-.*\..*|verify-.*\.md|research-.*\.(js|ts)|temp-.*/|test-.*/|.*_SUMMARY\.md|.*_REPORT\.md|.*_CHECKLIST\.md|.*_COMPLETE\.md|.*_GUIDE\.md|.*_ANALYSIS\.md|.*-analysis\.md|.*-examples\.(js|ts))$" | head -20 && echo "--- Found $(git ls-files | grep -E "(analyze-.*\.(js|ts)|debug-.*\.(js|ts)|test-.*\.(js|ts|sh)|.*-test\.(js|ts|sh)|quick-test\.(js|ts|sh)|.*-poc\..*|poc-.*\..*|.*_poc\..*|proof-of-concept-.*\..*|verify-.*\.md|research-.*\.(js|ts)|temp-.*/|test-.*/|.*_SUMMARY\.md|.*_REPORT\.md|.*_CHECKLIST\.md|.*_COMPLETE\.md|.*_GUIDE\.md|.*_ANALYSIS\.md|.*-analysis\.md|.*-examples\.(js|ts))$" | wc -l) committed cleanup candidates ---"; else echo "WORKING_DIR_CLEAN=false"; fi`

Launch ONE subagent to analyze the git status (including ignored files) and propose files for deletion. If the working directory is clean, also check for committed files that match cleanup patterns.

## Target Files for Cleanup

**Debug & Analysis Files:**
- `analyze-*.js`, `analyze-*.ts` - Analysis scripts (e.g., `analyze-race-condition.js`)
- `debug-*.js`, `debug-*.ts` - Debug scripts (e.g., `debug-detailed.js`, `debug-race-condition.js`)
- `research-*.js`, `research-*.ts` - Research scripts (e.g., `research-frontmatter-libs.js`)
- `*-analysis.md` - Analysis documents (e.g., `eslint-manual-analysis.md`)

**Test Files (temporary/experimental):**
- `test-*.js`, `test-*.ts`, `test-*.sh` - Test scripts (e.g., `test-race-condition.js`, `test-basic-add.js`, `test-poc.sh`)
- `*-test.js`, `*-test.ts`, `*-test.sh` - Test scripts with suffix
- `quick-test.js`, `quick-test.ts`, `quick-test.sh` - Quick test files
- `verify-*.md` - Verification documents (e.g., `verify-migration.md`)
- `*-examples.js`, `*-examples.ts` - Example files (e.g., `frontmatter-replacement-examples.ts`)

**Proof of Concept (POC) Files:**
- `*-poc.*` - POC files in any language (e.g., `test-poc.sh`, `auth-poc.js`)
- `poc-*.*` - POC files with prefix (e.g., `poc-validation.ts`)
- `*_poc.*` - POC files with underscore (e.g., `feature_poc.js`)
- `proof-of-concept-*.*` - Verbose POC naming

**Temporary Directories:**
- `temp-*` - Temporary directories (e.g., `temp-debug/`, `temp-test/`, `temp-test-fix/`)
- `test-*` - Temporary test directories (e.g., `test-integration/`, `test-2-concurrent/`)
- NOTE: These are different from standard `test/` or `tests/` directories which should be preserved

**Reports & Summaries:**
- `*_SUMMARY.md` - Summary reports (e.g., `TEST_SUMMARY.md`, `ESLINT_FIXES_SUMMARY.md`)
- `*_REPORT.md` - Various reports (e.g., `QUALITY_VALIDATION_REPORT.md`, `RELEASE_READINESS_REPORT.md`)
- `*_CHECKLIST.md` - Checklist documents (e.g., `MIGRATION_CHECKLIST.md`)
- `*_COMPLETE.md` - Completion markers (e.g., `MIGRATION_COMPLETE.md`)
- `*_GUIDE.md` - Temporary guides (e.g., `MIGRATION_GUIDE.md`)
- `*_ANALYSIS.md` - Analysis reports (e.g., `FRONTMATTER_ANALYSIS.md`)

## Safety Rules

**Files safe to propose for deletion:**
- Must be untracked (?? in git status) OR ignored (!! in git status)
- Should match or be similar to cleanup patterns above
- Must be clearly temporary/debug files

**Never propose these files:**
- Any committed files (not marked ?? or !!) unless working directory is clean
- CHANGELOG.md, README.md, AGENTS.md, CLAUDE.md (even if untracked)
- Core project directories: src/, dist/, scripts/, node_modules/, etc.
- Standard test directories: `test/`, `tests/`, `__tests__/` (without hyphens)
- Any files you're uncertain about

## Instructions

Launch ONE subagent to:

1. **Analyze the git status output** provided in the context above
2. **Check if WORKING_DIR_CLEAN=true**: If so, also analyze committed files that match cleanup patterns
3. **Identify cleanup candidates**:
   - For dirty working directory: Focus on untracked (??) and ignored (!!) files
   - For clean working directory: Also include committed files matching cleanup patterns
4. **Create a proposal list** of files and directories to delete
5. **Present the list to the user** for approval before any deletion
6. **Do NOT delete anything** - only propose what should be deleted

The agent should provide:
- Clear list of proposed deletions with reasons
- For untracked files: Confirmation they are marked (??) or (!!)
- For committed files: Clear indication they are committed and match debug/temp patterns
- Ask user for explicit approval before proceeding

**IMPORTANT**: The agent cannot delete files directly. It must present a proposal and wait for user confirmation.

## After User Approval

Once the user approves the proposed deletions:

1. **Delete the approved files** using appropriate commands:
   - For untracked/ignored files: `rm -f` or `rm -rf` for directories
   - For committed files: `git rm` to properly remove from git tracking
2. **Analyze the target cleanup patterns** and approved files to identify common types
3. **Propose .gitignore patterns** based on the cleanup patterns to prevent future accumulation:
   ```
   # Debug and analysis files
   analyze-*.js
   analyze-*.ts
   debug-*.js
   debug-*.ts
   research-*.js
   research-*.ts
   *-analysis.md
   
   # Temporary test files
   test-*.js
   test-*.ts
   *-test.js
   *-test.ts
   quick-test.js
   quick-test.ts
   verify-*.md
   *-examples.js
   *-examples.ts
   
   # Temporary directories
   temp-*/
   test-*/
   
   # Reports and summaries
   *_SUMMARY.md
   *_REPORT.md
   *_CHECKLIST.md
   *_COMPLETE.md
   *_GUIDE.md
   *_ANALYSIS.md
   ```
4. **Add suggested patterns to .gitignore** if user agrees

This prevents the same types of files from cluttering the workspace in future development sessions.

**Note**: When removing committed files, the agent should use `git rm` to ensure proper removal from git tracking, and remind the user to commit these removals.

## Example Output

Here's what a typical cleanup analysis looks like:

```
⏺ Based on my analysis, I've identified 17 files that can be cleaned up from your project. Here's what I found:

🗑️ Untracked Files to Remove (8 files)

Research/Debug files:
rm -f research-frontmatter-libs.js
rm -f eslint-manual-analysis.md
rm -f frontmatter-replacement-examples.ts
rm -f test-content-preservation.ts
rm -f test-migration.ts
rm -f verify-migration.md

Dated reports:
rm -f reports/RELEASE_READINESS_REPORT_2025-07-18.md
rm -f reports/TEST_FAILURE_ANALYSIS_2025-07-18.md

📁 Committed Files to Move or Remove (9 files)

These report files are in the root but should be in reports/:

# Move to reports/ (recommended):
git mv FRONTMATTER_ANALYSIS.md reports/
git mv MIGRATION_CHECKLIST.md reports/
git mv MIGRATION_COMPLETE.md reports/
git mv MIGRATION_GUIDE.md reports/
git mv PERFORMANCE_TEST_FIX_SUMMARY.md reports/
git mv QUALITY_VALIDATION_REPORT.md reports/
git mv RELEASE_READINESS_REPORT.md reports/
git mv TEST_FIXES_SUMMARY.md reports/
git mv VALIDATION_REPORT.md reports/

📝 Update .gitignore

Add these patterns to prevent future accumulation:

# Research and debug files
research-*.js
research-*.ts
*-manual-analysis.md
*-examples.ts
test-*.ts
!test/              # Exclude the test directory itself
verify-*.md

# Reports in root directory (should be in reports/)
/*_ANALYSIS.md
/*_CHECKLIST.md
/*_COMPLETE.md
/*_GUIDE.md
/*_SUMMARY.md
/*_REPORT.md
# Preserve important documentation
!CHANGELOG.md
!README.md
!AGENTS.md

# Dated reports
reports/*_[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9].md

Would you like me to proceed with the cleanup?
```

The command analyzes your project and categorizes cleanup items:
- **Untracked files**: Temporary debug/test files that can be deleted
- **Committed files**: Often reports that should be moved to the reports/ directory
- **.gitignore updates**: Patterns to prevent future accumulation

The agent will always ask for confirmation before making any changes.

© carlrannaberg · MIT · carlrannaberg/claudekit

Similar slash commands

All slash commands for Git and GitHub →

cleanup by other authors comes first.

cleanup SuperClaude-Org The cleanup command for Claude Code finds dead code, removes unused imports, and tidies project structure without breaking public APIs. CX Codex +1 ★ 23,950repo stars gsd-cleanup open-gsd gsd-cleanup — a skill for Claude Code and other environments that archives phase directories from completed milestones. It runs to clean up the workspace from accumulated planning data. CX Codex +1 573installs git-branch-cleanup gotalab git-branch-cleanup sorts local branches by merge status and remote tracking, then deletes the ones you pick after a confirmation. Useful once git branch gets out of hand. CX Codex +1 ★ 423repo stars worktree-retry-cleanup ZaxbyHub worktree-retry-cleanup is a Claude Code skill that cleans up a swarm worktree lane before a task is dispatched again. CX Codex +1 ★ 539repo stars windows-app-storage-inspector-cleanup official Daniel Scott-Raynsford windows-app-storage-inspector-cleanup inspects Windows app storage, shows disk usage, and safely moves approved cleanup files to the Recycle Bin. Helpful when clearing drive space. ★ 41,430repo stars cleanup-dashboards tomgranot cleanup-dashboards walks you through auditing HubSpot dashboards: spots abandoned screens, duplicates and test copies, then helps merge reports into a few that people actually open. CX Codex +1 ★ 81repo stars launchdarkly-flag-cleanup launchdarkly launchdarkly-flag-cleanup — a skill for Claude Code, Codex, and Cursor. Guides the safe removal of completed LaunchDarkly feature flags while preserving existing production behavior. CX Codex +1 4,200installs

From the same set54

The whole set →
migration migration moves CLAUDE.md, .cursorrules and the rest of your AI config files into one AGENTS.md, then links each tool's expected filename to it. CX Codex +1 ★ 763repo stars research-expert research-expert gathers web information in parallel, adapts depth across three distinct modes, and outputs full reports to files to avoid token bloat. CX Codex ★ 763repo stars create-subagent create-subagent builds a domain-focused subagent with defined tasks, tools, boundaries, and project context checks. Use it when a one-off command is too narrow. CX Codex +1 ★ 763repo stars research research fans a question out to parallel subagents, reads their saved reports from /tmp, and merges the lot into one cited file. CX Codex +1 ★ 763repo stars oracle oracle — a subagent for difficult debugging, architecture reviews, security audits, commit checks, and second opinions when a problem needs deeper analysis. CX Codex ★ 763repo stars code-review code-review fans out six review agents at once and merges what they find: architecture, code quality, security, performance, tests, docs. Useful before a large branch lands. CX Codex +1 ★ 763repo stars database-expert database-expert — a subagent for optimizing database queries, index layouts, connection pools, and migrations across PostgreSQL, MySQL, MongoDB, and SQLite. CX Codex ★ 763repo stars refactoring-expert The refactoring-expert subagent finds code smells and applies small refactoring steps without changing external behavior. Use it for duplication, long methods, and tangled conditionals. CX Codex ★ 763repo stars

Project sponsors

Companies that keep this analytics open