This is not a linter. This is a forensic investigation tool.
Detective analyzes codebases as crime scenes, generating reasoned forensic findings based on evidence. It frames code quality through investigative narratives, not metric dashboards.
A cross-platform CLI tool that generates professional, evidence-based investigation reports for technical audits, due diligence, and post-mortems.
Unlike traditional linters or code analyzers, Detective:
- Generates forensic narratives - Interprets evidence through investigator insights, not rules
- Timeline-aware analysis - Detects development activity patterns even without git history
- Context-sensitive evaluation - Adjusts severity based on project maturity (student vs enterprise)
- Audit-grade reports - Includes integrity hashes and professional formatting
- Reasoned inference - Transforms raw data into meaningful findings
- File System Analysis - Smart categorization of files (source, assets, dependencies, artifacts, config, docs, tests); identifies large files contextually
- Code Marker Detection - Identifies TODO, FIXME, HACK, BUG, NOTE markers with severity assessment and actionable resolution steps
- Git History Analysis - Commit frequency patterns, top contributors, commit message quality scoring, uncommitted changes, branch count, activity trends
- Timeline Analysis - Activity bursts, dormancy patterns, development velocity, file modification windows
- Project Type Detection - Auto-detects frameworks (Laravel, Node.js, Django, Docker) with framework-specific recommendations
- Security Analysis - Hardcoded secret detection (API keys, passwords, tokens), SQL injection patterns, XSS vulnerabilities, insecure crypto flags, weak protocols
- Health Scoring (Weighted) - Transparent 100-point system with breakdown: Version Control (20), Code Quality (25), Security (20), Performance (15), Documentation (10), Testing (10)
- Actionable Recommendations - Every finding includes specific next steps to remediate (e.g., "Add missing .gitignore", "Use parameterized queries")
- Context Modes - Evaluates projects differently based on maturity (student, enterprise, default)
- Multiple Export Formats - Text, JSON, and Markdown with optional styling and colors
- Report Integrity - SHA256 hash verification for audit trails and tamper detection
- Interactive Mode - Rescan findings (R), set watch interval (W), quit (Q) from menu after report
- Performance-Optimized - Fast mode (-fast) and custom exclusions (-exclude) to skip heavy directories
- Watch Mode - Periodic rescanning with -watch flag or toggle from interactive menu
- Go 1.21 or higher (download here)
Windows:
- Clone or download this repository
- Open the folder in File Explorer
- Double-click
install.bat - Follow the prompts
- Open a new terminal and run
detective -verbose
macOS/Linux:
go install github.com/geoffkats/detective-cli/cmd/detective@latestThen add ~/go/bin to your PATH if not already there.
cd detective-case
go mod download
go install ./cmd/detectiveThen add $USERPROFILE\go\bin (Windows) or ~/go/bin (macOS/Linux) to your system PATH.
detective [flags]Note: After installation, open a new terminal window before using detective.
Investigation Scope & Output
-path string- Directory to investigate (default: current working directory)-format string- Report format:text,json,markdown(default: text)-export string- Export report to file (e.g., report.json, report.md)-context string- Evaluation context:default,student,enterprise(default: default)
Filtering & Severity
-severity string- Filter findings by minimum severity:low,medium,high,critical-markers- Include detailed code markers section in report
Performance & Optimization
-fast- Fast mode: skip vendor/, node_modules/, .git/, bin/, and hidden files/dirs-exclude string- Comma-separated list of directories to exclude (e.g.,-exclude vendor,node_modules,dist)
CLI Experience
-verbose- Show analysis progress and detailed output-no-color- Disable colored text output-watch int- Watch mode: auto-rescan every N seconds (interactive or toggle from menu)-no-interactive- Skip interactive menu; print report and exit
Basic Investigation
detective # Quick scan current directory
detective -path /path/to/project # Scan specific directory
detective -verbose # Show progress during scanPerformance Optimization
detective -fast # Skip vendor, node_modules, .git, hidden dirs
detective -exclude vendor,dist # Custom directory exclusions
detective -fast -exclude build # Combined: fast mode + extra exclusionsContext-Aware Analysis
detective -context student -verbose # Lenient scoring for learning projects
detective -context enterprise -severity high # Strict audit for production systemsExport & Reporting
detective -format json -export report.json # JSON export
detective -format markdown -markers -export report.md # Markdown with markers
detective -format text -severity high -export critical.txt # High-severity findings onlySecurity & Compliance
detective -severity high # Show only high and critical issues
detective -fast -context enterprise # Production-grade fast auditWatch & Interactive
detective -watch 5 # Auto-rescan every 5 seconds (watch mode)
detective -verbose # Enter interactive menu: [R]escan, [W]atch, [Q]uit
detective -no-interactive # Batch mode: print and exit (for CI/CD)Real-World Scenarios
# Laravel project audit
detective -fast -context enterprise -format json -export laravel-audit.json
# Node.js portfolio review
detective -exclude node_modules -markers -format markdown -export review.md
# CI/CD continuous monitoring
detective -fast -no-interactive -severity high
# Development watch mode (rescan every 30 seconds)
detective -watch 30 -verbose- Banner - ASCII art header with tool branding
- Header - Investigation metadata, target path, timestamp
- Evidence Summary - File counts, git stats, code markers, security findings
- Findings - Severity-ranked (CRITICAL → LOW) with:
- Evidence (concrete data)
- Recommendations (actionable next steps)
- Category (Code Quality, Security, Version Control, etc.)
- Code Markers Detail - TODO, FIXME, HACK, BUG locations (optional with -markers)
- Health Assessment - Score (0-100) with weighted breakdown:
- Version Control (20 pts)
- Code Quality (25 pts)
- Security (20 pts)
- Performance (15 pts)
- Documentation (10 pts)
- Testing (10 pts)
- Investigator Notes - Forensic insights gleaned from patterns
- Report Integrity - SHA256 hash, context, and verification note
Structured data suitable for integration with CI/CD, dashboards, and automated reporting:
{
"targetPath": "...",
"investigatedAt": "...",
"findings": [ { "severity", "title", "description", "recommendations" } ],
"healthScore": 65,
"healthBreakdown": { "versionControl": 20, "codeQuality": 18, ... },
"reportHash": "sha256:..."
}- CRITICAL - Immediate action required (hardcoded secrets, SQL injection, blocked deployments)
- HIGH - Significant quality/security impact (no version control, known bugs, large code files)
- MEDIUM - Notable concerns (stale repos, high technical debt, missing tests, XSS patterns)
- LOW - Minor improvements (missing docs, high commit frequency, limited history)
Severity Coloring in Terminal Output
- CRITICAL: RED
- HIGH: RED
- MEDIUM: YELLOW
- LOW: GREEN
Detective operates as a forensic investigation platform:
- Forensic Not Prescriptive - Doesn't tell you what to do, shows what it found
- Evidence-Based - All findings tied to concrete evidence, not arbitrary rules
- Context-Aware - Adjusts analysis based on project maturity and evaluation context
- Narrative-Driven - Generates reasoned inferences, not rule violations
- Professional - Suitable for audits, client reports, and legal proceedings
Detective is a non-interactive, stateless tool that:
- Runs independently on each execution
- Produces deterministic, evidence-based output
- Maintains a professional, neutral investigative tone
- Focuses on objective analysis, not subjective opinions
Standard evaluation with balanced severity assessment.
More lenient severity for learning projects:
- Reduces HIGH → MEDIUM for version control and contributor issues
- Focuses on learning opportunities rather than hard requirements
Stricter evaluation for production systems:
- Elevates MEDIUM → HIGH for version control and repository staleness
- Prioritizes stability, collaboration, and maintenance practices
- Due Diligence - Evaluate acquired/inherited codebases before onboarding
- Post-Mortems - Forensic analysis after system failures or incidents
- Code Review Prep - Comprehensive health assessment before manual review
- Security Audits - Identify hardcoded secrets, injection vulnerabilities, weak practices
- Portfolio Review - Evaluate your own projects objectively for strengths/gaps
- Compliance & Audit Trails - Generate timestamped, hash-verified reports for legal/regulatory requirements
- Enterprise Assessments - Context-aware evaluation for different maturity levels
- CI/CD Integration - Automated continuous assessment in build pipelines
- Onboarding - Quick project health snapshot for new team members
Detective/
├── cmd/detective/ # CLI entry point and main logic
├── internal/
│ ├── scanner/ # File system, timeline, marker detection, categorization
│ ├── git/ # Git repository analysis
│ ├── detector/ # Project type detection
│ ├── security/ # Secret and vuln pattern scanning
│ ├── inference/ # Evidence → findings, scoring, recommendations
│ └── reporter/ # Report generation and formatting
└── pkg/models/ # Shared data structures
Detective uses Go's filepath package for cross-platform path handling and works on Windows, macOS, and Linux.
| Feature | Detective | Linter | Code Scanner | Git Analyzer |
|---|---|---|---|---|
| Forensic Narrative | ✓ | ✗ | ✗ | ✗ |
| Activity Timeline | ✓ | ✗ | ✗ | ~ |
| Context-Aware | ✓ | ✗ | ✗ | ✗ |
| Investigator Insights | ✓ | ✗ | ✗ | ✗ |
| Report Integrity Hash | ✓ | ✗ | ✗ | ✗ |
| Multiple Export Formats | ✓ | ~ | ~ | ~ |
MIT
Contributions welcome! Focus areas:
- Additional timeline analysis heuristics
- New forensic insight patterns
- Additional export formats
- Extended context modes