Real-time color overlay showing cognitive complexity per function — like a thermal camera for code quality.
The Problem
You know a file is "too complex" but you can't tell which part to refactor. Complexity metrics live in reports and CI dashboards — far from where you're actually writing code. By the time you see a SonarQube report, you've moved on.
What It Does
Cognitive Heatmap renders a live color overlay directly on your editor showing cognitive complexity per function. Green = simple. Yellow = getting complex. Red = too complex. The overlay updates as you type.
Features
- Live color overlay — real-time background tinting per function block
- Four complexity bands — low (green), medium (yellow), high (red), critical (deep red)
- Status bar — shows the most complex function in the current file
- Complexity report — open a detailed panel listing all functions sorted by score
- Keyboard shortcut —
Cmd+Shift+Hto toggle the heatmap - Configurable thresholds — adjust what counts as low/medium/high for your team
- Debounced refresh — re-calculates after you stop typing (configurable ms)
Getting Started
The heatmap activates automatically when you open a TypeScript or JavaScript file. Color overlays appear on functions based on their complexity score.
- Toggle on/off: Press
Cmd+Shift+Hor run Cognitive Heatmap: Toggle Overlay - See the report: Run Cognitive Heatmap: Show Complexity Report
Commands
| Command | Shortcut | Description |
|---|---|---|
Cognitive Heatmap: Toggle Overlay |
Cmd+Shift+H |
Show/hide the complexity overlay |
Cognitive Heatmap: Show Complexity Report |
— | Open the full complexity report for the current file |
Color Bands
| Color | Band | Default Score Range | Meaning |
|---|---|---|---|
| 🟢 Subtle green | low |
0–5 | Simple and readable |
| 🟡 Subtle yellow | medium |
6–10 | Getting complex — consider refactoring |
| 🔴 Subtle red | high |
11–20 | Complex — refactor this |
| 🔴 Deep red | critical |
21+ | Very complex — split into smaller functions |
Configuration
| Setting | Default | Description |
|---|---|---|
cognitiveHeatmap.enabled |
true |
Enable the heatmap by default |
cognitiveHeatmap.thresholds |
{ "low": 5, "medium": 10, "high": 20 } |
Complexity score thresholds per band |
cognitiveHeatmap.debounceMs |
500 |
Ms to wait after typing before recalculating |
Stricter thresholds (for high-quality codebases)
{
"cognitiveHeatmap.thresholds": {
"low": 3,
"medium": 7,
"high": 15
}
}
What Contributes to Complexity
The score increments for each:
| Construct | Increment |
|---|---|
if, else if, else |
+1 |
for, while, do |
+1 |
switch, case |
+1 |
catch |
+1 |
Ternary operator ? |
+1 |
Logical &&, ` |
|
| Nesting penalty | +1 per nesting level |
Example:
// Score: ~1 (just one if)
function isAdult(age: number) {
if (age >= 18) { return true; }
return false;
}
// Score: ~8 (nested ifs + loops + logical operators)
function processOrder(order: Order) {
if (order && order.items) { // +1 (if) +1 (&&)
for (const item of order.items) { // +1 (for) +1 nesting
if (item.stock > 0) { // +1 (if) +2 nesting
if (item.price || item.sale) { // +1 (if) +1 (||) +3 nesting
// ...
}
}
}
}
}
Tips
- Functions scoring over 20 should almost always be split into smaller functions
- Use the Complexity Report (sorted descending) to prioritize what to refactor
- Reducing nesting (early returns, guard clauses) is the fastest way to lower scores
- Keep the heatmap visible while refactoring — watch the color change as you simplify