Introducing alint: a fast, language-agnostic linter for your repository's structure

June 3, 2026

alint is an open-source, language-agnostic linter for the shape of a repository: which files exist, how they are named, what they contain, and how they relate to one another. You declare those rules once in a .alint.yml, and alint enforces them in CI, in your editor, or for an AI coding agent. It is a single static Rust binary that reads filesystem structure and file contents rather than parsing your code.

What is alint?

Every repository runs on rules that no compiler or code linter ever checks. Does every package have a README? Is a build directory like node_modules or target/ committed by mistake? Does the version in your changelog match the latest tag? Do your GitHub Actions pin third-party actions to a commit SHA? Most teams already encode a few of these, often as hand-rolled scripts wired into CI. Those work, but they tend to be slow, brittle, and a chore to keep current, and they seldom outlive the person who wrote them.

You declare them in one file:

version: 1
extends:
  - alint://bundled/oss-baseline@v1       # README, LICENSE, SECURITY, hygiene
  - alint://bundled/rust@v1               # auto-skips when there is no Rust
  - alint://bundled/ci/github-actions@v1

alint check runs every rule against the working tree; alint fix repairs the mechanical ones, like trailing whitespace and missing final newlines. There are more than 80 rule kinds and 21 bundled rulesets, so most repos start from a one-line extends: and add a handful of rules of their own.

Point it at a real codebase and it surfaces things code-level tools never look for. On the Flutter repository it flagged Unicode bidi-control characters, the CVE-2021-42574 “Trojan Source” class, that had been sitting in archived docs since the bug was disclosed in 2021. On kubernetes, a stack of the hand-written hack/verify-*.sh scripts turn out to be structural checks you can declare in a few lines instead of maintaining as code. Both are written up, with the config and the findings, under examples.

The problem: the rules your repo assumes but never checks

Most conventions never make it into a script at all. They live in a senior reviewer’s head and get caught in review, when the right person is paying attention. That holds up until they go on leave, a new contributor never learns the unwritten rule, and the convention quietly erodes. The ones that do get scripted have the opposite problem: they keep working, but they ossify, and nobody wants to touch them.

alint moves both kinds into one declarative file that runs on every pull request, the same way a code linter runs on every commit. Because it is a single Rust binary that reads the tree directly, it stays fast even on a large repo, where a stack of shell scripts would not.

Where alint fits

alint is deliberately narrow. It checks a repository’s structure and file contents, not the meaning of the code inside it, so it sits alongside your existing tools rather than replacing them.

The closest prior tool was Repolinter, which the TODO Group archived in February 2026. alint covers its structural checks and adds many more; there is a migration guide and a full comparison if you want the detail.

alint and AI coding agents

This is the part I reach for most day to day. Coding agents write code well and forget a repository’s conventions constantly, so they reintroduce the same mess you just cleaned up. AGENTS.md helps, but it drifts from what your CI actually enforces.

alint closes that gap from both sides. alint export-agents-md writes an AGENTS.md block straight from the rules alint enforces, so the agent reads the same rules your pipeline does. alint check --format agent emits each finding as JSON with a per-violation instruction the agent can act on. That gives you one source of truth for yourself, your CI, and the agent. There is more on the agent-friendly linter page.

How fast is it?

Fast enough that it is never the slow part of CI. alint runs a full rule pass across a 39,000-file checkout of nixpkgs in about 273 milliseconds, and stays under a second on a 100,000-file repository. It is a single static binary with no runtime to install, so it behaves the same on your laptop and in CI. The per-release benchmarks are published in full.

Try it

curl -sSL https://raw.githubusercontent.com/asamarts/alint/main/install.sh | bash
cd your-repo
alint init        # detects your ecosystem and writes a starter .alint.yml
alint check

It is also on Homebrew, crates.io, and npm, and ships as a Docker image and a GitHub Action. The current release is v0.11: the rule engine is stable and runs in alint’s own CI, while the config format is still settling toward 1.0, so adopting it now means your feedback shapes where it lands. The docs have the full rule catalogue and a cookbook, and the source is on GitHub under MIT or Apache-2.0. If your repository leans on a convention it never actually checks, I would like to hear which one.