Skip to content

Commit a3686a7

Browse files
DannylSyph3rDannylSyph3r
committed
Add Agent TOML & YAML files + README
1 parent 8fbedb2 commit a3686a7

File tree

3 files changed

+531
-0
lines changed

3 files changed

+531
-0
lines changed

‎agents/undertaker/README.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
# The Undertaker - Dead Code Detection Agent
2+
3+
Find unused functions, classes, variables, imports, and unreachable code with confidence scoring across your repository.
4+
5+
## Overview
6+
7+
The Undertaker is a reliable dead code detection agent that identifies unused code elements using static analysis. It provides deterministic confidence-based scoring to help you safely remove dead code while minimizing false positives.
8+
9+
## Features
10+
11+
- **Comprehensive Detection**: Identifies unused functions, classes, methods, variables, imports, types, enums, and unreachable code
12+
- **Multi-Language Support**: Analyzes multiple programming languages
13+
- **Confidence Scoring**: Deterministic scoring (50-100%) based on reference counts and export status
14+
- **Safe Analysis**: Read-only static analysis that never modifies your code
15+
- **Unreachable Code Detection**: Finds code after return/throw/break statements
16+
- **Export-Aware**: Distinguishes between private and exported/public code
17+
- **Detailed Reporting**: JSON output with actionable findings and reasoning
18+
19+
## Quick Start
20+
21+
### Basic Usage
22+
23+
```bash
24+
# Run default analysis with 70% confidence threshold
25+
qodo undertaker
26+
27+
# Use custom confidence threshold
28+
qodo undertaker --min_confidence=80
29+
30+
# Include test files in analysis
31+
qodo undertaker --include_tests=true
32+
33+
# Use both options together
34+
qodo undertaker --min_confidence=85 --include_tests=true
35+
```
36+
37+
## Configuration
38+
39+
The agent accepts the following parameters:
40+
41+
| Parameter | Type | Default | Description |
42+
|-----------|------|---------|-------------|
43+
| `min_confidence` | number | 70 | Minimum confidence threshold (50-100). Only results meeting or exceeding this threshold are included. |
44+
| `include_tests` | boolean | false | Whether to include test files in the dead code analysis. |
45+
46+
## How It Works
47+
48+
### Analysis Process
49+
50+
1. **Project Discovery**: Scans source files while excluding generated and vendor directories
51+
2. **Definition Detection**: Identifies function/class/variable/import definitions using language-specific patterns
52+
3. **Reference Counting**: Counts actual usage of each identifier across the codebase (excluding its definition)
53+
4. **Export Analysis**: Determines whether code is exported/public, which affects confidence scoring
54+
5. **Unreachable Code Detection**: Finds code after terminating statements (return/throw/break)
55+
6. **Confidence Scoring**: Applies deterministic rules to generate confidence scores
56+
57+
### Confidence Scoring
58+
59+
The agent uses the following rules to calculate confidence scores:
60+
61+
| Condition | Confidence | Tier |
62+
|-----------|-----------|------|
63+
| No references + not exported | 100% | Very High |
64+
| No references + exported | 90% | Very High |
65+
| 1 reference + not exported | 75% | High |
66+
| 1 reference + exported | 70% | High |
67+
| 2+ references | 60% or lower | Medium |
68+
| Unreachable code | 100% | Very High |
69+
70+
## Output Format
71+
72+
The agent returns a JSON object with the following structure:
73+
74+
```json
75+
{
76+
"summary": {
77+
"total_files_scanned": 42,
78+
"total_dead_code_items": 5,
79+
"confidence_counts": {
80+
"very_high": 3,
81+
"high": 1,
82+
"medium": 1
83+
},
84+
"estimated_lines_removable": 127
85+
},
86+
"dead_code_items": [
87+
{
88+
"identifier": "unusedFunction",
89+
"type": "function",
90+
"location": "src/utils.ts:42-55",
91+
"confidence_score": 100,
92+
"reference_count": 0,
93+
"is_exported": false,
94+
"reasoning": "Function is not referenced anywhere in the codebase and is not exported"
95+
}
96+
],
97+
"warnings": [],
98+
"success": true
99+
}
100+
```
101+
102+
## Interpreting Results
103+
104+
- **Very High Confidence (90-100%)**: Safe to remove. These are unused code elements with no references and typically not exported.
105+
- **High Confidence (70-89%)**: Likely safe to remove. Usually has minimal references or is exported but not used.
106+
- **Medium Confidence (50-69%)**: Exercise caution. Has some references but may still be dead code. Review before removing.
107+
108+
## Use Cases
109+
110+
### Clean Up Your Codebase
111+
Remove unused code that accumulates over time as features are refactored or deprecated.
112+
113+
### Pre-Refactoring Analysis
114+
Identify what can be safely removed before major refactoring efforts.
115+
116+
### Code Review
117+
Use in your CI/CD pipeline to flag potential dead code during code reviews.
118+
119+
### Dependency Reduction
120+
Identify unused exports that can be kept private or removed entirely.
121+
122+
## Tools Used
123+
124+
- **Git**: Version control operations
125+
- **Filesystem**: Directory and file traversal
126+
- **Ripgrep**: Efficient pattern matching and searching
127+
128+
## Error Handling
129+
130+
The agent handles errors gracefully:
131+
- If tools fail, analysis continues with warnings
132+
- Falls back to filesystem reading if pattern matching fails
133+
- Returns `success: true` with warnings rather than failing entirely
134+
- Handles cross-platform compatibility issues automatically
135+
136+
## Technical Details
137+
138+
The agent uses ripgrep for efficient cross-repository searching with language-specific patterns. It filters out comments and strings to minimize false positives and deduplicates results for accuracy.
139+
140+
## Limitations
141+
142+
- Static analysis only - cannot detect runtime dead code
143+
- May have false negatives if code is referenced dynamically
144+
- External library references may be missed if not directly imported in source files
145+
- Consider running multiple times with different `min_confidence` values for comprehensive analysis
146+
147+
## Examples
148+
149+
### Example 1: Basic Analysis
150+
151+
```bash
152+
qodo undertaker
153+
```
154+
155+
Scans the repository and returns all dead code with confidence >= 70%.
156+
157+
### Example 2: High Confidence Only
158+
159+
```bash
160+
qodo undertaker --min_confidence=90
161+
```
162+
163+
Returns only the most reliable dead code detections (90-100% confidence).
164+
165+
### Example 3: Including Tests
166+
167+
```bash
168+
qodo undertaker --include_tests=true
169+
```
170+
171+
Includes test files in the analysis, which is useful for identifying unused test helpers or fixtures.
172+
173+
## Integration
174+
175+
The JSON output can be easily integrated into:
176+
- CI/CD pipelines for automated reporting
177+
- Code review tools
178+
- Custom analysis scripts
179+
180+
## Best Practices
181+
182+
1. Start with the default `min_confidence=70` threshold
183+
2. Review "Very High" confidence items first as candidates for removal
184+
3. Use version control to safely remove dead code in isolated commits
185+
4. Run the agent periodically to maintain code quality
186+
187+
## Support
188+
189+
For issues or questions about the Undertaker agent, please refer to the project documentation or create an issue in the repository.

