Skip to main content

agent-comment-lint

Stops AI coding agents from bloating your code comments.

CI License: MIT Python 3.9 to 3.13 No dependencies Claude Code plugin


AI coding agents comment the way they chat: three lines restating what the next line does, and a pointer to the ticket or plan they were working from. The restatement drifts from the code, and the pointer rots when the document moves.

Your CLAUDE.md asks; this enforces.

agent-comment-lint holds every comment to one line, with no ticket or plan references. In Claude Code it blocks the write before the comment lands and shows the agent why, so the agent can rewrite it. The same check runs in CI, in pre-commit and from the command line.

src/a.ts:12: C1: 3-line prose block (limit 1)
src/a.ts:40: C3: governance reference 'ADR-0009'
agent-comment-lint: 2 violation(s) in 1 of 57 file(s) scanned.

What it checks

Rule Fails when
C1 A comment has more than one line of prose. Consecutive // or # lines, a multi-line /* */ and a Python docstring each count as one comment. One-line tags such as @param do not count, and neither do rulers like // ---- or other lines without a letter or digit.
C3 A comment names a ticket, pull request, decision record, plan or doc path, such as ADR-9, PR 519, work item 1234, docs/x.md or CLAUDE.md.
C5 An assertion message built with + "..." spans more than two lines.
C7 A line that carries a comment is over 120 characters.

The numbers skip because C2, C4 and C6 need a compiler or human judgment, and this tool does not check them.

Supported languages


C#
.cs

JavaScript
.js .jsx .mjs .cjs

TypeScript
.ts .tsx .mts .cts

CSS
.css

Shell
.sh

YAML
.yml .yaml

Terraform and HCL
.tf .tfvars .hcl

Python
.py

JSX and TSX are included. Other files are skipped, and so are dependency and build folders such as node_modules, dist and .venv. Each language's comment styles are listed in the reference.

Setup

Pick where it runs; every channel runs the same check. The snippets pin v1.2.0. Keep a pin, so a new release never changes your results without a commit of yours.

Claude Code

/plugin marketplace add OrodruinLabs/agent-comment-lint
/plugin install agent-comment-lint@agent-comment-lint

macOS, Linux and Windows are supported. The plugin finds Python as AGENT_COMMENT_LINT_PYTHON, python3, python, then py -3. A write that adds a bad comment is blocked, and Claude sees why. Old comments the write leaves alone never block it. To turn it on for a whole team, see Claude Code setup.

GitHub Actions

on: pull_request
jobs:
  comments:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: OrodruinLabs/agent-comment-lint@v1.2.0

Only the lines the pull request changes are checked. Keep fetch-depth: 0, or the step cannot see what changed and fails. Findings appear as annotations on the changed lines. GitHub shows at most 10 per step, and the job summary lists them all. The inputs are in the reference.

pre-commit

repos:
  - repo: https://github.com/OrodruinLabs/agent-comment-lint
    rev: v1.2.0
    hooks:
      - id: agent-comment-lint

This checks each staged file whole, not only its changed lines, so fix or exclude old findings before you turn it on.

Command line

uv tool install agent-comment-lint==1.2.0
pipx install agent-comment-lint==1.2.0

To install from the repository instead:

uv tool install git+https://github.com/OrodruinLabs/agent-comment-lint@v1.2.0
pipx install git+https://github.com/OrodruinLabs/agent-comment-lint@v1.2.0

uvx agent-comment-lint runs it without installing, which suits CI and trials.

agent-comment-lint --diff origin/main    # only what the branch changes
agent-comment-lint --all                 # every covered file in the repository
agent-comment-lint --files a.ts b.py     # the named files
Exit code Meaning
0 Clean.
1 At least one violation.
2 Could not scan. Never treated as a pass.

Configuration

Optional. Add .agent-comment-lint.json at the repository root. Settings can only make the check stricter: there are no limits to change and no way to silence one comment inline. Every entry states its reason.

Setting What it does
$schema Optional. Lets editors check and complete the file.
exclude Paths that are never checked, such as vendored or generated code.
governance.packs Turns on reference packs, below.
governance.extra Adds your own reference patterns, as regular expressions.
{
  "$schema": "https://raw.githubusercontent.com/OrodruinLabs/agent-comment-lint/v1.2.0/schema/agent-comment-lint.schema.json",
  "exclude": [{ "path": "vendor/", "reason": "third-party code" }],
  "governance": {
    "packs": ["azure-boards"],
    "extra": [{ "pattern": "\\bWEB-\\d+", "reason": "the web team's ticket ids" }]
  }
}

Reference packs

C3 always refuses the common shapes shown in What it checks. A pack adds the reference shapes of one tracker or convention. Packs are off by default because the same shapes mean other things in many codebases, so turn on only the ones your team uses.

Pack Turn it on if you use It refuses
agent-context AI agents that cite a plan, a chat or a notes file Task 8, step 3 of the plan, per the spec, as requested, the user asked, PLAN.md
azure-boards Azure Boards AB#4321, ADO #795, ADO 795
decision-ids numbered decisions D-7, D-12b, D7
task-ids task ids shaped prefix, dash, letter, number WEB-T022, AUTH-F053

Documentation

The reference has everything else:

  • every reference shape C3 refuses
  • each mode and exit code
  • team setup for Claude Code
  • what each language's lexer can and cannot tell apart
  • the known false positives

License

MIT. See LICENSE.

Metadata

Release files for agent-comment-lint 1.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agent-comment-lint 1.2.0
File Size Uploaded Provenance Actions
agent_comment_lint-1.2.0.tar.gz 63.8 kB With provenance Details for agent_comment_lint-1.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agent-comment-lint 1.2.0
File Interpreter ABI Platform Actions
agent_comment_lint-1.2.0-py3-none-any.whl Python 3 none any Details for agent_comment_lint-1.2.0-py3-none-any.whl

Total release size: 101.1 kB

Release files / agent_comment_lint-1.2.0.tar.gz

Download URL agent_comment_lint-1.2.0.tar.gz
Size 63.8 kB
Tags Source
SHA-256 checksum
How to use checksums
5751f13879482a6067fabd287534734025c82433d3c1e23aa5f12c619b76121e
BLAKE2b-256 checksum
How to use checksums
7ca7c60ad8fcffb5083b4aafeb82b0e0e3ce22e0487e5625eacc041537014702
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Release files / agent_comment_lint-1.2.0-py3-none-any.whl

Download URL agent_comment_lint-1.2.0-py3-none-any.whl
Size 37.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bb444785815d0789c8d7bde1b158b8b9bdba98c2a31d6a87a7c97ba548b528b7
BLAKE2b-256 checksum
How to use checksums
2653f775fb62f234b4eecb008590199c7911eb692a58961ce9779ae2912c993e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Security for agent-comment-lint 1.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for agent_comment_lint-1.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page