LintLang

Deterministic static analysis for agent configs, tool descriptions and system prompts — catch vague tools and missing stop conditions before runtime.

Stars
★ 147
Last updated
14d ago
License
Apache-2.0
Primary language
Python

At a glance

How it runs
CLI
Works with
Universal · cross-platformClaude CodeCodex (Partial support)
Cost
Free, no paid service needed
Setup effort
Low · running in minutes
You'll need
Python 3.10+uvx (optional)Homebrew (optional)Shell / CLINetwork accessLocal filesystem
Typical use
Teams maintaining an MCP server or function-tool set who want to confirm before release that sibling tool descriptions give the model a defensible choice.
Not a fit if
  • Teams wanting an LLM to rewrite or fix prompts, not deterministic checks
  • Teams that need runtime proof the agent picks the right tool
  • Teams needing tools from separate files merged into one selection namespace
Website
lintlang.ai ↗ set on GitHub
Maintenance
Commits in the last 30 dayslast commit 2026-11-06latest release v0.8.3 (2026-10-20)
Source review
81/100 · Good

What does this agent do, and when should you use it?

LintLang is a local, deterministic static linter from Hermes Labs aimed at the instructions and tool interfaces an AI agent is given. You point it at a project directory and it finds agent-facing content inside files you already keep: MCP and function-tool definitions nested in JSON/YAML, parameter schemas, system prompts, messages, output contracts, AGENTS.md, CLAUDE.md, GEMINI.md, SKILL.md, and supported Python prompt code. It uses no models at all, so results are reproducible and safe to gate in CI. The checks cover sibling tools that overlap without a clear reason to choose one, retries or loops with no stopping or progress condition, schemas missing required fields, prompts that name more than one output format, long instruction lists with no stated priority, SKILL.md metadata defects, stale context and broken tool-message sequences. Every result states what was inspected, and content with no recognized agent-facing structure is reported as SKIPPED rather than PASS. Reports are available as text, JSON, SARIF and GitLab Code Quality.

Running lintlang scan <path> walks the target directory, recognizes supported agent-facing carriers — MCP and function-tool definitions in JSON/YAML, parameter schemas, system prompts and messages, output contracts, AGENTS.md / CLAUDE.md / GEMINI.md / SKILL.md, and supported Python prompt code — and parses them. It then applies a fixed rule set: the H1.x family compares sibling tools inside one parsed input to expose overlapping choices; H5 flags long instruction lists with no priority order; H6 flags prompts naming two or more recognized output formats even when each is scoped to a case; further checks look for retries, loops or tool use with no explicit stopping or progress condition, schemas missing required fields or unclear parameters, SKILL.md with missing or invalid metadata or a name that does not match its directory, stale project references, unbounded persistence, malformed roles and broken tool-message sequences, plus literal tool definitions and selected pipeline thresholds inside supported Python prompts. The CLI exposes --fail-on fail (gate HIGH/CRITICAL only) and --fail-on review (include MEDIUM); --write-baseline records a reviewed .lintlang-baseline.json and --baseline then gates only new or changed findings; lintlang init --github --path . generates a pinned GitHub Actions workflow that gates HIGH or CRITICAL by default. Output formats are text, JSON, SARIF and GitLab Code Quality.

  1. Teams maintaining an MCP server or function-tool set who want to confirm before release that sibling tool descriptions give the model a defensible choice.
  2. Engineering teams that keep agent configs, prompts and skills in a repo and want PR-time blocking of high-risk configuration defects via GitHub Actions.
  3. Developers already using Claude Code, Cursor or Gemini CLI who want lintlang scan wired into a pre-commit hook for local checking.
  4. Reviewers of CLAUDE.md, SKILL.md or AGENTS.md who need a deterministic checklist for metadata, usage criteria and naming conventions.
  5. Projects with a large backlog of existing findings that want to freeze them in .lintlang-baseline.json and gate only newly introduced ones.
  6. Security and platform engineers who need results surfaced in GitHub Code Scanning or GitLab Code Quality dashboards through SARIF.

Key setup facts

Pulled from the install and usage notes below. The project README has the current values.

Install / run
  • uvx lintlang scan
  • pip install lintlang
  • brew install hermes-labs-ai/tap/lintlang
  • uvx lintlang scan AGENTS.md
Config files
agent.yaml .lintlang-baseline.json
Runtime
Python 3.10
Install notes cover
macOS

How do you install or deploy this agent?

Python 3.10 or newer is required. To try it once without installing:

uvx lintlang scan .

Install with pip:

pip install lintlang
lintlang scan .

On macOS you can also use Homebrew:

brew install hermes-labs-ai/tap/lintlang
lintlang scan .

How do you use this agent?

Point the scanner at a specific configuration source instead of the whole directory:

uvx lintlang scan AGENTS.md
uvx lintlang scan SKILL.md
uvx lintlang scan agent.yaml

Findings are advisory by default; to gate on HIGH or CRITICAL:

lintlang scan . --fail-on fail

Include MEDIUM findings in the gate:

lintlang scan . --fail-on review

Generate a pinned GitHub Actions workflow:

