GitHub - navxio/PRSense: High signal code reviews grounded in diff. Local first and powerful.

_{High-confidence signals grounded in diff}

PRSense (Patch-Review Sense) is an open-source, LLM-powered code review engine that surfaces high-confidence review signals from diff.

PRSense is experimental software, expect bugs.

Table of Contents

• Philosophy
• Features
• Requirements
• Installation
• Usage
• Configuration
• Design
• Architecture
• Command Reference
• Benchmarks
• Contributing
• License

Philosophy

PRSense is built around a few core principles:

• human-in-the-loop decision making
• high signal, low noise
• local-first and self-hosted operation
• transparency over automation
• inspectable reasoning
• composability over monoliths
• extensibility via hexagonal architecture — make it your own

Features

• Fast, local-first CLI for reviewing and analyzing code changes
• Self-hosted by default — run entirely on your own machine, no external services required
• Zero-infrastructure — bundled SQLite + sqlite-vec, no database to provision
• One-command setup
• Automatically reads your intent from branch name locally
• Pluggable models, or run everything locally via Ollama
• Auto-indexing by default for context-enriched review
• Human-in-the-loop decision making
• Diff-first intelligence, understanding:
  • local changes
  • pull request diffs from GitHub, GitLab, and Codeberg / Forgejo
• Pluggable LLM backends — Ollama, Anthropic, Google, OpenAI
• Built-in profiling
• Automatically reads from and writes to local .env
• AST-based chunking for TypeScript (more languages on the roadmap)
• Bundled pre-push git hook
• Tested with real-world C, C++, Rust, Go, TypeScript, Python, and Java repositories (see Benchmarks and Example Signals)

Requirements

• Node.js >= 22 <25
• git >= 2.31
• (optional) Ollama for local inference

Installation

First run will walk you through provider setup:

Usage

Review a local repository

Compares your current branch against the configured base branch and prints review signals to stdout.

Review a GitHub Pull Request

prsense review https://github.com/owner/repo/pull/123

Review a GitLab Merge Request

prsense review https://gitlab.com/group/project/-/merge_requests/42

Review a Codeberg / Forgejo Pull Request

prsense review https://codeberg.org/owner/repo/pulls/7

Index a repository (enable contextual review)

Builds a semantic index of the repository to enable contextual (RAG-enhanced) reviews.

Optional flags:

prsense index . --force
prsense index . --dry-run
prsense index . --stats

Install the pre-push hook

Runs PRSense against each pushed ref before the push completes. Bypass with git push --no-verify. See prsense hook --help for details.

Diagnose your setup

Typical Workflow

1. prsense index .
2. prsense review .

Configuration

defaults
   ↓
global config
   ↓
repo config
   ↓
CLI flags
   ↓
Resolved Configuration

PRSense separates review behavior from runtime credentials. Configuration is layered and deterministic.

Configuration Layers (Lowest → Highest Priority)

1. Built-in defaults
2. Global config (~/.config/prsense/config.yml)
3. Repository config (prsense.yml)
4. CLI flags

Environment variables are used exclusively for credentials, never review behavior.

This ensures:

• Reproducible reviews
• No secrets in source control
• Deterministic layering
• Clear separation of domain vs runtime concerns

Global Configuration (Optional)

Location:

$XDG_CONFIG_HOME/prsense/config.yml

or

~/.config/prsense/config.yml

Global config defines personal defaults applied to all repositories.

llm:
  provider: ollama
  model: qwen2.5-coder
  temperature: 0.1

embeddings:
  provider: ollama
  model: nomic-embed-text

Repository config overrides global config.

Repository Configuration (prsense.yml)

Placed at the root of your repository. Defines review behavior:

• LLM provider and model
• Embedding model
• Chunking strategy
• Review thresholds
• Retrieval limits

Example

llm:
  # Review model. Local (ollama) or cloud (openai | google | anthropic).
  provider: ollama
  # Provider-specific model name. Must support the provider's chat API.
  model: deepseek-coder-v2
  # Sampling randomness. Keep low for deterministic, repeatable reviews.
  temperature: 0.1

embeddings:
  # Embedding provider for RAG. Anthropic not supported (no embeddings API).
  provider: ollama
  # Must stay consistent across runs; changing it forces a full re-index.
  model: nomic-embed-text

index:
  # Character window per chunk. Larger = more context per chunk, fewer chunks.
  chunkSizeChars: 1000
  # Overlap between adjacent chunks. Preserves continuity across boundaries.
  # Must be < chunkSizeChars (schema-enforced).
  chunkOverlapChars: 200

review:
  # Minimum LLM-reported confidence (0–1) for a signal to be emitted.
  # Higher = stricter, fewer false positives, more false negatives.
  confidenceThreshold: 0.8
  # Display cap. Generation stays exhaustive; only the top-N are printed.
  topSignals: 3

