For developers running Claude Code on real repositories
Claude Code can build the feature. That doesn't mean the code is ready to ship.
It can work, pass the happy path, and still be wrong for your codebase — tangled into the wrong layer, missing tests, ignoring existing conventions, creating security problems, or leaving you with code that's painful to change later. Covenant is built to close that gap: from AI-generated working code to code you can actually put into production.
// the gap
The first version works.
The next question is whether you can live with it.
AI can give you a feature fast. Then come the things the happy path doesn't answer:
- Will the next developer understand it?
- Does it fit the rest of the repository?
- What did it break outside the demo?
- Did it duplicate something that already existed?
- Will the agent remember these decisions tomorrow?
That's the gap Covenant is built to close. Not between AI and code — between generated code and code you're comfortable shipping.
// one job
Stop spending five prompts finishing the first one.
You know the loop.
- "Build X."
- "No, use this instead."
- "That breaks Y."
- "Now add tests."
- "Don't put it there."
- "Why did you change that?"
Covenant starts by turning the job into something more complete before Claude begins touching the repository — what's being asked, what matters, what must not move, and how the result will be checked.
The goal isn't fewer prompts for the sake of fewer prompts. It's getting closer to the result you meant the first time.
- Recon — reads what's relevant. Nothing changes yet.
- Contract — scope, objective, constraints, and how it'll be checked, fixed before a line of code is written.
/prepbuilds one from a vague ask, if you'd rather not write it by hand. - Execute — writes and tests inside those boundaries. Stops and asks on anything that isn't its call — a new dependency, an auth change, a schema change.
- Verify — runs the check named in the contract and shows you the real output, not a status update.
// before the first rule
Your repository isn't generic. Its governance shouldn't be either.
Run /init-governance. Before it writes a single rule, Covenant studies what's
already there and shows you what it found. You correct the picture. Then it builds around the
repository you actually have — not a template.
What it shows you first
Stops and waits. Nothing past this point is written without your sign-off.
- Stack — real test/lint/build commands, read from your CI config, not guessed.
- Architecture as found — your real layers, your real dependency direction.
- Conventions as found — naming, error handling, test structure, as they are.
- Debt baseline — every existing finding, frozen — not fixed, just capped.
- CORE_FILES — the modules everything else depends on, flagged for stricter review.
// context
You shouldn't have to remind your coding agent what happened yesterday.
Or ten minutes ago. Repositories are bigger than one context window. Sessions end.
/clear happens. Decisions disappear. Covenant keeps track of the structure and the
work around a task, so the agent spends less time finding its way back to where it already was.
Session 01
- decision made
- commit
a1b2c3d
Session 02
- context restored
- repository state current
- task resumed
Less re-discovery. Less repeated context. Less "wait, what were we doing?"
// before it lands
The agent is done. Covenant still has questions.
CLAUDE.md and the execution contract shape what it tries to do. They don't decide
what's allowed to land. An agent can be talked out of a rule. It can't talk its way past an exit code.
- Claude Code hooks — agent-side, advisory. Watches it work; not the part anyone should trust.
- git hooks —
pre-commit/pre-pushrun the samecovenant.sha human commit gets. Locally bypassable with--no-verify— exactly why the next layer exists. - CI — re-runs everything regardless of what happened on the developer's machine. Un-bypassable once CODEOWNERS and branch protection are on — see what this doesn't solve.
Eight checks run at that boundary. The same eight, whoever wrote the diff — scoped to changed files, not the whole tree.
Protected branch
No direct commits to main, master, develop.
Secrets scan
Keyword, credential prefix, and PEM-header matching on the staged diff.
Layer boundary
No SQL in routes/services. No framework imports in the domain layer.
Lint · type · complexity
A debt ratchet grandfathers existing findings, blocks only new ones.
Tests + coverage
Opt-in at commit. Mandatory at push, in CI, and on architecture-critical files.
Token budget
Blocks an active agent session at 100%. Never blocks a human commit.
Receipts
A tree that already passed can skip re-checking at push.
Audited bypass
SKIP_COVENANT=1 demands a reason, logs it, opens a 24h clock.
Checks are scoped to changed files, and tests are opt-in at commit — mandatory only at push, in CI, or when an architecture-critical file is touched. That timing is from Covenant's own docs, not a marketing estimate.
| Branch check | < 0.1s |
|---|---|
| Secrets scan | < 0.5s |
| Layer boundary | < 0.2s |
| Lint | ~1–3s |
| Type check | ~1–3s |
| Complexity | < 1s |
| Tests (if run) | varies — opt-in at commit |
// your turn
You've seen the gap. Try closing it.
Pick a face. Claim a seat. We'll give you the setup for your machine on the other side.
Choose your avatar now!
// trust, briefly
The agent shouldn't be able to quietly change the rules that judge it.
Three independent locks stop it from trying: a deny-list its own tools refuse to write to, a guard that inspects command text before it runs, and a SHA-256 hash CI checks on every commit. The real anchor is a human one — CODEOWNERS and branch protection.
.claude/covenant_integrity.sha256
7 files, one hash — verified by CI on every commit
.githooks/covenant.sh.githooks/pre-commit.githooks/pre-push.githooks/verify_governance_integrity.sh.claude/hooks/pre_bash_trust_root_guard.sh.claude/hooks/graph_freshness_check.py.claude/checkpoint_tool.py
This has limits, and we'd rather tell you than have you find out.
Local hooks are bypassable.
A stripped .githooks/ or a plain --no-verify gets past the local covenant. CI, not the developer's machine, is the actual backstop.
The integrity manifest has no external anchor.
A single PR can edit covenant.sh and regenerate its own SHA-256 pin to match. Closing that needs CODEOWNERS and branch protection — a human step the installer cannot do for you.
The secrets scan is shape-based, not entropy-based.
It catches a keyword near a value, or a known prefix like sk_live_. An opaque token with no recognizable shape gets through. Run gitleaks or trufflehog alongside it.
Agent detection is a client-side signal.
$CLAUDECODE and process ancestry identify a cooperating agent. One that strips its own environment before running a command defeats both. Closes accidental detachment, not deliberate evasion.
The layer-boundary check is grep, not an import graph.
A re-export shim — a module that quietly imports the banned framework on your behalf — still gets through. Resolving that needs AST/import-graph analysis, not a regex.
The token budget is a deterrent, not a central control.
It lives in a local, per-machine file. A developer with shell access can raise their own ceiling. It stops a runaway loop — it isn't SOC 2 CC6.6 on its own.
| macOS / Linux | Windows | |
|---|---|---|
| Mechanical enforcement | ✓ | ✓ |
/init-governance | ✓ | ✓ |
| Trust-root lockdown | ✓ | ✓ |
| Debt ratchet (brownfield) | ✓ | ✓ |
| Bypass audit trail | ✓ | ✓ |
| CI backstop | ✓ | ✓ |
| Test depth | 158 bats tests / 30 files | 27 pytest tests |
CovenantMac needs WSL2 if you want covenant.sh itself on Windows — CovenantWin is the native path, a separate Python/PowerShell implementation at governance-generation parity.