lintlang init --github --path .

For an existing repository with known findings, record a baseline and then gate only new or changed findings:

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

What are this agent's strengths and limitations?

Pros
  • Fully local and model-free: no LLM calls, no API keys, reproducible output, and no need to ship prompts or configs to an external service.
  • The detectors target agent-specific failure modes — overlapping sibling tools, missing stopping conditions, schema gaps, mixed output formats, SKILL.md metadata errors — that generic YAML/JSON linters do not cover.
  • Honest reporting semantics: unrecognized content is SKIPPED rather than PASS, and every finding states what was inspected, so a clean scan is not overstated.
  • Native SARIF, JSON and GitLab Code Quality output make it droppable into GitHub Code Scanning, GitLab CI or MegaLinter, and the baseline mechanism lets legacy repos adopt gradually.
  • Low-friction entry: uvx runs it without installation, with pip and Homebrew alternatives, plus documented integrations for Claude Code, Cursor, GitHub Copilot CLI, Gemini CLI and pre-commit.
Limitations
  • No semantic contradiction detection: the project states it will not catch 'always do X' sitting next to 'never do X'; H5 and H6 only cover missing priority and output-format count.
  • No runtime verification: it does not run models or observe actual tool choices, so a clean scan only means the selected static checks found no covered defects in recognized content.
  • Tool comparison is scoped to one parsed input; a directory scan does not merge tools from separate files into one selection namespace, so cross-file conflicts need separate handling.
  • Coverage depends on recognition rules: unsupported structures are skipped rather than flagged, so unusual configuration styles can look clean without being checked.
  • Requires a Python 3.10+ runtime, and the docs only give a native macOS install path via Homebrew — Linux and Windows users need pip or uvx.

How does this agent compare with similar options?

Key facts side by side with the most closely related agents.

Agent Source review Form / cost Stars Updated Language Full support on
LintLang This agent 81 · Good CLIFree ★ 147 14d ago Python Claude Code
AgentSys 56 · Major gaps CLIFree + model costs ★ 1k 11d ago JavaScript Codex · Claude Code
Argot Repository Style Analyzer 78 · Good CLIFree ★ 48 2mo ago Rust Claude Code
Kotlin Footguns 76 · Good Agent plugin / skillFree ★ 2.5k 23d ago Python Codex · Claude Code

How does FollowAgents rate this agent?

FollowAgents source review · FARS-2.1
Good
81/ 100 5-point scale 4.1 / 5
Trust 21/29
Reliability 11/14
Adaptability 15/18
Convention 16/18
Effectiveness 12/13
Verifiability 6/8
Why each dimension lost points
Trust21 / 29 · 3.6/5

The source describes scans of local files with no network access and advisory findings by default, which keeps the permission scope narrow. However, --fix writes files; --dry-run and optional backup provide limited safeguards rather than a full transactional recovery path. The skill advises avoiding persistent files or shell history for stdin prompt text and says raw prompt/context is excluded from default preflight output, supporting data-flow transparency and sensitive-data handling, though the supplied sample does not show the full implementation. PyYAML is the only listed runtime dependency, and the CI Action is pinned to a commit with credential persistence disabled; no dependency vulnerability status is supplied. Hermes Labs and a maintainer email are named, but publisher identity is unverified, so attribution and responsibility receive partial credit.

Reliability11 / 14 · 3.9/5

README, AGENTS.md, and CLI descriptions mostly align on offline scanning, verdicts, and the narrow auto-fix scope, while some entrypoints differ in how prominently they describe preflight. The runtime dependency and Python 3.10+ requirement are explicit, but installation may still require fetching packages, so availability is not assured by the source. The CLI documents concrete input errors, skipped content, gates, and failure states; the supplied CLI excerpt is incomplete, so all error paths cannot be checked.

Adaptability15 / 18 · 4.2/5

README, AGENTS.md, and skill files address developers, CI, tool definitions, prompts, embedded Python prompts, and several integrations, while clearly excluding runtime evaluation and proof of production safety. Skill triggers are fairly specific, though the instructions support both named-file scans and repository discovery, leaving the user to choose scope. Several installation methods and CI coverage for Python 3.10–3.13 are stated; the supplied environment sample is mainly Linux, with Homebrew mentioned for macOS but little detail for other environments.

Convention16 / 18 · 4.4/5

Documentation separates quickstart, CI, integrations, technical reference, baselines, contribution, security, and changelog material, with copyable commands and failure examples. Apache-2.0 appears in metadata and the license file. Versions appear in pyproject, the Gemini extension, and pinned skills, and a changelog is linked, but older integration-test pins coexist with 0.8.3, so supported-version and update-path guidance is not fully uniform. Contribution instructions, a security contact, and a latest-release-only security policy provide some maintenance information; the publisher is unverified, so no identity-based inference is made.

Effectiveness12 / 13 · 4.6/5

Findings include locations, severity, and repair suggestions, with JSON, SARIF, GitLab output, gates, and baselines for developer and CI workflows. Static checks of instructions and tool interfaces add clear value beyond runtime model evaluation, which the project expressly does not provide. The project also says it has not published accuracy or false-positive rates on real projects, and value therefore depends on heuristic coverage; cost-benefit does not merit full marks.

