crag

Make every AI agent obey your codebase.

One governance.md -> compiled to CI, hooks, and every agent. No drift.

npx @whitehatd/crag

AGENTS.md | Claude Code | Cursor | Copilot | Gemini | Cline | Continue | Windsurf | Zed | Amazon Q | GitHub Actions | Forgejo Actions | Husky | Pre-commit | Aider | Goose | Junie | Kiro | CodeRabbit | GitLab CI | CircleCI | Azure DevOps | Lefthook

The problem

Your CI is the ground truth for what quality means in your repo. Your AI agents don't know it. When you add a lint gate in GitHub Actions, your Cursor rules don't update. Your CLAUDE.md doesn't update. 23 tool-specific files -- all drifting apart.

Developers fix bad AI suggestions in 2 seconds and think "AI is dumb sometimes." They never aggregate the cost: 30 seconds per bad suggestion x 10 devs x 50 prompts per day = hours of wasted time. Nobody diffs their config files.

The fix

crag reads your CI and codebase once, writes a single governance.md, and compiles it to every tool's native format. One file in. 23 files out. Change a rule once, recompile, done.

Deterministic. No LLM. No network. No API keys. Zero dependencies.

Install

# Global install
npm install -g @whitehatd/crag

# Or run directly
npx @whitehatd/crag

Requires Node.js 18+ and git.

Quick start

# 1. See it live on a temp project (~3 seconds)
crag demo

# 2. Analyze your repo -- generates governance.md
crag analyze

# 3. Compile to all AI tools and CI
crag compile --target all

# 4. Check for drift
crag audit

# 5. Auto-fix drift
crag audit --fix

# 6. Install pre-commit hook to keep configs in sync
crag hook install

Or do it all in one shot:

crag              # analyze + compile + audit
crag auto         # full pipeline: analyze, compile, audit, hook install

Commands

Command	Description
`crag`	Default: analyze + compile + audit in one shot
`crag analyze`	Read CI, package manifests, code patterns. Write `governance.md`
`crag analyze --write-governance`	Generate `governance.md` from scratch. Add `--force` to overwrite existing.
`crag compile --target <t>`	Compile governance.md to a specific target format
`crag compile --target all`	Compile to all 23 targets at once
`crag compile --target scaffold`	Generate hooks, settings, agents, CI playbook
`crag audit`	Detect drift between governance.md and compiled configs
`crag audit --json`	Machine-readable drift report
`crag audit --explain`	Show actionable fix hint per drift finding
`crag audit --fix`	Auto-recompile stale targets
`crag auto`	Full pipeline: analyze, compile, audit, hook install
`crag check`	Verify crag infrastructure is complete and current
`crag demo`	Self-contained proof-of-value on a temp project
`crag diff`	Show exactly where governance and codebase diverge
`crag doctor`	Deep diagnostic: integrity, drift, hook validity
`crag hook install`	Install pre-commit hook (auto-recompile on governance change)
`crag hook install --drift-gate`	Also block commits if drift is detected
`crag init`	Interactive setup for new projects
`crag login`	Authenticate with crag cloud
`crag sync`	Sync governance to crag cloud
`crag team`	Manage team governance (create, invite, join)
`crag upgrade`	Update universal skills in this repo
`crag upgrade --siblings`	Update all repos in the parent directory at once
`crag workspace`	Detect and display monorepo/workspace structure

Compile targets

crag compile --target all generates configs for 23 targets:

