Skip to main content
subagent CX Codex

refactor-cleaner · sangrokjung — Claude Code subagent for dead code cleanup

refactor-cleaner — a subagent that hunts down code nobody calls: unused files, exports and npm packages. Each hit gets a reference search before anything is deleted.

MIT ★ 880 updated 2026-09-03

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

What refactor-cleaner does

It runs three detectors at once: npx knip, npx depcheck, npx ts-prune. Results land in three buckets: safe, needs a closer look, and risky, which covers public API and shared helpers.

Every candidate gets a Grep pass first, dynamic imports included, plus a look at git history. Removals go one category per commit, with tests after each batch. The agent works on a feature branch only.

Some code stays off limits whatever the tools report: auth, wallet integration, database clients, search infrastructure, trading logic, real-time handlers. Files without test coverage need your approval before they go. If a batch breaks something, roll back with git revert HEAD and sort out why before the next run.

What it helps with

  • strip unused npm packages before a release
  • find exports that no file imports
  • collapse two copies of a helper into one
  • delete dead files without breaking the build
  • undo a bad cleanup with a single revert

Example prompts for the agent

  • Run knip and depcheck over src/, then remove the safe items and run tests after each batch
  • Find exports that nothing imports and delete them
  • Merge the duplicate formatDate implementations into one

How to install refactor-cleaner

Manually: put the files in place

.claude/agents/refactor-cleaner.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about refactor-cleaner

How do I install refactor-cleaner in Claude Code?

Place the agent file at .claude/agents/refactor-cleaner.md. Its frontmatter sets the model to sonnet and grants Read, Write, Edit, Bash, Grep and Glob.

What does refactor-cleaner do?

It detects dead code, unused exports and dependencies with three tools, checks each finding with Grep, then removes it in a separate commit and runs the tests.

Can it run on the main branch?

No, it is built for a feature branch. Code with no test coverage also needs your confirmation before removal.

Source text

refactor-cleaner.md · MIT
---
name: refactor-cleaner
description: |
  데드 코드·미사용 exports·의존성 제거, 중복 통합 전문. knip/depcheck/ts-prune 감지 → Grep 참조 검증 → 안전 제거. 피처 브랜치에서만 동작. Use proactively when "데드 코드", "미사용 코드", "정리해줘", "클린업", "리팩토링" 요청 시. 빌드 에러 수정은 build-error-resolver, 새 기능은 tdd-guide 사용.
tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
model: sonnet
memory: project
maxTurns: 20
isolation: worktree
color: yellow
---

<Agent_Prompt>
  <Role>
    You are Refactor Cleaner. Identify and remove dead code, duplicates, and unused exports through safe, systematic cleanup.
    When in doubt, don't remove. Safety first.
  </Role>

  <Success_Criteria>
    - All removals verified by detection tools (knip, depcheck, ts-prune)
    - All references checked via Grep before deletion
    - Build and tests pass after each removal batch
    - No regressions introduced
  </Success_Criteria>

  <Constraints>
    - Never remove without running detection tools first
    - Never remove RISKY items (public API, shared utilities) without explicit approval
    - Always Grep for all references (including dynamic imports) before deletion
    - Always run tests after each removal batch
    - Always work on a feature branch
    - One category per commit (unused deps / exports / files / duplicates)
    - NEVER REMOVE: Auth code, wallet integration, DB clients, search infra, trading logic, real-time handlers
  </Constraints>

  <Investigation_Protocol>
    1) Run detection tools in parallel: `npx knip`, `npx depcheck`, `npx ts-prune`
    2) Categorize: SAFE (unused exports/deps) | CAREFUL (dynamic imports possible) | RISKY (public API)
    3) Per item: Grep all references, check dynamic imports, review git history
    4) Remove SAFE items one category at a time, run tests after each batch
    5) For duplicates: choose best implementation, update imports, delete rest
  </Investigation_Protocol>
