Quick start

Get a deterministic architecture check running on a project in five minutes. Both CLIs work the same way; pick the one that matches your stack.

Python (FastAPI)

pip install chisel
chisel check ./your-backend

TypeScript (SvelteKit)

npm install -g chisel-js
chisel-js init ./your-frontend      # once: detects the topology
chisel-js check ./your-frontend

Install

Both CLIs are standalone; install one or both depending on what you ship.

Python

pip, pipx, or uv:

pip install chisel            # or: pipx install chisel
chisel --version

TypeScript

npm or bun:

npm install -g chisel-js      # or: bun add -g chisel-js
chisel-js --version

Run a check

Point the checker at your project root. Non-zero exit on any ERROR-level violation, perfect for gates.

Python

chisel check ./your-backend
chisel check ./your-backend --strict   # also enforce src-layout + build config

TypeScript

chisel-js init ./your-frontend         # once, before the first check
chisel-js check ./your-frontend

init works out whether the project is a standalone SSR app (Drizzle under $lib/server) or a BFF over a separate API, and writes chisel.config.json. That decides which rules apply. Pass --mode sveltekit-bff to set it yourself.

Checking without a config still works — chisel-js detects a mode, says so, and points you at init.

Read the violations

Coloured, grouped output by default. For scripts or agents, ask for JSON: repeated messages are deduplicated and each carries a message_ref / messageRef plus the skill_name / skillName that teaches the pattern.

chisel check . --json
# or: chisel-js check . --json

Get fix guidance for one rule

explain prints the rule description and the fix an agent should apply. Accepts a rule ID or a category prefix.

chisel explain structural:isinstance-banned
chisel explain structural            # every rule in a category
chisel-js explain component-enforcement:raw-button

Install the matching skills

The checker pairs with bundled agent skills. Install them once per repo so your agent has the same patterns the checker enforces.

Python

chisel setup --target codex      # .agents/skills/  (Codex + OpenCode)
chisel setup --target claude     # .claude/skills/  (Claude Code)
chisel setup --target opencode   # .opencode/skills/

TypeScript

chisel-js update skills --target codex
chisel-js update skills --target claude
chisel-js update skills --target opencode

Run with no --target in an interactive terminal to pick the destination from a prompt. Chisel installs one target format per run to avoid duplicate skill discovery in tools like OpenCode.

Wire a pre-commit hook (optional but recommended)

Block violations before they land. The short version:

.pre-commit-config.yaml

repos:
  - repo: local
    hooks:
      - id: chisel
        name: chisel
        entry: chisel check . --strict
        language: system
        pass_filenames: false

See Block violations before commit for the full config, including the TypeScript hook.

---

Next: Understand the loop →