Dead Code Detector

Dead Code Detector

Find and remove unused code across Python, TypeScript, and Rust codebases.

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

Tools by Language

Why these tools?

• vulture: AST-based, confidence scoring (60-100%), whitelist support
• knip: Successor to ts-prune (maintenance mode), monorepo-aware, auto-fix
• cargo clippy: Built-in to Rust toolchain, zero additional deps

When to Use This Skill

Use this skill when:

• Cleaning up a codebase before release
• Refactoring to reduce maintenance burden
• Investigating bundle size / compile time issues
• Onboarding to understand what code is actually used

NOT for: Code duplication (use quality-tools:code-clone-assistant)

Quick Start Workflow

Python (vulture)

# Step 1: Install
uv pip install vulture

# Step 2: Scan with 80% confidence threshold
vulture src/ --min-confidence 80

# Step 3: Generate whitelist for false positives
vulture src/ --make-whitelist > vulture_whitelist.py

# Step 4: Re-scan with whitelist
vulture src/ vulture_whitelist.py --min-confidence 80

TypeScript (knip)

# Step 1: Install (project-local recommended)
bun add -d knip

# Step 2: Initialize config
bunx knip --init

# Step 3: Scan for dead code
bunx knip

# Step 4: Auto-fix (removes unused exports)
bunx knip --fix

Rust (cargo clippy)

# Step 1: Scan for dead code warnings
cargo clippy -- -W dead_code -W unused_imports -W unused_variables

# Step 2: For stricter enforcement
cargo clippy -- -D dead_code  # Deny (error) instead of warn

# Step 3: Auto-fix what's possible
cargo clippy --fix --allow-dirty

Confidence and False Positives

Python (vulture)

Common false positives (framework-invoked code):

• Route handlers / controller methods (invoked by web frameworks)
• Test fixtures and setup utilities (invoked by test runners)
• Public API surface exports (re-exported for consumers)
• Background job handlers (invoked by task queues / schedulers)
• Event listeners / hooks (invoked by event systems)
• Serialization callbacks (invoked during encode/decode)

TypeScript (knip)

Knip uses TypeScript's type system for accuracy. Configure in knip.json:

{
  "entry": ["src/index.ts"],
  "project": ["src/**/*.ts"],
  "ignore": ["**/*.test.ts"],
  "ignoreDependencies": ["@types/*"]
}

Rust

Suppress false positives with attributes:

#[allow(dead_code)]  // Single item
fn intentionally_unused() {}

// Or module-wide
#![allow(dead_code)]

Integration with CI

Python (pyproject.toml)

[tool.vulture]
min_confidence = 80
paths = ["src"]
exclude = ["*_test.py", "conftest.py"]

TypeScript (package.json)

{
  "scripts": {
    "dead-code": "knip",
    "dead-code:fix": "knip --fix"
  }
}

Rust (Cargo.toml)

[lints.rust]
dead_code = "warn"
unused_imports = "warn"

Reference Documentation

For detailed information, see:

• Python Workflow - vulture advanced usage
• TypeScript Workflow - knip configuration
• Rust Workflow - clippy lint categories

Troubleshooting

Multi-Perspective Validation (Critical)

IMPORTANT: Before removing any detected "dead code", spawn parallel subagents to validate findings from multiple perspectives. Dead code may actually be unimplemented features or incomplete integrations.

Classification Matrix

Validation Workflow

After running detection tools, spawn these parallel subagents:

┌─────────────────────────────────────────────────────────────────┐
│                    Dead Code Findings                           │
└─────────────────────────────────────────────────────────────────┘
                              │
          ┌───────────────────┼───────────────────┐
          ▼                   ▼                   ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Intent Agent    │ │ Integration     │ │ History Agent   │
│                 │ │ Agent           │ │                 │
│ - Check TODOs   │ │ - Trace call    │ │ - Git blame     │
│ - Search specs  │ │   chains        │ │ - Commit msgs   │
│ - Find issues   │ │ - Check exports │ │ - PR context    │
│ - Read ADRs     │ │ - Test coverage │ │ - Author intent │
└─────────────────┘ └─────────────────┘ └─────────────────┘
          │                   │                   │
          └───────────────────┼───────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│              AskUserQuestion: Confirm Classification            │
│  [ ] True dead code - safe to remove                            │
│  [ ] Unimplemented - create GitHub Issue to track               │
│  [ ] Incomplete - investigate integration gaps                  │
│  [ ] False positive - add to whitelist                          │
└─────────────────────────────────────────────────────────────────┘

Agent Prompts

Intent Agent (searches for planned usage):

Search for references to [IDENTIFIER] in:
1. TODO/FIXME/HACK comments in codebase
2. Issue tracker (open and closed issues)
3. Design documents and architecture decision records
4. README and project documentation files
Report: Was this code planned but not yet integrated?

Integration Agent (traces execution paths):

For [IDENTIFIER], analyze:
1. All module import/include/use statements
2. Runtime module loading mechanisms (lazy loading, plugins)
3. Framework-invoked patterns (metadata attributes, config bindings, annotations)
4. Test files that may exercise this code path
Report: Is there a partial or indirect call chain?

History Agent (investigates provenance):

For [IDENTIFIER], check:
1. VCS blame/annotate - who wrote it and when
2. Commit message - what was the stated intent
3. Code review / merge request context - was it part of larger feature
4. Recent commits - was calling code removed or refactored
Report: Was this intentionally orphaned or accidentally broken?

Example: Validating Findings

# Step 1: Run detection tool for your language
<tool> <source-path> --confidence-threshold 80 > findings.txt

# Step 2: For each high-confidence finding, spawn validation
# (Claude Code will use Task tool with Explore agents)

Sample finding: unused function 'calculate_metrics' (src/analytics.py:45)

Multi-agent investigation results:

• Intent Agent: "Found TODO in src/dashboard.py:12 - 'integrate calculate_metrics here'"
• Integration Agent: "Function is imported in tests/test_analytics.py but test is marked skip/pending"
• History Agent: "Added in MR #234 'Add analytics foundation' - dashboard integration deferred"

Conclusion: NOT dead code - it's an unimplemented feature. Create tracking issue.

User Confirmation Flow

After agent analysis, use AskUserQuestion with multiSelect: true:

AskUserQuestion({
  questions: [
    {
      question: "How should we handle these findings?",
      header: "Action",
      multiSelect: true,
      options: [
        {
          label: "Remove confirmed dead code",
          description: "Delete items verified as truly unused",
        },
        {
          label: "Create issues for unimplemented",
          description: "Track planned features in GitHub Issues",
        },
        {
          label: "Investigate incomplete integrations",
          description: "Spawn deeper analysis for partial implementations",
        },
        {
          label: "Update whitelist",
          description: "Add false positives to tool whitelist",
        },
      ],
    },
  ],
});

Risk Classification

Sources

• vulture GitHub
• knip documentation
• Effective TypeScript: Use knip
• Rust dead_code lint
• DCE-LLM research paper (emerging LLM-based approach)

Post-Execution Reflection

After this skill completes, check before closing:

1. Did the command succeed? — If not, fix the instruction or error table that caused the failure.
2. Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
3. Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.