hone

name	hone
description	Run iterative codebase improvement with hone CLI; use when user asks to hone, iterate, maintain dependencies, assess, improve code quality, set up or fix quality gates, derive agents, mix agents, or check iteration history
metadata	{"version":"1.3.1","author":"Stacey Vetzal"}

Hone CLI

Hone wraps an LLM in a deterministic verification loop to iteratively improve codebases. The agent proposes improvements; hone independently verifies them through quality gates. The agent never self-certifies.

Quick Reference

Task	Command
First-time setup	hone derive /path/to/project
Run one improvement	hone iterate <agent> /path/to/project
Update dependencies	hone maintain <agent> /path/to/project
Augment a local agent	hone mix <agent> <folder> --from <global-agent> --principles --gates
Check available agents	hone list-agents
Show quality gates	hone gates /path/to/project
Run quality gates	hone gates /path/to/project --run
View past iterations	hone history /path/to/project
Iterate with external audit dir	hone iterate <agent> /path/to/project --audit-dir /tmp/audits
Show configuration	hone config

Prerequisites

Before using hone, verify:

1. Claude Code CLI (claude) is installed and authenticated
2. hone is installed (brew install svetzal/tap/hone on macOS)
3. For GitHub mode: GitHub CLI (gh) is installed and authenticated

hone --version
claude --version

Establishing Quality Gates

Quality gates are the foundation of hone's value. Without reliable gates, the verify stage has nothing to enforce and the agent can self-certify by default. Extracted gates from agents are unreliable — they often reference wrong commands, missing tools, or incorrect paths for the specific project. Always establish gates manually through interactive validation.

The Gate File

Gates live in .hone-gates.json in the project root. This file is version-controlled and takes priority over any LLM-based extraction.

{
  "gates": [
    { "name": "test", "command": "bun test", "required": true },
    { "name": "typecheck", "command": "bunx tsc --noEmit", "required": true },
    { "name": "lint", "command": "bunx biome check src", "required": true },
    { "name": "security", "command": "osv-scanner .", "required": false }
  ]
}

Each gate has three fields:

• name — short identifier shown in output
• command — exact shell command run via sh -c in the project directory
• required — true triggers the retry loop on failure; false reports but doesn't block

Interactive Gate Setup Workflow

When helping a user establish gates, work through this process one gate at a time:

Step 1: Discover what the project uses

Examine the project root for tooling signals:

File	Likely gates
package.json	npm test, npm run lint, npx tsc --noEmit, npm audit
mix.exs	mix test, mix credo --strict, mix format --check-formatted, mix deps.audit
pyproject.toml	pytest, ruff check src, ruff format --check src, pip-audit
CMakeLists.txt	ctest --output-on-failure, cppcheck --enable=all src/
Cargo.toml	cargo test, cargo clippy -- -D warnings, cargo audit
go.mod	go test ./..., golangci-lint run, govulncheck ./...
bun.lockb / bunfig.toml	bun test, bunx tsc --noEmit, bunx biome check src

Check package.json scripts, CI config files (.github/workflows/, .gitlab-ci.yml), Makefiles, and existing linter configs (.eslintrc, biome.json, .credo.exs, ruff.toml) for the actual commands the project already uses.

Do NOT guess — read the project files.

Step 2: Test each command individually

Before adding any gate, run the candidate command in the project directory and observe the result:

cd /path/to/project && bun test

There are only three outcomes:

1. Passes (exit 0) — Add it to .hone-gates.json
2. Fails (non-zero exit) — Investigate why. The project may have pre-existing failures, wrong paths, or missing configuration. Fix the underlying issue or adjust the command, then re-run.
3. Command not found — The tool isn't installed. Help the user install it or choose an alternative that's already available.

Do not add a gate that doesn't pass on the unmodified codebase. Hone's preflight stage runs all gates before any LLM work begins. If a required gate fails at preflight, hone stops immediately — the baseline is broken and there's no point sending an agent to fix environment problems.

Step 3: Build the gates file incrementally

Start with an empty gates file and add one gate at a time after each passes:

{ "gates": [] }

Add the most important gate first (usually tests), verify it works, then add the next. A typical build order:

