<p>After building a <a href="/ai-security-toolkit.html">security scanning toolkit</a>, I wanted the
same pattern for linting. Tedious rules that slow developers down are trivial for a
coding agent to stick to, and it'll help provide some baseline quality.</p>
<p>I also don't want the agent to ever make a mess, and knowing they love to git commit
constantly, I'm leaning again on pre-commit hooks to keep things deterministic.</p>
<h1 id="megalinter-is-slow">MegaLinter is SLOW</h1>
<p>I tried <a href="https://megalinter.io/">MegaLinter</a> first. It's a
popular containerized linter that bundles 100+ tools. The full
image is 17GB. The "cupcake" flavor with common languages is
10GB. Even the language-specific flavors are 5GB on disk.</p>
<p>The scan took over five minutes on a monorepo with a few
thousand files. That's not something I want AI agents running
on demand. So I built my own.</p>
<h1 id="introducing-kpericakai-lint-toolkit">Introducing kpericak/ai-lint-toolkit</h1>
<p>Cool thing about agentic coding is you can roll your own anything with basically no
effort. I asked it to make me my own faster one, and to run it then fix up my own
project.</p>
<p>Ended up with an image containing four linters, each the fastest in its category:</p>
<table>
<thead>
<tr>
<th>Language</th>
<th>Tool</th>
<th>Written in</th>
</tr>
</thead>
<tbody>
<tr>
<td>Python</td>
<td><a href="https://docs.astral.sh/ruff/">ruff</a></td>
<td>Rust</td>
</tr>
<tr>
<td>JS / TS</td>
<td><a href="https://biomejs.dev/">biome</a></td>
<td>Rust</td>
</tr>
<tr>
<td>Dockerfile</td>
<td><a href="https://github.com/hadolint/hadolint">hadolint</a></td>
<td>Haskell</td>
</tr>
<tr>
<td>Terraform</td>
<td><a href="https://github.com/terraform-linters/tflint">tflint</a></td>
<td>Go</td>
</tr>
</tbody>
</table>
<p>All four are single compiled binaries. No Python runtime, no
Node.js, no JVM. The final image is <strong>282MB</strong>.</p>
<p>Ruff replaces flake8, pylint, isort, and black in one tool.
Biome replaces eslint and prettier. Both are written in Rust
and finish in under a second on this monorepo.</p>
<h1 id="the-dockerfile">The Dockerfile</h1>
<p>Multi-stage build. Copy hadolint and tflint from their
official images, download ruff and biome as release binaries.</p>
<pre><code class="language-dockerfile">FROM hadolint/hadolint:v2.14.0-alpine AS hadolint
FROM ghcr.io/terraform-linters/tflint:v0.61.0 AS tflint

FROM alpine:3.21

ARG RUFF_VERSION=0.15.5
ARG BIOME_VERSION=2.4.6
ARG TARGETARCH

RUN apk upgrade --no-cache

COPY --from=hadolint /bin/hadolint /usr/local/bin/hadolint
COPY --from=tflint /usr/local/bin/tflint /usr/local/bin/tflint

# ruff: Python linter (Rust binary)
RUN if [ "$TARGETARCH" = "arm64" ]; then \
      RUFF_ARCH="aarch64"; else RUFF_ARCH="x86_64"; fi \
    &#x26;&#x26; wget -qO- \
    "https://github.com/astral-sh/ruff/releases/download/\
${RUFF_VERSION}/ruff-${RUFF_ARCH}-unknown-linux-musl.tar.gz" \
    | tar xz --strip-components=1 -C /usr/local/bin

# biome: JS/TS linter (Rust binary)
RUN if [ "$TARGETARCH" = "arm64" ]; then \
      BIOME_ARCH="linux-arm64-musl"; \
      else BIOME_ARCH="linux-x64-musl"; fi \
    &#x26;&#x26; wget -qO /usr/local/bin/biome \
    "https://github.com/biomejs/biome/releases/download/\
%40biomejs%2Fbiome%40${BIOME_VERSION}/biome-${BIOME_ARCH}" \
    &#x26;&#x26; chmod +x /usr/local/bin/biome

