CodeHeat

Find the files that hurt your team the most — and the people who know how to fix them.

CodeHeat crosses static analysis with git history to rank the files worth refactoring first, and match each one to the person who can fix it fastest — all without ever sending your code to an LLM.

• Ranked hotspots — complexity + nesting + churn + TODO age
• Ownership matching, not blame — who to ask, not who to blame
• AI-assisted prioritization using metadata only
• Your source code never leaves your machine

_{The full pipeline: scan → own (who to ask) → treemap dashboard → metadata-only AI → PR bot.}

Quick start · Example · Why · Compare · Features · Architecture

---

Quick start

pip install -e .        # needs lizard (multi-language complexity); TODO-age needs git

# 1. Scan: complexity + Smell Score → smell_report.json
codeheat scan . --output smell_report.json

# 2. Ownership: who knows each hotspot (reads the scan report) → ownership_report.json
codeheat own . --from-report smell_report.json --output ownership_report.json

# 3. AI-assisted priorities — metadata only, no code ever sent
codeheat insights smell_report.json --ownership-report ownership_report.json

That's it — three commands, three JSON reports, no config and no API key (the default AI backend is local Ollama). Each stage's report feeds the next.

Example output

Pointed at its own repo, CodeHeat ranks its hotspots — worst first:

Rank	Smell Score	Max CCN	File	Hotspot Function
#1	38.0	26	vscode-extension/src/reports.ts	(anonymous)
#2	29.0	17	dashboard/lib/merge.ts	(anonymous)
#3	27.5	15	codeheat/static_scan.py	build_smell_reports

codeheat own . then answers "who should I ask about static_scan.py?", and codeheat insights turns the whole thing into per-file "refactor this, ask this person, about this" — using function names and imports as context, but never the code itself. Full JSON schema in docs/algorithm.md.

Why CodeHeat

You clone a repo with 500 files. Where do you even start — and once you find the scary file, who do you ask?

Two ideas make CodeHeat different:

• Matching, not blame. It never asks "who broke this?" It asks "who can fix this fastest?" — by finding the contributor with the most domain knowledge of each hotspot (weighted toward whoever was there when the complexity spiked).
• Your code stays yours. The AI layer receives numbers and metadata only — never source code. Every stage's JSON is structured around that constraint, so it's safe for private and enterprise repos.

How it compares

	Complexity hotspots	Ownership / who-to-ask	AI prioritization	Metadata-only AI (no code sent)	Open source
SonarQube	Yes	No	Partial	Yes	Partial (Community)
CodeScene	Yes	Yes	No	Yes	No
CodeHeat	Yes	Yes	Yes	Yes	Yes

The distinctive combination: ownership matching + AI prioritization that runs on metadata alone, fully open source.

Core features

Three commands form the pipeline. Each emits JSON the next can consume. (The math and design trade-offs behind each score live in docs/algorithm.md — this is the 30-second version.)

codeheat scan — rank the hotspots

Per-file complexity (max CCN), a composite Smell Score (CCN + nesting + parameters + length, because deep nesting hurts a reader more than raw branch count), and TODO/FIXME markers with their age in days. Files ranked by Smell Score, descending. TODO detection is token-based, so s = "# TODO" in a string isn't mistaken for a task.

codeheat scan <repo> --no-todo-age   # skip git history for speed on large repos

→ Smell Score & TODO detection

codeheat own — who to ask

score = Σ(recency × change-magnitude), recency on a 1-year half-life. Change magnitude is function-level — only functions a commit actually touched are credited, so you're not tagged an expert for a typo fix in a 3,000-line file. Aggregated by email, merge commits excluded. Matching, not blame.

codeheat own <repo> --from-report smell_report.json   # follow stage-1 priority
codeheat own <repo> --churn-only                      # faster: weight by churn only

→ Ownership scoring & scaling

codeheat insights — AI priorities, metadata only

Turns the stage 1+2 JSON into a per-file refactor priority and "ask who, about what". No source code is sent — the prompt carries only the hotspot name, other function names, imports, and directory, so the model can phrase a specific question without seeing a line of code.

codeheat insights smell_report.json --ownership-report ownership_report.json  # local Ollama (default)
codeheat insights smell_report.json --backend anthropic   # needs codeheat[llm] + ANTHROPIC_API_KEY
codeheat insights smell_report.json --dry-run             # audit the exact prompt, no LLM call

→ How the metadata-only prompt works

Integrations

The core is a CLI; these put it where your team already works.

• Dashboard (dashboard/) — the treemap heatmap above. Area = LOC, color = complexity; click a file for its owner and AI insight. Backendless static site, data processed in the browser. cd dashboard && npm install && npm run dev. See dashboard/README.md.
• MCP server (codeheat-mcp) — lets AI coding tools (Claude Desktop, Cursor) query CodeHeat mid-task: "which file here is riskiest?", "who should I ask about this file?". Three tools (riskiest_files, who_knows, file_report), same code-never-leaves guarantee. pip install "codeheat[mcp]".
• GitHub Action PR bot — comments on each PR with how the heatmap temperature changed and who to ask about files that got hotter. Rule-based, so it only warns on critical rises instead of nagging every push. See docs/algorithm.md.
• VS Code extension (vscode-extension/) — the heatmap in your editor: a sidebar ranked by temperature, plus CCN N · owner in the status bar for the current file. See vscode-extension/README.md.

Architecture

┌──────────┐   ┌──────────────┐   ┌────────────────┐   ┌──────────────────────┐
│  scan    │ → │     own      │ → │   insights     │ → │  Output layers       │
│ lizard + │   │  git history │   │  LLM (metadata │   │  • PR bot (Actions)  │
│ pygments │   │   ownership  │   │   only)        │   │  • D3 dashboard      │
└──────────┘   └──────────────┘   └────────────────┘   │  • VS Code · MCP     │
   JSON            JSON               JSON              └──────────────────────┘

Each stage emits JSON that the next consumes; the pipeline is structured so the LLM layer only ever sees numbers and metadata, never code. Scoring internals, the output schema, and known limitations are all in docs/algorithm.md.

Roadmap

Auto-created GitHub Issues · Slack/Discord alerts · SARIF output · tree-sitter-based precise analysis (a more accurate nesting/cognitive-complexity source than the lizard nd extension).

License

MIT