Expert Janitor

Your agent for cleaning codebases by eliminating technical debt — removing dead code, simplifying complexity, and reducing unnecessary abstractions with a philosophy that less code equals less debt.

When to Use This Agent

Choose Expert Janitor when:

• Removing dead code, unused imports, and unreferenced files
• Simplifying over-engineered abstractions and unnecessary indirection
• Consolidating duplicated code into clean, minimal implementations
• Cleaning up after feature removals or migrations
• Reducing codebase complexity without changing functionality

Consider alternatives when:

• You need to add new features — use a developer agent
• You need architecture redesign — use an architect agent
• You need comprehensive refactoring with new patterns — use a refactoring agent

Quick Start

Copy
# .claude/agents/janitor.yml
name: Expert Janitor
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: Codebase cleanup agent for removing dead code, simplifying abstractions, and reducing technical debt

Example invocation:

claude "Scan the src/services/ directory for unused exports, dead code paths, and functions that are defined but never called — remove everything that's safely deletable"

Core Concepts

Cleanup Priorities

Priority	Target	Impact
1	Dead code (unreachable, never called)	Remove confusion, reduce bundle
2	Unused dependencies	Reduce attack surface, speed builds
3	Duplicate code	Reduce maintenance burden
4	Over-abstraction	Improve readability
5	Unnecessary comments	Remove noise
6	Stale configuration	Prevent confusion

Safe Deletion Checklist

Before deleting anything:
  ✓ Search for all references (imports, dynamic requires, reflection)
  ✓ Check test files for direct references
  ✓ Search for string-based references (dependency injection, config)
  ✓ Check public API surface (exported from index files)
  ✓ Verify no runtime dynamic loading
  ✓ Run tests after deletion to confirm nothing breaks

Configuration

Parameter	Description	Default
scope	Cleanup scope (file, directory, project)	directory
aggressiveness	How aggressive to be (conservative, moderate, aggressive)	moderate
dry_run	Preview changes without modifying files	true
preserve_tests	Keep test files even if tested code is removed	true
confirm_deletes	Require confirmation before deleting	true

Best Practices

1. Search for all references before deleting anything. A function that appears unused might be called dynamically, via string interpolation, or through dependency injection. Search for the function name as a string, not just as a code reference. Check configuration files, test fixtures, and build scripts.

2. Delete in small, testable increments. Remove one file or one function at a time and run the test suite between each deletion. If something breaks, you know exactly which deletion caused it. Batch deletions make broken builds impossible to diagnose.

3. Remove the abstraction when only one implementation exists. An interface with one implementor, a factory that creates one type, or a strategy pattern with one strategy — these add indirection without value. Inline the implementation and remove the abstraction layer.

4. Check for runtime references, not just static analysis. Dynamic imports (require(variable)), reflection, and configuration-driven instantiation won't show up in static search results. Check for patterns like container.resolve('ServiceName') or require(\./plugins/${name}`)`.

5. Commit cleanup separately from feature changes. Cleanup commits should be pure deletions or simplifications with no behavior changes. This makes code review straightforward ("does this change behavior? no → approve") and makes reverts clean if something breaks.

Common Issues

"Unused" code is actually called via dynamic dispatch. Dependency injection containers, plugin systems, and event-driven architectures reference code by string names, not imports. Before deleting a seemingly unused class, search for its name in configuration files, DI registrations, and event handler maps.

Test suite passes after deletion but production breaks. Tests may not cover the code path that uses the deleted function. Run integration tests and smoke tests against a staging environment after cleanup, not just unit tests.

Cleanup removes code that a WIP branch depends on. When multiple developers work in parallel, cleanup that removes a function another branch uses creates merge conflicts. Communicate cleanup plans with the team and check active branch diffs before large deletions.