Sergeant - open-source engineering reviewer

Sergeant

Sergeant (SRG) is an open-source software engineering review system created by THETECHGUY DIGITAL SOLUTIONS.

Sergeant inspects repositories, reviews pull requests, verifies engineering standards, and produces evidence-based reports. It is not a one-shot coding assistant. It is the reviewer that challenges assumptions, checks proof, and reports what remains before merge or release.

PASS
NEEDS WORK
BLOCK

Review architecture

Repository / changed files
        ↓
Deterministic Sergeant evidence
        ↓
Provider-routed semantic review
        ↓
Evidence grounding and rejection
        ↓
Optional challenger model
        ↓
Cross-source consensus
        ↓
Commander verdict

Main Review remains the reviewer core. An LLM is an independent evidence source, not the final authority.

Every accepted semantic blocker or major finding must identify a supplied repository path, a valid line range, and supporting source text. Unsupported high-severity claims are discarded before consensus. Deterministic tests, runtime proof and explicit contracts outrank model speculation.

This creates a stronger, auditable gate. It does not claim that any model or static rule can guarantee zero defects.

Who Sergeant is for

Individual developers who want a second engineering review before shipping.
Open-source maintainers reviewing pull requests and project changes.
Teams that care about standards, evidence, and repeatable review flow.
AI-assisted development workflows where generated code still needs independent review.
Self-hosted or model-agnostic environments that should not depend on one provider.

Core principles

Evidence before opinion.
Standards before assumptions.
Review before merge.
Verification before release.
Human judgment remains final.
Finish, then prove.
Claims must match implementation.

FCC-compatible provider routing

Sergeant adopts the protocol architecture demonstrated by Free Claude Code (FCC) without importing FCC as a hard Python dependency. Sergeant can talk to FCC through its local OpenAI Responses endpoint while preserving Python 3.10+ compatibility.

Supported routes:

Route	Default endpoint	Protocol
Free Claude Code	`http://127.0.0.1:8082/v1`	OpenAI Responses
Ollama	`http://127.0.0.1:11434/v1`	Chat Completions
LM Studio	`http://127.0.0.1:1234/v1`	Chat Completions
Explicit hosted/self-hosted endpoint	owner configured	Responses or Chat Completions

Automatic discovery probes loopback endpoints only. Sergeant never guesses a remote service. Code can leave the machine only when an owner explicitly configures a remote base URL.

When multiple models are exposed and no model is pinned, Sergeant prefers:

GLM-5.2
Qwen3-Coder-Next
Kimi K2.5
GLM-5.1
Qwen3-Coder
Kimi K2
provider fallback

The preference is configurable and is not a permanent claim that one model is universally best.

Semantic policies

Preferred is the product default:

use semantic review when a route is available;
fall back to deterministic Sergeant evidence when it is not;
state clearly in the report whether the semantic pass ran.

Required is the strict release gate:

no approval when the semantic route is unavailable or fails;
all required deterministic and semantic evidence must complete.

Disabled runs deterministic review only.

Adaptive model council

The default council mode is adaptive. A second discovered model is used for high-risk paths, large changes, primary-model major findings, or disagreement among deterministic sources.

Other modes:

always — use a challenger whenever another preferred model is available;
single — use only the selected primary model.

Full setup, privacy, grounding and configuration details are in docs/22-semantic-open-model-review.md.

Engineering workflow

Understand
    ↓
Review
    ↓
Challenge
    ↓
Verify
    ↓
Freeze
    ↓
Prove
    ↓
Ship

Sergeant V2 Command Center

Commander
    ↓
Mission
    ↓
Officers
    ↓
Weapon Manifest
    ↓
Deterministic Evidence
    ↓
Semantic Evidence
    ↓
Verification
    ↓
Commander Verdict
    ↓
Audit Trail

The VS Code extension provides a compact activity-bar launcher and a full editor Command Center. The JetBrains preview uses the same interface through JCEF and falls back to a native Swing panel when JCEF is unavailable.

The interface includes:

Commander dashboard and live workspace state.
Mission Planner for repository, changed-file, release, battle, final-proof, IDE and custom missions.
Semantic router controls for policy, provider, model, base URL, protocol and council mode.
Live mission progress and evidence.
Evidence views for static, runtime, semantic, UI, documentation, battle and optional external review.
Evidence Locker with report history, open, copy, export and refresh actions.
Officer deployment and armoury views.
Settings, Review Doctrine, Post-V2 Roadmap and Guide pages.
One-active-mission gates in both VS Code and JetBrains.

Writer safety boundary

Disabled by default.
Draft patches only.
Human approval required.
Never auto-merge.

Current capability set

Repository and engineering review

Repository inspection and understanding.
Pull-request, current-file and changed-file review.
Architecture and regression-risk checks.
Static analysis and security signals.
Documentation drift checks.
Evidence consensus and standards verification.
Evidence-grounded semantic review.
Adaptive open-model challenger review.
Verified learning and squad-style review intelligence.

Developer workflow

CLI review flow.
App bridge contract.
IDE Bench contract for VS Code, PyCharm, JetBrains and AI handoff.
Full VS Code Command Center.
JetBrains Command Center preview.
Read-only GitHub PR comment ingestion.
Live GitHub review bridge.
FCC, Ollama, LM Studio and explicit OpenAI-compatible routes.

Proof and battle validation

Battle-test fixtures and validator.
Static review-signal comparison.
Live PR patch fetch for battle comparison.
CI and clean-clone proof.
Browser-rendered Command Center proof at desktop and compact IDE widths.
Semantic router and duplicate-launch browser proof.
Mock FCC Responses wire-contract proof.
PyPI wheel/source validation, VSIX packaging and JetBrains plugin packaging.