RUN addgroup -S linter &#x26;&#x26; adduser -S linter -G linter
RUN mkdir -p /workspace &#x26;&#x26; chown linter:linter /workspace

WORKDIR /workspace
USER linter
ENTRYPOINT ["/bin/sh"]
</code></pre>
<p>The <code>TARGETARCH</code> arg is set automatically by Docker BuildKit,
so the same Dockerfile works on both amd64 and arm64. A
non-root <code>linter</code> user runs the tools. The image builds in
under 10 seconds because every tool is a precompiled binary.</p>
<p>Source:
<a href="https://github.com/kylep/multi/tree/main/infra/ai-lint-toolkit">GitHub</a></p>
<h1 id="asking-ai-agents-to-lint">Asking AI agents to lint</h1>
<p>Same approach as the
<a href="/ai-security-toolkit.html">security toolkit</a>. A <a href="/ruler-cross-tool-ai-rules.html">Ruler</a>
file provides the commands, then <code>ruler apply</code> injects them into CLAUDE.md and any
other tool config.</p>
<p>Note that this is nondetermistic and such not dependable.</p>
<pre><code class="language-markdown"># Linting

The Docker image `kpericak/ai-lint-toolkit:0.1` bundles
ruff, biome, hadolint, and tflint in one Alpine container.

Run from the repo root. Mount the project directory
as /workspace.

## Python (ruff)
docker run --rm -v "$(pwd):/workspace:ro" \
  kpericak/ai-lint-toolkit:0.1 \
  -c "ruff check /workspace --no-cache"

## JavaScript / TypeScript (biome)
docker run --rm -v "$(pwd):/workspace:ro" \
  kpericak/ai-lint-toolkit:0.1 \
  -c "biome lint /workspace/path/to/src"

## Dockerfiles (hadolint)
docker run --rm -v "$(pwd):/workspace:ro" \
  kpericak/ai-lint-toolkit:0.1 \
  -c "find /workspace -name 'Dockerfile*' \
  -not -path '*/node_modules/*' | xargs hadolint"

## Terraform (tflint)
docker run --rm -v "$(pwd):/workspace:ro" \
  kpericak/ai-lint-toolkit:0.1 \
  -c "cd /workspace/path/to/tf &#x26;&#x26; tflint"
</code></pre>
<p>The volume is mounted read-only. Linters don't need to write
to your source tree. Ruff needs <code>--no-cache</code> to skip writing
a cache directory since the mount is read-only.</p>
<p>For biome, point it at specific source directories rather
than the repo root. Otherwise it crawls <code>node_modules</code> and
takes forever.</p>
<h1 id="running-the-linters">Running the linters</h1>
<p>Here's what each tool found on the first scan of this
monorepo.</p>
<h2 id="ruff">ruff</h2>
<pre><code>46  F401  [*] unused-import
13  F841  [-] unused-variable
11  F541  [*] f-string-missing-placeholders
 1  F821  [ ] undefined-name
Found 71 errors.
[*] 59 fixable with the `--fix` option.
</code></pre>
<p>71 findings across all the Python in the monorepo. Most are
in older projects (kytrade, mods) that haven't been touched
in a while. The <code>[*]</code> markers mean ruff can auto-fix them.
Unused imports and f-string placeholders are the bulk of it.</p>
<p>Ruff scanned the entire repo in 0.5 seconds.</p>
<h2 id="biome">biome</h2>
<pre><code>7 lint/suspicious/noDoubleEquals
6 lint/style/noNonNullAssertion
4 lint/style/useConst
1 lint/correctness/useParseIntRadix
1 lint/correctness/noUnusedImports
</code></pre>
<p>19 findings. The double-equals warnings are in the blog's
route handler (<code>==</code> instead of <code>===</code>). The non-null
assertions are in test files for a game project. All fixable.</p>
<p>Biome scanned the JS/TS source in 0.7 seconds.</p>
<h2 id="hadolint">hadolint</h2>
<p>Hadolint found 14 findings across 5 Dockerfiles. The
interesting ones:</p>
<ul>
<li><strong>DL3020</strong>: Use COPY instead of ADD (2 errors in kytrade)</li>
<li><strong>DL3018</strong>: Pin versions in <code>apk add</code></li>
<li><strong>DL3013</strong>: Pin versions in <code>pip install</code></li>
<li><strong>DL4006</strong>: Set <code>SHELL</code> with <code>-o pipefail</code> before piped RUN</li>
</ul>
<p>The security toolkit's own Dockerfile got flagged for the
pipefail issue in its <code>wget | tar</code> pipe. Fair catch.</p>
<h2 id="tflint">tflint</h2>
<pre><code>Warning: terraform "required_version" attribute is required
Warning: Missing version constraint for provider "google"
Warning: [Fixable] data "aws_caller_identity" "current"
  is declared but not used
