covenant-agents 0.1.2

Quick start  ·  How it works  ·  Rules  ·  Docs  ·  Changelog

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.

It checks outcomes, not tool calls: the API surface after the edits, what happened to protected files however they were touched, and the order of events (tests passed after the last edit, before the commit).

Quick start

pipx install covenant-agents        # or: pip install covenant-agents

cd your-repo
covenant compile "Don't change public APIs, don't delete user data, run tests before committing."
covenant init        # installs git + Claude Code hooks and starts enforcing

That's it. Works on Windows, macOS and Linux with Python 3.11+. The getting started guide walks through what happens next.

💡 Tip: start from a ready-made rule set with covenant compile --pack hotfix "fix the login crash" (covenant packs lists them), or let covenant suggest propose rules from what went wrong in your repo's own history.

How it works

When something breaks a rule, the agent gets the rule, the evidence and a fix, and you can ask for the story any time:

$ covenant explain
At 01:23 on 01 Nov, the agent tried to use a tool. Covenant blocked it.

Rule C3: "never run destructive SQL"
  Why: The command counts as SQL that drops a table, database or schema: psql -c "DROP TABLE users".
  What the agent can do: Don't drop, truncate or wipe tables; change rows with a WHERE, or ask the human

What it can enforce

Say it in plain English; Covenant picks the checker.

Every checker, phrase and rule pack →

Works with

Set up each agent →   CI and the GitHub Action →

Tried on real repos

Claude Code ran live under Covenant on TinyDB, itsdangerous, humanize and prettytable, each with an honest task and a trap task. Every honest task committed; every trap was refused or blocked.

Covenant also replayed 1,446 real commits from 50 popular repositories (Python, TypeScript, Go, Rust and Java) through its CI check. It flagged 75; on review, 72 were real breaks of the rules (removed APIs, new dependencies, deleted tests) and 2 were false alarms.

Benchmark and trial notes →

Also included

Dashboard, undo, alerts and policies →

Documentation

Contributing

Bug reports, new checkers and benchmark tasks are welcome. See CONTRIBUTING.md, and SECURITY.md to report a way around Covenant privately.

_{Made for agents that mean well. Released under the MIT License.}