# lintlang: canonical handoff

This stable Hermes Labs URL is a backward-compatible handoff for agents and developers.

- Product home: https://lintlang.ai/ is the LintLang product URL. Everything below is a Hermes Labs page about that product, a documentation deep link, or a source of record.
- Product page and quick start on hermes-labs.ai: https://hermes-labs.ai/lintlang
- Add LintLang to an existing MegaLinter workflow: https://hermes-labs.ai/lintlang#megalinter
- FAQ and comparison with Agent Lint, promptfoo, Giskard, and NVIDIA NeMo Guardrails (jobs and boundaries, official sources, JSON at https://hermes-labs.ai/lintlang/faq.json): https://hermes-labs.ai/lintlang/faq
- Canonical README, current behavior, and limitations: https://github.com/hermes-labs-ai/lintlang#readme
- Source: https://github.com/hermes-labs-ai/lintlang
- PyPI: https://pypi.org/project/lintlang/
- Browser playground: the site still runs its verified 0.6.0 wheel; the current install commands below use 0.8.2.

## Install

```bash
pip install lintlang==0.8.2
```

Python 3.10+. lintlang is a deterministic static linter for AI agent configs, tool descriptions, and system prompts; no model or network call occurs in its analysis path.

## H1.6 pairwise differentia

Two tool descriptions can each be valid and still fail as a pair. H1.6 compares tool definitions within one parsed input and reports mutual no-differentia or one-sided domination under a finite term-and-synonym model.

H1.6 is a MEDIUM static finding. It does not aggregate definitions across files or establish runtime tool-selection improvement.

## Run once or add to Code Scanning

Run LintLang once without installing it:

```bash
uvx --from lintlang==0.8.2 lintlang scan AGENTS.md
```

To check every recognized instruction file in a repository, use discovery:

```bash
uvx --from lintlang==0.8.2 lintlang scan --discover .
```

Discovery finds AGENTS.md, CLAUDE.md, GEMINI.md, SKILL.md, agent.yaml/.yml/.json and GitHub Copilot instruction files. Names are case-sensitive, and other layouts such as Cursor rules need an explicit path. What gets scanned: https://lintlang.ai/docs/inputs

Version 0.8.2 can also emit deterministic SARIF 2.1.0 for GitHub Code Scanning:

```bash
lintlang scan AGENTS.md --format sarif --fail-on fail > lintlang.sarif
```

The maintained copy-paste workflow and its permissions boundary are documented at https://github.com/hermes-labs-ai/lintlang/blob/main/docs/github.md#code-scanning. SARIF makes findings ingestible by compatible tools; it does not turn them into security findings or prove runtime safety.

## Where to use it

The GitHub Action, pre-commit hook, and Claude Code CLI pins below use LintLang 0.8.2. The Gemini CLI guide remains pinned to the upstream-verified 0.5.3 source, and MegaLinter follows the package pin in its upstream descriptor. Section: https://hermes-labs.ai/lintlang#integrations

GitHub Action (or generate a pinned Code Scanning workflow with `lintlang init --github`; guide: https://github.com/hermes-labs-ai/lintlang/blob/main/docs/github.md):

```yaml
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
  with:
    persist-credentials: false
- uses: hermes-labs-ai/lintlang@v0.8.2
  with:
    path: AGENTS.md
```

Since 0.8.2 the Action's `fail-on` input defaults to empty, so this step is advisory: it reports findings and fails only on input errors. Add `fail-on: fail` under `with:` to block on HIGH or CRITICAL findings, or `fail-on: review` to include MEDIUM. The workflow written by `lintlang init --github` sets `fail-on: fail` explicitly. Release note: https://github.com/hermes-labs-ai/lintlang/releases/tag/v0.8.2

pre-commit (guide: https://github.com/hermes-labs-ai/lintlang/blob/main/docs/integrations.md#pre-commit):

```yaml
repos:
  - repo: https://github.com/hermes-labs-ai/lintlang
    rev: v0.8.2
    hooks:
      - id: lintlang
        args: [AGENTS.md]
```

Claude Code plugin: install the CLI with `pipx install lintlang==0.8.2`, then run `/plugin marketplace add hermes-labs-ai/lintlang` and `/plugin install lintlang@lintlang` in Claude Code. Its non-blocking PostToolUse hook returns repair guidance after Write or Edit changes a supported file. Guide: https://github.com/hermes-labs-ai/lintlang/blob/main/integrations/claude-code/README.md

Gemini CLI extension: a non-blocking AfterTool hook returns repair guidance after write_file or replace changes a supported file. It requires uv and remains pinned to the upstream-verified 0.5.3 source; take the commit-pinned install command from the guide: https://github.com/hermes-labs-ai/lintlang/blob/main/docs/gemini-cli-extension.md

MegaLinter: the opt-in external plugin `AI_LINTLANG`, configured at https://hermes-labs.ai/lintlang#megalinter

These are integration surfaces maintained in the LintLang repository, not endorsements by the host tools.

## Public ecosystem evidence

- Recurring package execution in Character.AI's public Larch CI: https://github.com/character-ai/larch/blob/ef7ee4b7f946f29fa51981f5422a1a93e83c79a7/.github/workflows/ci.yaml. The historical requirements pin is lintlang 0.3.1: https://github.com/character-ai/larch/blob/ef7ee4b7f946f29fa51981f5422a1a93e83c79a7/.github/workflows/requirements-agent-linters.txt. A public job records successful execution: https://github.com/character-ai/larch/actions/runs/32180477808/job/95852067633. Larch's linting reference identifies hermes-labs-ai/lintlang as upstream: https://github.com/character-ai/larch/blob/210d08a8f6c1b0dd14c27b709c66471bd31a5636/docs/linting.md.
- Independent Gentoo packaging in the unofficial Haven overlay, which tracks upstream releases across successive ebuild bumps: https://github.com/thehaven/haven-overlay/tree/fbed4463d4e213a3bce98babbfc72ef78722d255/dev-util/lintlang (its metadata.xml records hermes-labs-ai/lintlang as the upstream remote: https://github.com/thehaven/haven-overlay/blob/fbed4463d4e213a3bce98babbfc72ef78722d255/dev-util/lintlang/metadata.xml)
- MegaLinter's third-party plugin catalog lists lintlang as the AI_LINTLANG linter and resolves the descriptor from hermes-labs-ai/lintlang; the record documents an opt-in plugin entry, not a bundled MegaLinter default: https://github.com/oxsecurity/megalinter/blob/9d4e685d4f31cecdd53743a08704cd23d9c01811/docs/plugins.md
- Attributed product influence on Agent Lint: https://github.com/zhupanov/agent-lint/issues/192

Directory listings, not integrations or endorsements: MegaLinter External Plugins Catalog (https://github.com/oxsecurity/megalinter/pull/8899), awesome-gemini-cli (https://github.com/Piebald-AI/awesome-gemini-cli/pull/124), Product Hunt (https://www.producthunt.com/products/lintlang).

The linked records document recurring CI execution, independent packaging, an opt-in third-party plugin listing, and attributed product influence. A clean lintlang scan does not prove an agent is safe or correct; consult the canonical README for the maintained accuracy boundary and current usage.