cagr

cagr checks what a coding agent does (its commands, edits, stops and pull requests) and makes it run and obey your linters.

Coding agents slip. They run npm install in a bun repo, push to main, edit .env, skip hooks with --no-verify, and stop while the type check is still red. cagr watches what the agent does and stops each slip at the earliest moment it can see it. Every block message says what to do instead, so the agent fixes it on the next try.

• Commands: it denies the wrong package manager, a push to the protected branch, a force push, hook skips, and any command you list, before the command runs.
• Files: it denies edits to protected files such as .env* and lockfiles, before the edit happens.
• Lint suppressions: the lint-suppression guard blocks new eslint-disable, @ts-ignore, # noqa and other suppression directives after edits and in CI. The recommended preset also protects lint config files. Fix the cause, or ask a person to review an exception.
• Changes: cagr’s own change rules check companion changes, immutable existing files, and tests for new files at turn end and in CI.
• Edits: after each edit it runs your formatters and linters (Biome, ESLint, Ruff) and your own ast-grep code rules, on the changed files only. Layout rules stop a new file from being created with the wrong name or in the wrong folder.
• End of turn: the agent may not finish while your checks (tsc, mypy, pytest, bun run lint) fail. It blocks at most 2 stops in a row, then lets the agent go and tells the human, so it never traps the agent in a loop.
• Pull requests: gh pr create is denied until a reviewer agent in a fresh context has reviewed the current commit and every Important finding is fixed or answered. Agents may not merge or approve. See Review.
• Git: the commit-msg and pre-push hooks check commit subjects, branch names and pushes to main. They cover any agent, and any human, even without agent hooks.

cagr does not replace your tools. It runs them at the right moment and shows the agent only what matters: findings in the files it changed, deduped and cut short.

It works with Claude Code and Codex today, and through the git hooks with every other agent.

How it differs from a linter

A linter checks code. cagr checks what a coding agent does (its commands, edits, stops and pull requests) and makes it run and obey your linters. Most agent slips (npm install in a bun repo, a push to main, --no-verify, an edit to .env, stopping while tsc is red) leave nothing in the code for a linter to find. Where a linter does help, cagr runs it at the moment the agent can act on it: on the changed file right after the edit, and again before the agent may finish. It also differs from pre-commit hooks (too late, and skippable), CI (minutes later, in a log the agent may not read) and AGENTS.md (advice the agent can forget). How cagr differs has the full comparison.

Docs

The full docs are at krtinshet.github.io/cagr, and in docs/:

• How cagr differs: from linters, pre-commit hooks, CI, AGENTS.md, review bots and sandboxes.
• Getting started: install, cagr init, cagr doctor.
• Configuration: every key in cagr.toml.
• Guards: every built-in guard and its message.
• Hooks and events, Change rules, Code rules, Review, CI.
• CLI reference, Limits and troubleshooting and Releasing.

Quick start

curl -fsSL https://github.com/krtinshet/cagr/releases/latest/download/install.sh | sh
# or: bun add -d @krtinshet/cagr    /    npm i -D @krtinshet/cagr

cd your-repo
cagr init      # detects your stacks, writes cagr.toml and the hook files
cagr doctor    # checks the wiring, the tools, and how long each hook takes

init writes cagr.toml, .claude/settings.json, .codex/hooks.json and .githooks/, then sets core.hooksPath. Commit all of them. Codex asks you to trust project hooks once: open Codex in the repo and approve them with /hooks.

Config

cagr.toml, or [tool.cagr] in pyproject.toml:

extends = ["recommended"]
[git]
protected_branch = "main"
branch_name = "type/name"
commit_message = "conventional"
pre_push = "bun run verify"
[[stack]]
language = "typescript"
package_manager = "bun"
paths = ["**"]
on_edit = ["biome check --write {files}"]
on_turn_end = ["bun run lint", "bunx tsc --noEmit"]
[[stack]]
language = "python"
package_manager = "uv"
paths = ["services/ml/**"]
on_edit = ["ruff check --fix {files}", "ruff format {files}"]
on_turn_end = ["pytest -q services/ml"]
[files]
protected = [{ glob = ".env*", except = [".env.example"], reason = "Tell the user which key is missing." }]
[commands]
blocked = [{ match = "prisma db push", reason = "Use `bun run db:migrate --name <change>`." }]

• recommended turns on the git rules, blocks force pushes, hook skips and new lint suppressions, and protects .env*, lockfiles and lint configs. Lists of tables (stack, files.protected, commands.blocked) add to the preset's. Other values replace them.
• {files} becomes the changed files that match the stack's paths. A turn-end command without {files} runs once for the whole repo.
• After you change the config, run cagr sync to rewrite the hook files. cagr sync --check fails in CI when they drift.
• schema/cagr.schema.json is the JSON schema, for editor completion.

This is the beginning of the README. Read the rest at the original. Read the full README ↗