chisel

Opinionated architecture constraint checker for FastAPI backends. Designed to catch the patterns agents get wrong — use it as a pre-commit hook to block violations, or run it interactively to steer an agent while it's working.

It pairs with agent skills: the skill teaches the agent the right pattern, the checker enforces it deterministically. Run chisel explain <rule-id> to get fix guidance the agent can consume directly.

Installation

pip install chisel

Quick start

chisel check ./backend              # check a project
chisel rules                        # list all ~55 rules grouped by category
chisel explain structural:print-banned  # detailed fix guidance
chisel check . --json               # violations with message refs + skill names
chisel check . --no-strict          # skip src-layout enforcement
chisel update self                  # upgrade the installed CLI package
chisel update skills --target codex # overwrite installed skills with bundled copies

Commands

Agent skills

Install Chisel's bundled skills into a project so coding agents can load the same architecture guidance that the checker enforces:

chisel setup --target codex      # writes .agents/skills/
chisel setup --target claude     # writes .claude/skills/
chisel setup --target opencode   # writes .opencode/skills/

Without --target, chisel setup asks which agent to configure when running interactively. Use --skill qa to install one skill, --dry-run --json to preview, and --overwrite to replace existing skill directories.

Refresh previously installed skills after upgrading Chisel:

chisel update skills --target codex

This overwrites local modifications in the selected skill directories, so Chisel asks for confirmation before writing. Use --yes in automation and --dry-run --json to preview.

Agent-facing JSON output deduplicates repeated violation messages: each violation carries message_ref, and the top-level messages array contains each full message once with its skill_name.

What gets checked

Exceptions

Create a chisel-exceptions.toml at your project root:

[[exceptions]]
files = ["src/legacy/*.py", "src/cli/main.py"]
rules = ["structural:print-banned"]
reason = "CLI requires stdout output"

* matches all rules. A category prefix like structural matches all rules in that category.

Inline suppression per line: # noqa: rule-id — reason.

Severity tiers

How it works

models/         Pure data — Violation, Severity, FileInfo, ProjectInfo
services/       One service per rule category, self-describing via describe_rules()
repositories/   File discovery, import graph analysis (grimp)
controllers/    Orchestrates all services, filters exceptions, suppresses via noqa
factory.py      Zero-logic DI — wires all services into the controller
cli/main.py     Typer-based CLI — check, rules, explain
reporter.py     Coloured terminal output via rich

Adding a rule requires one new check method in a service + one describe_rules() entry. The CLI discovers it automatically.

Development

pip install -e ".[dev]"
pytest tests/ -q

The checker is self-validating: chisel check . --strict produces zero violations on its own source.