Hone

A CLI that hones your codebase one principle at a time.

You point it at a project and an agent. It finds the engineering principle your code violates most, plans a fix, executes it, and then — critically — runs your quality gates itself to make sure the agent didn't break anything. If a gate fails, it sends the agent back with the failure output until it gets it right.

The agent never self-certifies. Hone verifies independently.

See CHARTER.md for the design rationale behind these choices.

Prerequisites

Hone currently delegates to the Claude Code CLI (claude), which must be installed and authenticated. We recommend using the Claude Max plan if you want to do regular iteration on your codebase.

For GitHub mode, the GitHub CLI (gh) must also be installed and authenticated.

Install

macOS (Homebrew)

brew tap svetzal/tap
brew install hone

Linux

Download the binary from the latest release:

curl -L https://github.com/svetzal/hone-cli/releases/latest/download/hone-linux-x64.tar.gz | tar xz
sudo mv hone-linux-x64 /usr/local/bin/hone

Windows

Download hone-windows-x64.exe from the latest release and add it to your PATH.

From source

Requires Bun:

bun install
bun run build    # produces build/hone

Getting started with a new project

The fastest path from zero to iterating:

# 1. Generate an agent and quality gates for your project
hone derive /path/to/project

# 2. Review what was generated
hone list-agents
hone gates /path/to/project

# 3. Run your first improvement iteration
hone iterate <agent-name> /path/to/project

hone derive explores your project using Claude's tools (Read, Glob, Grep) to examine source code, architecture, conventions, and tooling, then generates an agent with principles, QA checkpoints, and coding guidelines derived from your actual codebase, plus a .hone-gates.json file.

If you already have an agent (from svetzal/guidelines or written by hand), skip derive and go straight to iterating.

The iteration pipeline

Each hone iterate invocation runs this pipeline:

Charter Check → Preflight → Assess → Name → Triage → Plan → Execute → Verify

Stage	What happens	Model	Access
Charter Check	Verifies the project has intent documentation	none (heuristic)	read-only
Preflight	Resolves gates, runs them against unmodified codebase — fails fast if broken	none (subprocess)	—
Assess	Identifies the most violated principle, produces a severity rating	opus	read-only
Name	Generates a kebab-case filename for audit records	haiku	read-only
Triage	Filters out low-severity and busy-work proposals	haiku	read-only
Plan	Creates a step-by-step correction plan	opus	read-only
Execute	Applies the plan	sonnet	full
Verify	Runs quality gates; retries on failure	none (subprocess)	—
Summarize	Generates headline + summary for commit messages (on success only)	haiku	read-only

Execute and Verify repeat up to --max-retries times (default: 3).

Charter check

Before any assessment, hone checks for intent documentation — a CHARTER.md, a CLAUDE.md with a ## Project Charter section, a README.md, or a description field in your package manager config. If nothing meets the minimum length threshold (default: 100 characters), hone stops with guidance on what to add.

Skip with --skip-charter. Adjust the threshold with --min-charter-length.

Preflight

After the charter check but before any LLM work, hone resolves quality gates and runs them against the unmodified codebase. If required gates fail before any changes are made, the gates themselves are broken (missing tools, wrong paths, pre-existing failures) — there's no point sending an agent to fix environment problems it can't fix.

Preflight is skipped when --skip-gates is set or when no gates are resolved.

Triage

After assessment, proposals pass through a two-layer filter:

1. Severity threshold — Proposals rated below the threshold (default: 3 on a 1-5 scale) are rejected immediately with no LLM call.

2. Busy-work detection — A separate LLM pass classifies the change and rejects busy-work categories: adding comments to unchanged logic, reorganizing imports, adding abstractions for single-use code, and "consistency" refactors that don't fix bugs or enable features.

When triage rejects a proposal, hone exits with success: true — the codebase is in good shape relative to the agent's principles.

Skip with --skip-triage. Adjust the severity bar with --severity-threshold.

Retry loop

When a required gate fails after execution, the agent gets a retry prompt with the original plan, which gates failed, and the captured output (last 200 lines). Each retry is saved separately (<name>-retry-N-actions.md).

Local mode vs GitHub mode

Local mode (default)

Proposals that pass triage are executed immediately. One proposal per invocation.

hone iterate typescript-craftsperson ./src

GitHub mode

Proposals become GitHub issues. The repo owner approves via thumbs-up reaction, rejects via thumbs-down. No code changes happen without sign-off.

hone iterate typescript-craftsperson ./src --mode github
hone iterate typescript-craftsperson ./src --mode github --proposals 3

Each invocation:

1. Housekeeping — closes any hone issues the repo owner has thumbs-downed
2. Execute approved backlog — processes thumbs-up issues oldest-first: execute, verify gates (retry loop), commit, close
3. Propose — assess, triage, plan, create new GitHub issue(s)

Behaviours:

This is the beginning of the README. Read the rest at the original. Read the full README ↗