find_dead_code

The 21-Call Problem

Finding dead code with native tools means: list all exports, then grep for each export name across the entire codebase to see if anything imports it. For a module with 20 exports, that is 21 calls — one to list the exports, then one grep per export. Each grep scans every file in the project. Each returns output that must be parsed to distinguish real imports from comments, strings, and partial matches.

Even after 21 calls, the results are unreliable. A grep for validateUser will match validateUserInput, revalidateUser, and occurrences in documentation or test descriptions. Manually filtering these false positives from potentially hundreds of matches per export is prohibitive.

find_dead_code uses the import graph already built into the index. It knows which files import which symbols because it parsed the actual import statements, not text patterns. One call returns a list of exported symbols with zero external references.

Framework-Aware Whitelisting

Not every unreferenced export is dead. Framework conventions create exports that are used by the runtime, not by your code:

• React: hooks like useEffect callbacks, component lifecycle methods
• NestJS: lifecycle hooks (onModuleInit, onModuleDestroy), decorators, guards, providers
• Next.js: page handlers (getServerSideProps, generateMetadata, route handlers in app/api/)
• Express: middleware functions, error handlers

find_dead_code maintains whitelists for these frameworks. Exports matching known framework patterns are excluded from the dead code list. This is why the false positive rate stays under 10% — the primary source of false positives (framework-consumed exports) is handled automatically.

Benchmark

Tested across three production codebases:

Approach	Tokens	Calls	Accuracy
grep per export	29,600	21	Low (many false positives from partial matches)
find_dead_code	5,400	1	High (import graph + framework whitelist)

The 82% token reduction comes from eliminating 20 redundant grep calls and replacing noisy text matches with structured import analysis.

What the Output Contains

Each dead code candidate includes:

• Symbol name and kind — function, class, type, constant
• File location — file path and line number
• Export type — named export, default export, re-export
• Confidence — whether the symbol matches any framework whitelist (if not, confidence is high that it is truly dead)

When to Use It

find_dead_code is a cleanup tool. Use it when:

• You are reducing bundle size and want to identify safe deletion candidates. Dead exports are zero-risk removals.
• A refactoring replaced one API with another and you want to verify the old exports are no longer referenced.
• Onboarding to a codebase and wanting to understand which parts are actively used versus vestigial.
• Before a major release, to prune accumulated dead code.

Use file_pattern to scope the analysis. Running find_dead_code on the entire codebase reads every file’s import graph, which can be slow on very large projects. Scoping to src/services/*.ts or a specific module keeps it fast and focused.

Do not run it routinely on every task. It is a periodic maintenance tool, not a development workflow step.