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 · Husky · Pre-commit

1. Analyze your repo → extract real CI + rules
2. Compile governance → all tools & agents
3. Audit drift → keep everything in sync

A deterministic engine that enforces your real CI gates across every AI agent. Zero dependencies. No LLM. No network. No API keys.

crag.sh · Docs · Dashboard · VS Code · Neovim · Status

What happens when you run it

crag analyze reads your project — CI workflows, package manifests, configs, directory structure, code patterns — and writes a governance.md that captures what a senior engineer would write after spending a week with your codebase:

## Gates (run in order, stop on failure)
### Lint
- npm run lint
### Test
- npm run test
### Build
- npm run build
- npm run typecheck

## Architecture
- Type: monolith
- Entry: bin/app.js

## Key Directories
- `src/` — source
- `test/` — tests (unit + integration)
- `prisma/` — database

## Testing
- Framework: vitest
- Naming: *.test.ts

## Code Style
- Indent: 2 spaces
- Formatter: prettier
- Linter: eslint

## Anti-Patterns
Do not:
- Use `any` in TypeScript — use `unknown`
- Use `getServerSideProps` with App Router — use Server Components

Then crag compile --target all takes that single file and generates configs for every AI tool your team uses — in each tool's native format, with the right frontmatter, activation patterns, and structure:

One file in, thirteen files out. Change a rule, recompile, done.

Then it watches your back

$ crag audit

  crag audit — governance drift report

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

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

  2 stale · 2 drift
  Fix: crag compile --target all — or — crag audit --fix

Install the pre-commit hook and it auto-recompiles on every commit:

crag hook install              # auto-recompile when governance changes
crag hook install --drift-gate # also block commits if drift detected

50 repos. Zero crashes. 46% had drift.

We cloned 50 of the highest-profile open-source projects and ran the full crag pipeline on each one. 20 languages. 7 CI systems. Monorepos to single-crate Rust libraries.

1,809 gates inferred across 50 repos. 46% had audit drift — governance rules that don't match codebase reality. Full results: benchmarks/phase1-benchmark.md

Get started

# One command — analyze + compile in one shot
npx @whitehatd/crag

# Or step by step:
npx @whitehatd/crag analyze                   # generate governance.md
npx @whitehatd/crag compile --target all       # compile to 13 targets
npx @whitehatd/crag compile --target scaffold  # generate hooks, settings, agents
npx @whitehatd/crag audit                      # check for drift
npx @whitehatd/crag hook install               # enforce on every commit

Requirements: Node.js 18+ and git. Zero runtime dependencies.

How it works

Analyze. Reads your repo: 25+ language detectors, 11 CI system extractors, 8 framework convention engines. Writes governance.md with gates, architecture, testing profile, code style, anti-patterns, and framework conventions. Under a second, zero config.

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

Audit. Three detection axes: (1) compiled configs older than governance.md, (2) governance references tools that don't exist, (3) AI tool directories present but no compiled config. Reports drift, suggests fixes.

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

Deterministic: same input produces byte-identical output. No LLM. No network. No API keys.

Proof

Further reading

• docs/commands.md — every subcommand, every flag, every exit code
• docs/compile-targets.md — the 13 compile targets and their formats
• docs/governance-format.md — the governance.md v2 format
• docs/languages.md — the 25+ stack detectors
• docs/ci-systems.md — the 11 CI extractors
• docs/workspaces.md — monorepo and workspace support

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)