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#

JavaScript

TypeScript

CSS

Shell

YAML

Terraform / HCL

Python

Ruby

TOML

Dockerfile

Makefile

Go

Java

Rust

JSX and TSX are included. Other files are skipped, and so are dependency and build folders such as node_modules, dist and .venv. The extensions and file names each language covers are in the reference.

Supported agents


Claude Code
Supported

Codex CLI
Preview

Windsurf / Devin
Preview

Gemini CLI
Preview

GitHub Copilot
Planned

Cursor
Planned

Kiro
Planned

Antigravity
Planned

Preview adapters are built from the agent's hook documentation and have not yet been seen blocking a write live. Planned agents wait for one captured hook event, because their docs do not say what a file write looks like. The details for each agent are in the reference.

Setup

Pick where it runs; every channel runs the same check. The snippets pin v1.6.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. When Claude stops, the plugin also checks the comments written any other way, such as through Bash, on the lines changed since the session started and not yet committed. To turn it on for a whole team, see Claude Code setup.

Other coding agents

For Codex CLI, Windsurf / Devin and Gemini CLI, install the command as under Command line, then copy the agent's template from integrations/ and the guard scripts at the v1.6.0 tag. The steps for each agent are in the reference.

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.6.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.6.0
    hooks:
      - id: agent-comment-lint-staged

This checks only the lines you stage, as the index holds them, so a repository with old findings can turn it on today. To judge each staged file whole instead, use id: agent-comment-lint, and fix or exclude old findings first.

The staged id is for commit time. Under pre-commit run --all-files, in pre-commit.ci or at a pre-push stage nothing is staged, so it judges nothing. In CI, use the GitHub Action (or --diff), or the whole-file id with --all-files.

Command line

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

To install from the repository instead:

uv tool install git+https://github.com/OrodruinLabs/agent-comment-lint@v1.6.0
pipx install git+https://github.com/OrodruinLabs/agent-comment-lint@v1.6.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.6.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" }]
  }
}

The Claude Code hook and the end-of-session check read this file as committed, so a new exclusion reaches them once a human commits it. Outside git, before the first commit, and with --config, they read the file on disk.

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.6.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.6.0
File Size Uploaded Provenance Actions
agent_comment_lint-1.6.0.tar.gz 117.4 kB With provenance Details for agent_comment_lint-1.6.0.tar.gz

Built distribution (wheel)

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

Total release size: 179.4 kB

Release files / agent_comment_lint-1.6.0.tar.gz

Download URL agent_comment_lint-1.6.0.tar.gz
Size 117.4 kB
Tags Source
SHA-256 checksum
How to use checksums
351212f81ac39a03e5ec7a678a44b969c9e546d2055475adc4dcfd8348a2dd5e
BLAKE2b-256 checksum
How to use checksums
f15d2fbf0a36404b9f4853b0280ad0adb989d537a31e3ef8d30b01b120fb592a
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 30, 2026.

Transparency log

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

Download URL agent_comment_lint-1.6.0-py3-none-any.whl
Size 62.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d07e7d65276876875d33cea47cd71b85c463abf71dbbc2e9a7e85f1cc55d4f11
BLAKE2b-256 checksum
How to use checksums
2e85f6e28914ff91f1f9fa69db8cab40ef6db12b6d034683eddfcf7a0fdd80a1
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 30, 2026.

Transparency log

Security for agent-comment-lint 1.6.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.6.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 30, 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