Headron

npx add-mcp 'https://headron.tech/mcp'

Contract 3.62.0 · MIT · verdicts carry receipts: headron verify --receipt <file>

• Is: a rule contract and CLI mapping changed files to checks. Hooks are optional; headron verify runs done gates.
• Is not: a coding agent, model, test framework, or proof code is correct. A check that cannot run reports SKIP or NOT RUN, never a pass; the hook lets that commit through.
• headron init writes: AGENTS.md, CLAUDE.md, .mcp.json, .codex/config.toml, .git/hooks/pre-commit. Use --no-wiring to skip hooks and configuration; headron enforce uninstall restores a displaced hook.
• Mind API: hosted, paid, needs a key; plans a declared change. The command line works without it.

Agents: llms.txt. Chats: CHAT.md. Evidence.

Why this exists

Headron connects changed files to declared checks and reports whether those checks ran. A skipped check is not a pass. An optional Git hook can run checks before a commit, whether the change came from a developer or an agent.

How it works

headron port <file> tells an agent what a file owes before it edits. atlas.yaml holds those checks; the commit hook and CI report PASS, FAIL, SKIP or NOT RUN. The hosted Mind API plans a declared change through headron mind.

$ headron gate scripts/doctor.py
1. formatter: ruff format --check scripts/doctor.py
2. compiler_or_typechecker: python3 -c 'import ast,sys; [ast.parse(open(f, encoding="utf-8").read(), f) for f in sys.argv[1:]]' scripts/doctor.py
3. unit_tests: pytest

Quickstart

# install
uv tool install headron-software && headron doctor
# editable, to change Headron itself
git clone --depth 1 --branch v3.62.0 https://github.com/HLIntel/Headron ~/headron && uv tool install --editable ~/headron && headron doctor

In your repository:

cd path/to/your-repo && headron init   # finds your checks, wires your agents, installs the commit hook, runs once
headron verify && headron proof <file> --verify   # after a change: verdicts, then a file's proof

With an impact map, headron verify --changed evaluates checks for modified files. Target a specific profile with headron verify --changed --change <class> (e.g. source_change, api_change, security_sensitive); headron verify remains the final full verdict.

Machines: bootstrap, facts, and JSON schema. Agents: adapters; the MCP interface is read-only. Another repository: CONSUMING.

Recorded results

See the instrument limits for their scope.

Instrument	Recorded result
Enforcement	31/31 breaks refused across 20 toolchains; 807 declared planted cases
Failure ledger	124 shapes, 212 sightings; 101 in-tree guarded, 23 host-only
Field ledger	940 verifications (136 clean); 1133 refusals; 394 landings; 711 lessons; 394 sessions
Verification outcomes	17,397 checks: 7,357 PASS, 1,097 REUSED, 1,278 FAIL, 7,665 NOT RUN. 533 runs failed; 271 stopped with an unrun check; 0 reported clean despite a failed or unrun check
Routing experiment	89% fewer prompt tokens than whole-tree; 50% fewer than unassisted, across identified models
Language roles	360 pairs: 110 runnable, 0 undeclared

Entry context: ~1,593 tokens. The 211 documents (699 KiB) load on demand; install: 10 KiB; hash lock with test tools: 8 packages. Field records. Routing data. Measures can overlap.

Where it fits

• Agents and runtimes: adapters describe supported integrations.
• Headron-Harness: a separate desktop dashboard and runtime; see product boundaries.
• Other repositories: headron init sets up a repository; CONSUMING covers CI.
• Languages: routes declare available checks and identify checks without a tool.

Agent contract

$ headron port scripts/doctor.py --line
◉ scripts/doctor.py │ ⠟backend │ python │ ⌂scripts │ ✓5 │ ⚠1 │ → headron gate scripts/doctor.py
$ headron port scripts --line
◎ scripts │ ⠟182 │ ⌂scripts │ → headron brainstorm
$ headron port . --line
○ . │ ⠟210 ⠿4 ⠁1 │ → headron check

• Discover: headron find <query> searches paths, symbols and vocabulary; headron sweep maps topology. Search does not guarantee semantic recall.
• Route: headron port <file>, or parse .agent/bootstrap.json; load only its names.
• Processes: headron process [<id>] --json lists workflows; with an id, its steps and gates.
• Mind: headron mind --route <file> routes; headron mind --receipts summarizes the latest local verification record.
• Beliefs: headron revise names what rests on a refuted claim; headron propose drafts each fix outside the tree.
• Automate: add --json; records follow the output schema.
• Before shell: headron shell --json "<cmd>"; exit 3 means its verdict would be misread.
• Land: python scripts/branchstate.py --land; check headron landed <branch> before deletion.
• Judge and report: use the judgment rungs; file breaks with the headron skill.

Find your way

• Every document: docs index · wiki
• Languages: atlas · routing · verification
• Agents: harness · .headron · runtimes
• Why a rule: headron why · headron failures · instruments
• Companion products: desktop, web, enterprise
• Security: policy · OpenSSF · contributing

Counts, computed

Generated on every build; check refuses drift.

• 52 hard invariants — enforced on every change, zero unowned
• 363 agreement edges — each a file tied to the declaration it answers for
• 95 instruments — each stating what it proves, what it does not, and what closes the gap
• 385 tool entries — across 40 manifests and 5 kinds, validated against tools/tools.schema.json
• 180 harness Python files — every one held by lint · format · typecheck
• 3.62.0 contract version — VERSION, asserted in 10 other files

Project

Version tracks the contract, not content (versioning). Built by HLIntel LLC, public on purpose (about). Contributions pass headron verify. MIT License.

Updated: contract v3.62.0