</Agent_Prompt>

## 실행 방법

```bash
npx knip                    # unused files, exports, dependencies, types
npx depcheck                # unused npm dependencies
npx ts-prune                # unused TypeScript exports
```

## 삭제 판단 기준

| Category | Action |
|----------|--------|
| SAFE (unused exports/deps) | Grep 확인 후 제거 |
| CAREFUL (동적 import 가능) | 추가 검증 필요 |
| RISKY (public API, shared) | 명시적 승인 필요 |

## 안전장치

- feature branch에서만 작업
- 문제 발생 시: `git revert HEAD` → 원인 조사 → NEVER REMOVE 리스트 업데이트
- 테스트 커버리지 없는 코드는 제거 전 사용자 확인

## Related Skills
- refactor-clean, component-refactoring, coding-standards

© sangrokjung · MIT · sangrokjung/claude-forge

Similar subagents

All subagents for Code review and refactoring →

refactor-cleaner by other authors comes first.

refactor-cleaner Affaan Mustafa refactor-cleaner is a Claude Code subagent that finds and removes unused code, duplicates, and dependencies. It runs knip, depcheck, and ts-prune during codebase cleanup. CX Codex ★ 6,739repo stars unused-code-cleaner davila7 unused-code-cleaner — 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. CX Codex 1,990installs fix-knip-unused-exports Factory-AI fix-knip-unused-exports resolves knip “Unused exports” violations by removing or relocating exports that have no production consumers. Use when npm run knip reports unused code. CX Codex +1 147installs ai-slop-cleaner Yeachan-Heo ai-slop-cleaner — a skill for Claude Code and Codex that removes dead code, duplicate branches, and redundant wrappers left by AI. Existing behavior is locked with regression tests before any file edits begin. CX Codex +1 1,700installs code-auditing jeffrigby code-auditing is a Claude Code skill that audits codebases step by step, finding security flaws, dead code, and technical debt, and checking library usage against official documentation. CX Codex +1 1installs dead-code-finder rohitg00 dead-code-finder scans the whole codebase for unused code and helps you delete it. Handy when a project accumulates functions and variables nobody calls anymore. ★ 2,858repo stars simplify SeifBenayed simplify — a skill for Claude Code, Codex and Cursor that reads code and cuts complexity that isn't earning its keep. Point it at recent changes or at one file that grew tangled. CX Codex +1 ★ 116repo stars

From the same set44

The whole set →
instinct-status Review learned instincts with their confidence levels, domains, and sources. Use the command to inspect what the agent has picked up from its observations. CX Codex +1 ★ 880repo stars doc-updater doc-updater rebuilds README, guides and codemaps from the actual source after code changes. Useful once the docs have drifted away from the code. CX Codex ★ 880repo stars instinct-export instinct-export exports continuous-learning instincts into a shareable file for team members or migration across machines. CX Codex +1 ★ 880repo stars eval This command defines eval criteria, runs checks, and builds reports. Use it to track a feature’s capabilities and catch regressions against a baseline. CX Codex +1 ★ 880repo stars task-grade-routing task-grade-routing sets documentation and review lane obligations for task sizes S, M, L, and XL based on workflow classification. CX Codex +1 ★ 880repo stars frontend-code-review The frontend-code-review skill checks frontend files against a checklist and formats findings in a fixed review structure. Use it for pending changes or specific files you name. CX Codex +1 ★ 880repo stars instinct-import instinct-import pulls instincts from a file or URL, checks them against the ones you already have, and files the keepers with a note of where they came from. CX Codex +1 ★ 880repo stars database-reviewer database-reviewer — a Claude Code subagent for reviewing SQL migrations, schema types, and RLS policies in PostgreSQL and Supabase projects. It spots N+1 queries and runs EXPLAIN ANALYZE. CX Codex ★ 880repo stars

Project sponsors

Companies that keep this analytics open