dead-code-detector — Claude Code skill: what it does, how to install
dead-code-detector finds unreachable code, unused imports, and dead exports across Python, TypeScript, and Rust codebases. Useful before major releases and refactoring sprints.
MIT 150 installs ★ 3 updated 2026-10-25
npx skills add terrylica/cc-skills --skill dead-code-detector -a claude-codeWhat dead-code-detector does
The skill orchestrates native analysis tools for each language ecosystem: vulture v2.14+ for Python, knip v5.0+ for TypeScript, and standard cargo clippy lints for Rust. It runs scans, applies confidence thresholds like 80% on Python AST analysis, and triggers automated fixes where the underlying tool supports it.
Detection handles framework callbacks, test fixtures, and public API surfaces through whitelist generation and ignore rules. Before applying deletions, the workflow classifies findings against a validation matrix to prevent removing incomplete features or intentional stub code.
Without vulture or knip installed in your project runtime, scanning steps in those languages will fail immediately. Code duplication analysis is also out of scope here; the documentation points to a dedicated clone assistant for that job.
What it helps with
- detect unused exports and orphaned packages in TypeScript via
knip - locate dead functions and unread variables in Python with
vulture - flag unused imports and functions in Rust using
cargo clippy - distinguish abandoned code from pending features before deletion
Example prompts for the agent
- Run a dead code check on this Python repository using vulture with 80% confidence.
- Inspect our TypeScript project with knip and list unused exports.
- Audit this Rust crate for unused imports and dead functions using cargo clippy.
How to install dead-code-detector
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill dead-code-detector -a claude-code2Manually: put the files in place
~/.claude/skills/dead-code-detector/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/dead-code-detector/
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill dead-code-detector -a codex2Manually: put the files in place
.agents/skills/dead-code-detector/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill dead-code-detector -a cursor2Manually: put the files in place
.cursor/skills/dead-code-detector/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install terrylica/cc-skills plugins/quality-tools/skills/dead-code-detector2Manually: put the files in place
.github/skills/dead-code-detector/SKILL.md1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill dead-code-detector -a gemini-cli2Platform CLI
gemini skills install https://github.com/terrylica/cc-skills --path plugins/quality-tools/skills/dead-code-detectorManually: put the files in place
.devin/skills/dead-code-detector/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill dead-code-detector -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about dead-code-detector
How to install dead-code-detector in Claude Code?
Run npx skills add terrylica/cc-skills --skill dead-code-detector -a claude-code in your terminal.
What does dead-code-detector do?
It coordinates vulture, knip, and cargo clippy to locate unreachable functions, imports, dependencies, and variables in polyglot codebases.
How does it avoid deleting code that is still under development?
It uses a validation matrix to check whether uncalled routines contain TODO comments or belong to documented public interfaces before pruning them.
Source text
SKILL.md · MIT
---
name: dead-code-detector
description: Detect unused/unreachable code in polyglot codebases (Python, TypeScript, Rust). TRIGGERS - dead code, unused functions, unused imports
allowed-tools: Read, Grep, Bash, Edit, Write
---
# 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
| Language | Tool | Detects |
| ---------- | --------------------------------------------------------- | --------------------------------------------- |
| Python | [vulture](https://github.com/jendrikseipp/vulture) v2.14+ | Unused imports, functions, classes, variables |
| TypeScript | [knip](https://knip.dev/) v5.0+ | Unused exports, dependencies, files |
| Rust | `cargo clippy` + `rustc` lints | Unused functions, imports, dead_code warnings |
**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)
```bash
# 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)
```bash
# 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)
```bash
# 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)
| Confidence | Meaning | Action |
| ---------- | ------------------------------------------- | ------------------------------- |
| 100% | Guaranteed unused in analyzed files | Safe to remove |
| 80-99% | Very likely unused | Review before removing |
| 60-79% | Possibly unused (dynamic calls, frameworks) | Add to whitelist if intentional |
**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`:
```json
{
"entry": ["src/index.ts"],
"project": ["src/**/*.ts"],
"ignore": ["**/*.test.ts"],
"ignoreDependencies": ["@types/*"]
}
```
### Rust
Suppress false positives with attributes:
```rust
#[allow(dead_code)] // Single item
fn intentionally_unused() {}
// Or module-wide
#![allow(dead_code)]
```
---
## Integration with CI
### Python (pyproject.toml)
```toml
[tool.vulture]
min_confidence = 80
paths = ["src"]
exclude = ["*_test.py", "conftest.py"]
```
### TypeScript (package.json)
```json
{
"scripts": {
"dead-code": "knip",
"dead-code:fix": "knip --fix"
}
}
```
### Rust (Cargo.toml)
```toml
[lints.rust]
dead_code = "warn"
unused_imports = "warn"
```
---
## Reference Documentation
For detailed information, see:
- [Python Workflow](./references/python-workflow.md) - vulture advanced usage
- [TypeScript Workflow](./references/typescript-workflow.md) - knip configuration
- [Rust Workflow](./references/rust-workflow.md) - clippy lint categories
---
## Troubleshooting
| Issue | Cause | Solution |
| ------------------------------ | ----------------------------- | -------------------------------------------------------------- |
| Reports framework-invoked code | Framework magic / callbacks | Add to whitelist or exclusion config |
| Misses dynamically loaded code | Not in static entry points | Configure entry points to include plugin/extension directories |
| Warns about test-only helpers | Test code compiled separately | Use conditional compilation or test-specific exclusions |
| Too many false positives | Threshold too low | Increase confidence threshold or configure ignore patterns |
| Missing type-only references | Compile-time only usage | Most modern tools handle this; check tool version |
---
## 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
| Finding Type | True Dead Code | Unimplemented Feature | Incomplete Integration |
| --------------------- | ----------------------------- | ----------------------------------- | ----------------------------- |
| Unused callable | No callers, no tests, no docs | Has TODO/FIXME, referenced in specs | Partial call chain exists |
| Unused export/public | Not imported anywhere | In public API, documented | Used in sibling module |
| Unused import/include | Typo, refactored away | Needed for side effects | Type-only or compile-time |
| Unused binding | Assigned but never read | Placeholder for future | Debug/instrumentation removed |
### 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
```bash
# 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`:
```typescript
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
| Risk Level | Criteria | Action |
| ------------ | ------------------------------------------------------- | --------------------------- |
| **Low** | 100% confidence, no references anywhere, >6 months old | Auto-remove with VCS commit |
| **Medium** | 80-99% confidence, some indirect references | Validate with agents first |
| **High** | <80% confidence, recent code, has test coverage | Manual review required |
| **Critical** | Public API surface, documented, has external dependents | NEVER auto-remove |
---
## Sources
- [vulture GitHub](https://github.com/jendrikseipp/vulture)
- [knip documentation](https://knip.dev/)
- [Effective TypeScript: Use knip](https://effectivetypescript.com/2023/07/29/knip/)
- [Rust dead_code lint](https://doc.rust-lang.org/rust-by-example/attribute/unused.html)
- [DCE-LLM research paper](https://aclanthology.org/2025.naacl-long.501.pdf) (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.
© terrylica · MIT · terrylica/cc-skills