crag

One governance.md. Any project. Generated in 250 ms.

Point crag at an existing codebase. It reads the filesystem, detects your stack, parses your CI, and writes a 30-line governance file that compiles to GitHub Actions, git hooks, and config for nine AI coding agents.

npx @whitehatd/crag analyze            # Generate governance.md from an existing project
npx @whitehatd/crag compile --target all  # Turn it into CI + 12 downstream configs

Zero dependencies. Node 18+. Validated across 20 OSS projects.

What it does

crag turns project-specific configuration work into a single file.

• You write: a 20–30 line governance.md describing your quality gates, branch strategy, and security rules.
• crag generates: GitHub Actions workflow, husky hooks, pre-commit config, and configuration for AGENTS.md (Codex/Aider/Factory), Cursor, Gemini, Copilot, Cline, Continue, Windsurf, Zed, and Sourcegraph Cody — from that one file.
• crag discovers: runtimes, frameworks, linters, test runners, CI systems, and monorepo layouts — at session time, from the filesystem. Nothing to hardcode.

The result is a single source of truth for your rules that stays in lock-step with your CI pipeline, your pre-commit hooks, and every AI tool your team uses.

Validation on real repos

Unlike most tools in this space, crag ships with a reproducible cross-repo benchmark. crag analyze --dry-run was run against 20 diverse open-source projects:

Repos tested: expressjs/express, chalk/chalk, fastify/fastify, axios/axios, prettier/prettier, vitejs/vite, psf/requests, pallets/flask, pallets/click, tiangolo/fastapi, BurntSushi/ripgrep, clap-rs/clap, rust-lang/mdBook, tokio-rs/axum, spf13/cobra, gin-gonic/gin, charmbracelet/bubbletea, spring-projects/spring-petclinic, sinatra/sinatra (Ruby), slimphp/Slim (PHP).

Full methodology, grading rubric, per-repo results, and raw outputs: benchmarks/results.md.

Quick start

# Use via npx (no install)
npx @whitehatd/crag analyze
npx @whitehatd/crag compile --target all

# Or install globally
npm install -g @whitehatd/crag
crag analyze
crag compile --target all

Requirements: Node.js 18+. Git. (Claude Code CLI is only needed for the interactive crag init flow.)

How it works

crag separates two things that every other tool in this space conflates:

┌────────────────────────────────────────────────────────────────┐
│  DISCOVERY  (ships with crag — universal, same for any repo)   │
│                                                                │
│  Reads the filesystem at runtime. Detects languages, frame-    │
│  works, CI systems, workspace layout, linters, test runners.   │
│                                                                │
│  Never hardcoded. Never goes stale. Add a service, switch      │
│  frameworks, change CI — discovery adapts automatically.       │
└───────────────────────────┬────────────────────────────────────┘
                            │
                            ▼
┌────────────────────────────────────────────────────────────────┐
│  GOVERNANCE  (your governance.md — project-specific)           │
│                                                                │
│  20-30 lines of YOUR rules: quality gates, branch strategy,    │
│  security requirements, deployment policy.                     │
│                                                                │
│  Human-controlled. Version-pinned. Changes only when you do.   │
└───────────────────────────┬────────────────────────────────────┘
                            │
                            ▼
┌────────────────────────────────────────────────────────────────┐
│  COMPILE  (crag compile --target all)                          │
│                                                                │
│  One governance.md → 12 outputs                                │
│                                                                │
│    CI / hooks:     GitHub Actions · husky · pre-commit         │
│    AI (native):    AGENTS.md · Cursor · Gemini                 │
│    AI (extras):    Copilot · Cline · Continue · Windsurf ·     │
│                    Zed · Sourcegraph Cody                      │
└────────────────────────────────────────────────────────────────┘

Change one line in governance.md, re-run crag compile --target all, and 12 downstream configs regenerate. Every AI tool on your team — plus your CI pipeline and pre-commit hooks — stays in sync from a single source.

What crag detects

Languages and runtimes

CI systems

crag analyze parses run: / script: / command: steps from nine CI systems and feeds them through a normalizer that dedupes matrix expansions, filters background processes, and strips shell plumbing:

GitHub Actions · GitLab CI · CircleCI · Travis CI · Azure Pipelines · Buildkite · Drone · Woodpecker · Bitbucket Pipelines

Task runners

Real target mining — not placeholders. Canonical test/lint/build targets extracted from:

• Makefile (.PHONY directives + column-0 targets)
• Taskfile.yml (tasks: sub-keys)
• justfile (recipe names)

Workspaces

Eleven workspace types, enumerated at discovery time:

pnpm · npm/yarn · Cargo · Go · Gradle · Maven · Nx · Turborepo · Bazel · git submodules · independent nested repos

Frameworks

Detected from manifest dependencies (runtime deps only — no false positives from dev fixtures):

Web: Next.js · React · Vue · Svelte · SvelteKit · Nuxt · Astro · Solid · Qwik · Remix · Express · Fastify · Koa · Hono · NestJS · Phoenix Backend: Rails · Sinatra · Hanami · Laravel · Symfony · Slim · Yii · CakePHP

Documentation mining

CONTRIBUTING.md and .github/PULL_REQUEST_TEMPLATE.md are scanned for gate candidates in code fences and inline backticks — advisory-only, capped at 5, gated by canonical-verb filter.

Commands

crag analyze                     # Generate .claude/governance.md from filesystem
crag analyze --dry-run           # Print what would be generated, don't write
crag analyze --workspace         # Analyze root + every workspace member
crag analyze --merge             # Preserve existing governance, append inferred sections

crag init                        # Interactive interview (needs Claude Code CLI)

crag compile --target <name>     # Compile governance to a single target
crag compile --target all        # Compile to all 12 targets at once
crag compile                     # List available targets

crag diff                        # Compare governance against codebase reality
crag upgrade                     # Update universal skills to latest version
crag upgrade --check             # Dry-run: show what would change
crag check                       # Verify Claude Code infrastructure is in place
crag workspace                   # Inspect detected workspace
crag workspace --json            # Machine-readable workspace report

crag version / crag help

The governance file

The only file you maintain. 20–30 lines. Everything else is universal or generated.

# Governance — StructuAI

## Identity
- Project: StructuAI
- Description: AI-powered Minecraft schematic describer

## Gates (run in order, stop on failure)
### Frontend (path: frontend/)
- npx eslint frontend/ --max-warnings 0
- cd frontend && npx vite build

### Backend
- node --check scripts/api-server.js
- cargo clippy --manifest-path source/decode/Cargo.toml
- cargo test --manifest-path source/decode/Cargo.toml

### Infrastructure
- docker compose config --quiet

## Branch Strategy
- Trunk-based, conventional commits
- Auto-commit after gates pass

## Security
- Schematic file uploads only (validate server-side)
- No hardcoded secrets or API keys

Annotations (all optional):

• ### Section (path: subdir/) — run this section's gates from subdir/
• ### Section (if: config.json) — skip if file doesn't exist
• - command # [OPTIONAL] — warn but don't fail
• - command # [ADVISORY] — log only, never block
• ## Gates (inherit: root) — merge with root governance (monorepo)

Compile targets (12 outputs)

The compiler detects runtime versions from your project (package.json engines.node, pyproject.toml requires-python, go.mod directive, Gradle toolchain). All writes are atomic — partial failures leave the old state intact.

Workspaces

crag workspace              # Human-readable
crag workspace --json       # Machine-readable

crag analyze --workspace    # Analyze every member and emit per-member gates

Detected types: pnpm · npm/yarn · cargo · go · gradle · maven · nx · turbo · bazel · git-submodules · independent-repos.

Test-fixture directories (playground/, fixtures/, examples/, demos/, __fixtures__/) are excluded from per-member enumeration so monorepos like Vite don't generate 79 sections for their playground directories.

Multi-level governance is supported: root governance sets cross-cutting rules (branch strategy, security), member governance adds stack-specific gates via ## Gates (inherit: root).

The session loop (Claude Code)

Once crag is set up in a Claude Code project, each session is:

/pre-start-context       → Discovers project, loads governance, caches runtimes
   ↓
   your task
   ↓
/post-start-validation   → Runs gates, auto-fixes lint/format, commits

