Skip to main content
This guide gets Fensu running against a Python repository and walks through reading its output.
Fastest wins. On a brand-new repo, run fensu init and keep everything on from the first commit. On a small existing repo, run fensu init in your pyproject.toml directory, then drive the faults to zero (a coding agent handles can handle these easily). That single pass is where Fensu pays off most. Larger codebases need more judgment; see Adopting Fensu.

​
1. Install

Fensu needs Python 3.12 or newer.

​
2. Initialize

fensu init is the fastest way to start. It detects your layout, writes a fensu.toml with the full ruleset enabled, runs a first check to show current drift, and offers to install agent skill files:
If you accept the prompts, your repository is configured and you can start checking right away. For an empty repository with no code yet, init scaffolds a src/ package and tests/ directory; pass --yes --name my_package to run it non-interactively. Prefer to write configuration by hand? A minimal fensu.toml only needs your product roots:
tests defaults to ["tests"], tooling is optional, and every rule family is on by default. See Configuration for scopes, selection, and the full schema.

​
3. Check and read a fault

Run Fensu against the configured repository:
If everything conforms, Fensu prints a summary and exits 0:
When it finds a problem, it prints a diagnostic for each fault and exits 1. The output points at the exact line, shows the source, and explains the fix:
Every diagnostic has two parts: the message states the contract that was violated, and the = help: line states the normal correction. The messages are written to be read at the moment of violation, by a person or an agent, so the fix is clear without opening the docs. Look up any code in full with fensu rule <CODE>.

​
Next steps

Architecture model

The scopes, roles, and default layout Fensu enforces.

Configuration

Every configuration key, threshold, and contract.

Rule families

What each family (FFL, FFR, FFS, FFN, FFH, FFT, FFA) checks.

Adopting Fensu

Rolling out on a new, small, or large repository.

fensu map

Render a deterministic downstream call tree for any function.

fensu skills

Generate and verify agent guidance from your active rules.