unused-code-cleaner — Claude Code subagent: dead code removal
A subagent that finds unused imports, functions and classes and removes them one at a time, validating after each step. Handy after a refactor or before a production deploy.
npx claude-code-templates@latest --agent development-tools/unused-code-cleanerWhat unused-code-cleaner does
The subagent runs in stages: it detects project languages and structure, maps entry points, builds a dependency graph, then removes unused elements incrementally with syntax and test validation. If validation fails, the change is rolled back. It has Read, Write, Edit, Bash, Grep and Glob at its disposal.
Before touching anything it copies the directory to a backup folder. Analysis leans on npx depcheck and npx ts-unused-exports for JS/TypeScript, py_compile and pytest for Python, javac and mvn test for Java. Dynamic access patterns stay untouched: getattr(), eval(), window[], Java reflection. So do framework pieces — Django models, Flask routes, React components, Spring beans — along with entry points like main.py or index.js, config files and tests.
Safety wins over aggressive cleanup here. When the purpose of a piece of code is unclear, the subagent keeps it and flags it for manual review. That means one pass won't leave you with a spotless codebase. What you get instead is no lost code that a template string or config file still calls.
What it helps with
- strip imports left behind after a module move
- find functions and classes nothing references anymore
- clean the project before a production deploy
- check whether tests still pass after a removal
- roll back a change when syntax or tests fail
Example prompts for the agent
- scan the project for unused code and show me the report
- remove dead imports in src and run tests after each step
- back up the repo, then clean unused functions and flag anything uncertain for review
How to install unused-code-cleaner
1claude-code-templates
npx claude-code-templates@latest --agent development-tools/unused-code-cleaner2Manually: put the files in place
.claude/agents/unused-code-cleaner.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/unused-code-cleaner.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/unused-code-cleaner.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about unused-code-cleaner
How do I install unused-code-cleaner in Claude?
Use the templates CLI: npx claude-code-templates@latest --agent development-tools/unused-code-cleaner. The subagent file lands at .claude/agents/unused-code-cleaner.md.
What does unused-code-cleaner do?
It detects unused imports, functions and classes across a project and removes them step by step, validating syntax and tests after each removal. Failed validation triggers a rollback.
What code will it refuse to remove?
Anything reached dynamically: getattr(), eval(), globals() in Python, window[] and dynamic import() in JavaScript, reflection and annotations in Java. Entry points, config files, tests and framework patterns are preserved too.