Verifiability6 / 8 · 3.8/5

The README ties features to documentation, fixtures, test paths, and merged upstream examples, and explicitly says the regression corpus does not estimate accuracy. Some version and dependency claims can also be checked against pyproject and workflows. Multiple files support offline, determinism, and scope claims, but are mostly repository-authored corroboration, and the supplied source sample is incomplete, so not every implementation claim can be independently checked. The project separates reported evidence, scope, and unpublished accuracy claims clearly.

Risks and how to mitigate them
  • A clean scan only means the recognized static checks found no covered issue; it does not establish runtime safety or correct agent behavior.
  • Accuracy and false-positive rates on real projects are not published. Auto-fix is narrow; review the change and preserve a recoverable copy before writing.
Evidence confidence: Low Reviewed Nov 08, 2026 Reviewed revision 5e5fefbce783
See the full review method →
Maintain this project? Add the FARS badge to your README

The badge shows the current review score and verdict and links back to this page. It refreshes about once an hour after a re-review.

FARS

[![FARS review](https://followagents.com/badge/lintlang.svg)](https://followagents.com/en/agents/lintlang)
<a href="https://followagents.com/en/agents/lintlang"><img src="https://followagents.com/badge/lintlang.svg" alt="FARS review"></a>

Recent releases

Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.

  1. v0.8.3 LintLang v0.8.3 — Better agent-file discovery and diagnostics
    Release notes excerpt
    LintLang v0.8.3 — Better agent-file discovery and diagnostics Find more of the instructions your agents rely on. Get clearer feedback when something needs fixing. LintLang is a local, deterministic static linter for AI agent instructions, prompts, and tool definitions. This release improves file discovery, configuration diagnostics, and developer integrations. What's new Cursor project-rule discovery LintLang now recognizes .cursor/rules/*.mdc files in supported instruction-file discovery workflows, including pre-commit. Clearer YAML tool diagnostics …
    View on GitHub ↗
  2. v0.8.2 0.8.2
    Release notes excerpt
    [0.8.2] - 2026-09-30 Added - A Simplified-Chinese quickstart (docs/zh-CN/) with a drift guard keeping it in step with the English docs. Added in [#156](https://github.com/hermes-labs-ai/lintlang/pull/156). Changed - Breaking: the GitHub Action's fail-on input now defaults to empty, making the workflow advisory: it reports findings but only fails on input errors, matching the CLI and pre-commit hook defaults. Workflows that relied on the previous blocking default must set fail-on: fail (or …
    View on GitHub ↗
  3. v0.8.1 0.8.1
    Release notes excerpt
    [0.8.1] - 2026-09-29 Fixed - Markdown front matter is now read as skill selection metadata only on explicit selection-definition paths: a file named SKILL.md, .claude/agents/*.md, .claude/commands/**, and .cursor/rules/*.mdc. Previously, any Markdown file with a description: key was treated as a skill at any path (H1.8 on ordinary docs pages), and any name: key under a skills/, agents/, or commands/ directory triggered H1.1 — including a skill's own assets/, references/, and example files. Directory scans …
    View on GitHub ↗

FAQ

Does LintLang call an LLM or need an API key?
No. It performs zero-LLM deterministic static checks, makes no model requests and requires no model API key, so the same input yields the same result.
If a scan passes, is my agent safe to ship?
No. LintLang does not run models, observe runtime tool choices or establish production safety. A clean scan means only that the selected static checks found no covered defects in recognized content; unrecognized content is reported as SKIPPED, not PASS.
Does it upload my prompts or code anywhere?
It is designed as a local tool that scans a local project directory from a developer machine or CI runner, and nothing in the repository describes sending content to an external service.
Can it detect overlapping tools across different files?
It detects overlapping sibling tool descriptions within one parsed input (the H1.x family). A directory scan does not combine tools from separate files into one selection namespace, so cross-file comparisons need separate handling.
How do I adopt it on a repo with a large backlog of findings?
Record a reviewed baseline with lintlang scan . --write-baseline .lintlang-baseline.json, then add --baseline .lintlang-baseline.json to subsequent scans so only new or changed findings are gated.
Is LintLang free?
Yes. LintLang is free to use and does not need a paid service.
Is LintLang open source?
Yes. The source code is on GitHub (hermes-labs-ai/lintlang) under the Apache-2.0 licence.
Is LintLang still maintained?
Yes. The latest commit on GitHub is from 2026-11-06, within the last 30 days. The latest release is v0.8.3 (2026-10-20).
Who makes LintLang?
LintLang is published on GitHub by the account hermes-labs-ai. FollowAgents has not verified which person or company is behind that account.
What is LintLang's official website?
The project's GitHub repository lists https://lintlang.ai/ as its website. That link is set by the repository owner; the source code itself is on GitHub (hermes-labs-ai/lintlang).
Was this page helpful?
View on GitHub ↗ Install ↓

Compare agents like this one

The same FARS review applied across the shortlist this agent qualifies for.

Related concepts