Headron MCP
Read-only Headron MCP server for routing, planning, and evidence lookup without running verification.
Run validated read-only Headron CLI commands, singly or in batches up to 8 with optional parallel execution.
Get a pre-edit brief for a file, directory, or tree with
port.Explain path-to-language-pack routing and show gate commands/states without executing them.
Build ordered work plans and deterministic change scopes with planned gates and tools.
Look up agent failure patterns with guards and related successful practices.
Classify changed files by category/risk, plan gates/isolation, and select agent/model tiers.
Inspect Mind API health, read local verification receipts and validity/verdicts.
Search the repository code index for symbols, paths, or phrases.
Provides the same adapter-based integration for Google Antigravity agents, keeping native tooling intact while enforcing identical deterministic boundaries: targeted evidence lookup, proof obligations per file kind, and refusal verdicts before landing.
Connects Headron's read-only MCP surface to OpenAI Codex agents, letting them look up file-to-check routing, retrieve repository facts and instruments, and read the same deterministic verdicts that the commit hook enforces, so autonomous changes are gated by one sovereign contract.
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 verifyruns 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 initwrites: AGENTS.md, CLAUDE.md, .mcp.json, .codex/config.toml, .cursor/mcp.json, .git/hooks/pre-commit.--dry-runpreviews;--no-wiringskips hooks/config;headron enforce uninstallrestores 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.
$ 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: pytestRelated MCP server: Magga
From task to proof
Owe:
obligations.py extract <task> <contract>binds requirements to checks.Check:
headron verify --receipt verify.jsonwrites tree-bound receipts.Seal:
ronbundle.py pack <task> out.ron --receipt verify.jsonwrites digest.ronbundles.Trust:
headron mind --micro ron.verify out.ron: acts only on verifiedok.
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 doctorIn 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 proofheadron 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.
Boundaries: product strategy covers capabilities, boundaries, and keyless onboarding.
Adoption:
headron initconfigures 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 checkDiscover:
headron find <query>searches paths and symbols;headron sweepmaps 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;--receiptssummarizes verification records.Microprograms:
headron mind --micro listnames programs (status, evidence, receipt).Beliefs & shell:
headron reviseaudits claims;headron shell --json "<cmd>"executes bounded.Land:
python scripts/branchstate.py --land; checkheadron landed <branch>before prune.Reporting: judgment rungs; report via
headronskill.
Find your way
All documents: docs index · wiki
Languages: atlas · routing · verification
Why a rule:
headron why·headron failures· instrumentsCompanion products: desktop, web, enterprise
Security: policy · OpenSSF · contributing
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 toolsfailuresARead-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.
gateARead-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.
headronARead-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_classifyARead-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_healthARead-onlyIdempotent
Show Mind API health telemetry, cache statistics, and system status.
Inputs: no named parameters.
mind_planARead-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_receiptsARead-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_routeARead-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.
mind_searchARead-onlyIdempotent
Search this repository's code index for a symbol, path or phrase; returns ranked file hits.
Inputs: query (required).
portARead-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.
proofBRead-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.
routeARead-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).
stepsARead-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.
successesARead-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
Scored across 14 tools
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.
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.
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.
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
Related MCP Connectors
The AI orchestration agent for modern software teams.
QA platform for agents: coverage signals, in-repo test plans, verified tests and release governance.
Browser-based QA for AI-built software. Test pages with real browsers via agents.
Governed behavior for AI applications and coding agents: define, evaluate, release and inspect.
Related MCP Servers
- FlicenseAqualityDmaintenanceProvides AI coding agents with dependency analysis, impact detection, and build verification tools.14-
- AlicenseNot gradedqualityCmaintenanceMagga 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 npmApache 2.0

corbatofficial
AlicenseAqualityDmaintenancePolicy and quality engine for AI coding agents that enforces team coding standards and provides validation gates for agent-assisted software delivery.754 npm5MIT- AlicenseNot gradedqualityAmaintenanceEnables 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 npm8PolyForm Noncommercial 1.0.0