scrutin 0.1.4

Local pre-commit review briefs from your git diff — scrutinize changes, stage, and commit with confidence

Scrutin

Review local git changes before you commit — risk highlights, file diffs, stage/unstage, and commit from the browser. Everything runs on your machine.

Install with Python (PyPI)

Step 1 — Check requirements

python3 --version
git --version

Step 2 — Install from PyPI

pip install scrutin
scrutin --help

If scrutin: command not found, ensure pip’s script directory is on your PATH, or use python3 -m scrutin.cli --help.

Step 3 — Start the server

cd /path/to/your-project
scrutin serve

Your browser should open http://127.0.0.1:8787. To start without opening a tab:

scrutin serve --no-open

To pin a specific repository on startup:

scrutin serve --repo /path/to/your-project

Step 4 — Set the repository in the UI

In the left Workspace panel:

1. Repository — full path to your git root (e.g. /Users/you/your-project)
2. Click ◎ Detect repo if the field is empty or wrong
3. Confirm the hint under Compare shows changed paths

Step 5 — Choose compare mode and refresh

Use the Compare dropdown, then click ↻ Refresh brief:

Mode	What it shows
working	Staged + unstaged vs HEAD (default for pre-commit)
staged	Index vs HEAD only
unstaged	Working tree vs index only
branch	base…head (e.g. main…HEAD) — set Base and Head when selected

Step 6 — Review, stage, and commit

1. Read the dashboard (KPIs, risk overview, summary)
2. In Files to scrutinize, open View diff and click Mark reviewed on each flagged file
3. Stage per file or use Stage all in the Commit panel
4. Write a commit message or click Suggest message, then Commit staged

Commit gate: Commit staged stays disabled until every file in Files to scrutinize is marked reviewed and at least one change is staged. Files under Other changed files do not require “Mark reviewed” but can still be staged and committed.

More UI detail: Browser guide (step by step) below.

IDE plugins — coming soon

Sidebar plugins are not listed on the Marketplace yet. Until they ship, use the browser UI from the Python.

Planned:

• VS Code — Scrutin brief in the activity bar, connected to scrutin serve on port 8787
• Cursor — same experience as the VS Code extension
• IntelliJ — JetBrains plugin for IDEA and compatible IDEs

All plugins will use the same local server — no cloud required.

---

First run

1. Open a terminal and go to your project:

   cd ~/your-project
   

2. Make sure you have something to review (edit files, or stage them):

   git status
   

3. Start the server (Python)

4. Click Refresh brief after you change files

---

Browser guide (step by step)

Start the server

From your project directory (or any path; you can set the repo in the UI):

cd ~/your-project
scrutin serve

Alternative — brief in terminal, then open UI:

scrutin brief --open

Read the dashboard

The main panel is your pre-commit brief:

• KPIs — files changed, review progress, lines added/removed, brief engine (Sharpen vs LLM)
• Diff activity / File mix — size and risk breakdown
• Risk overview — categories (secrets, CI/CD, migrations, etc.)
• Summary / Why — what changed and why it matters
• Risk areas — tags for the kinds of risk detected

Review flagged files (“Files to scrutinize”)

1. Click View diff — side-by-side Original / Modified panes
2. In the diff modal:
   • Stage / Unstage — update the git index for that file
   • Mark reviewed — track that you have looked at this file (required before commit is enabled)
3. On the card you can also Stage / Unstage without opening the diff

The File review bar shows progress (e.g. 5 / 12 reviewed).

Handle all other changes (“Other changed files”)

Same actions: View diff, Stage, Unstage. These files do not require “Mark reviewed” for the commit button.

Optional: configure LLM

Expand LLM (optional) in the sidebar → set provider, model, key → Save LLM settings → Refresh brief. See Optional: LLM polish.

Stage and commit

• Per file: Stage on a card or in the diff modal
• Bulk: Stage all in the Commit panel
• Suggest message → Commit staged

