Hotspot

Hotspot is a CLI tool that analyzes Git history to diagnose technical debt and bus factor risk based on developer activity, ownership, and churn patterns.

This tool operates as a data-driven development intelligence. While traditional SCA tools focus on code structure and style, and DORA metrics track team performance, Hotspot analyzes actual development behavior - commit patterns, ownership distribution, churn trends, and maintenance activity - to diagnose technical debt and bus factor risk within your code at the file and folder level.

Features

• 🔍 See what matters - rank files and folders by activity, complexity, etc.
• ⚡ Fast results - analyze thousands of files in seconds
• 🧮 Rich insights - contributors, churn, size, age, and risk metrics
• 🎯 Actionable filters - narrow down by path or track trends over time
• 🕓 Robust time windows - support for human-readable time
• 📊 Export results - save to CSV/JSON/Parquet/Markdown to track trends and progress
• 🔄 CI/CD integration - enforce risk thresholds in pipelines

Installation

Requirements

• Go 1.25+ for building from source
• Git 2.2.0+ for repository analysis

Install from source

go install github.com/huangsam/hotspot@latest

Download pre-built binary

Visit the latest release and download the tar archive for your system (supports Windows, macOS, and Linux), then extract the binary to your $PATH.

Quick start

# Analyze files for immediate, tactical risk
hotspot files

# Analyze folders for strategic, subsystem risk
hotspot folders

# For an explicit path
hotspot files /path/to/repo/pkg

MCP server

Hotspot includes a Model Context Protocol (MCP) server. This allows AI agents (like Claude Desktop or Cursor) to analyze your repositories directly with full support for filtering and time-anchored trends!

# Start the MCP server (stdio)
hotspot mcp

The MCP tools (get_files_hotspots, compare_hotspots, etc.) support the same parameters as the CLI, including repo_path, mode, limit, start, and end.

Documentation

• USERGUIDE.md: Detailed commands, configuration options, backend setup, data exports, and common workflows.
• PLAYBOOK.md: Actionable guidance on using this data to foster a healthy engineering culture.

Performance

All measurements are done using 14 concurrent workers on a Macbook Pro with the M3 Max chip.

Test repositories

The benchmarks use repositories of varying scales to demonstrate performance characteristics:

Repository	Language	Scale	Description
csv-parser	C++	Small	Focused single-purpose CSV parsing library
fd	Rust	Medium	Actively maintained CLI file search utility
git	C	Large	Complex version control system
kubernetes	Go	Massive	Distributed container orchestration platform

Benchmark results

Comprehensive performance benchmarks using this script. This shows cold vs warm timings:

Repository	Files (Cold/Warm)	Compare Files (Cold/Warm)	Timeseries (Cold/Warm)
csv-parser	0.079s / 0.031s	0.172s / 0.069s	0.204s / 0.092s
fd	0.055s / 0.029s	0.113s / 0.068s	0.176s / 0.096s
git	0.610s / 0.050s	1.491s / 0.187s	2.269s / 0.329s
kubernetes	3.436s / 0.127s	8.083s / 1.357s	12.650s / 1.208s

The data shows that Hotspot caches Git analysis results to speed up repeated runs.