1. test — Does the test suite pass? This is the most critical gate.
2. typecheck — Does the project have static type checking configured?
3. lint — Is there a linter configured and passing?
4. format — Is there a formatter in check mode? (Often combined with lint via &&)
5. security — Is there an audit tool available? (Usually required: false)

Step 4: Verify the full gate set together

After building the file, run all gates through hone to confirm:

hone gates /path/to/project --run

This runs each gate sequentially and reports pass/fail per gate, just as hone's preflight and verify stages will.

Common Gate Problems and Fixes

Test gate fails with missing dependencies: The test suite needs setup first. Check if npm install / bun install / mix deps.get needs to run. Gates assume dependencies are already installed.

Lint gate fails on files outside the project scope: Narrow the command path. Instead of eslint . try eslint src or check the lint config for ignorePatterns.

Typecheck gate fails on generated files: Add excludes to tsconfig.json or narrow the scope: tsc --noEmit --project tsconfig.build.json.

Security gate fails on known vulnerabilities: Mark security gates as required: false so they report without blocking. Or use npm audit --audit-level=high to only fail on high/critical.

Format gate fails immediately: The codebase hasn't been formatted yet. Run the formatter once (mix format, ruff format src, npx biome format --write src) to establish the baseline, then add the check-mode gate.

Command works in terminal but fails in hone: Hone runs commands via sh -c with the project directory as cwd. Check that:

• The command doesn't rely on shell aliases or functions
• PATH includes the tool (use full paths like npx, bunx if needed)
• The command doesn't need an interactive terminal

Gate passes locally but takes too long: The default gate timeout is 120 seconds. Large test suites may need more time. Adjust gateTimeout in ~/.config/hone/config.json or split slow gates so fast ones still provide quick feedback.

Combining Related Commands

Use && to combine commands that form a single logical gate:

{ "name": "lint", "command": "mix credo --strict && mix format --check-formatted", "required": true }

Both must pass for the gate to pass. This keeps the gates file concise and groups related checks.

When to Use required: false

Non-required gates provide information without blocking iteration. Use for:

• Security audits (often have findings outside developer control)
• Style checks that are aspirational rather than enforced
• Slow checks you want visibility into but don't want blocking the retry loop

A failed non-required gate still appears in output — the developer sees it, but hone won't send the agent into a retry loop over it.

Workflows

New Project Setup

For a project that has never used hone:

# 1. Generate agent (gates file from derive is a starting point only)
hone derive /path/to/project

# 2. Review the generated agent
hone list-agents

# 3. Establish quality gates interactively (see above)
#    Do NOT trust the derived .hone-gates.json — validate every gate

# 4. Run first iteration once gates are solid
hone iterate <agent-name> /path/to/project

Running an Improvement Iteration (Local Mode)

Local mode executes immediately without approval gates:

# Basic iteration
hone iterate typescript-craftsperson ./src

# Skip quality gates (when setting up, before gates are established)
hone iterate python-craftsperson . --skip-gates

# More retries for complex fixes
hone iterate elixir-phoenix-craftsperson ./apps/web --max-retries 5

# Skip triage to force execution of even low-severity findings
hone iterate cpp-qt-craftsperson . --skip-triage

# Raise the severity bar (only fix critical issues)
hone iterate typescript-craftsperson . --severity-threshold 4

# Send audit logs to an external directory (absolute path)
hone iterate typescript-craftsperson . --audit-dir ~/hone-audits/my-project

Running an Improvement Iteration (GitHub Mode)

GitHub mode creates issues for human approval before executing:

# Single proposal
hone iterate typescript-craftsperson ./src --mode github

# Multiple proposals per run
hone iterate typescript-craftsperson ./src --mode github --proposals 3

Each GitHub-mode invocation:

1. Closes issues the repo owner has thumbs-downed
2. Executes approved (thumbs-up) issues oldest-first
3. Creates new proposal issues

Re-invoke via cron or CI to process approvals — hone does not poll.

Maintaining Dependencies

Maintain proactively updates dependencies and verifies gates still pass. Unlike iterate, there is no assess/triage/plan pipeline — it goes straight to execution with a verify/retry loop.

# Basic dependency update
hone maintain typescript-craftsperson ./src

# More retries for complex breakage
hone maintain python-craftsperson . --max-retries 5

# Use a stronger model for tricky updates
hone maintain elixir-craftsperson . --execute-model opus

