# DiffHound (by Continuum) — Zero-Noise AI Anti-Regression Engine

<div align="center">

<img src="docs/assets/diffhound_logo.jpg" alt="DiffHound Logo" width="220" style="border-radius: 50%; box-shadow: 0 4px 20px rgba(56, 189, 248, 0.3);" />

<h3>The Hound that catches the regressions rabbits miss.</h3>

**English** | [中文说明](README_CN.md)

</div>

[![Rust: 100% Native](https://img.shields.io/badge/Rust-100%25%20Pure%20Native-dea584.svg?logo=rust&logoColor=white)](crates/continuum-core)
[![Zero External Crates](https://img.shields.io/badge/Dependencies-0%20(Pure%20std)-brightgreen.svg?logo=rust&logoColor=white)](#)
[![Tests: 100% Passing](https://img.shields.io/badge/tests-44%20Rust%20%2B%2058%20Python%20passing-brightgreen)](#)
[![Memory: Flat O(K)](https://img.shields.io/badge/Memory-750%20Slots%20Flat%20O(K)-blue.svg)](#)
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-purple.svg)](LICENSE)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22765180.svg)](https://doi.org/10.5281/zenodo.22765180)

> **“The Hound that catches the regressions rabbits miss.”**  
> Continuum is an industrial-grade, deterministic memory manifold and PR gatekeeper.  
> It equips AI coding assistants (Cursor, Claude Code, Windsurf) and CI/CD pipelines with **zero-noise regression interception**—preventing new AI sessions from repeating bugs your team has already solved.

---

## 🐕 What is DiffHound?

With over 40% of code now generated by AI, engineering teams are drowning in PR review fatigue. Existing AI reviewers (CodeRabbit, Greptile) flood pull requests with dozens of superficial comments on style and variable naming, causing human reviewers to suffer alert blindness.

**DiffHound** enforces one dogmatic principle:
> **Zero-Noise Law**: If an incoming PR does not break a historical fix or violate an architectural post-mortem, **it stays 100% silent and exits 0**. It only speaks when a true regression is intercepted.

```
                    Pull Request Unified Diff
                               │
                               ▼
               DiffHound AST Hunk Extraction
                               │
                               ▼
               Continuum Causal Temporal Manifold
               (750 bounded physical slots, < 100 μs)
                               │
             ┌─────────────────┴─────────────────┐
             │                                   │
      Score < Threshold                   Score >= Threshold
     (0 Regressions Risk)                (Historical Anchor Hit!)
             │                                   │
             ▼                                   ▼
      • Exit Code 0                       • Exit Code 1 (Block Merge)
      • ZERO Comment Spam                 • Laser-Focused Warning Table:
        (Zero-Noise)                        - File & Line Number
                                            - Historical Commit Hash
                                            - Post-Mortem Remediation
```

---

## ⚡ Key Highlights

- **100% Native Rust Standard Library**: Zero external crate dependencies. Compiles standalone in `< 2 seconds` with zero runtime bloat.
- **Physical $O(K)$ Bounded Memory**: State is strictly constrained to 750 slots (Hot working memory + Cold candidate manifold).
- **Sub-Millisecond Execution**: Retrospective causal scoring runs in `< 3 ms` inside GitHub Actions.
- **Microsecond Zero-Loss Persistence**: Complete snapshot in tens of kilobytes, atomic write + parent directory `fsync` with checksum verification.
- **Dual Form Factors**:
  - **DiffHound CLI & Action**: Local developer tool & GitHub Actions CI Gatekeeper.
  - **Continuum MCP Server**: Integrated stdio protocol for Cursor, Claude Code, Windsurf.

---

## 🚀 Quickstart

### 1. Run 1-Shot CI Installer
Add DiffHound zero-noise regression protection to any Git repository with one command:
```bash
curl -fsSL https://raw.githubusercontent.com/reacherwu/diffhound/main/crates/diffhound-cli/install-ci.sh | bash
```

### 2. Standalone CLI Review
```bash
# Build & install diffhound globally
cargo install --path crates/diffhound-cli

# Review current branch against main before pushing
diffhound review --base origin/main --fail-on-regression
```

### 3. Add to GitHub Actions (`.github/workflows/diffhound.yml`)
```yaml
name: DiffHound Anti-Regression Guard
on: [pull_request]

jobs:
  guard:
    name: DiffHound Zero-Noise PR Guard
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: reacherwu/diffhound@main
        with:
          fail-on-regression: true
          threshold: '0.65'
```

---

## 🛠️ MCP Integration (Cursor / Claude / Windsurf)

Continuum provides a built-in, zero-dependency Model Context Protocol server.

#### Cursor (`~/.cursor/mcp.json`):
```json
{
  "mcpServers": {
    "continuum": {
      "command": "continuum-cli",
      "args": ["mcp"]
    }
  }
}
```

#### Claude Code / Claude Desktop:
```bash
claude mcp add continuum continuum-cli mcp
```

---

## 🔬 Benchmark: DiffHound vs. Traditional AI Reviewers

| Metric | Traditional Cloud AI Reviewer | Naive Vector Store | **DiffHound (Pure Rust)** |
| :--- | :---: | :---: | :---: |
| **Analysis Latency** | 4,200 ms – 8,500 ms | 120 ms – 350 ms | **2.4 ms (2,410 μs)** |
| **CI Memory Overhead** | > 1.2 GB (Node/Python runtime) | > 450 MB | **< 12 MB (Zero-runtime)** |
| **Spam Comments on Clean PRs** | 8 – 24 comments | 0 | **0 (Zero-Noise Law)** |
| **Historical Root Exemption** | ❌ No (Penalized by recency) | ❌ No | **✅ Yes (Causal Bridge)** |
| **External API Dependencies** | OpenAI / Anthropic Key required | Vector DB required | **None (100% Local / Self-Hosted)** |

---

## 📄 Academic Citation & Prior Art

The foundational two-tier manifold and retrospective causal revision architecture were independently derived and archived on **CERN Zenodo**:
- **Paper**: *Continuum: A Deterministic O(K)-Bounded Two-Tier Memory Manifold for Resilient Autonomous Agents under Temporal Alert Storms*
- **Author**: Jun Wu
- **DOI**: [https://doi.org/10.5281/zenodo.22765180](https://doi.org/10.5281/zenodo.22765180)

---

## 📜 License

Released under the **GNU Affero General Public License v3.0 (AGPL-v3)**. Free and open-source for developers and teams locally.