Target	Output file	Consumer
`github`	`.github/workflows/gates.yml`	GitHub Actions
`forgejo`	`.forgejo/workflows/gates.yml`	Forgejo / Gitea Actions
`husky`	`.husky/pre-commit`	Husky pre-commit hooks
`pre-commit`	`.pre-commit-config.yaml`	pre-commit.com
`agents-md`	`AGENTS.md`	Codex, Aider, Factory (60K+ repos)
`cursor`	`.cursor/rules/governance.mdc`	Cursor
`gemini`	`GEMINI.md`	Gemini, Gemini CLI
`copilot`	`.github/copilot-instructions.md`	GitHub Copilot
`cline`	`.clinerules`	Cline
`continue`	`.continuerules`	Continue.dev
`windsurf`	`.windsurf/rules/governance.md`	Windsurf Cascade
`zed`	`.rules`	Zed
`amazonq`	`.amazonq/rules/governance.md`	Amazon Q Developer
`claude`	`CLAUDE.md`	Claude Code
`aider`	`CONVENTIONS.md`	Aider
`lefthook`	`lefthook.yml`	Lefthook
`gitlab`	`.gitlab-ci.yml`	GitLab CI
`coderabbit`	`.coderabbit.yaml`	CodeRabbit
`junie`	`.junie/guidelines.md`	Junie
`kiro`	`.kiro/steering/quality-gates.md`	Kiro
`circleci`	`.circleci/config.yml`	CircleCI
`azuredevops`	`azure-pipelines.yml`	Azure DevOps
`goose`	`.goose/GOOSEHINTS`	Goose

Each target uses the tool's native format: MDC frontmatter for Cursor, YAML triggers for Windsurf, numbered steps for AGENTS.md, path-scoped files for monorepos.

The scaffold meta-target generates hooks, editor settings, agent configurations, and CI playbooks.

Audit system

crag audit detects drift across three axes:

Axis	What it catches
Stale configs	Compiled configs older than governance.md
Phantom gates	Governance references tools that don't exist (e.g., "run eslint" but eslint isn't installed)
Missing targets	AI tool directories exist (`.cursor/`, `.github/copilot-instructions.md`) but no compiled config

$ crag audit

  crag audit -- governance drift report

  Compiled configs
  X .cursor/rules/governance.mdc     stale -- governance.md is newer
  X AGENTS.md                        stale -- governance.md is newer
  OK .github/workflows/gates.yml     in sync
  OK .husky/pre-commit               in sync

  Gate reality
  X npx tsc --noEmit                 tsc not in devDependencies
  X npm run lint                     "lint" script not in package.json

  2 stale, 2 drift
  Fix: crag compile --target all

JSON output

crag audit --json

Returns:

{
  "summary": { "stale": 2, "drift": 2, "extra": 0, "missing": 1, "total": 5 },
  "stale": [{ "path": ".cursor/rules/governance.mdc", "target": "cursor" }],
  "drift": [{ "command": "npx tsc --noEmit", "detail": "tsc not in devDependencies" }],
  "extra": [],
  "missing": [{ "tool": "Copilot", "target": "copilot" }],
  "current": ["github", "husky"],
  "unmanagedCI": []
}

Auto-fix

crag audit --fix    # recompiles all stale targets

GitHub Action

Add drift detection to your CI with crag-audit-action:

# .github/workflows/crag-audit.yml
name: crag audit
on: [pull_request]
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: WhitehatD/crag-audit-action@v1

The action runs crag audit on every PR and posts a comment with the drift report. Optional fail-on-drift: true blocks merging when drift is detected.

Web audit tool

Audit any public GitHub repo at crag.sh/audit. Paste a repo URL, get a drift report in seconds. No install required.

Connect GitHub to also audit private repos.

Benchmark: 99 repos audited

We audited 100 of the most popular open-source repos (1 clone timeout). 20+ languages. Multiple CI systems. Monorepos to single-file libraries.

Metric	Result
Repos audited	99
Zero AI config files	54 (55%)
AI config adoption	45 (45%)
Repos with genuine drift	13 (13%)
Total gates inferred	3,540
Mean gates per repo	35.8
Crashes	0

Top repos by gate count:

Repo	Stack	Gates	Score
grafana/grafana	React + TypeScript + Docker	65	88
astral-sh/ruff	Rust + Python + Docker	53	88
astral-sh/uv	Rust + Python + Docker	52	88
calcom/cal.com	TypeScript + Docker	52	85
rollup/rollup	TypeScript + Node	50	68
vercel/turborepo	TypeScript + Rust	49	46

