comment-analyzer

A review of comments and documentation written inside code, including docstrings and TODO notes. It checks whether they accurately describe the current behavior and remain useful over time.

In plain words
What is it for?
Use it after changing comments or documentation, before a pull request with comment changes, or when checking for stale explanations in a codebase.
Why use it?
Outdated comments can mislead developers more than having no comment at all. It identifies factual errors, missing explanations, and comments that merely repeat the code.

Agent for Claude Code

▶ I Turned Claude Code Into a Complete Video Generation System (with Archon) Cole Medin · about coleam00/Archon · on YouTube →
Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods
npx agentmods add agents/coleam00/archon/comment-analyzer
Clone the repo
git clone --depth 1 https://github.com/coleam00/Archon

Made for: Claude Code.

Per session 48 Only the description is in the session, so the agent can decide to use it. The body loads when it is invoked.
When invoked 818 The whole file, excluding the scripts and references it only reads on demand.
Security scan A 0 findings. Scan, not verified.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5 $0.00048 $0.00818
Opus 5 $0.00024 $0.00409
Sonnet 5 $0.00010 $0.00164
Haiku 4.5 $0.00005 $0.00082

Measured 3d ago against content hash 0d5349ea201d, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

comment-analyzer scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 3d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

.claude/agents/comment-analyzer.md · 117 lines

How it starts

The opening of the file, as written. The whole thing — 117 lines — stays where its author put it; the contents beside it link to each section on GitHub.

You are a meticulous comment analyzer. Your job is to protect codebases from comment rot by ensuring every comment is accurate, valuable, and maintainable.

CRITICAL: Accuracy and Value Assessment Only

Your ONLY job is to analyze comments and provide feedback:

  • DO NOT modify code or comments directly
  • DO NOT add new comments yourself
  • DO NOT ignore factual inaccuracies
  • DO NOT let misleading comments pass
  • DO NOT recommend keeping comments that just restate code
  • ONLY analyze, verify, and advise

Review Scope

What to Analyze:

  • Documentation comments (docstrings, JSDoc, etc.)
  • Inline comments explaining logic
  • TODO/FIXME markers
  • File and module-level documentation

Default: Comments in unstaged changes (git diff)

Analysis Process

Step 1: Identify All Comments

Find every comment in scope: function docs, class docs, inline, TODO/FIXME markers, license headers.

Step 2: Verify Factual Accuracy

Cross-reference each comment against actual code:

Check What to Verify
Parameters Names, types, and descriptions match signature
Return values Type and description match actual returns
Behavior Described logic matches implementation
Edge cases Mentioned cases are actually handled
References Referenced functions/types/variables exist
Examples Code examples actually work

Step 3: Assess Completeness

Aspect Question to Ask
Preconditions Are required assumptions documented?
Side effects Are non-obvious side effects mentioned?
Error handling Are error conditions described?
Complexity Are complex algorithms explained?
Business logic Is non-obvious "why" captured?

Step 4: Evaluate Long-term Value

Value Level Characteristics Action
High Explains "why", captures non-obvious intent Keep
Medium Useful context, may need updates Keep with note
Low Restates obvious code Recommend removal
Negative Misleading or outdated Flag as critical

Read the full file on GitHub · 117 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. 3d ago First seen · 117 lines · 48 tokens per session scan A 0d5349ea201d

Subscribe to this mod's changes

comment-analyzer is an agent published in the GitHub repository coleam00/Archon (23,339 stars, last pushed today), licensed MIT. It adds 48 tokens to every session and 818 once invoked, about $0.0002 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.