llms.txt git:20260701.81de30eA

Immutable. This exact content is served forever at /api/v1/blob/a7707f88a7deb232.

# IronLint

> IronLint is a local, static policy gate for AI coding agents: every proposed edit runs the shell checks from a trusted `.ironlint.yml` before it lands, and any nonzero exit (1–125) blocks the write. A machine-readable verdict with stable exit codes makes the result consumable by CI and agent adapters.

A check is a file glob plus a shell command (or a `steps:` sequence). IronLint hands the command the proposed content on stdin plus a small env ABI (`$IRONLINT_FILE`, `$IRONLINT_FILES`, `$IRONLINT_ROOT`, `$IRONLINT_EVENT`, `$IRONLINT_TMPFILE`) and reads back only the exit code — no engines, no severities, no output parsing; the check owns the decision. Checks fire on two lifecycles: `write` (per edit, pre-landing) and `pre-commit` (once over the staged set). An out-of-repo trust store means an unblessed config never runs. The verdict JSON (schema 5) and the append-only `.ironlint/log.jsonl` telemetry log are versioned wire formats consumed by CI and by agent adapters (Claude Code, OpenCode, pi, Reasonix).

## Start here

- [Documentation index](docs/README.md): table of contents for every guide and reference.
- [Getting started](docs/getting-started.md): install the binary, scaffold a `.ironlint.yml`, and gate your first edit.
- [Architecture](docs/architecture.md): how config, the trust store, the check runner, and the verdict fit together (with a diagram).

## Reference

- [CLI reference](docs/reference/cli.md): every subcommand and flag — `check`, `trust`, `validate`, `init`, `explain`, `show-resolved-config`, `doctor`, `schema`, `watch`, `update`.
- [Config schema](docs/reference/config-schema.md): the `.ironlint.yml` format — `checks:` entries with `files`, `run` or `steps`, `on`, `name`, plus `extends:` and `execution:`.
- [Verdict JSON](docs/reference/verdict-json.md): the machine-readable verdict wire format (schema 5), statuses, and the exit-code contract (0/1/2/3).
- [show-resolved-config](docs/reference/show-resolved-config.md): print the post-`extends:` merged check set, attributing each check to its source file.

## Writing checks

- [Anatomy of a check](docs/writing-checks/README.md): `files`, `run`/`steps`, the stdin/env ABI, and the exit-code contract.
- [Check recipes](docs/writing-checks/recipes.md): grep checks, linters over stdin, and whole-tree tools.

## Configuring

- [Targeting files](docs/configuring/targeting-files.md): the `files:` glob semantics each check matches.
- [Disabling a check in-line](docs/configuring/disabling.md): `ironlint-disable:` directives.
- [Sharing config with extends](docs/configuring/inheritance.md): compose `.ironlint.yml` files across repos; local checks win on collision.

## Operating

- [Running checks](docs/operating/running-checks.md): `ironlint check` in file and diff modes, exit codes, and fail-open behavior.
- [Inspecting your config](docs/operating/inspecting-config.md): debug scope and check resolution with `explain` / `show-resolved-config`.
- [Telemetry](docs/operating/telemetry.md): the append-only `.ironlint/log.jsonl` check log.
- [Diagnostics](docs/operating/diagnostics.md): `ironlint doctor` environment, config, and adapter health checks.

## Adapters

- [Adapters overview](docs/adapters/README.md): the shared adapter contract — the check ABI, exit codes, and fail-open-on-internal-error behavior.
- [Claude Code adapter](docs/adapters/claude-code.md): the PostToolUse plugin that gates `Edit`/`Write`.
- [OpenCode adapter](docs/adapters/opencode.md): the `tool.execute.before` plugin gate.
- [Reasonix adapter](adapters/reasonix/README.md): the PreToolUse hook for DeepSeek-Reasonix.
- [pi adapter](adapters/pi/README.md): the `tool_call` pre-write gate for pi.

## Security

- [The trust store](docs/security/trust.md): why IronLint refuses an unblessed config, and how `ironlint trust` works.

## Optional

- [Visual elevator pitch](docs/visual-elevator-pitch.md): a one-screen visual overview.
- [Changelog](CHANGELOG.md): release notes.
- [Repo guidance (AGENTS.md)](AGENTS.md): conventions for contributors and coding agents working in this repo.