Code review is dead. Review intent instead.
AI writes code faster than any human can read it. In the age of generative code, checking diffs is a fool's errand. Sigil moves the "peer" in peer review up the stack: specs, ADRs, and architectural constraints live in your repo as a queryable graph. Every PR gets an intent diff — what decisions changed, what specs apply, what gates failed. Humans agree on the why; Sigil enforces the what.
Try the live demo →·Install·Quickstart
# See what Sigil looks like on a real codebase — no setup required
sigil demoOr run it on your own repo:
cd your-project && sigil init
# Scans your repo, builds the knowledge graph, opens the viewerThat's the shift: intent lives in Git, not in Slack. Specs and decisions are first-class artifacts, queryable and diffable. Gates block PRs that violate what was agreed on. Your codebase can never drift from the plan — because the plan is enforced.
Click any node to see the full reasoning. Trace from a component through its specs, decisions, and gates. Ask "why does this file exist?" and get a real answer:
$ sigil why services/auth/auth.py
Owned by: Auth Service (COMP-auth-service)
What is being built:
[accepted] SPEC-0002: JWT Authentication
| Give users a way to sign up, log in, and prove their identity to
| other services. Using stateless JWT tokens so services can verify
| requests without calling back to auth on every request.
Why it was built this way:
[accepted] ADR-0002: Use JWT tokens instead of server-side sessions
| Use JWT-style tokens signed with HMAC-SHA256. Each service can
| verify tokens independently without a shared session store.
What enforces it:
GATE-0002: Auth service must hash passwords, never return them in plaintextMap blast radius before touching anything:
$ sigil impact COMP-payment-gateway
Direct (2)
→ ● GATE-0005 Payment gateway must never handle raw card numbers (PCI)
← ◆ SPEC-0009 Payment Processing
Secondary (4)
→ ■ COMP-order-service Order Service
→ ◈ API-PAYMENTS-V1 Payments API
→ ◆ SPEC-0004 Checkout Flow
→ ◈ API-AUTH-V1 Auth API
==================================================
Blast radius: 21 nodes — 1 adr, 5 components, 3 gates, 5 interfaces, 1 rollout, 6 specsKnow what breaks before you write a line.
Once specs are agreed on, gates enforce them. When code ships:
- CI gates block merges that violate stated constraints — pattern checks, coverage thresholds, dependency rules
- PR comments surface which specs govern the changed code, which gates passed or failed, which files have no architectural owner
- Drift detection flags code that exists outside the intent graph — no owner, no spec, no constraint
The real moment is when a gate fails:
GATE GATE-0005: Payment gateway must never handle raw card numbers
kind: pattern | policy: block | scope: 3 node(s)
FAIL services/payments/checkout.py: forbidden pattern 'raw_card_number' found (1 match(es))
Gates: 4 passed, 1 failed, 0 warning(s)
A developer touched the payment service. The diff looked clean. But the gate caught a raw card number access — a pattern forbidden by PCI constraint, written once three sprints ago. PR blocked until the intent is updated.
That's the loop: specs define intent, gates enforce it, code can't drift.
# Recommended: install as a global tool
uv tool install git+https://github.com/fielding/sigil.git
# or: pipx install git+https://github.com/fielding/sigil.git# or: pip install git+https://github.com/fielding/sigil.gitRequires Python 3.11+.
Note:
pip install sigil-cli(PyPI) coming soon. Install from GitHub in the meantime.
Install from source (contributors)
git clone https://github.com/fielding/sigil.git
cd sigil && pip install -e .Want to see what Sigil looks like on a real codebase before setting it up on your own? Run:
sigil demoOpens the full intent graph for a bookstore app — 9 services, 36 nodes, 87 edges — in your browser. No cloning required. Click around, explore the views, then come back when you're ready to set it up on your own project with sigil init.
No install? Open the live demo →
Once you've seen the demo, set it up on your own project:
cd your-project
sigil initScans your repo, scaffolds the structure, detects components from package manifests, builds the knowledge graph, and opens an interactive viewer.
Sigil tracks five things. That's it.
| What | In plain English | Example |
|---|---|---|
| Component | A service or module in your system | auth-service, payment-gateway |
| Spec | The plan for what you're building and why | "Token refresh flow" — intent, constraints, acceptance criteria |
| Decision (ADR) | Why you chose one approach over another | "Use JWT with short-lived tokens" — context, options, outcome |
| Gate | A rule that must pass before code ships | "Auth tokens must expire within 1 hour" — enforced in CI |
| Interface | An API contract or event schema | API-ORDERS-V1 — the surface area between services |
These connect into a graph with typed edges (depends_on, gated_by, decided_by, ...). That graph is what makes everything queryable, diffable, and visible.
Alignment. Write specs before code. Sigil structures them into a graph that both product and engineering can review together. Gaps are visible. Missing specs show up red. Interfaces without consumers are flagged. Everyone sees the same picture before a sprint starts.
Structure. Specs, decisions, gates, and interfaces follow templates with typed frontmatter. Intent lives next to code, not in a wiki nobody checks.
Connections. Everything links. Ask sigil why src/auth.ts and trace from file to component to spec to decision. Ask sigil ask "payment processing" and search your architecture like a knowledge base.
Enforcement. Gates block merges that violate your stated intent. Pattern checks, coverage thresholds, lint rules — defined once in YAML, enforced forever in CI with sigil ci.
Visibility. Eight interactive views in a bundled browser UI:
| View | Key | Shows |
|---|---|---|
| Graph | g | Force-directed knowledge graph |
| Impact Radar | r | Blast radius of any node |
| Hierarchy | h | Components → Specs/Gates → Decisions |
| Coverage | c | Health score (0–100%) |
| Drift | d | Where code and intent have diverged |
| Timeline | t | Git-backed intent evolution |
| Matrix | m | Dependency heatmap |
| Review | w | Governance snapshot |
Command palette (Cmd+K), keyboard nav (j/k, / to search), live reload via sigil serve.
Before writing any code:
# Register a service
sigil new component auth-service --owner platform-team
# Write the spec for what you're building
sigil new spec auth-service "Token refresh flow"# Record the key architectural decision
sigil new adr auth-service "Use JWT with short-lived tokens"# Define the interface contract
sigil new interface auth "API-AUTH-V1"# Set the constraint that must hold forever
sigil new gate "Auth token expiry" --applies-to COMP-auth-service
# See the full picture of what the team has agreed to build
sigil serveOnce specs are agreed on, write the code. Then:
# Check all gates pass
sigil check
# See intent graph health
sigil statusOnce specs are agreed on, gates enforce them automatically. One step in your GitHub Actions workflow:
- uses: fielding/sigil@v1with:
github-token: ${{ secrets.GITHUB_TOKEN }}On every push, Sigil runs gate enforcement and coverage checks. On every PR, it posts an intent analysis comment: coverage percentage, governed vs. ungoverned changes, gate results, and links to the intent graph.
Add strict: true to fail on warnings:
- uses: fielding/sigil@v1with:
github-token: ${{ secrets.GITHUB_TOKEN }}strict: trueManual install (advanced)
- run: pip install sigil-cli
- run: sigil ci
- run: sigil pr ${{ github.event.pull_request.number }}if: github.event_name == 'pull_request'env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}The commands you'll use most:
sigil init Scaffold, index, open viewer — zero to working
sigil status Terminal dashboard with health bar and stats
sigil serve Dev server with live reload
sigil check Run gate enforcement
sigil drift Find where code and intent have diverged
sigil review Analyze git diff for intent coverage
sigil why Trace the full intent chain for any file
sigil ask Search intent docs with natural language
sigil impact Show blast radius of a node
sigil ci Full CI pipeline in one command
sigil pr Post intent analysis to a GitHub PR
Full command reference with all flags and examples: docs/CLI.md.
All commands
| Command | Description |
|---|---|
init | Zero-to-working setup: scaffold, index, and open viewer |
index | Build the knowledge graph from your repo |
status | Terminal dashboard with health bar and stats |
serve | Dev server with file watching and auto-rebuild |
new | Create a new spec, ADR, component, gate, or interface |
lint | Check intent docs for structural issues |
fmt | Normalize intent doc formatting |
bootstrap | Scan repo and create missing component stubs |
scan | Deep-scan: detect components, APIs, decisions, infra |
diff | Compute graph changes between commits |
drift | Compare intent graph against actual code |
check | Run gate enforcement checks |
review | Analyze git diff for intent coverage |
suggest | Show which intent docs govern a file |
ask | Search intent docs with natural language |
why | Trace why a file exists through the intent chain |
map | Terminal-rendered dependency map |
impact | Show blast radius of a node in the graph |
timeline | Build evolution history from git log |
export | Generate self-contained HTML snapshot |
badge | Generate coverage badge SVG |
hook | Install/uninstall git pre-commit hook |
pr | Analyze GitHub PR and post intent coverage comment |
doctor | Diagnose installation and repo health |
ci | Full CI pipeline in one command |
watch | Watch intent files and re-index on change |
After sigil init:
components/ What your system is made of (YAML)
intent/ Why it's built this way
{component}/
specs/ Plans: what we're building and constraints
adrs/ Decisions: why we chose this approach
rollouts/ How we're shipping it
interfaces/ Contracts between services
gates/ Rules that must pass before code ships
templates/ Scaffolding for new docs
.intent/ Generated artifacts (gitignored)
Available in tools/sigil-vscode/ with intent graph integration, inline diagnostics, and CodeLens for intent links.
See CONTRIBUTING.md for development setup, testing, and contribution guidelines.
MIT