Refactor Cleaner Agent

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.

string

default:"refactor-cleaner"

Agent identifier

string

default:"sonnet"

Uses Claude Sonnet for safe refactoring

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

Dead Code Detection — Find unused code, exports, dependencies
Duplicate Elimination — Identify and consolidate duplicate code
Dependency Cleanup — Remove unused packages and imports
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

Unused dependencies (safest)
Unused exports (safe if not public API)
Unused files (verify no dynamic imports)
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.

Overview

Development Agents

Specialized Agents

Language-Specific Agents

Overview

When to Use

Core Responsibilities

Detection Commands

Workflow

1. Analyze

2. Verify

3. Remove Safely

4. Consolidate Duplicates

Safety Checklist

Before Removing

After Each Batch

Example: Remove Unused Exports

Example: Remove Unused Dependencies

Example: Consolidate Duplicates

Key Principles

Start Small

Test Often

Be Conservative

Document

Removal Priority

Example Workflow

When NOT to Use

Success Metrics

Usage Example

​Overview

​When to Use

​Core Responsibilities

​Detection Commands

​Workflow

​1. Analyze

​2. Verify

​3. Remove Safely

​4. Consolidate Duplicates

​Safety Checklist

​Before Removing

​After Each Batch

​Example: Remove Unused Exports

​Example: Remove Unused Dependencies

​Example: Consolidate Duplicates

​Key Principles

Start Small

Test Often

Be Conservative

Document

​Removal Priority

​Example Workflow

​When NOT to Use

​Success Metrics

​Usage Example

Overview

When to Use

Core Responsibilities

Detection Commands

Workflow

1. Analyze

2. Verify

3. Remove Safely

4. Consolidate Duplicates

Safety Checklist

Before Removing

After Each Batch

Example: Remove Unused Exports

Example: Remove Unused Dependencies

Example: Consolidate Duplicates

Key Principles

Removal Priority

Example Workflow

When NOT to Use

Success Metrics

Usage Example