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

crag.sh | Audit Tool | Leaderboard | Dashboard | Docs | VS Code | Neovim | Status

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

Compile targets

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

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:

$ 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: 87 repos, 99% have drift

We audited 87 of the most popular open-source repos. 20+ languages. Multiple CI systems. Monorepos to single-file libraries.

Top repos by gate count:

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.

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

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:

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

Ecosystem

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)