LintLang

Static analysis for the instructions your AI agents execute.

LintLang is developed by Hermes Labs.

Hermes Labs studies failure modes in agent and LLM systems, develops open-source tools that treat language as part of the runtime, and works with teams to remediate reliability failures in production.

Product page · Browser playground · PyPI · Documentation

LintLang catches ambiguous tool descriptions, missing operational limits, schema/description mismatches, conflicting output contracts, and other bounded instruction defects before a model runs.

Local · deterministic · zero LLM calls · no telemetry or network access during a scan

Quick start

Requires Python 3.10+.

Run once without installing:

uvx lintlang scan AGENTS.md

Or install it:

pip install lintlang
lintlang scan AGENTS.md

Use the instruction file your agent actually reads: AGENTS.md, CLAUDE.md, GEMINI.md, GitHub Copilot instructions, or another supported prompt/configuration path.

No instruction file yet? Try the checkout-free first run.

A normal scan reports findings without blocking:

REVIEW — findings detected

To make HIGH or CRITICAL findings fail CI:

lintlang scan AGENTS.md --fail-on fail

What LintLang catches

• Ambiguous tools — empty, vague, or overlapping descriptions without a clear selection rule.
• Missing bounds — retries, loops, or tool use without explicit stopping or progress conditions.
• Contract mismatches — descriptions that disagree with schemas, malformed message roles, or conflicting output-format requirements.
• Context and prompt defects — vague or unscoped context, instruction files that point at project files that no longer exist, embedded prompt issues, and selected problems in supported Python prompt pipelines.
• Skill metadata — a SKILL.md whose front-matter description is missing, over the 1024-character limit, or never says when to use the skill; a name that is invalid or differs from its directory.

Every finding has a stable identifier, severity, evidence, and a suggested review action where the parser can justify one. Findings in text files carry the line number.

Every result also says what it inspected:

FAIL — 2 HIGH
Inspected: 18 tools (18 described, 18 with a schema)

A file LintLang could read nothing from is reported SKIPPED, never PASS.

Reports also explain the separate HERM confidence label using its current coverage proxies: whether prompt-like framing and input-boundary language were detected. The guidance is conditional on the document's purpose; reference material can naturally receive lower confidence. This label is not a statistical probability, a finding-certainty estimate, or the structural PASS/REVIEW/FAIL verdict. The current coverage bands are high at 90% or more, medium at 75% or more, and low below 75%.

Conservative automatic rewrite

scan --fix currently handles one exact case: a direct, standalone Don't be verbose instruction (with or without a final period; curly apostrophe is also accepted). It prints the unified diff before writing. Use --dry-run to preview without writing, or --backup to preserve the exact original bytes as FILE.lintlang.bak before the write; an existing backup is never overwritten.

lintlang scan AGENTS.md --fix --dry-run
lintlang scan AGENTS.md --fix --backup

The file must start with a top-level # Instructions heading, followed only by blank lines and the supported instruction as its first body line. Other headings, preambles, quoted, commented, code, and ambiguous contexts are left untouched; malformed lexical scope fails closed. Only one explicit .md, .txt, or .prompt file is accepted. H1/H2 suggestions that would invent tool behavior, output formats, or scope; security negatives; other priority rules; and cross-file conflicts remain manual. This is a narrow syntactic rewrite, not an automatic-fix score or a claim that other suggestions are safe to apply.

LintLang does not decide whether arbitrary prose is true, predict runtime model behavior, or certify an agent as safe.

What it can scan

See the technical reference for detector coverage, extraction behavior, and the CLI flags for repository discovery (--discover) and standard-input scanning (--stdin-filename).

Use it where instructions change

Local review

lintlang scan AGENTS.md

Existing repositories

Create a baseline for findings already reviewed, then gate only new findings:

lintlang scan AGENTS.md --write-baseline .lintlang-baseline.json
lintlang scan AGENTS.md \
  --baseline .lintlang-baseline.json \
  --fail-on review

See baseline adoption for matching semantics and maintenance.

GitHub CI and Code Scanning

Generate a pinned workflow for a known instruction path:

lintlang init --github --path AGENTS.md

The generated workflow runs the same scanner and can upload SARIF for GitHub Code Scanning.

Integrations

LintLang fits existing developer workflows rather than requiring a runtime service.

See the integrations and ecosystem guide for setup instructions and public ecosystem references. The GitHub Copilot CLI plugin guide gives the direct install command.

Results and exit behavior

Findings are non-blocking by default. Use --fail-on to choose a CI threshold. Input errors remain nonzero regardless of that threshold; a scan that inspects zero files is one of them, and --allow-empty is the opt-out for an input that may legitimately be empty. See the GitHub CI guide for the exact per-channel behavior.

Machine-readable JSON and SARIF output are available for automation.

Where LintLang fits

syntax and schema validation
        ↓
LintLang static instruction checks
        ↓
runtime agent evaluation
        ↓
domain and security review

LintLang is an authoring and review control. It does not run models, observe tool selection at runtime, prove semantic correctness, replace evaluation, or establish that an agent is production-safe.

A clean scan means only that the selected static checks found no covered defects in the recognized content.

Evidence

Character.AI’s public Larch repository pins a LintLang release in recurring CI. MegaLinter catalogs LintLang as the AI_LINTLANG external plugin.

See the integrations and ecosystem guide for additional public references.

LintLang is an engineering evolution of Hermes Labs’ research into structural epistemic failure modes in language models. See Research and design lineage.

Documentation

Contributing

Bug reports, disputed findings, reproducible false positives, documentation corrections, and focused contributions are welcome. Read CONTRIBUTING.md before opening a pull request.

License

Apache License 2.0