An agent-friendly linter: findings your coding agent can act on

The loop an agent runs

1. After its change, it runs alint check --format agent --fail-on-warning.
2. It runs each fix_command in the report.
3. It fixes the other findings by hand, following each agent_instruction.
4. It runs the check again, and stops when alint exits with status 0.

--fail-on-warning makes it stop at the right time: without it, alint exits with 0 when it finds only warnings, and every finding in the run below is a warning. A section in AGENTS.md tells the agent to run the loop:

## Before you finish a task

Run `alint check --format agent --fail-on-warning`. Run each
`fix_command` it lists as `alint <args>`, fix the other findings by
hand, and run the check again until it exits with status 0.

Before and after the loop

A small TypeScript repository set up the way an agent session often leaves one, checked with the config on this page. The tree marks each of the 9findings of alint check on the file it's about.

{  "schema_version": 1,  "format": "agent",  "summary": {    "total_violations": 9,    "by_severity": {      "error": 0,      "warning": 9,      "info": 0    },    "fixable_violations": 2,    "passing_rules": 17,    "failing_rules": 9  },  "violations": [    {      "rule_id": "agents-md-paths-exist",      "severity": "warning",      "file": "AGENTS.md",      "line": 7,      "column": 22,      "human_message": "backticked path `src/checkout.ts` doesn't resolve to a file or directory",      "agent_instruction": "warning: backticked path `src/checkout.ts` doesn't resolve to a file or directory. To resolve: edit AGENTS.md:7:22.",      "fix_available": false    },    {      "rule_id": "ts-final-newline",      "severity": "warning",      "file": "src/coupons.ts",      "human_message": "A TypeScript file doesn't end with a newline",      "agent_instruction": "warning: A TypeScript file doesn't end with a newline. To resolve: edit src/coupons.ts (or run `alint fix --only ts-final-newline` to apply the auto-fix).",      "fix_available": true,      "fix_command": [        "fix",        "--only",        "ts-final-newline"      ],      "proposed_edit": [        {          "path": "src/coupons.ts",          "region": {            "start_line": 2,            "start_column": 37,            "end_line": 2,            "end_column": 37          },          "inserted": "\n"        }      ]    }⋯ 7 more findings  ]}

⋯ 7 more findings warning [ts-final-newline]:  ✓ appended final newline to src/coupons.ts warning [ts-no-trailing-whitespace]:  ✓ trimmed trailing whitespace in src/cart.ts 2 applied, 0 skipped, 7 unfixable.

⋯ 7 more findings warning [ts-final-newline]:  ✓ appended final newline to    src/coupons.ts warning [ts-no-trailing-whitespace]:  ✓ trimmed trailing whitespace in    src/cart.ts 2 applied, 0 skipped, 7 unfixable.

alint fix applies every fix at once; each report entry's fix_command applies one rule's. The other 7 findings need an edit. The second run follows the edits an agent following each agent_instruction would make: deleted PLAN.md and src/cart_old.ts, took out the console.log and the TODO signed by a model, pointed AGENTS.md at src/cart.ts, and pinned the workflow's checkout action and made its token read-only.

{  "schema_version": 1,  "format": "agent",  "summary": {    "total_violations": 0,    "by_severity": {      "error": 0,      "warning": 0,      "info": 0    },    "fixable_violations": 0,    "passing_rules": 26,    "failing_rules": 0  },  "violations": []}

No findings, and alint exits with status 0: here an agent would stop.

The config

For a TypeScript repository, and the one every run above used. For another language, change the paths of the last two rules.

version: 1
extends:
  - url: alint://bundled/agent-context@v1
    except: [agent-context-no-stale-paths]
  - alint://bundled/agent-hygiene@v1
  - alint://bundled/hygiene/no-tracked-artifacts@v1
  - alint://bundled/ci/github-actions@v1

