# clrd - AI-Native Code Maintenance Tool
> **"Transparent, Delicate, and Fast"**
## Project Overview
**clrd** (pronounced "Cleared") is a high-performance dead code detection tool built with Rust for the modern "Agentic" era. Unlike traditional linters that blindly delete code, clrd combines **Rust's speed** with **LLM intelligence** for safe, accurate code cleanup.
### Core Philosophy
1. **Transparent**: Clear reporting of what code is dead and why
2. **Delicate**: Confidence scoring to minimize false positives
3. **Fast**: Oxc parser + Rayon parallelism for maximum performance
### Target Users
- AI agents (Claude, Cursor, GPT-based tools)
- Developers using AI-assisted code maintenance
- Teams wanting to keep codebases clean
---
## Architecture: The Scan-Map-Judge-Act Protocol
```
┌─────────────────────────────────────────────────────────────────┐
│ clrd Architecture │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Phase 1: SCAN Phase 2: MAP Phase 3: ACT │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ FileWalker │ │ Mapper │ │ Fix │ │
│ │ (parallel) │──────▶│ (context) │──────▶│ (remove) │ │
│ │ AstAnalyzer │ │ claude.md │ │ --dry-run │ │
│ │ RefGraph │ │ agent.md │ │ --soft │ │
│ └─────────────┘ └─────────────┘ │ --force │ │
│ │ │ └─────────────┘ │
│ ▼ ▼ │ │
│ ┌─────────────┐ ┌─────────────┐ │ │
│ │ ScanOutput │ │ AI Context │◀───────────┘ │
│ │ (JSON) │──────▶│ Files │ LLM Judgment │
│ └─────────────┘ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
```
### Phase 1: Scan (Rust Speed)
- Parallel file walking with `rayon` and `ignore` crate
- AST parsing with `oxc_parser` (fastest JS/TS parser)
- Cross-file reference graph building
- Confidence-based dead code detection
### Phase 2: Map (Context Injection)
- Generates AI context files: `claude.md`, `agent.md`, `.cursorrules`
- Provides "vision" to AI agents before asking them to fix code
- Smart section replacement preserving user content
### Phase 3: Act (Delicate Execution)
- `--dry-run`: Preview mode (default)
- `--soft`: Comment out code instead of deleting
- `--force`: Hard delete (requires clean git status)
---
## Directory Structure
```
src/
├── main.rs # CLI binary entry point
├── lib.rs # Library root + NAPI exports for npm
├── cli/
│ ├── mod.rs # CLI argument parsing (clap)
│ └── commands/
│ ├── init.rs # `clrd init` - create context files
│ ├── scan.rs # `clrd scan` - detect dead code
│ ├── map.rs # `clrd map` - update context files
│ ├── fix.rs # `clrd fix` - remove dead code
│ └── schema.rs # `clrd schema` - output JSON schema
├── scanner/
│ ├── mod.rs # Scanner orchestrator
│ ├── file_walker.rs # Parallel file system traversal
│ ├── analyzer.rs # Oxc-based AST analysis
│ └── reference_graph.rs # Cross-file reference tracking
├── mapper/
│ ├── mod.rs # Context file generator
│ └── templates.rs # Template content for context files
├── tui/
│ └── mod.rs # Interactive terminal UI (ratatui)
└── types/
└── mod.rs # Core data structures + JSON schemas
```
---
## Key Modules
### Scanner (`src/scanner/`)
The core engine that detects dead code through three phases:
| `FileWalker` | Parallel file collection, respects .gitignore |
| `AstAnalyzer` | Oxc-based AST parsing, extracts exports/imports |
| `ReferenceGraph` | Builds cross-file reference map, finds dead code |
**Dead Code Types Detected:**
- `UnusedExport` - Exported symbol with no external references
- `UnusedImport` - Import never used in file
- `ZombieFile` - File never imported by others
- `UnreachableFunction` - Function never called
- `UnusedType/Class/Enum` - Type definitions never referenced
### Mapper (`src/mapper/`)
Generates and updates AI context files:
- **claude.md**: XML-formatted for Claude Code
- **agent.md**: Universal markdown format
- **.cursorrules**: Cursor editor format
### Types (`src/types/`)
Core data structures with `schemars` JSON schema support for LLM integration:
- `DeadCodeItem` - Individual finding with confidence score
- `ScanOutput` - Complete scan results
- `LlmJudgmentRequest/Response` - LLM communication format
---
## Tech Stack
| Parser | `oxc` (v0.56) | Ultra-fast JS/TS parsing |
| Parallelism | `rayon` | Data parallel processing |
| CLI | `clap` (v4.5) | Argument parsing |
| TUI | `ratatui` + `crossterm` | Interactive terminal UI |
| Serialization | `serde` + `schemars` | JSON + schema generation |
| Node.js | `napi-rs` | NPM distribution |
| Async | `tokio` | Async runtime |
---
## CLI Commands
```bash
# Initialize project with AI context files
clrd init [--force]
# Scan for dead code
clrd scan [--format pretty|json|compact|tui]
[--extensions ts,tsx,js]
[--ignore "**/*.test.ts"]
[--confidence 0.5]
[--include-tests]
[--output report.json]
# Update AI context files with scan results
clrd map [--confidence 0.5]
# Fix dead code
clrd fix [--dry-run] # Preview only (default)
[--soft] # Comment out instead of delete
[--force] # Hard delete (requires clean git)
[--confidence 0.8]
# Output JSON schema for LLM integration
clrd schema
```
---
## Build & Development
### Prerequisites
- Rust 1.75+
- Node.js 18+ (for npm distribution)
### Build Commands
```bash
# Development build
cargo build
# Release build (optimized)
cargo build --release
# Run tests
cargo test
# Build for npm (via napi-rs)
npm run build
# Debug build for npm
npm run build:debug
```
### Running Locally
```bash
# Via Cargo
cargo run -- scan --format pretty
# Via npm (after build)
node bin/clrd.js scan --format pretty
```
---
## Code Style Guidelines
### Rust Conventions
- Use `anyhow::Result` for error handling in CLI/application code
- Use `thiserror` for library error types
- Prefer `tracing` over `println!` for logging
- Use builder pattern for configurable structs (see `Scanner`)
### Module Organization
- Each module has `mod.rs` as entry point
- Public types re-exported at module level
- Internal implementation in separate files
### Performance Considerations
- Use `rayon::par_iter()` for CPU-bound parallel operations
- Minimize lock contention with `Arc<Mutex<>>` only when necessary
- Prefer owned types over references in parallel code
---
## Confidence Scoring
Dead code items have a confidence score (0.0 - 1.0):
| 0.8+ | High confidence | Safe to auto-remove |
| 0.5-0.8 | Medium confidence | Review recommended |
| <0.5 | Low confidence | LLM judgment needed |
**Factors that lower confidence:**
- Dynamic imports/requires
- Test files
- Entry point files (index, main, app)
- Public API markers
---
## LLM Integration
### JSON Schema
Use `clrd schema` to output JSON schema for LLM tool use.
### Judgment Request Format
```json
{
"items": [
{
"file_path": "src/utils/helper.ts",
"name": "unusedFunction",
"kind": "unused_export",
"confidence": 0.75,
"code_snippet": "export function unusedFunction() {...}",
"reason": "0 references found"
}
],
"project_context": {
"name": "my-project",
"framework": "react"
}
}
```
### Expected Response Format
```json
{
"confirmed": [
{ "file_path": "src/utils/helper.ts", "name": "unusedFunction", "action": "delete" }
],
"rejected": [
{ "file_path": "...", "name": "...", "reason": "Used via dynamic import" }
]
}
```
---
## Platform Support
Built for cross-platform distribution via npm:
- Windows (x64, arm64)
- macOS (x64, arm64, universal)
- Linux (x64, arm64, musl variants)
- FreeBSD (x64)
---
## Contributing
1. Fork the repository
2. Create a feature branch
3. Write tests for new functionality
4. Ensure `cargo test` passes
5. Submit a pull request
### Areas for Improvement
- [ ] Configuration file support (.clrdrc.json)
- [ ] Incremental scanning with caching
- [ ] Plugin system for custom detectors
- [ ] IDE/LSP integration
- [ ] Module resolution improvements