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 drains it one fix per commit. 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 CLI for the bundled /heal-setup, /heal-code-review, and /heal-code-patch skills

1. Install

Pick one — same heal binary regardless of method.

brew install kechol/tap/heal-cli

cargo install heal-cli

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), installs the post-commit hook that flags the next Critical / High after every commit, and offers to extract the bundled skills for every AI agent it finds on your PATH (Claude Code → .claude/skills/, OpenAI Codex → .agents/skills/). Use --yes to install for all detected agents without prompting, or --no-skills to skip them entirely.

3. Tune strictness with `/heal-setup`

Optional but recommended on the first run. The bundled setup wizard surveys your codebase, picks a sensible strictness level, and offers to turn on the opt-in Test / Docs families. Run it through whichever agent you installed:

/heal-setup

It asks Strict / Default / Lenient, updates .heal/config.toml, then chains into /heal-doc-pair-setup (writes .heal/doc_pairs.json) or /heal-test-reporter-setup (proposes the lcov reporter wiring) if you opt into either family. Re-run later when the codebase has shifted enough that the bar should move.

4. See the TODO list

The Severity-grouped TODO list, ready to act on.

heal status

Prints the per-file TODO list grouped by Severity. Filters and JSON output: CLI › heal status.

5. Audit and drain with your agent

Pick the bundled skill that matches what you want to do. Each feature family ships a read-only review skill (architectural audit, no writes) and a write patch skill (one commit per fix, refuses a dirty worktree). The examples below use claude; Codex users can substitute codex — the slash-command form is the same.

# Always available — the always-on Code family:
claude /heal-code-review     # what is HEAL really saying? Architectural read of the flagged code, prioritized refactor TODO list, no source writes.
claude /heal-code-patch      # work through the TODO list mechanically: one fix per commit, in Severity order, never pushes or amends.

# When [features.docs] is on:
claude /heal-doc-review      # audit your docs through the Diátaxis lens — find where readers get lost.
claude /heal-doc-patch       # auto-fix broken internal links, dangling identifiers, and orphan pages.

# When [features.test] is on:
claude /heal-test-review     # test-pyramid view of coverage gaps and silently-skipped tests.
claude /heal-test-patch      # write the missing tests the review flagged — one commit per uncovered hot path.

Two more, for less common situations:

claude /heal-doc-scaffold    # [features.docs]: stand up a fresh doc tree from codebase signals — useful on a project with no docs yet.
claude /heal-cli             # ask the agent about the heal CLI itself — every flag and JSON shape, treated as a stable contract.

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