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. See the installation plans in the roadmap.

Quick start

Start with these commands. The CLI reference lists all commands and options:

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 feedback <fingerprint> --verdict fp --note "…"
crimes feedback summary
crimes feedback recheck

crimes hotspots --since 90d --format json

Built for agents

Run crimes init --agents in your project to install the bundled Claude Code and Codex skills, a managed section in AGENTS.md, and the Claude Code edit hook. Normal CLI use checks for skill updates after an npm upgrade. See agent setup and updates for details.

Recommended loop

1. Before editing a specific file, run crimes context <file> --format json. Read every high severity finding first. Under Claude Code with the 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 what you touched: crimes scan --changed --format json. Diff the findings against the pre-edit run.
4. Before opening the PR, run 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. To review the wider repo, use 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, and check it against the code.

CI

Choose a gate for selected files, new findings against a baseline, or changes across a branch. All three use the same exit codes: 0 success / no blocking findings, 1 a configured --fail-on threshold met, 2 a usage or environment error.

GitHub Actions example

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

jobs:
  crimes:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          # Fetch full history so `verdict` can resolve `origin/main`.
          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 (bundled fixture, without Git history)

stale pins: 1 recorded entry match no finding in this scan.
            1 × suppressions: still reported under a new fingerprint — NOT silenced any more
            Run with --explain-coverage for the detail.

CRIME SCENE REPORT
repo: messy-ts-app  ·  37 findings across 18 files  ·  5 high  16 medium  16 low  ·  +2 in non-domain paths

Repo-level
  1. src/api/files.ts
     Charge: Missing Agent Context
     Summary: Repo ships no agent-readable instruction files (AGENTS.md, CLAUDE.md, .claude/skills/*/SKILL.md, .agents/skills/*/SKILL.md). Agents loading this repo will not see project commands, conventions, or safety rules and are more likely to make confident-but-wrong edits.
     Evidence:
       · no AGENTS.md found at repo root
       · no CLAUDE.md found at repo root
       · no .claude/skills/*/SKILL.md present
       · no .agents/skills/*/SKILL.md present
       · package.json declares bin(s): messy — agents have no way to discover commands
     id=crime_00002  confidence=0.90
  2. package.json:1 (undeclared imports)
     Charge: Phantom Accomplice
     Summary: 1 external package(s) are imported but declared in no applicable package.json. They resolve today through hoisting; a clean install can fail.
     Evidence:
… (excerpt)

JSON finding (excerpt; other report fields omitted)

{
  "schema_version": "0.8.0",
  "report_type": "scan",
  "findings": [
    {
      "id": "crime_00001",
      "type": "return_shape_roulette",
      "charge": "Return Shape Roulette",
      "severity": "low",
      "confidence": 0.73,
      "file": "src/petty.ts",
      "symbol": "resolvePaymentResult",
      "lines": [
        21,
        32
      ],
      "summary": "resolvePaymentResult returns several object shapes without an explicit return type. Callers and agents may infer the wrong result contract.",
      "evidence": [
        "3 object-literal return shapes",
        "lowest key overlap: 0%",
        "example keys: { code, message, ok } vs { permanent, url }"
      ],
      "effort": "small",
      "fix_shape": "pick one return shape; use a discriminated union if you need both",
      "scores": {
        "severity": 0.3,
        "confidence": 0.73,
        "agent_risk": 0.43,
        "churn": 0,
        "test_gap": 0.5,
        "blast_radius": 0,
        "blast_radius_transitive_importers": 0,
        "blast_radius_direct_importers": 0,
        "recency": 0
      },
      "suggested_actions": [
        {
          "kind": "name_return_shape",
          "description": "Add an explicit return type or split branch-specific results into named result variants.",
          "risk": "low"
        }
      ],
      "pack": "language-js",
      "detector_id": "return_shape_roulette.js",
      "tier": "domain",
      "fingerprint": "return_shape_roulette::src/petty.ts::resolvePaymentResult"
    }
  ]
}

schema_version is bumped on breaking changes, so agents can refuse to consume an unfamiliar shape. Every finding includes effort (quick/small/medium/large) and fix_shape (a one-line description of the shape of the fix). These references describe the contract:

• docs/agent-usage.md covers the pre-edit and post-edit workflow, shipped and deferred commands, and exit-code behaviour
• docs/json-schema.md describes every field of the wire format, including required and reserved fields
• docs/fixtures/messy-ts-app.json contains the full, version-controlled sample output

What it detects today

81 detectors across ten families. The two tables below are the founding families, shown in full because they are the easiest to picture. Every family after them links to its own reference page. Each lists the detectors, what raises and lowers its confidence, and the near-misses it deliberately does not fire on.

Beyond one language

Language packs decide what can be seen at all. The universal pack (v0.12.0) runs on every file in any language, so a Rust or Go repo still gets file-level and git-derived findings. The Python pack (v0.14.0) brings real parsing to .py sources, and the Java (v0.29.6) and Kotlin (v0.29.8) packs to .java and .kt, with one dependency graph across both, including the same-package references the JVM resolves without an import, and the Swift pack (v0.29.8) to .swift, where a module's types need no import at all. The cross-language pack (v0.15.0) reports what neither language's own tooling can: a frontend calling a path the backend does not serve, a closed set listed differently on each side, or the same concept called team in one language and workspace in the other.

Structural detectors · shipped in v0.1.0

Information architecture detectors

IA crimes surface deterministic evidence that names, locations or implementations of a product concept disagree. The checks run locally without an LLM or API key. 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)

IA findings describe possible ambiguity. Check the cited files before deciding whether the difference is intentional. 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).

FAQ