ra-yavuz › chiron
chiron
A mentor kit for coding agents: an operating doctrine plus mechanical enforcement hooks, so weaker models work with the discipline of stronger ones. Named after the centaur who trained heroes.
Coding agents on weaker models fail in predictable ways: they patch symptoms, invent flags, delete the failing test, and claim "done" without running anything. Prose rules help a little; models ritualize checklists and drift past them. chiron's bet is that enforcement beats prose: the doctrine is paired with hooks that deny the bad tool call outright and block the dishonest "finished".
How it works
| Layer | What it does |
|---|---|
| Doctrine | A written operating doctrine: verify before acting, no workarounds, respect the specs, honest completion claims, push back when the request is wrong. Loaded once at session start, reinforced by a compressed per-turn reminder. |
| Ground truth | A session-start hook injects the project's real file inventory, detected test runner, and spec locations, so file paths do not get hallucinated. |
| Project checklist | An optional, user-owned .chiron/checklist.md with project-specific steps ("run shellcheck before committing"). Read live from disk and carried into every turn (inlined when small, pointed to when oversized), so an edit takes effect on the next prompt; the agent may change the file only on explicit request. |
| Guard | A PreToolUse hook denies --no-verify, || true error swallowing, force pushes, and test deletion or weakening. The doctrine reason is fed back to the model; a denied tool call cannot be drifted past. |
| Stop gate | A Stop hook blocks "finished" once when code changed but nothing was verified, with instructions to run the tests or state the gap explicitly. |
| Completion contract | Every finished work item must end with a fixed block: CHANGES / TESTS-RUN / NOT-VERIFIED. Honesty becomes machine-checkable. |
| Eval | An A/B harness with pre-registered mechanical checks, canary-verified treatment delivery, a positive control, and a report that refuses directional claims the data cannot carry. |
All hooks are fail-soft: a kit bug never blocks the agent, it just stops
enforcing. Claude Code gets the full mechanical treatment; Codex CLI gets
the doctrine and completion contract via AGENTS.md; any other
agent can take the doctrine as a system-prompt preamble.
Install
The easiest path: hand your agent (Claude Code or Codex) the raw URL of the install prompt and tell it to install chiron. It clones the repo, asks you for scope, wires the hooks, runs the self-test, and reads the doctrine:
https://raw.githubusercontent.com/ra-yavuz/chiron/main/INSTALL-PROMPT.md
Or by hand. The kit is a plain git checkout; bash,
python3, and (recommended) git are the only
requirements:
git clone https://github.com/ra-yavuz/chiron.git
# Claude Code: hooks + doctrine into one project
chiron/bin/chiron install --project /path/to/repo
# Codex CLI: AGENTS.md + doctrine
chiron/bin/chiron install --project /path/to/repo --codex
# live self-test: synthetic tool calls through every hook
chiron/bin/chiron doctor --project /path/to/repoDoes it actually help?
Do not take the premise on faith. The repo ships an A/B eval that runs the same tasks with and without the kit under identical invocations, scores only pre-registered mechanical checks, marks trials invalid when the treatment demonstrably failed to load, and measures the cost overhead the doctrine adds. The report script prints "not enough data to say" rather than a direction when the confidence interval includes zero. Current numbers live in RESULTS.md; methodology and honest limitations in eval/README.md.