Full results: benchmarks/leaderboard.md | Live leaderboard

Previous benchmark (50 repos): benchmarks/phase1-benchmark.md

How it works

Analyze. Reads your repo with 25+ language detectors, 12 CI system extractors, and 8 framework convention engines. Writes governance.md with gates, architecture, testing profile, code style, and anti-patterns. Under a second, zero config. Use --write-governance to generate a governance.md from scratch (guarded by --force if one already exists).

Compile. Converts governance.md to each tool's native format. MDC frontmatter for Cursor. YAML triggers for Windsurf. Numbered steps for AGENTS.md. Path-scoped files for monorepos. Custom content survives recompilation.

Audit. Three detection axes: staleness (compiled configs older than governance.md), reality (governance references tools that don't exist), completeness (AI tool directories present but no compiled config). Run with --explain to see actionable fix hints inline.

Diff. Shows where governance and codebase diverge: gates in governance missing from CI, gates in CI missing from governance, and which files caused the discrepancy.

Doctor. Deep diagnostic that verifies governance integrity, hook installation, compile target presence, and latent drift that audit might miss.

Hook. Pre-commit hook auto-recompiles when governance.md changes. Optional drift gate blocks commits if configs are stale.

Universal skills

AI agents forget context between sessions. Two skills ship with crag to fix this:

Skill	What it does
`pre-start-context`	Loads full project context at session start: stack, architecture, governance rules, prior session state. Every agent starts informed.
`post-start-validation`	Runs governance gates after any task, captures decisions as searchable knowledge, writes session state for continuity.

crag compile --target scaffold    # install into .claude/skills/
crag upgrade --siblings           # update across all repos

The skills read governance.md and adapt. Nothing hardcoded. Works with Claude Code, Cursor Agent, Copilot Chat, any IDE with agent support.

Verification

Metric	Result
99-repo benchmark	99 repos, 0 crashes, 3,540 gates, 55% zero AI config
50-repo benchmark	50 repos, 0 crashes, 1,809 gates
Stress test	101 repos, 4,400 invocations, 0 crashes
Reference benchmark	40/40 Grade A across 7 language families
Determinism	SHA-verified, byte-identical across Ubuntu + macOS + Windows
Tests	598 passing
Dependencies	0

Ecosystem

Surface	URL
Website	crag.sh
Web Audit	crag.sh/audit
Leaderboard	crag.sh/leaderboard
Dashboard	app.crag.sh
API	api.crag.sh
VS Code	Marketplace
Neovim	crag.nvim
GitHub Action	crag-audit-action
npm	@whitehatd/crag
Status	crag.sh/status

Contributing

Issues and PRs at github.com/WhitehatD/crag.

If crag analyze misses a language, CI system, or gate pattern on a public repo, file an issue with the repo URL and crag analyze --dry-run output. That's the most valuable bug report.

MIT -- Alexandru Cioc (WhitehatD)

Name		Name	Last commit message	Last commit date
Latest commit History 246 Commits
.amazonq/rules		.amazonq/rules
.github		.github
.windsurf/rules		.windsurf/rules
assets		assets
benchmarks		benchmarks
bin		bin
docs		docs
scripts		scripts
src		src
test		test
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.rules		.rules
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
package.json		package.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

crag

The problem

The fix

Install

Quick start

Commands

Compile targets

Audit system

JSON output

Auto-fix

GitHub Action

Web audit tool

Benchmark: 99 repos audited

How it works

Universal skills

Verification

Ecosystem

Contributing

About

Uh oh!

Releases 101

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

crag

The problem

The fix

Install

Quick start

Commands

Compile targets

Audit system

JSON output

Auto-fix

GitHub Action

Web audit tool

Benchmark: 99 repos audited

How it works

Universal skills

Verification

Ecosystem

Contributing

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 101

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages