Covenant

Covenant turns the rules you give a coding agent ("don't change public APIs, don't delete user data, run tests before committing") into checks that actually run, and enforces them while the agent works, in git, and in CI.

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).

sh install.sh                          # or on Windows: powershell -File install.ps1  (pipx, from GitHub)
cd your-repo
covenant compile "Update dependencies, but don't change public APIs, don't delete user data, and run tests before committing."
covenant init                          # git hooks + Claude Code hooks, then start enforcing

Or start from a ready-made rule set: covenant compile --pack hotfix "fix the login crash" (covenant packs lists them). covenant suggest proposes rules from what went wrong in the repo's own history.

How it works

1. Compile (covenant compile): Claude, or the offline extractor with --offline, splits the instruction into a goal and clauses. Claude is reached through ANTHROPIC_API_KEY if it is set, and otherwise through your Claude Code login (claude -p), so a Claude subscription is enough (--backend api|claude-code to choose). Deterministic passes then:

   • ground each clause in the repo: the real exports, data folders, tables and test command;
   • bind it to a checker;
   • ask at most three questions about specific things in the repo;
   • check the result statically.

   You approve the resulting covenant.yaml. To add a rule mid-task (covenant amend "also don't touch config/"), the new rules apply from then on and the task's history is kept.

2. Enforce locally: hooks turn what the agent does into events. Checkers judge them, and a violation goes back to the agent as a report naming the rule, the evidence and a fix.

3. Enforce in CI (covenant ci / the GitHub Action): every pull request is judged against the Covenant from its base commit.

Checkers

A rule with no checker ("keep the code readable") becomes an llm_review rule when Claude is available: Claude reads each commit's change against it, and its findings go to the agent and to you as warnings that never block. With --offline or --no-review the rule is kept and marked unenforceable, never silently dropped.

Rules the compiler understands

command_guard categories: force_push, history_rewrite, branch_delete, discard_changes, sudo, pipe_to_shell, recursive_delete, install_packages, publish, deploy, network, read_secrets, database_cli, kill_processes, system_changes, destructive_sql, plus your own patterns. It guards against mistakes and shortcuts; an agent determined to hide a command (by writing it into a script first) needs the sandbox.

• Destructive SQL (Postgres, MySQL, SQLite, SQL Server, DuckDB, MongoDB, Redis): Covenant reads the SQL itself, inline (psql -c, mysql -e, piped in), in .sql files fed to a client, and in database MCP tool calls. DROP, TRUNCATE, ALTER TABLE ... DROP, and DELETE or UPDATE without a WHERE are refused; a DELETE ... WHERE is fine.
• Network allowlist: with allow_hosts, only those hosts (and their subdomains) can be reached, by commands, git push/pull (the remote's host), package installs (their registry) and the WebFetch tool. A network command whose destination can't be worked out is refused.
• Path ownership: an agent says who it is with COVENANT_AGENT=payments claude; edits to folders it doesn't own are refused, and so is a commit that changes them.
• Budgets: checked before each action. Cost is estimated from the token counts in Claude Code's session log at Anthropic's API prices (on a subscription nothing is charged per token, but it is still a fair measure of how much work was done).

Rule packs

covenant compile --pack NAME adds a ready-made rule set to your instruction. Packs always compile offline, so a pack means the same rules everywhere.

Rules over the agent's steps

A step is one recorded action: an edit, a command, a test run, a commit or a push.

The operators:

• S (since), Y (previous step), O (at some step so far) and H (at every step so far);
• bounded forms of these, O[<=n], H[<=n] and a S[<=n] b / a S[>=n] b, which count steps back;
• #a <= n (also <, >=, >, ==), which counts how often a has happened.

A limit counts every commit or push this task, including ones later undone with git reset.

Agents

Claude Code: covenant init (or covenant install-claude) adds hooks to .claude/settings.json:

The hook fails closed: if it crashes before a tool call, the call is denied.

Hooks are fast: each one starts a tiny client that uses only Python's standard library and hands the event to a background covenant daemon for the repo, which keeps Covenant loaded. That takes about 0.2 s per agent action on Windows instead of about 1 s. When no daemon answers, the client runs the full check itself and starts one, so a missing daemon never skips a check. The daemon listens on 127.0.0.1 only, exits after 30 idle minutes, and restarts when Covenant is upgraded. covenant init --no-fast-hooks starts a fresh Python for every hook instead.

A test run counts when it runs the whole suite and its exit status is visible. Extra flags that only change output or speed (-x, -v, -p no:cacheprovider, --cov, -n auto, 2>&1) are fine. A run that picks some tests (a path, -k, -m, --lf) or pipes its output doesn't count, and the agent is told why right away.

Cursor, Codex and other MCP clients: covenant --repo <path> mcp is an MCP server with covenant_rules, covenant_run_tests, covenant_record_edit, covenant_preflight, covenant_check, covenant_check_command and covenant_explain. MCP only works when the agent chooses to call it, so the git hooks (and CI) are what enforce commits and pushes for these agents.

// .cursor/mcp.json
{ "mcpServers": { "covenant": { "command": "covenant", "args": ["--repo", ".", "mcp"] } } }

# ~/.codex/config.toml
[mcp_servers.covenant]
command = "covenant"
args = ["--repo", "/path/to/repo", "mcp"]

Team policies

A repo's covenant.yaml can list extends: [policies/team.yaml]. Policy files hold clauses in the same format and can extend each other. COVENANT_POLICY (paths separated by your OS's path separator) applies policies to every repo on a machine.

