Skip to main content
Glama

Contract 3.64.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 or model. An unrun check reports SKIP or NOT RUN, never a pass; hooks allow missing local tools (override: --strict), CI verifies all.

  • headron init writes: AGENTS.md, CLAUDE.md, .mcp.json, .codex/config.toml, .cursor/mcp.json, .git/hooks/pre-commit. --dry-run previews; --no-wiring skips hooks/config; headron enforce uninstall restores hooks.

  • Mind API: optional hosted verifier. CLI and local MCP work 100% offline and free with no key or account.

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

How it works

headron port <file> tells an agent what a file owes before it edits; atlas.yaml holds the checks. The hook and headron verify report PASS, FAIL, SKIP or NOT RUN: a skipped check is never a pass, whoever wrote the change. headron ci runs CI locally.

Task-to-evidence map.

$ 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

Related MCP server: Magga

From task to proof

  1. Owe: obligations.py extract <task> <contract> binds requirements to checks.

  2. Check: headron verify --receipt verify.json writes tree-bound receipts.

  3. Seal: ronbundle.py pack <task> out.ron --receipt verify.json writes digest .ron bundles.

  4. Trust: headron mind --micro ron.verify out.ron: acts only on verified ok.

Tasks checkpoint on git refs: headron task compile|run|resume|inspect. Steps 1 and 3 run python scripts/… in a clone.

Quickstart

# install
uv tool install headron-software && headron doctor
# editable, to change Headron itself
git clone --depth 1 --branch v3.64.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 checks, wires agents, installs hook, runs once (--dry-run previews)
headron verify && headron proof <file> --verify   # after a change: verdicts, then a file's proof

headron verify --changed checks only modified files (--change <class> narrows it); plain headron verify is the final verdict.

Recorded results

See the instrument limits for their scope.

Instrument

Recorded result

Enforcement

31/31 breaks refused across 20 toolchains; 869 declared planted cases

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

Task bench, 3 Claude models (contract 2.29.0)

with Headron 137/138; blind 78/138; every task answered by both arms

Free-model screen, 18 lanes answered (contract 3.63.0, 22 tasks)

on the 138 tasks both arms answered: with Headron 115/138; blind 58/138

Entry context: ~1,644 tokens; the rest loads on demand. Each row is its own record, contract version and task set: rows are never summed into one figure, and no run crowns a model. Routing data. Task records, screen. Per model, per record.

Where it fits

  • Agents & runtimes: adapters describe integrations; local MCP is read-only.

  • Machines: bootstrap (entry JSON) · facts.

  • Boundaries: product strategy covers capabilities, boundaries, and keyless onboarding.

  • Adoption: headron init configures repositories; CONSUMING covers CI, Actions, and MCP.

  • Languages: routes declare toolchains and checks per file pattern.

Agent contract

$ headron port scripts/doctor.py --line
◉ scripts/doctor.py │ ⠟backend │ python │ ⌂scripts │ ✓5 │ ⚠2 │ → headron gate scripts/doctor.py
$ headron port scripts --line
◎ scripts │ ⠟231 │ ⌂scripts │ → headron brainstorm
$ headron port . --line
○ . │ ⠟257 ⠿3 │ → headron check
  • Discover: headron find <query> searches paths and symbols; headron sweep maps topology.

  • Route: headron port <file> or parse .agent/bootstrap.json.

  • Tasks & processes: headron task compile|run|resume|inspect --json; headron process [<id>] --json.

  • Mind: headron mind --route <file> routes; --receipts summarizes verification records.

  • Microprograms: headron mind --micro list names programs (status, evidence, receipt).

  • Beliefs & shell: headron revise audits claims; headron shell --json "<cmd>" executes bounded.

  • Land: python scripts/branchstate.py --land; check headron landed <branch> before prune.

  • Reporting: judgment rungs; report via headron skill.

Find your way

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.64.0

Available Tools

14 tools
failuresA
Read-onlyIdempotent

Mistakes agents made with a file (for) or with an error text (match), each with the guard that stops it. The whole ledger is not offered: scope it with for, match or one shape's id. Successful structured results include the command record and exit code.

Inputs: id, for, limit, match.

gateA
Read-onlyIdempotent

Show the command and state for a file's named verification gate; it does not execute the command. Use steps for an ordered work plan. Successful structured results include the command record and exit code.

Inputs: path (required), gate, change.

headronA
Read-onlyIdempotent

