claude-crap

Deterministic Quality Assurance plugin for Claude Code. Forces the agent through mathematical hooks, CRAP / TDR thresholds, and SARIF 2.1.0 reports before a single line of code is allowed to ship.

claude-crap turns Claude Code into a disciplined QA engineer. It wraps every Write, Edit, and Bash call with a synchronous PreToolUse gatekeeper, a retrospective PostToolUse verifier, and a final Stop quality gate that refuses to close a task until maintainability, reliability, and security ratings pass policy.

Every decision that touches source code must be backed by a result from the deterministic MCP engines — compute_crap, compute_tdr, analyze_file_ast, ingest_sarif, score_project, and others. This is the Fat Platform / Thin Agent thesis: the LLM is an efficient worker, but the rails are mathematical and outside the model's reach.

CRAP stands for Change Risk Anti-Patterns — a metric originally developed by Alberto Savoia and Bob Evans at Google (2007). Read the original post.

Quick Start · Configuration · How It Works · MCP Tools · Documentation · Development · Contributing

Quick Start

npx claude-crap install

This downloads the package, compiles dist/ from source, creates .claude-crap/reports/ in your project, and prints the Claude Code command to register the plugin:

  Next steps — pick ONE of the following:

  1. Native install:
       /plugin install /.../claude-crap

  2. Marketplace install:
       /plugin marketplace add https://github.com/ahernandez-developer/claude-crap
       /plugin install claude-crap@herz

Once registered, open any new session. The SessionStart hook prints a briefing with thresholds and the dashboard URL. From that point the PreToolUse gatekeeper and Stop quality gate run automatically — no further setup required.

Configuration

Default: warn. No config file needed. The Stop gate shows all violations but lets tasks close. Teams that want hard enforcement can set "strict" in .claude-crap.json.

The strictness value controls how the Stop gate reacts to failures:

Override per workspace:

// .claude-crap.json — commit to git for team-wide policy
{
  "strictness": "strict"
}

Or per session: CLAUDE_CRAP_STRICTNESS=strict claude

Precedence: env var > .claude-crap.json > hardcoded warn.

See docs/quality-gate.md for the full CRAP formula, TDR formula, letter ratings, and adoption strategy.

How It Works

All findings are normalized to SARIF 2.1.0 — one vocabulary, exact coordinates, no grep walls in the context window.

See docs/architecture-overview.md for the boot sequence, data flow, and design decisions.

MCP Tools

Ten deterministic tools and two resources, all with strict JSON Schema validation.

Full schemas, inputs, outputs, and examples in docs/mcp-tools.md.

System Requirements

• Node.js >= 20 — the only runtime. No .NET, JDK, or Python.
• Bun >= 1.0 also works (bun run build, bun test).
• Claude Code with local plugin support.
• Zero native deps — WASM-backed tree-sitter, no C compiler needed.

Windows: requires a POSIX shell (Git Bash or WSL). See docs/contributing.md for Windows setup details.

Supported Languages & Scanners

AST analysis = tree-sitter cyclomatic complexity per function. LOC only = counted toward workspace metrics but no per-function analysis.

Monorepo auto-discovery

In monorepos, claude-crap automatically discovers sub-projects at session startup — no per-project configuration needed. The plugin probes npm workspaces and common directories (apps/, packages/, libs/, modules/, services/) to build a project map:

Session start
  → discover project map
  → detect sub-projects by type (TypeScript, Dart, C#, Python, etc.)
  → install missing scanners (ESLint auto-installed via npm)
  → run each scanner from its project directory
  → aggregate all findings into one SARIF store
  → score_project ready with real data

The project map is persisted to .claude-crap/projects.json and exposed via the list_projects MCP tool. Use score_project with the optional scope parameter to score a single sub-project:

// Score only one sub-project
score_project({ format: "both", scope: "frontend" })

See docs/supported-languages.md for detailed per-language setup and behavior.

File exclusions are centralized and cover all major frameworks out of the box: dist/, build/, bundle/, vendor/, .next, .nuxt, .astro, .svelte-kit, .dart_tool, .expo, .angular, .turbo, and more. Custom exclusions can be added via .claude-crap.json:

{
  "strictness": "strict",
  "exclude": ["apps/legacy/", "generated/", "*.proto.ts"]
}

Documentation

Development

npm install          # postinstall builds dist/ automatically
npm test             # 355 tests across 93 suites
npm run build:fast   # esbuild dev build (10-20x faster than tsc)
npm run doctor       # full diagnostic

Release via np: npm run release:patch / release:minor / release:major. prepublishOnly runs clean + build + test + audit automatically.

Full dev loop, test commands, and standalone MCP server instructions in docs/contributing.md.

Bug Reports

npx claude-crap bug-report    # writes claude-crap-bug-report-<ts>.md
npx claude-crap bug-report --stdout

Collects plugin version, Node/npm/platform info, doctor output, SARIF summary, and resolved env vars (secrets auto-redacted). Review the output, then open an issue at github.com/ahernandez-developer/claude-crap/issues.

Contributing

1. Fork and branch off main.
2. Write the test first — the Golden Rule forbids code before a safety net.
3. Run npm test — full suite must stay green.
4. Update CHANGELOG.md.
5. Open a PR in the rigid deduction format.

Full guide: docs/contributing.md.

License

MIT. See LICENSE. Copyright (c) 2026 Alan Hernandez.