heal

heal watches your codebase decay between commits — complexity creep, hotspots, duplication — and turns every problem it spots into a TODO your next Claude session can work through, one fix per commit. No human in the polling path.

Quick Start (5 min)

Read the concept

Why heal

AI coding agents are good at producing the next change you request. Codebases, however, evolve continuously: complexity accumulates, the same files get touched repeatedly, and duplicated blocks drift in. The agent doesn’t observe these long-term shifts — without an external signal, the human is the only one tracking them.

heal fills that gap. A git post-commit hook surfaces every Critical / High problem right inside the commit output, and heal status lays out the same TODO list for the /heal:refactor Claude skill — which proposes fixes and commits the ones you approve, one at a time.

Three feature families, plus an opt-in semantic layer, shape what heal observes:

• Code is always on — complexity, churn, duplication, hotspots, cohesion. Seven metrics plus the Hotspot decoration, on every project after heal init.
• Test (opt-in) reads lcov.info from your existing reporter and surfaces uncovered hot paths plus drifting tests.
• Docs (opt-in) compares paired documentation against the source it describes and flags drift, broken links, and orphan pages.
• Semantic (opt-in) asks TypeSafe’s Jev classifier what metrics cannot answer — misnamed functions, tests that check nothing, docs that no longer match the code. It is the only part of heal that sends content over the network, and only when you run heal semantic ask. See Semantic (Jev).

See Features for the full picture.