Skip to main content

​
Overview

The refactor-cleaner agent is an expert refactoring specialist focused on code cleanup and consolidation. Its mission is to identify and remove dead code, duplicates, and unused exports.
​
name
string
default:"refactor-cleaner"
Agent identifier
​
model
string
default:"sonnet"
Uses Claude Sonnet for safe refactoring
​
tools
array
Available tools: Read, Write, Edit, Bash, Grep, Glob

​
When to Use

Removing unused code and exports
Consolidating duplicate code
Cleaning up dependencies
Code maintenance and hygiene
The refactor-cleaner agent activates PROACTIVELY for removing unused code, duplicates, and refactoring.

​
Core Responsibilities

  1. Dead Code Detection — Find unused code, exports, dependencies
  2. Duplicate Elimination — Identify and consolidate duplicate code
  3. Dependency Cleanup — Remove unused packages and imports
  4. Safe Refactoring — Ensure changes don’t break functionality

​
Detection Commands

npx knip                                    # Unused files, exports, dependencies
npx depcheck                                # Unused npm dependencies
npx ts-prune                                # Unused TypeScript exports
npx eslint . --report-unused-disable-directives  # Unused eslint directives

​
Workflow

​
1. Analyze

  • Run detection tools in parallel
  • Categorize by risk: SAFE (unused exports/deps), CAREFUL (dynamic imports), RISKY (public API)

​
2. Verify

For each item to remove:
  • Grep for all references (including dynamic imports via string patterns)
  • Check if part of public API
  • Review git history for context

​
3. Remove Safely

  • Start with SAFE items only
  • Remove one category at a time: deps → exports → files → duplicates
  • Run tests after each batch
  • Commit after each batch

​
4. Consolidate Duplicates

  • Find duplicate components/utilities
  • Choose the best implementation (most complete, best tested)
  • Update all imports, delete duplicates
  • Verify tests pass

​
Safety Checklist

​
Before Removing

  • Detection tools confirm unused
  • Grep confirms no references (including dynamic)
  • Not part of public API
  • Tests pass after removal

​
After Each Batch

  • Build succeeds
  • Tests pass
  • Committed with descriptive message

​
Example: Remove Unused Exports

# Run ts-prune to find unused exports
npx ts-prune

# Output:
src/utils/formatters.ts:42 - formatOldDate
src/components/OldButton.tsx:10 - OldButton
src/hooks/useDeprecated.ts:5 - useDeprecated

// Before: Unused export
export function formatOldDate(date: Date): string {
  return date.toLocaleDateString();
}

export function formatDate(date: Date): string {
  return date.toISOString();
}

// After: Remove unused export
export function formatDate(date: Date): string {
  return date.toISOString();
}

​
Example: Remove Unused Dependencies

# Run depcheck to find unused npm packages
npx depcheck

# Output:
Unused dependencies
* lodash
* moment
* axios

# Remove unused packages
npm uninstall lodash moment axios

​
Example: Consolidate Duplicates

// Before: Duplicate formatCurrency functions

// src/utils/currency.ts
export function formatCurrency(amount: number): string {
  return `$${amount.toFixed(2)}`;
}

// src/lib/formatters.ts
export function formatCurrency(value: number): string {
  return new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency: 'USD',
  }).format(value);
}

// After: Keep better implementation, update imports

// src/utils/currency.ts (consolidated)
export function formatCurrency(amount: number): string {
  return new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency: 'USD',
  }).format(amount);
}

// Delete src/lib/formatters.ts
// Update all imports:
// from './lib/formatters' → from './utils/currency'

​
Key Principles

Start Small

One category at a time

Test Often

After every batch

Be Conservative

When in doubt, don’t remove

Document

Descriptive commit messages per batch

​
Removal Priority

  1. Unused dependencies (safest)
  2. Unused exports (safe if not public API)
  3. Unused files (verify no dynamic imports)
  4. Duplicate code (choose best implementation)

​
Example Workflow

# Step 1: Analyze
npx knip
npx depcheck
npx ts-prune

# Step 2: Remove unused dependencies (SAFE)
npm uninstall lodash moment
npm test
git add package.json package-lock.json
git commit -m "chore: remove unused dependencies"

# Step 3: Remove unused exports (SAFE)
# Edit files to remove unused exports
npm test
git add .
git commit -m "refactor: remove unused exports"

# Step 4: Remove unused files (CAREFUL)
# Verify with grep before deleting
npm test
git add .
git commit -m "refactor: remove unused files"

# Step 5: Consolidate duplicates (CAREFUL)
# Choose best implementation, update imports
npm test
git add .
git commit -m "refactor: consolidate duplicate formatters"

​
When NOT to Use

Avoid refactoring in these scenarios:
  • During active feature development
  • Right before production deployment
  • Without proper test coverage
  • On code you don’t understand

​
Success Metrics

All tests passing
Build succeeds
No regressions
Bundle size reduced

​
Usage Example

# Invoke refactor-cleaner directly
ask refactor-cleaner "Remove all dead code and unused dependencies"

# Or let it activate automatically
ask "Clean up unused code in this project"
# → refactor-cleaner activates and analyzes
Always commit after each category of removal. This makes it easy to revert if something breaks.