A policy can also live at an https address, such as a raw file in an org-wide repo: extends: ["https://example.com/team.yaml#sha256=<hash>"]. The #sha256= pin is optional; with it, a policy that changes without the pin being updated is an error. The last good copy is kept in ~/.covenant/policies/ and used when the network is down.

Policy rules:

• are merged in first, with an origin naming their policy;
• can't be redefined by a repo: an id clash is an error;
• are protected from the agent like Covenant's own files;
• in CI, come from the base commit, and a PR that changes them is flagged.

Dashboard

covenant dashboard opens a page on 127.0.0.1:8765 covering every repo Covenant enforces on this machine:

• each repo's rules, with how close each is to handing over to a human;
• a timeline of blocks and reports;
• recent events and protected paths;
• an editor for the rules: write a rule in plain English and Claude drafts it, check the result, then save and approve. Added rules apply from now on, like covenant amend; changing or removing a rule restarts the task, after asking;
• a replay of any task, this one or one of the last 30: step through everything the agent did and every decision Covenant made, with why each rule fired and how to fix it.

It refreshes every few seconds and rejects requests whose Host header isn't localhost. Changes need a key created at start: the browser gets it in the part of the address after #, which is never sent over the network, and the page removes it from the address bar. Requests from other web pages are refused. --read-only turns editing off.

Undo, explain, alerts

• Undo snapshots: before a risky step (rm, mv, git reset/checkout/clean, sed -i, redirects, formatters, rewriting a whole file), Covenant records the working tree, untracked files included, as a git commit under refs/covenant/snapshots/. Your branch, index and stash aren't touched, and the refs are never pushed. covenant snapshots lists them and covenant undo [ID] restores one. An undo first snapshots the current state, so it can be undone too. COVENANT_SNAPSHOTS=0 turns them off.
• covenant explain: what was blocked, why, what the agent can do and what you can do, in plain words (-n 3 for the last three).
• Alerts: a Slack message, a webhook call or an email when an agent needs a human (and optionally whenever it is blocked). Set COVENANT_SLACK_WEBHOOK, COVENANT_ALERT_WEBHOOK or COVENANT_ALERT_EMAIL, or write ~/.covenant/alerts.yaml (see src/covenant/alerts.py). covenant alerts test sends a test message. The same problem alerts at most once every 10 minutes.
• covenant suggest: reads the repo's history for reverted changes, removed secrets, deleted tests, debug code cleaned up later, restored APIs and rolled-back upgrades, and proposes rules with the evidence. --github also reads recent PR review comments.

Sandbox

covenant sandbox runs the agent in Docker, in three containers on a private network with no route to the internet:

• agent: your repo and Claude Code (or any command after --);
• hooks: covenant serve, holding the task's state in a volume the agent can't see;
• proxy: the only way out, and only to api.anthropic.com, the hosts in your allow_hosts rules and --allow hosts. Everything else gets a 403.

So an agent that dodges a command rule (say, by writing the command into a script) still can't reach a host that isn't allowed, or touch Covenant's state. covenant sandbox --print writes the files and shows the docker compose commands without running them. One limit: the hook token is in the agent's settings, so a determined agent could post made-up hook events. The server still checks commits, pushes and diffs itself, but a made-up "tests passed" would count; run covenant test from outside when that matters.

