heal

hook-driven evaluation & autonomous loop — heal watches your codebase decay between commits and hands the next refactor to your AI coding agent, one fix per commit.

AI coding agents are reactive: they wait for a human to file the next task. Meanwhile, codebases decay — complexity creeps, hotspots shift, duplicates pile up. heal closes that gap. Every commit it re-measures the codebase and produces a Severity-ranked TODO list your agent can drain — no human in the polling path.

Documentation: https://kechol.github.io/heal/

Supported languages

heal supports six languages out of the box — TypeScript / JavaScript / Python / Go / Scala / Rust, all bundled into the release binary.

Metric	Languages
LOC	Every language tokei recognizes.
Churn / Change Coupling / Hotspot	Language-agnostic — driven by git log.
CCN / Cognitive / Duplication	TypeScript / JavaScript / Python / Go / Scala / Rust.
LCOM	TypeScript / JavaScript / Python / Rust. (Go has no class scope; Scala awaits the LSP backend.)

The opt-in Test family runs on any language whose reporter emits an lcov.info. The opt-in Docs family pairs Markdown / RST docs against any of the six source languages above. Hotspot composes complexity with churn, so on a language without a tree-sitter grammar it falls back to a churn-only signal.

Feature families

heal groups its observers into three families. Each family carries its own metrics, configuration block, and pair of bundled skills (one to review, one to patch).

• Code (always on) — "Where is the codebase hard to change?" Eight metrics covering complexity, churn, duplication, cohesion, and a Hotspot decoration that highlights files that are both complex and frequently touched. Enabled by default after heal init.
• Test (opt-in via [features.test]) — "Which production code is dark to the test suite, and which tests have drifted or are silently skipped?" Reads lcov.info from your existing reporter and adds a test_hotspot decoration so uncovered hot paths bubble to the top.
• Docs (opt-in via [features.docs]) — "Which documentation has drifted from the code it describes?" Compares paired docs against their source files, flags broken internal links / orphan pages / TODO density, and adds a doc_hotspot decoration.

Adoption order is usually Code first, then Test once you have (or can produce) an lcov.info, then Docs once drift becomes a recurring surprise. Details: Features.

Install

Pick whichever fits your environment.

# Homebrew (macOS / Linux)
brew install kechol/tap/heal-cli

# Cargo (Rust toolchain)
cargo install heal-cli

# Shell installer
curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/kechol/heal/releases/latest/download/heal-cli-installer.sh | sh

Details: Installation.

Quick Start

Inside any git repository:

heal init                      # set up .heal/, calibrate, install hook, offer skills for each detected agent
claude /heal-setup             # tune strictness; optionally turn on Test / Docs
heal status                    # render the Severity-grouped TODO list
claude /heal-code-patch        # work through it, one fix per commit

heal init extracts the bundled skills into every supported agent it detects on PATH — Claude Code (.claude/skills/) and OpenAI Codex (.agents/skills/). Substitute codex for claude above if that's your CLI.

/heal-setup is the first-run wizard: it surveys the codebase, picks Strict / Default / Lenient, writes .heal/config.toml, and chains into /heal-doc-pair-setup or /heal-test-reporter-setup when you opt into either family.

Full walkthrough: Quick Start.

Documentation

Topical pages on the docs site:

• Concept — design idea in three minutes
• Features — Code (always on), Test, Docs
• CLI — every subcommand
• Code › Metrics, Code › Configuration, Code › Skills — the always-on family
• Test › Skills, Docs › Skills — the opt-in families' skills
• Architecture — internals

Development

Standard workspace commands; CI runs all five on push / PR.

cargo build  --workspace
cargo test   --workspace
cargo fmt    --all
cargo clippy --workspace --all-targets -- -D warnings
cargo deny   check

Project conventions live in CLAUDE.md.

License

Dual-licensed under Apache-2.0 OR MIT (LICENSE-APACHE, LICENSE-MIT). Contributions are dual-licensed unless stated otherwise.