A crime scene investigator for your codebase.

Install

crimes is published on npm and requires Node.js 18 or newer.

# Global install
npm install -g crimes
crimes scan .

Or one-shot via npx:

npx crimes scan .

pnpm dlx crimes scan and bunx crimes scan also work. Homebrew lands after npm — see the roadmap.

Quick start

Nine commands cover everything crimes does today:

crimes scan .

crimes scan . --format json

crimes context src/billing/tax.ts --format json

crimes scan --changed --format json
crimes scan --changed --base main --format json
crimes scan --changed --fail-on high

crimes diff main...HEAD --format json
crimes diff origin/main...HEAD --format json

crimes baseline save
git add .crimes/baseline.json && git commit -m "Add crimes baseline"
crimes baseline check --fail-on medium

crimes verdict --base origin/main --format json
crimes verdict --base origin/main --fail-on new-high

crimes triage
crimes triage --list
crimes triage --retriage src/billing.ts

crimes hotspots --since 90d --format json

Built for agents

The wedge isn't "better linter". It's local, open-source, agent-native codebase risk and context. crimes ships two on-disk artefacts that AI coding agents pick up automatically — there is nothing to install into a prompt.

Recommended loop

1. Before editing a specific file — crimes context <file> --format json. Read every high severity finding first. Under Claude Code with the 0.11.1 PreToolUse hook installed, this fires automatically on every Edit / Write / NotebookEdit.
2. Triage findings interactively — crimes triage walks each finding top-of-rank first, asking for a disposition (fix-now / fix-this-PR / needs-design / wont-fix / scaffolding), one-line reason, and owner. Silenced entries resurface in scan when the file is touched on the branch.
3. After editing — re-scan only what you touched: crimes scan --changed --format json. Diff the findings against the pre-edit run.
4. Before opening the PR — crimes verdict --base origin/main --fail-on new-high for the one-line "did this branch help or hurt?" answer, with a hard gate on any new high finding.
5. Triaging the wider repo — crimes hotspots --format json ranks files by an aggregate of git churn and current findings.

Decision rule: any new severity: "high" finding introduced by your edit is a blocker — fix it, or surface it to the user citing the finding id and charge. Quote evidence[] back to the user when you explain a decision: it is deterministic AST or file-content data, not opinion.

CI

crimes is built for CI. Three deterministic gating modes — pick whichever fits the contract you want with your team. All three share the same exit-code shape: 0 success / no blocking findings, 1 a configured --fail-on threshold met, 2 a usage or environment error.

GitHub Actions — copy / paste

# .github/workflows/crimes.yml
name: crimes
on:
  pull_request:
  push:
    branches: [main]

jobs:
  crimes:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          # `verdict` resolves `origin/main` — fetch full history.
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - run: npm install -g crimes
      - run: crimes verdict --base origin/main --fail-on new-high

Full integration guide and Mode A / B swaps: docs/ci.md. Copy-paste workflow: examples/github-actions/crimes.yml.

Example output

Human report

CRIME SCENE REPORT
repo: messy-ts-app  ·  5 findings

HIGH severity (1)
  1. src/billing.ts:37-240 (generateInvoice)
     Charge: God Function
     Summary: generateInvoice spans 204 lines — past the 60-line
     threshold for a single function. Bodies this size usually mix
     unrelated responsibilities, and an agent editing one section
     often misses interactions in another.
     Evidence:
       · lines 37–240 (204 lines)
       · 3.4× the configured 60-line threshold
       · function declaration
     id=crime_00001  confidence=0.95

MEDIUM severity (3)
  1. src/billing.ts:44-260
     Charge: Temporal Recklessness
     Summary: 7 direct uses of Date.now()/new Date(). Reading the
     system clock in domain code makes behaviour non-deterministic
     and couples tests to wall time.
     ...

Total 5  ·  high 1  medium 3  low 1

JSON report (the contract)

{
  "schema_version": "0.2.0",
  "report_type": "scan",
  "repo": { "name": "messy-ts-app", "root": "/..." },
  "summary": { "total": 5, "high": 1, "medium": 3, "low": 1 },
  "findings": [
    {
      "id": "crime_00001",
      "type": "large_function",
      "charge": "God Function",
      "severity": "high",
      "confidence": 0.95,
      "file": "src/billing.ts",
      "symbol": "generateInvoice",
      "lines": [37, 240],
      "summary": "generateInvoice spans 204 lines — past the …",
      "evidence": [
        "lines 37–240 (204 lines)",
        "3.4× the configured 60-line threshold",
        "function declaration"
      ],
      "effort": "medium",
      "fix_shape": "extract orchestration; move pure helpers to a sibling module",
      "scores": {
        "severity": 0.9,
        "confidence": 0.95,
        "agent_risk": 0.95
      },
      "suggested_actions": [
        {
          "kind": "extract_function",
          "description": "Extract cohesive sections into named helpers …",
          "risk": "low"
        }
      ]
    }
  ]
}

schema_version is bumped on breaking changes, so agents can refuse to consume an unfamiliar shape. The "0.1.0" → "0.2.0" bump in 0.11.0 added two required Finding fields: effort (quick/small/medium/large) and fix_shape (a one-line description of the shape of the fix). Three docs back this contract up:

• docs/agent-usage.md — pre-edit / post-edit workflow, shipped vs deferred, exit-code behaviour
• docs/json-schema.md — every field of the wire format, required vs reserved
• docs/fixtures/messy-ts-app.json — the full pinned sample output, version-controlled

What it detects today

Structural detectors · shipped in v0.1.0

Information architecture detectors · new in v0.3.0

IA crimes surface deterministic evidence that the repo tells multiple competing stories about the same product concept — what something is called, where it lives, which implementation owns it. No LLM, no API key, no network. Every finding cites concrete files, lines, and string literals; cross-file findings populate related_files and render as an "Also touches:" block in the human report.

Example IA findings (from the bundled fixture)

# Concept Alias Drift
alias group: tenant
aliases found: account, organisation, team, workspace
"account" in 2 file(s): docs/billing.md, src/routes/account/subscription.tsx
"team" in 2 file(s): docs/teams.md, src/routes/team/index.tsx
"workspace" in 2 file(s): docs/teams.md, src/routes/workspace/members.tsx

# Route Metadata Drift
route path: /settings/billing
file: src/routes/settings/billing.tsx
component: PricingPage
metadata.title: Plans
<title>: Subscription
nav label in src/nav/registry.ts: Plans

# Duplicated Navigation Source
destination: /settings/billing
src/nav/registry.ts label: Plans
src/nav/sidebar.ts label: Billing

# Missing Agent Context
no AGENTS.md found at repo root
no CLAUDE.md found at repo root
no .claude/skills/*/SKILL.md present
package.json declares bin(s): messy — agents have no way to discover commands

# Docs-Code Drift
docs/teams.md:5 → ./setup.md (not found)

Built for humans and coding agents. IA findings phrase summaries as "appears to" / "may" — they are ambiguity signals, not claims of semantic truth. Long-form reference (quorum rules, false-positive notes, suggested fixes): docs/finding-types/ia.md.

Every finding includes evidence (raw facts the detector observed) and scores (severity, confidence, agent_risk). No verdicts without receipts.

FAQ

Short, direct answers to the questions that come up most often. Every answer is also encoded as FAQPage structured data, so AI assistants can quote them verbatim.