‎agents/undertaker/agent.toml‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# The Undertaker - Dead Code Detection Agent
2+
version = "1.0"
3+
4+
[commands.undertaker]
5+
description = "Reliable dead code detection agent that identifies unused functions, classes, variables, imports, and unreachable code with confidence scoring"
6+
7+
instructions = """
8+
You are a dead code detection agent. Find unused code elements in the repository using static analysis.
9+
10+
CORE MISSION:
11+
Identify unused functions, classes, variables, imports, types, enums, methods, and unreachable code.
12+
Provide confidence scoring based on reference counts and export status.
13+
Be reliable and dependable within reasonable limits.
14+
Output clean JSON results for integration.
15+
16+
ANALYSIS PROCESS:
17+
1. Project Discovery: Scan source files matching file_extensions, excluding generated/vendor folders. Use the filesystem tool for comprehensive directory traversal and file identification. Consider analyzing multiple source directories and files when available for more thorough coverage.
18+
2. Definition Detection: Find function/class/variable/import definitions using language-specific patterns. Use ripgrep for efficient pattern matching across multiple files. Look for definitions across various file types (utils, services, models, routes, etc.).
19+
3. Reference Counting: For each identifier, count actual usage across the codebase (excluding its definition). Use ripgrep with precise patterns to count references and exclude false positives.
20+
4. Export Analysis: Detect if code is exported/public, which affects confidence scoring.
21+
5. Unreachable Code: Find code after return/throw/break statements in the same block.
22+
6. Confidence Scoring: Apply deterministic confidence rules based on usage patterns.
23+
24+
CONFIDENCE RULES:
25+
No references + not exported = 100% confidence (very_high: 90-100).
26+
No references + exported = 90% confidence (very_high: 90-100).
27+
1 reference + not exported = 75% confidence (high: 70-89).
28+
1 reference + exported = 70% confidence (high: 70-89).
29+
2+ references = 60% or lower (medium: 50-69).
30+
Unreachable code = 100% confidence (very_high: 90-100).
31+
32+
IMPORTANT: When calculating summary counts, ensure confidence_tier matches confidence_score ranges:
33+
very_high: scores 90-100
34+
high: scores 70-89
35+
medium: scores 50-69
36+
37+
TECHNICAL REQUIREMENTS:
38+
Use ripgrep for efficient cross-repository searching.
39+
Filter out comments, strings, and false positives.
40+
Handle multiple programming languages with appropriate patterns.
41+
Deduplicate results and merge when appropriate.
42+
Only include items with confidence >= min_confidence threshold.
43+
44+
OUTPUT REQUIREMENTS:
45+
First, you MUST use the filesystem tool to write the final JSON output to a file named 'dead_code_analysis.json'.
46+
Second, you MUST return the same valid JSON matching the output_schema to standard output.
47+
Include summary statistics and detailed findings.
48+
After writing the file, stop all operations. Do not perform any additional analysis or processing.
49+
50+
ERROR HANDLING:
51+
If tools fail, add warnings but continue analysis.
52+
Fall back to filesystem reading if ripgrep patterns fail.
53+
Mark success=true with warnings rather than failing entirely.
54+
Handle cross-platform compatibility issues gracefully.
55+
56+
FOCUS ON RELIABILITY:
57+
Prioritize working correctly over handling every edge case.
58+
Use simple, proven patterns over complex regex.
59+
Provide useful results even with partial data.
60+
Be dependable for common dead code scenarios.
61+
"""
62+
63+
# Arguments for customizing the analysis
64+
arguments = [
65+
{ name = "min_confidence", type = "number", required = false, default = 70, description = "Minimum confidence threshold (50-100)" },
66+
{ name = "include_tests", type = "boolean", required = false, default = false, description = "Whether to include test files in analysis" }
67+
]
68+
69+
# Tools the agent can use
70+
tools = ["git", "filesystem", "ripgrep"]
71+
72+
# Use plan strategy for multi-step analysis
73+
execution_strategy = "plan"
74+
75+
# Simplified but comprehensive output schema
76+
output_schema = """
77+
{
78+
"type": "object",
79+
"required": ["summary", "dead_code_items", "success"],
80+
"properties": {
81+
"summary": {
82+
"type": "object",
83+
"description": "Summary statistics of the dead code analysis.",
84+
"required": ["total_files_scanned", "total_dead_code_items", "confidence_counts", "estimated_lines_removable"],
85+
"properties": {
86+
"total_files_scanned": {
87+
"type": "number",
88+
"description": "Number of source files analyzed."
89+
},
90+
"total_dead_code_items": {
91+
"type": "number",
92+
"description": "Total dead code items found."
93+
},
94+
"confidence_counts": {
95+
"type": "object",
96+
"description": "Breakdown of dead code items by confidence tier.",
97+
"properties": {
98+
"very_high": { "type": "number" },
99+
"high": { "type": "number" },
100+
"medium": { "type": "number" }
101+
}
102+
},
103+
"estimated_lines_removable": {
104+
"type": "number",
105+
"description": "Estimated lines that can be safely removed."
106+
}
107+
}
108+
},
109+
"dead_code_items": {
110+
"type": "array",
111+
"description": "List of dead code items found, sorted by confidence.",
112+
"items": {
113+
"type": "object",
114+
"required": ["identifier", "type", "location", "confidence_score", "reference_count", "is_exported", "reasoning"],
115+
"properties": {
116+
"identifier": {
117+
"type": "string",
118+
"description": "Name of the code element."
119+
},
120+
"type": {
121+
"type": "string",
122+
"enum": ["function", "class", "method", "variable", "interface", "type", "enum", "import", "unreachable_code", "file"],
123+
"description": "Type of code element."
124+
},
125+
"location": {
126+
"type": "string",
127+
"description": "File path and line range, e.g., 'src/utils.js:10-15'."
128+
},
129+
"confidence_score": {
130+
"type": "number",
131+
"minimum": 50,
132+
"maximum": 100,
133+
"description": "Confidence this is dead code (50-100)."
134+
},
135+
"reference_count": {
136+
"type": "number",
137+
"description": "Number of times referenced in the codebase (excluding definition)."
138+
},
139+
"is_exported": {
140+
"type": "boolean",
141+
"description": "Whether the code is exported/public."
142+
},
143+
"reasoning": {
144+
"type": "string",
145+
"description": "Explanation for why this is considered dead code."
146+
}
147+
}
148+
}
149+
},
150+
"warnings": {
151+
"type": "array",
152+
"items": { "type": "string" },
153+
"description": "Warnings encountered during analysis."
154+
},
155+
"success": {
156+
"type": "boolean",
157+
"description": "Whether the analysis completed successfully."
158+
}
159+
}
160+
}
161+
"""
162+
163+
# Success condition for CI/CD integration
164+
exit_expression = "success"

0 commit comments

Comments
 (0)