hotspot

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.

Motivation

For years, I've managed projects where everyone knew which files were the maintenance nightmares—the ones where a small change led to a two-day debugging session. As engineers, we invest heavily in Code Correctness - we run linters, use SCA tools, and write comprehensive unit tests.

However, these traditional QA methods often fail against System Resilience. Outages rarely stem from syntax errors; they're caused by code that's too complex, too fragile, or owned by too few people.

Hotspot was born to fix that: providing a transparent, auditable tool for teams to diagnose the technical debt and knowledge risk that truly drive production instability.

Key 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, exclude noise, or track trends over time
• 📊 Export results - save to CSV/JSON/Parquet to track trends and progress
• 🔄 CI/CD integration - enforce risk thresholds in pipelines

Target audience

• 🧑‍💻 Developers tracking sprint or release activity
• 🧹 Tech leads prioritizing refactors and risk across projects
• 🧾 Managers monitoring bus factor and maintenance debt

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

For detailed usage, configuration options, and common workflows, see USERGUIDE.md.

Live demo

Here's a demo of Hotspot in action:

Real world output

Here is what the tool shows for kubernetes/kubernetes:

This ranking displays the complexity score and a colored label based on:

hotspot files --mode complexity --start 2024-01-01T00:00:00Z --end 2025-01-01T00:00:00Z --workers 16 --follow --exclude 'vendor/,.pb.go'

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:

Benchmark results

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

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