tobihagemann/find-dead-code

Find Dead Code

Identify dead code in a codebase. Core rule: code only used in tests is still dead code. Only production usage counts.

In an incomplete or abandoned implementation, a declared-but-unused symbol may be intended-but-not-yet-used. When git history shows it was added as a deliberate part of an unfinished stack, recommend investigate rather than delete.

Step 1: Detect Languages, Scope & Test Boundaries

Determine the project structure:

1. Check for config files: package.json, tsconfig.json, pyproject.toml, setup.py, Package.swift, .xcodeproj, Cargo.toml, go.mod, pom.xml, build.gradle
2. Glob for source files: **/*.ts, **/*.py, **/*.swift, **/*.go, **/*.rs, **/*.java
3. Identify source roots — where production code lives (e.g., src/, lib/, Sources/)
4. Partition the codebase into analysis units by top-level source directories (e.g., src/auth/, src/api/, src/utils/, lib/models/). Each directory becomes one sub-agent's scope in Step 3.

If the user specified a scope, restrict analysis to that scope.

Test File Patterns

Establish which files are test files. Code referenced ONLY from these locations is dead.

| Language | Test file patterns | |----------|-------------------| | TS/JS | *.test.{ts,tsx,js,jsx}, *.spec.{ts,tsx,js,jsx}, __tests__/**, __mocks__/**, *.stories.{ts,tsx,js,jsx} | | Python | test_*.py, *_test.py, tests/**, test/**, conftest.py | | Swift | *Tests.swift, *Test.swift, Tests/**, *UITests.swift, XCTestCase subclasses | | Go | *_test.go, testdata/** | | Rust | tests/**, benches/**, #[cfg(test)] modules (inline test modules within source files) | | Java/Kotlin | src/test/**, *Test.java, *Tests.java, *Spec.java, *Test.kt | | General | fixtures/**, __fixtures__/**, mocks/**, testutils/**, testhelpers/**, spec/** |

Also exclude: test runner configs (jest.config.*, vitest.config.*, pytest.ini), storybook files, benchmark files.

Step 2: Quick Wins — CLI Tools (Optional)

If a CLI tool is installed, run it as a fast first pass for zero-reference dead code.

| Language | Tool | Check | Run | |----------|------|-------|-----| | TS/JS | knip | npx knip --version | npx knip --no-exit-code | | Python | vulture | vulture --version | vulture <src_dirs> --min-confidence 80 | | Swift | periphery | which periphery | periphery scan --skip-build | | Go | deadcode | which deadcode | deadcode ./... | | Rust | compiler warnings | — | cargo build 2>&1 \| grep "dead_code" |

Important limitation: CLI tools count test imports as real usage. They cannot detect code that is only used in tests. They only find symbols with literally zero references anywhere. Step 3 is required for test-only detection.

If no CLI tool is installed, skip to Step 3. Do not ask the user to install anything.

Step 3: Test-Only Analysis — Parallel Sub-agents (Core)

Before dispatching, read the project's test configuration and CI workflow to identify any test tier that resets a shared external resource between tests, such as a database, a fixed port, or a cache. Such tiers have no cross-process interlock, so sub-agents running them concurrently wipe each other's state and return failures that look like real defects. Name any such tier to every sub-agent as off-limits.

This is the primary analysis. Launch one sub-agent per top-level source directory from Step 1 with spawn_agent / wait_agent using inherited model defaults so they run concurrently. State the count explicitly when emitting the calls. Each sub-agent's prompt directs it to treat the shared working tree and its git index as read-only — any empirical check runs in an isolated git worktree created under $TMPDIR and discarded afterward. Give that worktree its own dependency install rather than reaching the shared tree's install by any route: removing a worktree deletes through symlinks, and a redirected suite writes into the shared install. When its own install is not possible, the check is left unrun and reported as such. Afterward the sub-agent verifies that git worktree list no longer shows the worktree, that git status --short is clean, and that the shared tree's dependency directory still resolves (a destroyed install leaves git status clean, since it is gitignored). Damage the sub-agent cannot repair is reported with the exact repair command in place of findings.

Sub-agent Strategy

Each sub-agent receives:

1. Its assigned directory to scan for exported symbols
2. The test file patterns from Step 1
3. The full project root path so it can grep across the entire codebase

Sub-agent Task

Each sub-agent performs these steps on its assigned directory:

a) Find exported/public symbols:

| Language | Exported symbol patterns | |----------|--------------------------| | TS/JS | export function, export const, export let, export var, export class, export interface, export type, export enum, export default, module.exports | | Python | Top-level def and class in non-_-prefixed modules, module-level constants (FOO = ...), symbols in __all__, public functions (no _ prefix) | | Swift | public func, public var, public let, public class, public struct, public enum, public protocol, open class, open func, open var | | Go | Capitalized identifiers: func FooBar, type FooBar struct, var FooBar, const FooBar (Go uses capitalization for public visibility) | | Rust | pub fn, pub struct, pub enum, pub trait, pub const, pub static, pub type, pub mod | | Java/Kotlin | public class, public static, public void, public fields, val/var properties, fun (top-level), @Bean, @Component, @Service annotated classes |

b) For each symbol, grep across the entire codebase for references, excluding:

• The definition file itself
• Generated/vendored directories (node_modules/, dist/, build/, vendor/, __pycache__/, .tox/, .build/, DerivedData/, target/)

c) Classify each reference as test or production based on the test file patterns.

CRITICAL — same-module references count as production usage. A symbol called by another production file within the same module/package is alive. Do not report symbols as "dead" when they have zero external callers but are used internally. Only report symbols with zero production references from any file. "Unnecessarily public" (could be internal/unexported) is a visibility issue, not dead code — do not include it.

d) Report structured results for each symbol:

• Symbol name, type (function/class/const/etc.), definition file and line range
• Number of production references (with file paths) — including same-module references
• Number of test references (with file paths)
• Classification: dead (zero prod refs anywhere), test-only (only test refs), alive (has prod refs)

Merging Results

After all sub-agents complete, collect and merge their results. Deduplicate any symbols that appear in multiple reports (e.g., re-exports).

Step 4: Filter, Classify & Evaluate

Apply these filters to the merged results from Steps 2 and 3:

1. Framework entry points: Skip symbols used by convention — React components in barrel files, Django views in URL configs, Go init() and main() functions, Go interface implementations, Rust main(), Rust trait implementations, #[derive(...)] generated code, CLI handlers registered in main, magic/lifecycle methods (__init__, __repr__), serialization methods (to_json, from_dict), interface/protocol implementations
2. Re-export chains: Trace barrel files (index.ts, __init__.py) before declaring a symbol dead. A symbol re-exported through a barrel may have indirect consumers.
3. Dynamic usage: Flag symbols that might be used via reflection (getattr, importlib, reflect package in Go, proc_macro in Rust), string-based lookups, or decorator/attribute registration as "likely dead" rather than "definite"
4. Cross-package references: In monorepos, verify a symbol isn't imported by a sibling package before declaring it dead
5. Design docs / specs / roadmaps: If the project has spec files, roadmaps, or TODO files (e.g., .turbo/specs/, ROADMAP.md, TODO.md), cross-reference test-only findings against them. Test-only APIs may be planned features awaiting integration — flag as investigate rather than delete

Classify each finding:

• Definite dead: zero references outside its definition file
• Test-only dead: references exist, but ALL are in test files
• Likely dead: uncertain due to dynamic usage, framework conventions, or complex re-export chains

Evaluate Findings

Run the $evaluate-findings skill on the classified results to verify each finding against the actual code and weed out false positives. Read the full definition file for each finding — not just the flagged symbol. The surrounding code may reveal that the feature is already implemented differently (e.g., a public ping() method may be test-only while a private keepalive loop in handleConnect() does the real work).

Proceed with the evaluation results in the next section.

Recommend Action

For each surviving finding, assign a recommendation:

| Signal | Recommendation | |--------|---------------| | No tests, no production usage | delete | | Has tests but no production usage, and no spec/roadmap reference | delete (method + test assertions) | | Has tests but no production usage, referenced in spec/roadmap/TODO | investigate (planned feature, not dead) | | Partially wired up, unclear intent, or needs domain context | investigate |

For findings marked investigate, run the $investigate skill to determine whether the code is a planned feature, an unwired integration, or truly dead.

Common Dead Code Patterns

Watch for these high-yield patterns that tools and simple grep often miss:

1. Test-only state accessors: Public properties/methods that expose internal state solely for test assertions (e.g., isEnabled, count, currentItems). The module's production consumers use behavior (events, callbacks, side effects) — only tests peek at the internal state. When removing these, the corresponding test assertions must also be removed or rewritten to use behavior-based verification.
2. Unused data model fields: Properties on serializable types (Codable structs, dataclasses, POJOs) that are decoded but never read by any production code. When removing a field from a serializable type, also update all data files that encode it (JSON, YAML, XML, database schemas, migration files).
3. Vestigial enum cases: Enum cases defined but never constructed or matched against in production code.
4. Orphaned convenience methods: Public wrappers that call through to another public method with slightly different parameters, where all callers use the underlying method directly.

Adjacent Findings

While scanning for dead code, note (but do not act on) these related issues for the user:

• Bugs near dead code: Dead code often neighbors buggy code — a missing call, a wiring gap, or an incomplete integration
• Unwired features: Code that is "almost alive" — defined, tested, but not connected to the rest of the system. Distinguish from truly dead code.

Step 5: Present Findings

Group results by confidence level:

Definite Dead (zero references outside definition)

| File | Symbol | Type | Line Range | Recommendation | |------|--------|------|------------|----------------|

Test-Only Dead (referenced only in tests)

| File | Symbol | Type | Test files referencing it | Recommendation | |------|--------|------|--------------------------|----------------|

Likely Dead (verify manually)

| File | Symbol | Type | Reason for uncertainty | Recommendation | |------|--------|------|------------------------|----------------|

Include:

• Total count per category
• Estimated removable lines
• Suggested removal order (leaf dependencies first)

Rules

• If no dead code is found, report that explicitly and note any scope limitations or analysis caveats.