Efficient Cleanup Handler

Perform comprehensive codebase cleanup by removing dead code, unused imports, orphaned files, and deprecated API usage across the entire project.

When to Use This Command

Run this command when...

• You have accumulated unused imports and dead code over multiple refactoring cycles
• You want to find and remove orphaned files that are no longer referenced anywhere
• You are preparing for a major release and want to minimize code surface area

Avoid this command when...

• You are mid-refactor and some "unused" code will be wired up shortly
• You need to preserve backward compatibility with deprecated APIs for external consumers

Quick Start

Copy
# .claude/commands/efficient-cleanup-handler.md
---
allowed-tools: ["Bash", "Read", "Grep", "Glob", "Edit"]
---
Scan the codebase for unused imports, dead code, orphaned files,
and deprecated API calls. Report findings and optionally auto-fix.

Example usage:

/efficient-cleanup-handler --fix

Example output:

Scanning codebase...
  Unused imports:    34 across 18 files
  Dead functions:     7 (never called anywhere)
  Orphaned files:     3 (no imports referencing them)
  Deprecated APIs:    2 usages of legacy endpoints

Applied fixes:
  Removed 34 unused imports
  Flagged 7 dead functions (manual review needed)
  Listed 3 orphaned files for deletion

Cleanup complete. Review changes with: git diff

Core Concepts

Concept	Description
Import analysis	Detects imports that are declared but never referenced in the file
Dead code detection	Finds exported functions that have zero callers anywhere
Orphan detection	Identifies files with no inbound imports from the rest of the codebase
Deprecation scan	Flags usage of APIs or patterns marked as deprecated

Codebase --> Build Import Graph --> Find Dead Ends
                                         |
                              +----------+----------+
                              |          |          |
                         Unused     Dead Code   Orphaned
                         Imports   Functions    Files
                              |          |          |
                              +--- Cleanup Report --+

Configuration

Option	Default	Description
fix	false	Automatically apply safe fixes (unused imports only)
scope	src/	Directories to analyze
ignore	tests,mocks	Directories to exclude from the analysis
report	text	Output format (text, json, csv)
depth	full	Analysis depth (imports-only, full)

Best Practices

1. Run after major refactors -- refactoring often leaves behind unused code that simple linters miss.
2. Only auto-fix imports -- dead functions and orphaned files need manual review before deletion.
3. Exclude test utilities -- test helpers are often not imported directly and would appear as false positives.
4. Commit before running -- make cleanup changes a separate commit so they can be reviewed independently.
5. Pair with tree-shaking -- for frontend projects, cleanup plus tree-shaking eliminates dead code from production bundles.

Common Issues

1. False positive on dynamic imports -- require(variable) and import() are not statically analyzable. Exclude files with dynamic loading patterns.
2. Test helpers flagged as dead -- test utilities imported only from test files may fall outside the scan scope. Include test directories.
3. Circular dependency missed -- files that only import each other appear used but may be collectively unreachable. Check for isolated subgraphs.