Run a read-only Headron CLI command as argv when no dedicated tool fits; verbs: commands, check, proof, invariants, doctor, index, learn, process, index-search, find, do, pick, decide, decide-engine, pipeline, judge, revise, propose, links, model, intake, shell, delegate, handoff, cadence, schedtargets, mind, sweep, role, resume, steps, failures, successes, md, landed, brainstorm, inspect, data, task, port, why, gate, route, compile, plan. Programs: mind --micro list. ["commands", "--json"] lists arguments; exit code is the verdict.

Inputs: argv, batch, parallel.

mind_classifyA
Read-onlyIdempotent

Classify a set of changed files by category and risk. Use proof for a single file's planned gates; this does not run verification.

Inputs: files.

mind_healthA
Read-onlyIdempotent

Show Mind API health telemetry, cache statistics, and system status.

Inputs: no named parameters.

mind_planA
Read-onlyIdempotent

Classify changed files and return Mind's planned gates and isolation needs. Use steps for an ordered file-specific work plan; neither runs checks.

Inputs: files.

mind_receiptsA
Read-onlyIdempotent

Retrieve verification receipts and their validity and verdicts. Locally this reads the last verification receipt, if present; a configured hosted service supplies its own results. Validity does not rerun checks. Use proof to plan verification.

Inputs: limit.

mind_routeA
Read-onlyIdempotent

Select an agent and model tier for classified changes using capabilities and policy. Use route to explain a file's language pack; this does not authorize or execute an action.

Inputs: files.

portA
Read-onlyIdempotent

START HERE before editing a file: its route, tier, the gates to run, the lessons that apply, and the next commands. Successful structured results include the command record and exit code.

Inputs: target (required), runtime.

proofB
Read-onlyIdempotent

Deterministic scope of a change to one file: its change class, planned gates and tools. Measured verification (--verify) runs gates and stays on the CLI. Successful structured results include the command record and exit code.

Inputs: path (required), task, change.

routeA
Read-onlyIdempotent

Explain how a file path resolves to a language pack: returns the rule, evidence, guide, manifest and precedence. Use port for the full pre-edit brief; mind_route selects an agent instead. Successful structured results include the command record and exit code.

Inputs: path (required).

stepsA
Read-onlyIdempotent

Build an ordered work plan for one file, including its route and checks; no steps are executed. Tier, change class and runtime shape the plan. Use mind_plan for change classification and isolation guidance. Successful structured results include the command record and exit code.

Inputs: path (required), tier, change, runtime.

successesA
Read-onlyIdempotent

Look up recorded practices that address recurring failures, including when to use them, evidence and proving instruments. Scope by file or task with for, or by pattern id; limit applies to for. Use failures for the corresponding mistake patterns. Successful structured results include the command record and exit code.

Inputs: id, for, limit.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 14 tools

    Disambiguation2/5

    Port, steps, proof, gate, route, and the headron catch-all all operate on pre-edit planning/verification for a file, and their descriptions differentiate by nuance rather than clearly separate resource/action boundaries. The headron tool explicitly duplicates many dedicated verbs (proof, steps, failures, successes, port, gate, route, plan), so an agent could easily choose the wrong entry point.

    Naming Consistency3/5

    All names are lowercase snake_case and readable, but there is no consistent verb_noun convention: some are bare nouns (gate, steps, port, route, proof) while others use a mind_ prefix (mind_search, mind_receipts, mind_classify). The mix of prefixed and unprefixed families makes naming only partially predictable.

    Tool Count4/5

    Fourteen tools is within a reasonable range for a repo-analysis and verification server. However, several overlap-heavy planning tools (port, steps, proof, gate, route) reduce the sense that every tool earns its place, and the catch-all headron inflates the effective surface.

    Completeness4/5

    For a read-only change-planning and verification domain, the surface covers search, routing, gates, plans, receipts, failure/success lookup, and health telemetry. Missing direct execution or recording capabilities appear intentional or are handled through the CLI fallback, leaving only minor gaps.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Magga lets coding agents prove their changes before claiming they’re done by building the code and verifying that newly added tests fail before the fix and pass after it. It returns evidence-backed verdicts through the verify_change tool and supports 16 languages, including Rust, Go, Python, Solidity, and C/C++.
      8 npm
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      Policy and quality engine for AI coding agents that enforces team coding standards and provides validation gates for agent-assisted software delivery.
      7
      54 npm
      5
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI coding agents to enforce spec-driven development and verify code before it is marked done, using six tools that catch invented APIs, scan for hallucinated content, check plugin conformance, sandbox-run tests, validate schemas, and record audit evidence.
      771 npm
      8
      PolyForm Noncommercial 1.0.0