Skip to main content
This guide gets Strata running against a Python repository, explains the configuration it needs, and walks through reading its output.

​
Prerequisites

  • Python 3.12 or newer.
  • A Python repository with a src/-style package layout.
The PyPI distribution is named stratalint; the command it installs is strata. You install stratalint once and type strata from then on.

​
1. Install

pip install stratalint
Install Strata into the same environment as the project you want to check. Because Strata parses your code with the interpreter it runs under, running it in the project’s environment means it parses the project’s syntax by construction.

​
2. Configure

Strata reads a strata.toml from your repository, or a [tool.strata] table in pyproject.toml. Create a strata.toml at the repository root: 
roots = ["src/my_package"]
tests = ["tests"]
tooling = ["scripts"]
Each key declares a scope that receives a different set of rules:
KeyScopeWhat it gets
rootsProduct codeThe full structural rule set: layers, roles, shape, naming, hygiene, annotations. Required.
testsTest suiteTest-convention rules and annotation rules. Defaults to ["tests"].
toolingDev toolingThe same structural rules as product roots, at one less nesting level. Optional.
roots is the only required key and must not contain nested or overlapping paths. Anything outside all three scopes is not scanned. That is the whole minimal config. By default every Strata rule family is on, so you do not select anything to get started. When you want to narrow what runs, use select and ignore; see choosing rules for how. Full schema in Configuration.

​
3. Check

Run Strata against the configured repository: 
strata check
If everything conforms, Strata prints a summary and exits 0: 
Found 0 faults
When Strata 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: 
SFA002  function 'run' must define a return type annotation
 --> src/my_package/main/run.py:5:0
  |
5 | def run(a, b):
  | ^
  |
  = help: Declare the returned value type, using None when the function returns no value.

SFS120  function has 2 positional parameters
 --> src/my_package/main/run.py:5:0
  |
5 | def run(a, b):
  | ^
  |
  = help: Insert * before optional or secondary parameters so call sites name their meaning.
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. You can also check specific paths instead of the configured roots by passing them as arguments: 
strata check src/my_package/main

​
4. Inspect a rule

Any code in the output can be looked up in full: 
strata rule SFS120

SFS120 keyword-only-arguments
Family: shape
Severity: error
Kind: core
Enabled by default: yes
Source: core
Message: ...
Remediation: ...
See strata rule for details.

​
5. Choose which rules run

Every family is on by default. To narrow that, use select and ignore in your config. They take family prefixes (SFL, SFS, …) and individual rule codes (SFS120), the same way you would in a tool like ruff. 
# Run only some families:
select = ["SFL", "SFR", "SFS", "SFN"]

# Or run everything except a few rules:
select = ["SF"]
ignore = ["SFX007", "SFA103"]

# Or run only a hand-picked set of rules:
select = ["SFL001", "SFL101", "SFS120"]
See choosing rules for how selection composes. Rolling Strata out on an existing codebase rather than a new one? See Adopting Strata for a gradual approach.

​
6. See the shape

Where strata check enforces structure, strata map renders it. Point it at a function to get a deterministic downstream call tree: 
strata map run

run(...)  src/my_package/main/run.py:5
├── load(...)  src/my_package/main/load.py:8
└── render(...)  src/my_package/main/render.py:12
strata map does not require Strata configuration or rule adoption, so you can use it on any repository. Locations are repository-relative by default so editors like VS Code can make them clickable. See strata map for depth, path, and import-root options.

​
7. Generate agent guidance

If agents work in your repository, generate skill files from your active rules so their instructions stay in sync with what CI enforces: 
strata skills update
This installs a SKILL.md for each supported agent. See strata skills.

​
Next steps

Architecture model

The scopes, roles, and default layout Strata enforces.

Configuration

Every configuration key, threshold, and contract.

Rule families

What each family (SFL, SFR, SFS, SFN, SFX, SFT, SFA) checks.

Philosophy

Why Strata is strict by default and how to deviate deliberately.