</code></pre>
<p>4 warnings across 2 Terraform directories. Missing version
constraints and an unused data source. Standard Terraform
hygiene stuff.</p>
<h1 id="size-comparison">Size comparison</h1>
<table>
<thead>
<tr>
<th>Image</th>
<th>Size on disk</th>
<th>Run time</th>
</tr>
</thead>
<tbody>
<tr>
<td>MegaLinter (full)</td>
<td>17 GB</td>
<td>5+ min</td>
</tr>
<tr>
<td>MegaLinter (cupcake)</td>
<td>10 GB</td>
<td>untested</td>
</tr>
<tr>
<td>MegaLinter (javascript)</td>
<td>5 GB</td>
<td>untested</td>
</tr>
<tr>
<td>ai-lint-toolkit</td>
<td>282 MB</td>
<td>&#x3C; 5 sec</td>
</tr>
</tbody>
</table>
<p>The custom image is 60x smaller than MegaLinter's full image
and runs in seconds. The tradeoff is that it only covers four
languages. But those are the four I need, and adding more is
one <code>wget</code> or <code>COPY</code> away.</p>
<h1 id="pre-commit-hooks-as-lazy-ci">Pre-commit hooks as lazy CI</h1>
<p>I already had semgrep and gitleaks running as pre-commit
hooks from the
<a href="/ai-security-toolkit.html">security toolkit</a>. Adding
ruff and biome follows the same pattern.</p>
<pre><code class="language-yaml">repos:
- repo: local
  hooks:
    - id: ruff
      name: Ruff
      entry: >-
        bash -c 'docker run
        -v "$(pwd):/workspace:ro" --rm
        kpericak/ai-lint-toolkit:0.1
        -c "ruff check /workspace --no-cache"'
      language: system
      stages: ["pre-commit"]
    - id: biome
      name: Biome
      entry: >-
        bash -c 'docker run
        -v "$(pwd):/workspace:ro" --rm
        kpericak/ai-lint-toolkit:0.1
        -c "biome lint /workspace/apps/blog/blog/pages
        /workspace/apps/blog/blog/components
        /workspace/apps/blog/blog/utils"'
      language: system
      stages: ["pre-commit"]
    - id: semgrep
      name: Semgrep
      entry: >-
        bash -c 'docker run
        -v "$(pwd):/workspace:ro" --rm
        kpericak/ai-security-toolkit-1:0.2
        -c "semgrep scan --config auto
        --error /workspace"'
      language: system
      stages: ["pre-commit", "pre-push"]
- repo: https://github.com/gitleaks/gitleaks
  rev: v8.30.0
  hooks:
    - id: gitleaks
      stages: ["pre-commit", "pre-push"]
</code></pre>
<p>Every commit now gets linted for Python and JS/TS issues,
scanned for security bugs by semgrep, and checked for
leaked secrets by gitleaks. Four tools, no CI server
required.</p>
<p>Hadolint and tflint aren't in the hooks. Dockerfiles and
Terraform configs change rarely enough that running them
on demand through the AI agent is fine.</p>


Kyle Pericak

Lint Toolkit for AI Agents