regression-analyzer

Mines a git repository's fix history, clusters recurring regression patterns, and proposes agent-guidance rules (additions to CLAUDE.md, AGENTS.md, or .cursor/rules/*). The tool runs locally, redacts secrets before any provider call, and never edits source files — it only writes patches to .regression-analyzer/reports/ for a human reviewer to apply.

What it does

• Mines fix-like commits via pydriller, normalizes diffs, splits suspicious bundle commits, and extracts repo-generic subsystem plus semantic fix-type tags.
• Embeds redacted evidence locally (sentence-transformers/all-MiniLM-L6-v2) and clusters normalized vectors with HDBSCAN without building a quadratic pairwise-distance matrix.
• Calls Anthropic (Claude Opus 4.8 by default) once per cluster to produce a structured proposed rule + scores.
• Reuses unchanged embeddings, clustering results, and per-cluster analyses across runs.
• Compares clusters across runs and reports correlational REDUCED / WORSENED / SHIFTED pattern trends; it does not claim accepted rules caused the change.

What it doesn't do

• No SaaS. Runs entirely on the developer's machine.
• No auto-apply. The CLI writes patches; the reviewer chooses to git apply or copy-paste.
• No cross-repo pooling. Each run is scoped to a single working directory.
• No AI attribution in generated commits or reports.
• No telemetry. No data is collected about runs.

Install

Install from a local checkout:

git clone https://github.com/scanadi/regression-analyzer.git
cd regression-analyzer
pipx install -e .

Quickstart

1. cd <your-repo>
2. regression-analyzer init — writes .regression-analyzer.toml and adds .regression-analyzer/ to .gitignore.
3. Export env vars:

   export ANTHROPIC_API_KEY=sk-ant-api03-...
   # Optional — overrides [models] analysis_model (default claude-opus-4-8):
   export REGRESSION_ANALYZER_AI_MODEL=claude-opus-4-8
   

4. regression-analyzer analyze --since 6m --propose-rules
5. Inspect outputs under .regression-analyzer/reports/.

To reproduce the quickstart without pointing the analyzer at your own code, build the deterministic 50-commit fixture repository:

uv run python scripts/build_sanitized_fixture_repo.py /tmp/regression-analyzer-fixture
regression-analyzer init --cwd /tmp/regression-analyzer-fixture
regression-analyzer analyze --cwd /tmp/regression-analyzer-fixture --since 1y --no-llm

The fixture and its ground-truth redaction corpus contain synthetic values only. See examples/sanitized-fixture-repo/.

Required env vars

No env var is required for the embedding stage — sentence-transformers/all-MiniLM-L6-v2 runs on CPU. With --no-network, model loading is cache-only (local_files_only=true); mining-only runs do not import Torch or load a model.

Configuration

regression-analyzer init writes .regression-analyzer.toml at the repo root. Major sections:

CLI flags override config values for --since, --until, --author, --min-cluster-size, and --allow-redacted-send.

Privacy defaults

Full policy: docs/privacy-policy.md. Outbound payload shape: docs/provider-payload-contract.md. Per-provider disclosure: docs/provider-disclosure.md.

Cost controls

The analysis stage is the only paid step (one Anthropic call per cluster + per severe singleton). It is guarded on three axes:

A live dashboard (progress bar + running cost + severity-tagged findings feed) renders in a TTY. Actual token usage and USD are recorded in the maintainer report and the analyze summary.

Outputs

All written under .regression-analyzer/reports/:

The cache lives under .regression-analyzer/cache/: redacted-items.json, embeddings.json, clusters.json, analysis.json, analysis-input-hashes.json, guidance-index.json, prompt-debt.json, accepted-rules.json, plus calibration artifacts. Embedding reuse is keyed by evidence, model, dimensions, and composition version; analysis reuse is keyed by the full redacted cluster input, guidance excerpts, model, system prompt, and tool schema.

CLI reference

analyze flags:

Examples

First run, six months of history, with rule patches:

regression-analyzer analyze --since 6m --propose-rules

Local-only (skip Anthropic, embedding-only output):

regression-analyzer analyze --since 3m --no-llm

Cross-run comparison against the previous run:

regression-analyzer analyze --since 6m --compare-to last --propose-rules

What it proposes vs. what it applies

The CLI ONLY writes patches under .regression-analyzer/reports/. It NEVER edits source guidance files (CLAUDE.md, AGENTS.md, .cursor/rules/*). After review, the reviewer chooses to git apply --unidiff-zero .regression-analyzer/reports/proposed-rules.patch (or copy individual sections from proposed-rules-summary.md into the target files).

License

Licensed under the Apache License 2.0.