Keel MCP server

keel

An observable autonomy harness for AI coding agents. — by TokenDrift

keel is an MCP server that gives your coding agent (Claude Code, Cline, …) the tools to run a long task end to end — without drifting, cheating, or losing its work — while recording everything it does so you can steer on cost and quality.

You start the task. The agent disciplines itself. You come back to a milestone report.

The name: a keel is the part of a boat you never see — the spine under the waterline that stops it from being blown sideways by the wind. That's the job.

The problem

An agent left alone on a long task tends to do four things you can't see until it's too late:

• It loses the thread. Context gets compacted, earlier decisions are forgotten, work is redone or contradicted.
• It cheats. Faced with "make the tests pass," an agent will quietly edit the tests themselves — reward hacking. The suite goes green; nothing actually works.
• It loses files. An overwrite, a bad refactor, an hour of work gone with no checkpoint.
• It's a black box on cost. You have no idea what the run cost you, which model burned the budget, or whether the agent looped twenty times on one step.

keel puts a tool on each of these, and the agent calls them itself — because the rules are injected into its CLAUDE.md at init. Every call emits an event, so the whole run is legible afterward.

keel in action

A real run on a throwaway calc-kit project — the agent was told to implement add(a, b) so the locked tests pass, following the keel protocol. This is the actual sequence, unedited:

1.  load_context      → project loaded, tests intact
2.  record_decision   → "add = a + b, minimal, no deps" logged
3.  (writes calc.py)
4.  save_progress     → state persisted
5.  verify            → green: 2 passed, tampered: false
6.  checkpoint        → commit fac81a4 — milestone CERTIFIED
7.  check_drift       → no drift
8.  log_usage         → sonnet, 4000/1200 tok → $0.03
9.  route_task        → (sensitive) recommends EU-hosted model;
                        US + CN clouds excluded
10. stats             → 1 verify / 100% pass, 1 certified milestone, 0 cheat alerts
11. report            → milestone report written to .keel/reports/

Then, to show the anti-cheat is real — we modified a locked test file by hand (simulating an agent tampering to force a green) and ran verify:

{
  "tampered": true,
  "tests_changed": ["~ tests/test_calc.py (modified)"],
  "passed": true
}

tampered: true and passed: true at the same time. keel doesn't confuse "the tests pass" with "the tests are intact" — it reports both axes separately. An agent can make the suite green by rigging it, and keel still sees it. That distinction is the whole point.

The anti-cheat: a proof regime, not a prison

The hard problem with any optional-tool harness: an agent can ignore verify and just run pytest in the terminal, short-circuiting the one mechanism that catches cheating. A polite instruction in CLAUDE.md shapes what the agent tries to do — it doesn't stop anything.

keel closes this with three layers, on the principle that no single layer is perfect but together no path is simultaneously easy, silent, and untraced:

1. Persuasion — the CLAUDE.md block tells the agent, in no uncertain terms, that verify is the only judge and direct test runs are forbidden. Handles the dominant case: an agent that drifts out of negligence, not malice.

Shortened. The full README is on GitHub.