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:

Target	Output	Consumer
agents-md	AGENTS.md	Codex, Aider, Factory (60K+ repos)
cursor	.cursor/rules/governance.mdc	Cursor
copilot	.github/copilot-instructions.md	GitHub Copilot
gemini	GEMINI.md	Gemini, Gemini CLI
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
github	.github/workflows/gates.yml	GitHub Actions
husky	.husky/pre-commit	husky
claude	CLAUDE.md	Claude Code
pre-commit	.pre-commit-config.yaml	pre-commit.com

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.

Repo	Stack	Gates	Finding
grafana/grafana	Go + React + Docker	67	Clean
calcom/cal.com	Next.js + React + Docker	53	Clean
hashicorp/vault	Go + Docker + Node	50	Clean
biomejs/biome	Rust + React + TS	47	Clean
excalidraw/excalidraw	TypeScript + Docker	46	2 drift
moby/moby	Go + Docker	45	Clean
vuejs/core	TypeScript	44	2 drift
tauri-apps/tauri	Rust + TypeScript	44	Clean
supabase/supabase	TS + React + Docker	43	1 drift
apache/airflow	Python + Docker	41	Clean
prisma/prisma	TypeScript	40	2 drift
django/django	Python	38	Clean
angular/angular	TypeScript	38	1 drift
remix-run/remix	TypeScript	37	1 drift
dotnet/aspnetcore	.NET + TypeScript	37	1 drift
pandas-dev/pandas	Python + C	35	Clean

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

Metric	Result
Phase 1 benchmark	50 repos · 0 crashes · 1,809 gates · 46% drift
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	589 passing
Dependencies	0

---

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

Surface	URL	What it does
Website	crag.sh	Landing page, docs, status
Dashboard	app.crag.sh	Cloud sync, team governance, audit history
API	api.crag.sh	REST API for governance sync
VS Code	Marketplace	Sidebar, CodeLens, auto-recompile, diagnostics
Neovim	crag.nvim	Commands, statusline, diagnostics, auto-compile
npm	@whitehatd/crag	CLI package

---

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)