Installation

Python / CLI

Published stable package:

python -m pip install sergeant-reviewer==0.4.0

Current source development:

git clone https://github.com/jaydumisuni/Sergeant.git
cd Sergeant
python -m pip install -e .

Requires Python 3.10 or newer.

VS Code

Install Sergeant from the Visual Studio Marketplace or Open VSX. For a local package:

npx @vscode/vsce package --no-dependencies
code --install-extension sergeant-reviewer-0.4.0.vsix --force

Open Sergeant from the activity bar, then use Open Full Command Center.

JetBrains IDEs

The current marketplace preview targets the 2025.2 / build 252 line. Install the Sergeant CLI first:

python -m pip install sergeant-reviewer==0.4.0

Set SERGEANT_CLI when the executable is not on the IDE process path.

Quick start

Deterministic-only review

sergeant review . --pretty

Complete independent review

The full reviewer uses deterministic evidence and semantic review when available:

sergeant pr-review . --pretty

Review explicit files:

sergeant pr-review . --files "src/app.py,tests/test_app.py" --pretty

Check the active semantic route:

sergeant llm-status --pretty

Require a working route:

sergeant llm-status --require --pretty

FCC

export SERGEANT_LLM_PROVIDER=fcc
export SERGEANT_LLM_POLICY=preferred
export SERGEANT_LLM_PROTOCOL=responses
export SERGEANT_LLM_BASE_URL=http://127.0.0.1:8082/v1
sergeant llm-status --require --pretty
sergeant pr-review . --pretty

Ollama

export SERGEANT_LLM_PROVIDER=ollama
export SERGEANT_LLM_MODEL=qwen3-coder-next
sergeant pr-review . --pretty

LM Studio

export SERGEANT_LLM_PROVIDER=lm-studio
sergeant pr-review . --pretty

Explicit OpenAI-compatible endpoint

export SERGEANT_LLM_PROVIDER=configured
export SERGEANT_LLM_BASE_URL=https://your-endpoint.example/v1
export SERGEANT_LLM_MODEL=your-model-slug
export SERGEANT_LLM_PROTOCOL=chat_completions
export SERGEANT_LLM_API_KEY=your-runtime-secret
sergeant pr-review . --pretty

The API key is read from the process environment. It is not returned by llm-status, stored by the Command Center, written into reports, or committed to the repository.

Additional commands

sergeant app-review . --mode pull_request --files "src/app.py,tests/test_app.py" --pretty
sergeant v2-mission . --mission-type pull_request_review --mode pull_request --files "src/app.py,tests/test_app.py" --pretty
sergeant proof-suite . --pretty
sergeant final-proof . --pretty
sergeant verify-standard . --pretty
sergeant battle-tests . --pretty
sergeant ide-bench-contract --pretty

Configuration reference

SERGEANT_LLM_ENABLED=auto|true|false
SERGEANT_LLM_POLICY=preferred|required|disabled
SERGEANT_LLM_PROVIDER=auto|fcc|ollama|lm-studio|configured
SERGEANT_LLM_BASE_URL=<explicit /v1 endpoint>
SERGEANT_LLM_MODEL=<provider model slug>
SERGEANT_LLM_PROTOCOL=auto|responses|chat_completions
SERGEANT_LLM_COUNCIL=adaptive|always|single
SERGEANT_LLM_CHALLENGER_MODEL=<optional model slug>
SERGEANT_LLM_API_KEY=<runtime secret>
SERGEANT_LLM_TIMEOUT_SECONDS=90
SERGEANT_LLM_MAX_OUTPUT_TOKENS=5000
SERGEANT_LLM_MAX_INPUT_CHARS=120000
SERGEANT_LLM_MAX_FILE_CHARS=18000

Battle testing

Current fixtures include:

psf/requests#7502 — focused regression and test-clarity case.
pallets/flask#5812 — architecture and lifecycle case.
django/django#19610 — URL query-string merge case.

Battle comparison reviews patch text in a temporary workspace. It does not execute target code. Its agreement score remains transparent rather than being treated as an LLM-judged truth score.

Safety boundary

Sergeant refuses to:

Execute untrusted pull-request-controlled code.
Run shell commands supplied by PR content.
Automatically modify project code.
Write or merge patches as part of review.
Use privileged write tokens during analysis.
Silently fake success after a failed live fetch.
Treat an LLM or external reviewer as final authority.
Auto-discover remote model endpoints.
Emit the semantic-review API key in status or reports.

Strictest defensible review gate

For high-risk releases:

export SERGEANT_LLM_POLICY=required
export SERGEANT_LLM_COUNCIL=adaptive
sergeant pr-review . --pretty

Then require:

repository review;
diff review;
standard verification;
capability review;
semantic route available;
grounded semantic pass;
challenger when risk triggers it;
tests and runtime proof;
consensus with no unanswered major or blocker.

That is a complete configured gate—not a promise of literal 100% defect detection.

Public boundary

This repository contains reusable review infrastructure. Private project rules, customer evidence, deployment secrets and write-token operations do not belong in the public repository.

Contributing

Contributions, issue reports, feature requests and engineering discussions are welcome. Sergeant values evidence-based changes, reproducible results, clear reasoning, respect for existing architecture, standards compliance and useful signals over noisy output.

Identity

Sergeant / SRG is created by THETECHGUY DIGITAL SOLUTIONS.

Observe. Analyze. Verify.