Quickstart

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 with --yes --name NAME and keep everything on from the first commit. On a small existing repo, run fensu init --yes in your pyproject.toml directory, then drive the faults to zero (a coding agent can handle these easily). That single pass is where Fensu pays off most. Larger codebases need more judgment; see Adopting Fensu.

1. Install

pip install fensu
fensu --version

Fensu needs Python 3.12 or newer.

The fensu distribution provides the Python authoring/API surface and installs the lockstep fensu-cli binary distribution, which owns the fensu command. Use that executable for built-in commands; python -m fensu is retired. See the CLI execution model for native commands and custom-rule hosting.

Fensu includes a compiled analysis core. Prebuilt wheels cover Linux (x86_64 and aarch64), macOS (Intel and Apple silicon), and Windows (x86_64). Where no compatible wheel is available, pip builds from source; this requires Rust 1.95 or newer, including when installing fensu-cli from its source distribution.

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 installs agent skill files:

fensu init --yes

The native initializer is non-interactive. For an empty repository with no code, run fensu init --yes --name my_package; init scaffolds a src/ package and tests/ directory. Pass --no-skills only when automation explicitly needs configuration without repository-local agent guidance.

Existing configuration is preserved: init changes nothing when fensu.toml already exists. Use fensu skills to install or refresh guidance for a configured project. See fensu init for detection and setup options, or the Rust and TypeScript/SvelteKit guides for language-specific configuration.

Verify that every generated local skill is present and current before calling onboarding complete:

fensu skills --check

Prefer to write configuration by hand? A minimal fensu.toml only needs your product roots:

roots = ["src/my_package"]

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:

fensu check

If everything conforms, Fensu prints a summary and exits 0:

Found 0 faults

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:

FFL102  import 'my_package.payments.processing._helpers.charge_card' reaches into internal structure of 'my_package.payments'
 --> src/my_package/orders/checkout/main/place_order.py:1:0
  |
1 | from my_package.payments.processing._helpers.charge_card import charge_card
  | ^
  |
  = help: Import from classes, models, types, constants, exceptions, or a thin main/ entry.

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>.

4. Optional: look for duplicated code

fensu check cannot see that two valid functions are the same logic. Run the advisory duplicated-code report to find copies that may have drifted apart:

fensu dupes

It exits 0 whatever it finds, so there is nothing to fix before you move on. See Duplicated code for how to read the clusters.

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 or upstream call tree for any function.

fensu skills

Generate and verify agent guidance from your active rules.