/pre-start-context classifies task intent, uses a content-hashed discovery cache to skip ~80% of redundant scans on unchanged code, and reads governance.md fresh every session so the rules are always current.

/post-start-validation runs gates in the order declared in governance.md, stops on [MANDATORY] failure, retries mechanical errors (lint, format) up to twice with auto-fix, runs a security review, and creates a conventional-commit commit when everything passes.

Installation and requirements

npm install -g @whitehatd/crag
# or
npx @whitehatd/crag <command>

• Node.js 18+ — uses built-in https, crypto, fs, child_process. No runtime dependencies.
• Git — for branch strategy inference and the discovery cache.
• Claude Code CLI — only needed for the interactive crag init flow. analyze, compile, diff, upgrade, workspace, check all run standalone.

The package is published under @whitehatd/crag but the binary name is plain crag after install.

Release pipeline

Every push to master runs the full CI matrix (Ubuntu / macOS / Windows × Node 18 / 20 / 22) and, if tests pass, auto-bumps the patch version and publishes to npm with SLSA provenance attestation. Tags are created automatically. GitHub releases are generated from CHANGELOG.md.

To skip a release on a specific push, put crag:skip-release on its own line in the commit body.

Design principles

1. Discover, don't hardcode. Every fact about the codebase is read at runtime. Skills never say "22 controllers" — they say "read the controller directory." They never go stale because there is nothing to go stale.

2. Govern, don't hope. Your quality bar lives in governance.md. Skills enforce it but never modify it. It changes only when you change it.

3. Ship the engine, generate the config. Universal skills ship once and work for every project. governance.md is generated per project. The engine works forever. The config is 20 lines.

4. Enforce, don't instruct. Hooks are 100% reliable at zero token cost. Prose rules in context files are ~80% compliant. Critical behavior (destructive-command blocks, gate enforcement) goes in hooks.

Honest status

• Published: 2026-04-04 as @whitehatd/crag on npm. Scoped public package.
• Tests: 323 unit tests, passing on Ubuntu/macOS/Windows × Node 18/20/22.
• Benchmark: 17/20 grade A, 0/20 grade C across the 20 reference repos. Reproducible via benchmarks/results.md.
• Languages fully supported: Node, Deno, Bun, Python, Rust, Go, Java, Kotlin, Ruby, PHP, .NET, Swift, Elixir (+ Terraform/Helm/K8s infra gates).
• CI systems parsed: 9 (GitHub Actions, GitLab CI, CircleCI, Travis, Azure Pipelines, Buildkite, Drone, Woodpecker, Bitbucket).
• Compile targets: 12 (GitHub Actions, husky, pre-commit, AGENTS.md, Cursor, Gemini, Copilot, Cline, Continue, Windsurf, Zed, Cody).

Known limitations

• FastAPI and similar repos where CI runs via uv run ./scripts/*.py data-pipeline scripts: crag captures the script invocations as gates. A user reviewing the output should prune the ones that aren't quality checks.
• Complex CI matrix template expansions (clap's make test-${{matrix.features}} pattern): line-based extraction captures one variant per template; multi-line YAML join is not implemented yet.
• Jenkinsfile (Groovy): CI system is detected but step extraction is not attempted.
• No telemetry, no network calls beyond the optional crag upgrade --check npm registry ping (24h cached, 3s timeout, graceful offline).

What crag does not do

• It does not write or modify code in your repo.
• It does not call any LLM. Discovery, analysis, and compilation are pure filesystem operations.
• It does not replace your CI provider, your linters, or your test runners. It generates config for them.
• It does not gate-keep. You can add, remove, or edit any gate in governance.md at any time.

Why "crag"

A crag is a rocky outcrop — an unmoving landmark that stands while seasons, paths, and generations change around it. Your skills discover, your gates run, your CI regenerates — but governance.md, the crag, doesn't move until you say so. Your AI agents anchor to it.

Contributing

Issues and PRs welcome at github.com/WhitehatD/crag. See CONTRIBUTING.md for the workflow.

If you run crag on a repo and it misses something — a language, a CI system, a gate pattern — that's the bug report I want most. Include the URL of the repo and a paste of crag analyze --dry-run output.

License

MIT — see LICENSE.

Built by Alexandru Cioc (WhitehatD).