comment-checker

100% vibe coded. zero comments in my code, zero comments in yours.

this entire repo - code, docs, readme, everything - was written by LLMs. shoutout to claude opus 4.5.

A PostToolUse hook for Claude Code / OpenCode that yells at you when you write unnecessary comments.

Built with Rust + tree-sitter. Fast. Opinionated. No mercy.

why

comments are code smell. if your code needs comments to be understood, your code sucks.

this hook watches every Write, Edit, MultiEdit and screams when it detects comments.

exceptions exist. BDD comments (# given, # when, # then), linter directives (# noqa, // @ts-ignore), shebangs - these are fine. everything else? delete it. yes, even docstrings.

install

npm / bun

npm install -g @code-yeongyu/comment-checker
bun add -g @code-yeongyu/comment-checker

homebrew (macos/linux)

brew tap code-yeongyu/tap
brew install comment-checker

manual

grab binary from releases.

setup

add to ~/.claude/settings.json (or .claude/settings.json in your project):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "comment-checker"
          }
        ]
      }
    ]
  }
}

done. now claude will think twice before leaving // TODO: fix later in your code.

what it catches

// bad: unnecessary comment
x := 1 + 1  // adds one to one

// bad: todo that will never be done
// TODO: refactor this later

// bad: commented out code
// fmt.Println("debug")

what it allows

# given - BDD comments are fine
def test_something():
    # when
    result = do_thing()
    # then
    assert result == expected

# noqa: E501 - linter directives are fine

#!/usr/bin/env python - shebangs are fine

30+ languages

python, go, typescript, javascript, rust, c, c++, java, ruby, php, swift, kotlin, scala, elixir, and more.

if tree-sitter supports it, we support it. the archived Go implementation lives under go/; the production CLI is Rust.

how it works

1. hook receives JSON from Claude Code
2. extracts content from Write/Edit/MultiEdit tool input
3. detects language from file extension
4. parses AST with tree-sitter
5. finds comment nodes
6. filters out allowed patterns (BDD, directives, shebangs)
7. if anything remains → exit 2 with warning message

the Rust workspace also has buildable wasm32-unknown-unknown and N-API binding crates for future consumers. those paths are CI buildability gates for now; npm still ships native binaries.

exit codes

code	meaning
0	pass - no comments found or skipped
2	warning - problematic comments detected

custom prompt

you can replace the default warning message with your own using --prompt:

comment-checker --prompt "Custom warning! {{comments}}"

use {{comments}} placeholder to insert the detected comments XML. if omitted, only your custom message is shown.

with oh-my-opencode

{
  "comment_checker": {
    "custom_prompt": "DETECTED:\n{{comments}}\nFix it."
  }
}

philosophy

"Code is like humor. When you have to explain it, it's bad." - Cory House

write self-documenting code. use meaningful names. extract functions. stop explaining what the code does and make the code explain itself.

license

MIT. do whatever.