Skip to content
← ALL PROJECTS
012026

Covenant

PLAIN ENGLISH → RULES → CHECKS → ENFORCED

PythonClaude Code hooksMCPGit hooksGitHub ActionsDocker
SOURCE CODE ↗

COVENANT.YAML

  • “don't change public APIs”→ api_surface
  • “never force push”→ refused
  • “run tests before committing”→ step_order

$ covenant explain

psql -c "DROP TABLE users"
✕ BLOCKED · rule C3
never run destructive SQL

VIOLATIONS / TASK

1.17 → 0

task success 100%

ON PYPI

outcomes, not tool calls

THE IDEA

You tell an agent "don't change public APIs, don't delete user data, run tests before committing." It usually listens. Covenant makes sure it does — by checking outcomes rather than tool calls: the API surface after the edits, what happened to protected files however they were touched, and whether the tests passed after the last edit and before the commit.

THE PIPELINE

  1. PLAIN-ENGLISH RULES
  2. COMPILEgrounded in the repo → covenant.yaml
  3. AGENT WORKSClaude Code · Cursor · Codex · any MCP client
  4. CHECK OUTCOMESAPI surface · protected files · order of events
  5. BLOCK + EXPLAINrule · evidence · fix

THE SYSTEM

  • Its compiler reads plain-English rules, grounds them in the repo, and binds each one to a checker in covenant.yaml.
  • Checkers cover public APIs in Python, TypeScript, Go, Rust and Java; protected files and SQLite rows (restored from a snapshot if lost); destructive migrations; dependency changes; folder scope; secrets and skipped tests; change size; and the order and count of the agent's steps.
  • Risky commands — force pushes, deploys, destructive SQL and more, 16 categories — are refused before they run, with a network allowlist and time, action and cost budgets.
  • Enforced through Claude Code hooks, an MCP server for Cursor, Codex and others, git pre-commit and pre-push hooks, a GitHub Action that judges each PR by its base commit's rules, a VS Code panel, and a Docker sandbox.
  • When a rule is broken, the agent gets the rule, the evidence and a fix; its explain command tells the story, and its undo command restores the working tree from a restore point.

THE PROCESS

  • Benchmarked on CovenantBench, plus live trials with Claude Code on four real open-source repos (TinyDB, itsdangerous, humanize, prettytable) — each with an honest task and a trap task.
  • Published on PyPI as covenant-agents, with tests in CI, on Windows, macOS and Linux.

THE RESULT

Violations per task fell from 1.17 to 0 on CovenantBench with task success unchanged at 100%. On the four real repos every honest task committed and every trap was refused or blocked — at about 0.2 seconds per agent action.

rules that hold