Quick Start

heal turns codebase decay into agent work. Every commit, it re-measures complexity, hotspots, and duplication, then hands the resulting TODO list to Claude — which proposes fixes and applies the ones you approve, one commit each. The human steps out of the polling loop. This walkthrough sets that loop up end-to-end in about five minutes.

Requirements

Before you start.

• macOS or Linux
• A git repository to evaluate
• (Optional) Claude Code for the heal plugin’s /heal:setup, /heal:refactor, /heal:docs, and /heal:tests skills

1. Install

Pick one — same heal binary regardless of method.

Homebrew

brew install kechol/tap/heal-cli

Cargo

cargo install heal-cli

Shell

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

heal --version

Method-by-method details: Installation.

2. Bootstrap the repository

One command sets up .heal/ and installs the git hook.

heal init

Creates .heal/ (config and calibration) and installs the post-commit hook that flags the next Critical / High after every commit. It is safe to re-run: an existing config and calibration are kept unless you pass --force. heal doctor shows what is set up and what is left.

3. Add the plugin and run /heal:setup

The skills ship as a Claude Code plugin. In Claude Code, run:

/plugin marketplace add kechol/heal
/plugin install heal@heal

Then run the setup skill. Optional but recommended on the first run:

/heal:setup

It starts from heal doctor, so it only does what is missing: it asks Strict / Default / Lenient and updates .heal/config.toml, offers to turn on the opt-in Test / Docs / Semantic families and builds what they need (doc pairs, a coverage reporter, a concept list), and recalibrates only when you agree. Re-run it any time — on a project that is already set up it just reports that everything is in place.

4. See the TODO list

The TODO list is grouped by effective Drain Tier and Severity, with same-family rows ordered by descending hotspot score.

heal status

Prints the per-file TODO list in Tier, Severity, then score order. Filters and JSON output: CLI › heal status.

5. Work through the findings with Claude

Each skill reads what heal found, proposes changes, and applies only the ones you approve — one commit per proposal, with your tests run before each commit. None of them push or open a pull request.

/heal:refactor          # read the code findings as a system and propose refactors, structural ones included
/heal:refactor plan     # propose only; apply later
/heal:docs              # [features.docs]: fix, rewrite, move, or split docs through the Diátaxis lens
/heal:docs scaffold     # [features.docs]: stand up a doc tree from the codebase on a project with no docs yet
/heal:tests             # [features.test]: write, align, re-enable, or remove tests through the test pyramid

Skill details: Code › Skills, Docs › Skills, Test › Skills.

Further reading

Topical pages on the docs site:

• Concept — the why behind heal
• Features — Code (always on), Test ([features.test]), Docs ([features.docs])
• CLI — every subcommand
• Code › Metrics — the seven Code metrics
• Code › Configuration — .heal/config.toml reference

When you’re ready for more than the always-on Code family:

• Test › Configuration for lcov.info ingestion and the coverage / skip-ratio reports it turns on.
• Docs › Configuration for paired-doc drift and broken-link checks.

If a step does not behave as documented, please file an issue.