rules:
  - id: agents-md-paths-exist
    kind: markdown_paths_resolve
    paths: ["AGENTS.md"]
    prefixes: ["src/", "tests/"]
    level: warning

  - id: ts-final-newline
    kind: final_newline
    paths: "src/**/*.ts"
    level: warning
    message: "A TypeScript file doesn't end with a newline"
    fix:
      file_append_final_newline: {}

  - id: ts-no-trailing-whitespace
    kind: no_trailing_whitespace
    paths: "src/**/*.ts"
    level: warning
    message: "A line in a TypeScript file ends with spaces"
    fix:
      file_trim_trailing_whitespace: {}

version: 1
extends:
  - url: alint://bundled/agent-context@v1
    except: [agent-context-no-stale-paths]
  - alint://bundled/agent-hygiene@v1
  - alint://bundled/hygiene/no-tracked-artifacts@v1
  - alint://bundled/ci/github-actions@v1

rules:
  - id: agents-md-paths-exist
    kind: markdown_paths_resolve
    paths: ["AGENTS.md"]
    prefixes: ["src/", "tests/"]
    level: warning

  - id: ts-final-newline
    kind: final_newline
    paths: "src/**/*.ts"
    level: warning
    message: "A TypeScript file doesn't end with a newline"
    fix:
      file_append_final_newline: {}

  - id: ts-no-trailing-whitespace
    kind: no_trailing_whitespace
    paths: "src/**/*.ts"
    level: warning
    message: "A line in a TypeScript file ends with spaces"
    fix:
      file_trim_trailing_whitespace: {}

What makes the agent run it

The section in AGENTS.md is a request, and an agent can skip it, more often late in a long session (Chroma found models get less reliable as their input grows). These three run the same check whether the agent remembers or not.

- uses: asamarts/alint@c08c68be72e0c3a3a02051bd15f4a7d768fa5cbe # v0.18.2
  with:
    version: v0.18.2
    fail-on-warning: true

The GitHub Action fails the pull request until the findings are fixed. The step is pinned to the release's commit, and version: keeps the binary at the same release.

repos:
  - repo: https://github.com/asamarts/alint-pre-commit
    rev: v0.18.2
    hooks:
      - id: alint
        args: [--fail-on-warning]

The pre-commit hook checks every commit, the agent's included, and refuses the commit while there are findings.

{ "hooks": { "Stop": [{ "hooks": [{ "type": "command", "command": "alint check --format agent --fail-on-warning >&2 || exit 2" }] }] } }

In Claude Code, a Stop hook runs when the agent is about to finish. Exit status 2 keeps the session going and gives the agent the report. A finding the agent can't fix keeps it going too, so use it with rules an agent can act on.

AGENTS.md from your config

alint export-agents-md turns the rules in your config into a section for AGENTS.md, one line per rule, from each rule's message. With --inline it writes the section into the file, between its start and end markers, and leaves the rest of the file alone:

<!-- alint:start -->

## Lint rules enforced by alint

Generated from `.alint.yml` by `alint export-agents-md`. Re-run after editing the lint config - these directives must stay in sync with what alint blocks at commit time. Manual edits inside this section are overwritten.

### Errors (commit will fail)

- **`agent-no-debugger-statements`**: `debugger;` / `breakpoint()` must not be committed. These halt execution at runtime. Remove before merge.
- **`hygiene-no-cargo-target`**: dir_absent rule on **/target
- **`hygiene-no-env-files`**: Environment files containing real values must not be committed. Use `.env.example` (or similar) for shared non-secret defaults.
- **`hygiene-no-macos-junk`**: macOS Finder metadata must not be committed.
- **`hygiene-no-node-modules`**: `node_modules/` must not be committed. Add it to .gitignore.
- **`hygiene-no-python-cache`**: Python caches and virtualenvs must not be committed.
- **`hygiene-no-windows-junk`**: Windows shell metadata must not be committed.

### Warnings (review before merge)

- **`agent-context-non-stub`**: Agent-context file is suspiciously short. Either fill it in with real guidance or remove it. Empty context files mislead agents that load them.
- **`agent-no-console-log`**: `console.log` / `.debug` / `.trace` left in non-test source. Route through the project logger or remove before merge.

The section goes on the same way for 12 more rules: 21 of the config's26, since the 5 at level: info are left out (--include-info adds them). Run it again when .alint.yml changes, or in CI, so the file never lists rules CI no longer checks.