context:
  # Max retrieved chunks per changed file (applied per-file since 0.14.0).
  # Total prompt context scales ~maxChunks × N files.
  maxChunks: 5

git:
  # Branch to diff against when reviewing local changes.
  baseBranch: main

Configuration Sections

llm

Controls the review generation model. Supported providers: ollama, openai, google, anthropic. temperature controls randomness; lower values produce more deterministic output.

embeddings

Controls vector embeddings used for indexing and retrieval. If changed, re-indexing is required and embedding dimensions must match the database schema.

index

Controls repository chunking.

• chunkSizeChars — characters per chunk
• chunkOverlapChars — overlap between chunks

review

Controls signal filtering.

• confidenceThreshold — minimum confidence
• topSignals — number of highest-priority signals emitted

context

Controls retrieval (RAG).

• maxChunks — number of chunks retrieved per changed file

Environment Variables

Credentials only. Never store in prsense.yml.

LLM credentials

VCS read tokens (for remote PR/MR review)

Storage

Bundled SQLite + sqlite-vec. Stored under the PRSense state directory (~/.local/state/prsense/). No setup required.

Logging

PRSENSE_LOG_LEVEL=debug | info | warn | error

Inspecting Effective Configuration

Shows the layered merge with provenance per field, plus credential availability per provider (never the secrets themselves).

Defaults

If no configuration is provided:

• ollama is used as the default LLM provider
• nomic-embed-text is used for embeddings
• Safe chunking defaults applied

Security Notes

• Never commit API keys or tokens.
• Global config should not contain secrets.

Configuration Summary

Design

PRSense is built using a hexagonal (ports-and-adapters) architecture.

This design separates core review logic from external concerns such as Git, filesystems, databases, LLM providers, and user interfaces. The goal is to keep the system easy to reason about, test, and extend.

Core (Domain + Engine)

At the center of PRSense is a small, declarative core:

• domain types such as ReviewSignal and ReviewContext
• pure review logic and orchestration
• no direct IO
• no network access
• no filesystem assumptions

The core does not know where data comes from or where results go. It only operates on well-defined inputs and produces structured outputs.

This makes the core:

• deterministic
• testable
• portable
• resistant to integration churn

Ports

Ports are the abstract boundaries through which the core interacts with the outside world.

In PRSense, ports take the form of TypeScript interfaces and function contracts, for example:

• context retrievers
• LLM providers
• embedding generators
• vector stores
• reporters

Ports describe what the core needs, not how it is implemented.

Adapters

Adapters live at the edges of the system and implement ports.

Examples include:

• filesystem-based context retrieval
• git diff ingestion
• Ollama or OpenAI LLM providers
• CLI reporters

Adapters are inherently imperative and may fail. Those failures are handled at the boundary, not inside the core.

Imperative Shell

The outermost layer consists of applications that parse user input, load configuration, wire adapters together, call the core, and present results.

The shell is free to be messy. The core is not.

Why This Matters

This architecture allows PRSense to:

• swap LLM providers without touching review logic
• add new retrieval strategies without rewriting the engine
• support new VCS platforms with a small adapter
• remain understandable as complexity grows

Most importantly, it allows PRSense to treat LLMs as interchangeable tools rather than structural dependencies.

The result is a system that is flexible without being fragile.

Architecture

      ┌─────────────┐
      │   Git / PR  │
      └──────┬──────┘
             │
        [ Diff Input ]
             │
    ┌────────▼────────┐
    │ Ingestion       │
    │ (diff + meta)   │
    └────────┬────────┘
             │
    ┌────────▼────────┐
    │ Context Builder │◄──── Repository, files, history
    └────────┬────────┘
             │
    ┌────────▼────────┐
    │ Review Engine   │
    │ (LLM + Context) │
    └────────┬────────┘
             │
    ┌────────▼────────┐
    │ Signal Compiler │
    └────────┬────────┘
             │
    ┌────────▼────────┐
    │ Reporters       │
    │ (CLI, others)   │
    └─────────────────┘

PRSense follows a hexagonal architecture:

• a declarative domain core
• a functional review engine
• imperative adapters for IO, git, LLMs, and storage

CLI
─────────────── execution environment
Workflows
─────────────── orchestration
Engine / Context / Adapters / LLM
─────────────── capabilities
Domain
─────────────── pure types

Command Reference

A complete command reference is available in:

docs/man/prsense.1

or just run man prsense

Benchmarks

Benchmarks track per-review latency, token usage, and grounding metrics for flagship and local (Ollama) models.

See benchmarks.json.

Running benchmarks

Clone the repo, install with pnpm i from the root, then:

1. Create a GitHub token and set PRSENSE_GITHUB_BENCH_TOKEN
2. pnpm bench

Ensure cloud provider credentials are set, and Ollama is running with the models under test available.

Contributing

PRs welcome.

License

PRSense is licensed under the Apache 2.0 License.