Sentinel

An autonomous, gated, strict guardrail system for your code. A team of open-source AI models reviews every change; a deterministic gate decides what happens next. Everything runs on your Mac. No API keys, no cloud calls, nothing leaves your machine.

What it does

Every code change — working tree edits, commits, pushes — goes through this pipeline:

1. Ingest — Sentinel takes the diff (your working tree, a commit, or a branch) plus which files changed.
2. Guru council — 3–4 open-source models (via Ollama) each review the same diff blind: none of them sees the others' output. Each has its own lens — correctness, edge cases, security, architecture — and each returns the same typed report card: severity (0–4), confidence (0–1), file, line, what breaks, and a suggested fix.
3. The gate (jev-like) — this is the key step, and there is no AI in it. A small deterministic program takes the typed findings, computes a risk score, and applies thresholds you declare in gates.yaml. First matching rule wins: APPROVE, FIX, or ESCALATE. Thresholds are versioned config, not prompts — you can diff them, test them, and tune them like code.
4. Fix loop — on FIX, a builder model proposes a minimal patch. The patch is checked (it must apply cleanly), the council re-reviews, the gate re-decides. Two tries max, then it escalates. Patches are proposed, never applied — you decide.
5. Report — an informative markdown report per change: verdict, risk score, findings table, what looks good, pros/cons, and exactly what was checked. Saved under ~/.sentinel/reports/.

The pre-push git hook is the actual gate: it runs the pipeline on what you're pushing and blocks the push on ESCALATE or any critical (severity-4) finding, printing the report path. Strict by default.

Setup (once)

unzip sentinel-v1.zip && cd sentinel-v1
./install.sh
sentinel init ~/path/to/your/repo   # repeat per repo, or pass several at once

install.sh checks your Mac, links the sentinel command, makes sure Ollama is there (offers to install it), and pulls the guru models (one-time, ~4–5 GB each). sentinel init registers repos and installs the pre-push hook. It can also keep the orchestrator running in the background for you.

Requirements: Apple Silicon Mac, Python 3.10+, git, Ollama with the pulled models. If Ollama isn't running, every command tells you so plainly instead of dumping a traceback.

Commands

• sentinel review — review your working tree right now.
• sentinel review main..HEAD — review a commit or range.
• sentinel review --repo ~/other/repo — review a different repo.
• sentinel review --pr-comment — also post the report as a GitHub PR comment (needs the gh CLI, best-effort, never blocks).
• sentinel watch — sit in a terminal and auto-review whenever a registered repo changes.
• sentinel report --list / sentinel report <id> — read past reports.
• sentinel config / sentinel config --set ollama.timeout=900 — inspect and tweak settings.
• sentinel serve — run the orchestrator in the foreground (the CLI normally starts it for you).

The orchestrator also speaks MCP (stdio): sentinel-mcp exposes review_change and get_report, so your IDE agents can invoke reviews. Point your MCP client at the sentinel-mcp executable.

How the gate works (tuning)

Open ~/.sentinel/gates.yaml. Rules run top to bottom; the first match decides. Defaults:

• any severity-4 finding with confidence ≥ 0.6 → ESCALATE
• 3+ severity-3 findings → ESCALATE
• risk score ≥ 35 → FIX (builder agent tries a patch)
• risk score ≥ 20 → ESCALATE
• otherwise → APPROVE

Risk score = min(100, Σ severity × confidence × guru-weight × 10). Security findings weigh 1.25×, architecture notes 0.75×. Change the numbers, re-run a review, watch the verdict move. That's the whole point: the gate is code and config, not vibes.

The guru team lives in ~/.sentinel/gurus.yaml. Swap any model: line for another Ollama model you have pulled; edit a system prompt to change a lens. Keep the JSON schema hint intact so findings stay typed.

Why the reviews are non-biased (by design)

• Blind: gurus never see each other's output before the verdict.
• Typed: findings are severity/confidence/file/line/title/rationale — no prose reaches the decision.
• Deterministic gate: same findings in → same verdict out, every time.
• Anti-sycophancy prompts: each guru is told that inventing issues hurts its score and that "no findings" is a respectable answer.

Verification step (strict)

Every review also runs verifiers: independent checks in an isolated throwaway git worktree (your working tree is never touched). v1 ships two:

• local-worktree — the diff must apply cleanly and changed Python files must compile.
• local-tests — the repo's own test suite actually runs against the change (pytest/unittest, npm test, go test, cargo test, auto-detected). No suite found? It passes with a "skipped" note — a missing suite is not a failure. Runs are timeout-bounded (SENTINEL_TEST_TIMEOUT, default 300s); set SENTINEL_SKIP_TESTS=1 to skip test execution.

A failed verifier counts like a high-severity finding.

orchestrator/verifiers/ is a plugin directory: drop in a module exposing a Verifier class and it's picked up automatically. The intended next one is an E2B sandbox verifier — clone the change into a fresh cloud microVM and run the repo's real test suite per review. That's a v2 step (it needs an E2B key, which isn't in v1's zero-keys design).

Docs

• docs/QUICKSTART.md — zero to first gated push in 10 minutes
• docs/ARCHITECTURE.md — components, pipeline stages, state, protocols
• docs/CONFIGURATION.md — tuning gates.yaml, gurus.yaml, env vars
• docs/TROUBLESHOOTING.md — when something misbehaves
• CHANGELOG.md — what shipped in this version

Bypass

Strict doesn't mean bricked. SENTINEL_BYPASS=1 git push skips the hook, and the bypass is logged to ~/.sentinel/bypass.log so it's auditable.

Files

• bin/sentinel, bin/sentinel-mcp — executables (linked to your PATH)
• sentinel/ — the CLI package
• orchestrator/ — pipeline, gate, HTTP service, MCP server, verifiers
• config/gates.yaml, config/gurus.yaml — shipped defaults (copied to ~/.sentinel/ on first run; edit the copies)
• tests/ — unit tests; run with python3 -m unittest discover tests

All state lives in ~/.sentinel/ (reports, config, logs). Delete that folder to reset everything.