_{High-confidence review 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.

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

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

• 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 review intent from branch name locally
• Pluggable models, or run everything locally via Ollama
• Stays silent if no issues to be reported
• 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
• Deterministic pipeline for identifying cross file issues for Typescript (more languages on the roadmap)
• Tested with real-world C, C++, Rust, Go, TypeScript, Python, and Java repositories (see Benchmarks and Example Signals)

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

npm i -g @prsense/cli

First run will walk you through provider setup:

prsense init

prsense review .

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

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

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

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

prsense index .

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

prsense hook install

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

prsense doctor

1. prsense index .
2. prsense review .

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

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

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

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.

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

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

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

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

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

Controls repository chunking.

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

Controls signal filtering.

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

Controls retrieval (RAG).

• maxChunks — number of chunks retrieved per changed file

Credentials only. Never store in prsense.yml.

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

PRSENSE_LOG_LEVEL=debug | info | warn | error

prsense config inspect

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

If no configuration is provided:

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

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

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.

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 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 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.

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.

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.

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

A complete command reference is available in:

docs/man/prsense.1

or just run man prsense

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

See benchmarks.json.

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.

PRs welcome.

PRSense is licensed under the Apache 2.0 License.