# Send audit logs to an external directory
hone maintain typescript-craftsperson . --audit-dir ~/hone-audits/my-project

Maintain requires gates to be configured — it exits with an error if no gates are found. The agent provides coding context/principles for making good fixes during retries.

Audit files use maintain-YYYY-MM-DD-HHMMSS naming in the project's audit directory.

Mixing Agents

Mix augments a local (project-specific) agent with ideas from a global agent. Useful when you've derived a local agent and want to incorporate principles or gates from a broader agent:

# Mix engineering principles from a global agent into a local one
hone mix local-agent . --from typescript-craftsperson --principles

# Mix quality gates
hone mix local-agent . --from typescript-craftsperson --gates

# Mix both
hone mix local-agent . --from typescript-craftsperson --principles --gates

The local agent must exist in <folder>/.claude/agents/. The foreign agent (--from) must exist in ~/.claude/agents/. Separate Claude calls per aspect prevent cross-contamination.

Reviewing History

hone history /path/to/project

# History from an external audit directory
hone history /path/to/project --audit-dir ~/hone-audits/my-project

Audit files live in <project>/audit/ (or the path specified by --audit-dir) as markdown:

• <name>.md — Assessment
• <name>-plan.md — Plan
• <name>-actions.md — What the agent did
• <name>-retry-N-actions.md — Retry attempts

Pipeline Stages

Each hone iterate runs this pipeline:

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

Stage	Model	Access	Skip Flag
Charter Check	none	read-only	--skip-charter
Preflight	none	subprocess	--skip-gates
Assess	opus	read-only	—
Name	haiku	read-only	—
Triage	haiku	read-only	--skip-triage
Plan	opus	read-only	—
Execute	sonnet	full	—
Verify	none	subprocess	--skip-gates
Summarize	haiku	read-only	— (only runs on success)

Override models with --assess-model, --plan-model, --execute-model, --summarize-model.

Override audit directory with --audit-dir <path> (relative to project, or absolute). Available on iterate, maintain, and history commands.

Charter Requirement

Hone requires project intent documentation before it will run. It looks for:

• CHARTER.md
• CLAUDE.md with a ## Project Charter section
• README.md
• A description field in package manager config

Content must meet minimum length (default 100 chars, override with --min-charter-length). Skip with --skip-charter.

Triage Behavior

After assessment, proposals pass through two filters:

1. Severity threshold — Below the threshold (default 3, scale 1-5) rejects immediately
2. Busy-work detection — Rejects: adding comments to unchanged logic, reorganizing imports, single-use abstractions, "consistency" refactors

When triage rejects, hone exits with success — the codebase is in good shape.

JSON Output

All commands support --json for machine-readable output:

hone iterate typescript-craftsperson . --json 2>/dev/null | jq .success
hone gates . --run --json | jq '.results[] | select(.passed == false)'

Successful runs include headline (max 72 chars, imperative, for git commit subject) and summary (2-5 lines, for git commit body) fields:

hone iterate agent . --json 2>/dev/null | jq -r '.headline'
hone maintain agent . --json 2>/dev/null | jq -r '.summary'

Configuration

Defaults in ~/.config/hone/config.json:

{
  "models": {
    "assess": "opus",
    "name": "haiku",
    "plan": "opus",
    "execute": "sonnet",
    "gates": "sonnet",
    "derive": "opus",
    "triage": "haiku",
    "mix": "opus",
    "summarize": "haiku"
  },
  "auditDir": "audit",          // relative to project, or absolute path
  "maxRetries": 3,
  "gateTimeout": 120000,
  "mode": "local",
  "minCharterLength": 100,
  "severityThreshold": 3
}

CLI flags override config per invocation.

Troubleshooting

Problem	Solution
"No charter found"	Add CHARTER.md, README.md, or use --skip-charter
Preflight fails	Gates are broken on the unmodified codebase — fix gates before iterating
Triage rejects everything	Codebase is in good shape, or lower --severity-threshold
Agent can't fix gate failures	Increase --max-retries or fix manually and re-run
No agents found	Run hone list-agents and hone derive . to generate one
Gates not detected	Create .hone-gates.json manually — don't rely on extraction
Iterate hangs at verify	A gate command may be hanging — check gateTimeout and test commands individually