Install Scrutin with Python

Use this path when you have Python 3.11+ and git on your machine. Scrutin installs from PyPI and runs a local web server so you can review changes before committing. Prefer no Python? Use the Docker guide instead.

After following these steps, you should be able to:

Run scrutin serve and open the UI at http://127.0.0.1:8787.
Point Scrutin at your git repo, refresh the brief, and review flagged files.
Stage changes and commit from the browser (IDE plugins for VS Code, Cursor, and IntelliJ are coming soon).

Step 1 — Check requirements

Requirement	Notes
Python 3.11+	Runs the Scrutin server and CLI
git	On your `PATH`
A git repository	Existing repo or `git init`—first commit is optional for uncommitted review
Browser (web UI)	Any modern browser

python3 --version
git --version

Step 2 — Install from PyPI

Install into your user environment or an active virtualenv:

pip install scrutin
scrutin --help

If scrutin: command not found, ensure the directory where pip installs scripts is on your PATH, or use python3 -m scrutin.cli --help.

Step 3 — Start the server

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

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:

Repository — full path to your git root (e.g. /Users/you/your-project).
Click ◎ Detect repo if the field is empty or wrong.
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

Read the dashboard (KPIs, risk overview, summary).
In Files to scrutinize, open View diff and click Mark reviewed on each flagged file.
Stage per file or use Stage all in the Commit panel.
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.

IDE plugins — coming soon

Sidebar plugins are not listed on the Marketplace yet. Until they ship, use the browser UI from Steps 3–6 above.

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 you start with scrutin serve—no cloud required.

Optional — LLM polish

Without an API key, Scrutin uses Sharpen heuristics (local rules, no API calls). To enable an LLM, expand LLM (optional) in the sidebar, set provider/model/key, click Save LLM settings, then Refresh brief. Keys are stored in .env in your repo (or ~/.scrutin/.env).

Troubleshooting

Problem	What to do
`scrutin: command not found`	`pip install scrutin` 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
Port 8787 in use	Stop the old server (`Ctrl+C`) or use `scrutin serve --port 8788`
Commit button disabled	Mark all scrutinize files reviewed and stage at least one file

Quick cheat sheet

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

scrutin brief          # terminal-only brief
scrutin brief --json