Hotspot

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

Visual Risk Intelligence: Hotspot transforms Git metadata into interactive heatmaps that instantly reveal your codebase's risk distribution. Files are color-coded by risk level (green=low, red=high) and sized by complexity, making technical debt visible at a glance.

Unlike traditional linters or team-velocity metrics, Hotspot analyzes development behavior. It turns Git metadata into high-fidelity signals for technical debt, knowledge silos, and refactoring ROI—empowering both humans and AI agents to make data-driven architecture decisions.

Features

• 🗺️ Visual Risk Radar - SVG heatmaps that make technical debt instantly visible.
• 🤖 Agentic Intelligence - MCP server with shape-aware "Reasoning" for analysis.
• 🚢 Fleet-Scale Discovery - Recursive analysis and risk mapping across projects.
• 💼 Professional Analytics - High-fidelity metrics with standard data exports.

Installation

Requirements

• Go 1.26+ for building from source
• Git 2.2+ 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: Choose your path

Hotspot is designed for both human-driven tactical analysis and AI-driven strategic auditing.

🤖 Path A: AI Agent

Hotspot includes a Self-Documenting Agentic Hub via the Model Context Protocol (MCP). This allows AI agents to autonomously explore your repository.

# Start the MCP server (stdio)
hotspot mcp

🔍 Path B: Tactical CLI

For immediate terminal-based checks and CI/CD integration.

# Initialize hotspot with sensible defaults
hotspot init

# Generate heatmap
hotspot files --mode hot --output heatmap --output-file heatmap.svg

# Analyze files in tabular format
hotspot files

# Analyze folders in tabular format
hotspot folders

# Discover and assess multiple repositories (Fleet Analysis)
hotspot batch --auto /path/to/projects

Documentation

• USERGUIDE.md: Essential guide for analysis features, scoring modes, and core workflows.
• PLAYBOOK.md: Actionable guidance on using this data to foster a healthy engineering culture.

Performance

Hotspot is optimized for speed, even on massive repositories, by caching Git analysis results and using concurrent workers.

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.