agent-comment-lint
Stops AI coding agents from bloating your code comments.
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 or AGENTS.md asks; this enforces.
agent-comment-lint holds every comment to one line, with no ticket or plan references. Inside Claude Code and Codex CLI, and in preview inside Gemini CLI and Windsurf, 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 |
Python |
Ruby |
TOML |
Dockerfile |
Makefile |
Go |
Java |
Rust |
SQL |
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 Supported |
Windsurf Preview |
Gemini CLI Preview |
Copilot Planned |
Cursor Planned |
Kiro Planned |
Antigravity Planned |
Supported agents have been seen blocking a write live. 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.7.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.7.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.7.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.7.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.7.0
pipx install agent-comment-lint==1.7.0
To install from the repository instead:
uv tool install git+https://github.com/OrodruinLabs/agent-comment-lint@v1.7.0
pipx install git+https://github.com/OrodruinLabs/agent-comment-lint@v1.7.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.7.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.7.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agent_comment_lint-1.7.0.tar.gz | 127.4 kB | With provenance | Details for agent_comment_lint-1.7.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agent_comment_lint-1.7.0-py3-none-any.whl | Python 3 | none | any | Details for agent_comment_lint-1.7.0-py3-none-any.whl |
Total release size: 194.0 kB
Release files / agent_comment_lint-1.7.0.tar.gz
| Download URL | agent_comment_lint-1.7.0.tar.gz |
|---|---|
| Size | 127.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e93279ab502884199e4012608d9621789881a41cb57f5592ac727e169867422c
|
|
BLAKE2b-256 checksum How to use checksums |
853b02eb6afa7309557488f970b5c22d49609e4ed22cf56d718a6a44ed1e53f5
|
| 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 logRelease files / agent_comment_lint-1.7.0-py3-none-any.whl
| Download URL | agent_comment_lint-1.7.0-py3-none-any.whl |
|---|---|
| Size | 66.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e77b7e9e0c42c4bcbb168bab256a40c624d910308f049f8636decd3512a2a273
|
|
BLAKE2b-256 checksum How to use checksums |
8b972febe99926383fcb64994d9a79ca8567ee594057e12e674b76b7aa8a96a8
|
| 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 logSecurity for agent-comment-lint 1.7.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.
Attestation for agent_comment_lint-1.7.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 logA 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.