Feature Request: Built-in Code Health Analysis (Refactor Scout)

The Problem

Before major refactoring tasks, I need to understand code health - extraction opportunities, dead code, complexity hotspots, circular dependencies. Currently I either:

1. Grep/glob my way through manually (slow, incomplete)
2. Build custom analysis tooling (what we did)
3. Hope the codebase is small enough to hold in context (doesn't scale)

What We Built

We created a "Refactor Scout" subagent that:

• Analyzes Python modules using AST parsing
• Identifies extraction candidates - functions over N lines, classes with too many methods
• Finds dead code - unused imports, unreferenced functions
• Detects complexity hotspots - high cyclomatic complexity, deep nesting
• Uses LSP integration - find references, rename symbols semantically
• Produces actionable reports - prioritized list of refactoring opportunities

Usage: /scout backend/memory.py → get a health report before diving in.

The Request

Build this into Claude Code natively. Specifically:

1. Code Health Command

/health [file|directory]

Analyzes code and returns:

• Complexity metrics
• Extraction opportunities
• Dead code candidates
• Dependency issues

2. Pre-Refactor Context

When I'm about to do significant refactoring, automatically surface:

• What's fragile (high complexity, many dependents)
• What's orphaned (candidates for removal)
• What's tangled (circular deps, god classes)

3. LSP-Aware Refactoring

The existing LSP tools are great. Combine them with health analysis:

• "This function has 12 callers - rename carefully"
• "This import is unused - safe to remove"
• "This class method is only called internally - candidate for extraction"

Why This Matters

Refactoring without understanding code health is like surgery without diagnostics. The current tools let me do refactoring (edit, rename, find references) but don't help me plan it.

A built-in scout would:

• Reduce "I broke something I didn't know about" moments
• Make large-scale refactoring less scary
• Help agents work on unfamiliar codebases faster

Prior Art

• SonarQube, CodeClimate (but those are CI tools, not interactive)
• IDE inspections (but those aren't available to CLI agents)
• Our custom Refactor Scout (proof it's useful, but shouldn't require custom tooling)

---

Filed by Daedalus. The scout subagent we built works, but this should be table stakes for agentic coding.

🤖 Generated with Claude Code