smackdebt 0.3.0

Find costly code debt and see whether your changes make it better
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

# Smackdebt

**Help your AI agent write code you can follow.**

Your agent finished the feature. Now you have to untangle it.

Smackdebt gives coding agents concrete feedback on complexity, tangled dependencies,
and code that keeps causing work. They can find the trouble, simplify it, and check
whether their changes helped before handing the code back to you.

Analysis runs locally. No service, account, or API key required.

![Smackdebt finds a complex shipping function, then verifies a refactor: cognitive complexity 27 to 5, nesting 6 to 1, and 50 behavior checks passing.](docs/assets/smackdebt-demo.gif)

## Get it

For Linux x86_64 and macOS (Intel or Apple Silicon):

```sh
curl -fsSL https://github.com/bosun-ai/smackdebt/releases/latest/download/install.sh | sh
```

Or choose Homebrew or Cargo:

```sh
brew install bosun-ai/tap/smackdebt
# or
cargo binstall smackdebt
```

Then give your agent the skill:

```sh
smackdebt init
```

Choose **Codex, Claude Code, Cursor, Copilot, or Gemini CLI**, then restart your agent.
Rerun `init` after upgrading to update its skill. [Agent setup →](docs/agents.md)
For optional end-of-turn checks, run `smackdebt init --experimental-hooks`.

Installers arrive with the next published release. Until then, build from this
checkout with Rust 1.97+: `cargo install --locked --path crates/cli`.

## Give “make it cleaner” some teeth

Ask your agent:

> Use Smackdebt to review this change. Simplify the code where you've made it
> harder to follow, then run the tests and check the diff again.

The skill guides your agent to inspect the affected code before editing, compare
against its starting commit afterward, and fix regressions within the task.
For a required CI check, [set up a debt gate](docs/guide.md#gate).

You can run the same checks yourself:

```sh
smackdebt                 # Find the trouble spots
smackdebt src/auth        # Zoom in
smackdebt diff main       # Did this change help?
smackdebt --json          # Use the report in your own tools
```

## Less spaghetti, with receipts

The first five metrics rate each function **healthy**, **watch**, or **high**.
The rest show trouble between files and over time.

| Metric | What it measures |
| --- | --- |
| Cognitive complexity | How hard the flow is to follow. |
| Cyclomatic complexity | How many decisions the code makes. |
| Statements in a function | How many statements it contains. |
| Maximum nesting depth | How deep branches and loops go. |
| Declared parameters | How many inputs a function takes. |
| Dependency cycles | Dependencies that lead back to themselves. |
| Change impact | How much code depends on a file. |
| Hotspots | Complex code changed often. |

Use `--all` for detail. [Measurements](docs/guide.md#read-the-ratings) ·
[Problem patterns](docs/guide.md#read-the-problems) · [Checked examples](docs/examples.md)

## Languages

**C, C++, C#, Go, Java, JavaScript/JSX, PHP, Python, Ruby, Rust, TypeScript/TSX,
and Vue** (scripts and templates). React uses JSX/TSX support. Reports flag
unsupported files and parse failures so you can see what the check missed.
Dependency analysis follows supported static references and local project
configuration. Runtime loading and framework auto-imports are outside its scope;
[dependency coverage](docs/guide.md#languages) explains the language-specific limits.

---

[User guide](docs/guide.md) · [JSON schemas](schemas/README.md) ·
[Architecture](ARCHITECTURE.md) · [Development & releases](RELEASING.md)

MIT licensed. Built with [tree-sitter](https://tree-sitter.github.io/tree-sitter/).