{"id":48330923,"url":"https://github.com/whitehatd/crag","last_synced_at":"2026-04-17T04:01:15.944Z","repository":{"id":349244562,"uuid":"1197860288","full_name":"WhitehatD/crag","owner":"WhitehatD","description":"The bedrock layer for AI coding agents. One governance.md. Any project. Never stale. Universal skills + cross-agent compilation (Claude, Cursor, Codex, Gemini, Aider).","archived":false,"fork":false,"pushed_at":"2026-04-15T00:30:00.000Z","size":5561,"stargazers_count":26,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-15T02:35:23.772Z","etag":null,"topics":["agent-governance","ai-agents","ai-coding","aider","claude-code","codex","crag","cursor","developer-tools","gemini-cli","meta-framework","monorepo","self-improving","workflow-automation"],"latest_commit_sha":null,"homepage":"https://github.com/WhitehatD/crag","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WhitehatD.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":"docs/governance-format.md","roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-01T00:24:38.000Z","updated_at":"2026-04-15T00:29:28.000Z","dependencies_parsed_at":"2026-04-06T02:00:33.359Z","dependency_job_id":null,"html_url":"https://github.com/WhitehatD/crag","commit_stats":null,"previous_names":["whitehatd/crag"],"tags_count":84,"template":false,"template_full_name":null,"purl":"pkg:github/WhitehatD/crag","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WhitehatD%2Fcrag","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WhitehatD%2Fcrag/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WhitehatD%2Fcrag/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WhitehatD%2Fcrag/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WhitehatD","download_url":"https://codeload.github.com/WhitehatD/crag/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WhitehatD%2Fcrag/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31914458,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T18:22:33.417Z","status":"online","status_checked_at":"2026-04-17T02:00:06.879Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-governance","ai-agents","ai-coding","aider","claude-code","codex","crag","cursor","developer-tools","gemini-cli","meta-framework","monorepo","self-improving","workflow-automation"],"created_at":"2026-04-05T01:03:28.594Z","updated_at":"2026-04-17T04:01:15.938Z","avatar_url":"https://github.com/WhitehatD.png","language":"JavaScript","readme":"# crag\n\n**Make every AI agent obey your codebase.**\n\nOne `governance.md` -\u003e compiled to CI, hooks, and every agent. No drift.\n\n```bash\nnpx @whitehatd/crag\n```\n\n\u003e AGENTS.md | Claude Code | Cursor | Copilot | Gemini | Cline | Continue | Windsurf | Zed | Amazon Q | GitHub Actions | Forgejo Actions | Husky | Pre-commit\n\n![crag on django/django -- zero config to 38 gates in 390ms](https://raw.githubusercontent.com/WhitehatD/crag/master/assets/poster-demo.gif)\n\n[![npm version](https://img.shields.io/npm/v/%40whitehatd%2Fcrag?color=%23e8bb3a\u0026label=npm\u0026logo=npm)](https://www.npmjs.com/package/@whitehatd/crag)\n[![Test](https://github.com/WhitehatD/crag/actions/workflows/test.yml/badge.svg)](https://github.com/WhitehatD/crag/actions/workflows/test.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)\n[![Node](https://img.shields.io/node/v/%40whitehatd%2Fcrag)](https://nodejs.org)\n[![Zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](./package.json)\n[![99 repos audited](https://img.shields.io/badge/benchmark-99%20repos%20%C2%B7%200%20crashes-brightgreen)](./benchmarks/leaderboard.md)\n[![55% zero AI config](https://img.shields.io/badge/audit-55%25%20zero%20AI%20config%20in%2099%20repos-orange)](./benchmarks/leaderboard.md)\n\n**[crag.sh](https://crag.sh)** | [Audit Tool](https://crag.sh/audit) | [Leaderboard](https://crag.sh/leaderboard) | [Dashboard](https://app.crag.sh) | [Docs](https://crag.sh/docs) | [VS Code](https://marketplace.visualstudio.com/items?itemName=whitehatd.vscode-crag) | [Neovim](https://github.com/WhitehatD/crag.nvim) | [Status](https://crag.sh/status)\n\n---\n\n## The problem\n\nYour 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.\n\nDevelopers 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.\n\n## The fix\n\ncrag 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.\n\nDeterministic. No LLM. No network. No API keys. Zero dependencies.\n\n---\n\n## Install\n\n```bash\n# Global install\nnpm install -g @whitehatd/crag\n\n# Or run directly\nnpx @whitehatd/crag\n```\n\nRequires Node.js 18+ and `git`.\n\n---\n\n## Quick start\n\n```bash\n# 1. See it live on a temp project (~3 seconds)\ncrag demo\n\n# 2. Analyze your repo -- generates governance.md\ncrag analyze\n\n# 3. Compile to all AI tools and CI\ncrag compile --target all\n\n# 4. Check for drift\ncrag audit\n\n# 5. Auto-fix drift\ncrag audit --fix\n\n# 6. Install pre-commit hook to keep configs in sync\ncrag hook install\n```\n\nOr do it all in one shot:\n\n```bash\ncrag              # analyze + compile + audit\ncrag auto         # full pipeline: analyze, compile, audit, hook install\n```\n\n---\n\n## Commands\n\n| Command | Description |\n|---|---|\n| `crag` | Default: analyze + compile + audit in one shot |\n| `crag analyze` | Read CI, package manifests, code patterns. Write `governance.md` |\n| `crag compile --target \u003ct\u003e` | Compile governance.md to a specific target format |\n| `crag compile --target all` | Compile to all 14 targets at once |\n| `crag compile --target scaffold` | Generate hooks, settings, agents, CI playbook |\n| `crag audit` | Detect drift between governance.md and compiled configs |\n| `crag audit --json` | Machine-readable drift report |\n| `crag audit --fix` | Auto-recompile stale targets |\n| `crag auto` | Full pipeline: analyze, compile, audit, hook install |\n| `crag check` | Verify crag infrastructure is complete and current |\n| `crag demo` | Self-contained proof-of-value on a temp project |\n| `crag diff` | Show exactly where governance and codebase diverge |\n| `crag doctor` | Deep diagnostic: integrity, drift, hook validity |\n| `crag hook install` | Install pre-commit hook (auto-recompile on governance change) |\n| `crag hook install --drift-gate` | Also block commits if drift is detected |\n| `crag init` | Interactive setup for new projects |\n| `crag login` | Authenticate with crag cloud |\n| `crag sync` | Sync governance to crag cloud |\n| `crag team` | Manage team governance (create, invite, join) |\n| `crag upgrade` | Update universal skills in this repo |\n| `crag upgrade --siblings` | Update all repos in the parent directory at once |\n| `crag workspace` | Detect and display monorepo/workspace structure |\n\n---\n\n## Compile targets\n\n`crag compile --target all` generates configs for 14 targets:\n\n| Target | Output file | Consumer |\n|---|---|---|\n| `github` | `.github/workflows/gates.yml` | GitHub Actions |\n| `forgejo` | `.forgejo/workflows/gates.yml` | Forgejo / Gitea Actions |\n| `husky` | `.husky/pre-commit` | Husky pre-commit hooks |\n| `pre-commit` | `.pre-commit-config.yaml` | pre-commit.com |\n| `agents-md` | `AGENTS.md` | Codex, Aider, Factory (60K+ repos) |\n| `cursor` | `.cursor/rules/governance.mdc` | Cursor |\n| `gemini` | `GEMINI.md` | Gemini, Gemini CLI |\n| `copilot` | `.github/copilot-instructions.md` | GitHub Copilot |\n| `cline` | `.clinerules` | Cline |\n| `continue` | `.continuerules` | Continue.dev |\n| `windsurf` | `.windsurf/rules/governance.md` | Windsurf Cascade |\n| `zed` | `.rules` | Zed |\n| `amazonq` | `.amazonq/rules/governance.md` | Amazon Q Developer |\n| `claude` | `CLAUDE.md` | Claude Code |\n\nEach 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.\n\nThe `scaffold` meta-target generates hooks, editor settings, agent configurations, and CI playbooks.\n\n---\n\n## Audit system\n\n`crag audit` detects drift across three axes:\n\n| Axis | What it catches |\n|---|---|\n| **Stale configs** | Compiled configs older than governance.md |\n| **Phantom gates** | Governance references tools that don't exist (e.g., \"run eslint\" but eslint isn't installed) |\n| **Missing targets** | AI tool directories exist (`.cursor/`, `.github/copilot-instructions.md`) but no compiled config |\n\n```bash\n$ crag audit\n\n  crag audit -- governance drift report\n\n  Compiled configs\n  X .cursor/rules/governance.mdc     stale -- governance.md is newer\n  X AGENTS.md                        stale -- governance.md is newer\n  OK .github/workflows/gates.yml     in sync\n  OK .husky/pre-commit               in sync\n\n  Gate reality\n  X npx tsc --noEmit                 tsc not in devDependencies\n  X npm run lint                     \"lint\" script not in package.json\n\n  2 stale, 2 drift\n  Fix: crag compile --target all\n```\n\n### JSON output\n\n```bash\ncrag audit --json\n```\n\nReturns:\n\n```json\n{\n  \"summary\": { \"stale\": 2, \"drift\": 2, \"extra\": 0, \"missing\": 1, \"total\": 5 },\n  \"stale\": [{ \"path\": \".cursor/rules/governance.mdc\", \"target\": \"cursor\" }],\n  \"drift\": [{ \"command\": \"npx tsc --noEmit\", \"detail\": \"tsc not in devDependencies\" }],\n  \"extra\": [],\n  \"missing\": [{ \"tool\": \"Copilot\", \"target\": \"copilot\" }],\n  \"current\": [\"github\", \"husky\"],\n  \"unmanagedCI\": []\n}\n```\n\n### Auto-fix\n\n```bash\ncrag audit --fix    # recompiles all stale targets\n```\n\n---\n\n## GitHub Action\n\nAdd drift detection to your CI with [crag-audit-action](https://github.com/WhitehatD/crag-audit-action):\n\n```yaml\n# .github/workflows/crag-audit.yml\nname: crag audit\non: [pull_request]\njobs:\n  audit:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: WhitehatD/crag-audit-action@v1\n```\n\nThe 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.\n\n---\n\n## Web audit tool\n\nAudit any public GitHub repo at [crag.sh/audit](https://crag.sh/audit). Paste a repo URL, get a drift report in seconds. No install required.\n\nConnect GitHub to also audit private repos.\n\n---\n\n## Benchmark: 99 repos audited\n\nWe audited 100 of the most popular open-source repos (1 clone timeout). 20+ languages. Multiple CI systems. Monorepos to single-file libraries.\n\n| Metric | Result |\n|---|---|\n| Repos audited | 99 |\n| Zero AI config files | 54 (55%) |\n| AI config adoption | 45 (45%) |\n| Repos with genuine drift | 13 (13%) |\n| Total gates inferred | 3,540 |\n| Mean gates per repo | 35.8 |\n| Crashes | 0 |\n\nTop repos by gate count:\n\n| Repo | Stack | Gates | Score |\n|---|---|---|---|\n| grafana/grafana | React + TypeScript + Docker | 65 | 88 |\n| astral-sh/ruff | Rust + Python + Docker | 53 | 88 |\n| astral-sh/uv | Rust + Python + Docker | 52 | 88 |\n| calcom/cal.com | TypeScript + Docker | 52 | 85 |\n| rollup/rollup | TypeScript + Node | 50 | 68 |\n| vercel/turborepo | TypeScript + Rust | 49 | 46 |\n\nFull results: [`benchmarks/leaderboard.md`](./benchmarks/leaderboard.md) | [Live leaderboard](https://crag.sh/leaderboard)\n\nPrevious benchmark (50 repos): [`benchmarks/phase1-benchmark.md`](./benchmarks/phase1-benchmark.md)\n\n---\n\n## How it works\n\n**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.\n\n**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.\n\n**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).\n\n**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.\n\n**Doctor.** Deep diagnostic that verifies governance integrity, hook installation, compile target presence, and latent drift that `audit` might miss.\n\n**Hook.** Pre-commit hook auto-recompiles when governance.md changes. Optional drift gate blocks commits if configs are stale.\n\n---\n\n## Universal skills\n\nAI agents forget context between sessions. Two skills ship with crag to fix this:\n\n| Skill | What it does |\n|---|---|\n| `pre-start-context` | Loads full project context at session start: stack, architecture, governance rules, prior session state. Every agent starts informed. |\n| `post-start-validation` | Runs governance gates after any task, captures decisions as searchable knowledge, writes session state for continuity. |\n\n```bash\ncrag compile --target scaffold    # install into .claude/skills/\ncrag upgrade --siblings           # update across all repos\n```\n\nThe skills read `governance.md` and adapt. Nothing hardcoded. Works with Claude Code, Cursor Agent, Copilot Chat, any IDE with agent support.\n\n---\n\n## Verification\n\n| Metric | Result |\n|---|---|\n| 99-repo benchmark | [99 repos, 0 crashes, 3,540 gates, 55% zero AI config](./benchmarks/leaderboard.md) |\n| 50-repo benchmark | [50 repos, 0 crashes, 1,809 gates](./benchmarks/phase1-benchmark.md) |\n| Stress test | [101 repos, 4,400 invocations, 0 crashes](./benchmarks/stress-test.md) |\n| Reference benchmark | [40/40 Grade A](./benchmarks/results.md) across 7 language families |\n| Determinism | SHA-verified, byte-identical across Ubuntu + macOS + Windows |\n| Tests | 598 passing |\n| Dependencies | 0 |\n\n---\n\n## Ecosystem\n\n| Surface | URL |\n|---|---|\n| Website | [crag.sh](https://crag.sh) |\n| Web Audit | [crag.sh/audit](https://crag.sh/audit) |\n| Leaderboard | [crag.sh/leaderboard](https://crag.sh/leaderboard) |\n| Dashboard | [app.crag.sh](https://app.crag.sh) |\n| API | [api.crag.sh](https://api.crag.sh/api/status) |\n| VS Code | [Marketplace](https://marketplace.visualstudio.com/items?itemName=whitehatd.vscode-crag) |\n| Neovim | [crag.nvim](https://github.com/WhitehatD/crag.nvim) |\n| GitHub Action | [crag-audit-action](https://github.com/WhitehatD/crag-audit-action) |\n| npm | [@whitehatd/crag](https://www.npmjs.com/package/@whitehatd/crag) |\n| Status | [crag.sh/status](https://crag.sh/status) |\n\n---\n\n## Contributing\n\nIssues and PRs at [github.com/WhitehatD/crag](https://github.com/WhitehatD/crag).\n\nIf `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.\n\n---\n\nMIT -- [Alexandru Cioc (WhitehatD)](https://github.com/WhitehatD)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwhitehatd%2Fcrag","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwhitehatd%2Fcrag","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwhitehatd%2Fcrag/lists"}