Self-checks and rollback

• Ask yourself — 5 self-checks — prompts before you push
• Rollback — quick reference for git restore, git revert, etc.

---

Compare modes

Mode	Git equivalent	Typical use
working	git diff HEAD (+ untracked where supported)	“What am I about to commit?”
staged	git diff --cached	“What’s already in the index?”
unstaged	git diff	“What’s changed but not staged?”
branch	git diff base...head	Feature branch vs main

Switch mode → Refresh brief.

---

Review, stage, and commit

What “scrutinize” means

Scrutin does not hide other files. It prioritizes a subset:

• Risky paths (secrets, config, migrations, CI/CD, large API surface, etc.)
• If nothing is risky, the largest edits in the current scope

Everything else appears under Other changed files.

Review gate

Commit staged stays disabled until:

1. Every file in Files to scrutinize is Mark reviewed (or the list is empty), and
2. Git has staged changes (git diff --cached not empty)

What gets committed

The button runs git commit with your message. It commits whatever is staged in that repo — including files you staged from “Other changed files” or from the terminal.

Suggested workflow:

Edit files → Refresh brief → Review scrutinize list → Stage (per file or Stage all)
→ Suggest message → Commit staged

---

Optional: LLM polish

Without a key, Scrutin uses Sharpen heuristics (local rules, no API calls).

With a key, summary, why, and self-checks can be enhanced. Configure via UI or .env:

Provider	Environment variables
OpenAI	OPENAI_API_KEY, OPENAI_MODEL
Anthropic	ANTHROPIC_API_KEY, ANTHROPIC_MODEL
Google Gemini	GOOGLE_API_KEY, GOOGLE_MODEL
Groq	GROQ_API_KEY, GROQ_MODEL
Mistral	MISTRAL_API_KEY, MISTRAL_MODEL

Active provider: SCRUTIN_LLM_PROVIDER=openai (or none).

Env file locations (first match wins):

1. SCRUTIN_ENV if set
2. .env in the repo
3. ~/.scrutin/.env (legacy: ~/.reviewpack/.env still read)

Copy .env.example to .env as a starting point.

Privacy: LLM calls send metadata (paths, stats, risk tags) — not full diff bodies.

---

Optional: ignore noisy paths

Create .scrutinignore in the repo root (one pattern per line):

.venv/
node_modules/
dist/
*.egg-info/

Legacy name .reviewpackignore is still honored if .scrutinignore is missing.

---

CLI reference

Terminal-only brief (no UI):

cd ~/your-project
scrutin brief
scrutin brief --json

Modes:

scrutin brief --mode working
scrutin brief --mode staged
scrutin brief --mode unstaged
scrutin brief --mode branch --base main --head HEAD

Server:

scrutin serve
scrutin serve --port 8788 --no-open
scrutin serve --repo /path/to/repo

From a saved diff file:

scrutin brief --diff changes.patch --repo .

---

Troubleshooting

Problem	What to do
scrutin: command not found	pip install scrutin from PyPI or activate the venv where you installed it
Not inside a git repository	cd to the repo root, or run git init
No diff to analyze	Save edits, git add some files, or switch compare mode
UI empty / wrong repo	Set Repository → Detect repo → Refresh brief; or scrutin serve --repo /full/path
Port 8787 in use	Stop old server (Ctrl+C), or scrutin serve --port 8788
Brief only in terminal	Use scrutin serve or scrutin brief --open
LLM panel missing / save fails	pip install -U scrutin; restart serve
Commit button disabled	Mark all scrutinize files reviewed and stage at least one file

Quick command cheat sheet

# Python (PyPI)
pip install scrutin
cd ~/your-project
scrutin serve
# → http://127.0.0.1:8787 → Detect repo → Refresh brief → review → Stage all → Commit staged

curl http://127.0.0.1:8787/health
scrutin brief --json

---