Hook server

covenant serve --install runs Covenant as a long-lived local server.

• Claude Code uses HTTP hooks to reach it at /hook.
• Git hooks call it with curl, and refuse the commit if it's unreachable.

State and snapshots then live with the server instead of wherever the agent runs, which is the building block for running agents in a container. Requests need a bearer token created at start; that keeps other local processes out, but not an agent that can read the hook settings.

VS Code

vscode-extension/ adds a Covenant panel, the current violations in Problems, a 🔒 badge on protected files, and commands to compile rules, approve them and run tests. It updates live as an agent's hooks record events. Its checks never change files. Build it with npm run package and install the .vsix (see vscode-extension/README.md).

CI

# .github/workflows/covenant.yml
on: pull_request
permissions:
  contents: read
  pull-requests: write          # for the comments
jobs:
  covenant:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: visweshdev/Covenant@main
        # with: { comment: "false", run-tests: "false", agent: payments }

The action comments on the exact lines that break a rule (once; re-runs don't repeat a comment) and keeps one summary comment on the PR up to date. Problems with no changed line to point at, like a deleted protected file, go in the summary. Without the action: covenant ci --format github --comment does the same with GITHUB_TOKEN set.

How the CI check judges a pull request:

• The rules come from the base commit, so a PR can't weaken them; a PR that changes covenant.yaml is flagged for human review.
• API and migration checkers compare against the base.
• Protected files are checked against the diff.
• Test commands run on the PR's final state.

Commands

Exit codes: 0 clean, 1 violations (the agent should revise), 2 needs a human, 3 bad setup.

Compiling with Claude reads ANTHROPIC_API_KEY, or uses your Claude Code login when it isn't set. If ANTHROPIC_BASE_URL points somewhere other than Anthropic (agent CLIs and proxies often export it), compile warns you; set COVENANT_ANTHROPIC_BASE_URL=https://api.anthropic.com to override it for Covenant only.

Safety model

• State lives outside the repo, in ~/.covenant/workspaces/<repo>-<hash> (set COVENANT_HOME to move it). A file lock keeps parallel hooks from corrupting it.
• The approved Covenant is pinned when a session starts. If covenant.yaml, the git hooks or the Claude settings change, it's reported as an INTEGRITY violation, and so is disableAllHooks or core.hooksPath.
• A verifier that can't run blocks rather than passes.

Limits. Outside the sandbox, Covenant runs as your user. An agent with a shell could still edit its state folder directly. That gets detected, but it isn't prevented; covenant sandbox prevents it. Effects are found by comparing hashes on every event, not by kernel events. SQLite databases are compared row by row; for other databases, Covenant sees the SQL the agent runs (commands, .sql files, database tools) and migrations, but not queries the app makes on its own.

Development

pip install -e ".[dev]"
npm install --prefix /tmp/ts typescript@5.6.3   # for the TypeScript checker tests
COVENANT_TYPESCRIPT=/tmp/ts/node_modules/typescript python -m pytest -q

Layout of src/covenant/:

• ir.py: the rule format;
• policy.py: team policies;
• runtime.py, monitors/ and verifiers/: enforcement;
• compiler/;
• integrations/: Claude Code and MCP;
• ci.py, server.py, dashboard.py and cli.py;
• bench/: CovenantBench.

The worked example from the proposal is in examples/mylib. The benchmark tasks are in bench/tasks/, and the VS Code extension is in vscode-extension/.

Not built yet

• The sandbox hasn't run in Docker yet: its compose file, images and allowlist proxy are built and tested (the proxy for real, over sockets), but this project's development machine has no Docker, so the three containers haven't been started together.
• Live database proxy: row-level rollback of SQL as it runs against Postgres or MySQL, including queries the app makes on its own. Destructive SQL the agent runs is already refused (destructive_sql), and SQLite is guarded row by row. It needs a database server to test against.
• A real-repo CovenantBench: the harness, metrics and six synthetic tasks exist. The proposal's 60–200 tasks from real repos, using commits after the models' training cutoff and with annotated ground truth, are curation work.
• Publishing: .github/workflows/release.yml publishes to PyPI and the VS Code Marketplace on a v* tag, once the PyPI trusted publisher and the VSCE_PAT secret are set up.

Contributing and license

See CONTRIBUTING.md for setup and tests, and SECURITY.md to report a way around Covenant. Covenant is released under the MIT License.