bobbin-ai 0.25.2

Local-first context injection engine for AI coding agents
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110

---
title: hotspots
description: Identify code hotspots with high churn and high complexity
tags: [cli, hotspots]
status: draft
category: cli-reference
related: [guides/hotspots.md, cli/related.md, cli/history.md]
commands: [hotspots]
feature: hotspots
source_files: [src/cli/hotspots.rs]
---

# hotspots

Identify code hotspots — files with both high git churn and high structural complexity.

## Synopsis

```bash
bobbin hotspots [OPTIONS]
```

## Description

The `hotspots` command combines git commit history with AST-based complexity analysis to surface files that are both frequently changed and structurally complex. These files are the most likely sources of bugs and the best candidates for refactoring.

The **hotspot score** is the geometric mean of normalized churn and complexity:

```text
score = sqrt(churn_normalized * complexity)
```

Where:

- **churn** is the number of commits touching a file in the time window, normalized against the most-changed file.
- **complexity** is a weighted AST complexity score in the range \[0, 1\].

Non-code files (markdown, JSON, YAML, TOML) and unknown file types are automatically excluded.

## Options

| Option | Short | Default | Description |
|--------|-------|---------|-------------|
| `--path <DIR>` | | `.` | Directory to analyze |
| `--since <EXPR>` | | `1 year ago` | Time window for churn analysis (git date expression) |
| `--limit <N>` | `-n` | `20` | Maximum number of hotspots to show |
| `--threshold <SCORE>` | | `0.0` | Minimum hotspot score (0.0–1.0) |

## Examples

Show top 20 hotspots from the last year:

```bash
bobbin hotspots
```

Narrow to the last 3 months, top 10:

```bash
bobbin hotspots --since "3 months ago" -n 10
```

Only show files with a score above 0.5:

```bash
bobbin hotspots --threshold 0.5
```

Verbose output includes a legend explaining the scoring:

```bash
bobbin hotspots --verbose
```

JSON output for CI or dashboards:

```bash
bobbin hotspots --json
```

## JSON Output

```json
{
  "count": 3,
  "since": "1 year ago",
  "hotspots": [
    {
      "file": "src/cli/hook.rs",
      "score": 0.823,
      "churn": 47,
      "complexity": 0.72,
      "language": "rust"
    }
  ]
}
```

## Supported Languages

Complexity analysis supports: Rust, TypeScript/JavaScript, Python, Go, Java, C, C++.

## Prerequisites

Requires a bobbin index and a git repository. Run `bobbin init` and `bobbin index` first.

## See Also

- [Hotspots Guide](../guides/hotspots.md) — strategies for using hotspot data
- [status](status.md) — check index statistics