pi-comment-checker

Pi extension that enforces self-documenting code by warning when unnecessary comments are written. Integrates go-claude-code-comment-checker.

Why? Comments are often a code smell—better naming and structure eliminate the need for them. This extension catches problematic comments before they reach your codebase.

Installation

1. Install the Binary

go install github.com/code-yeongyu/go-claude-code-comment-checker/cmd/comment-checker@latest

Verify: comment-checker --help

2. Install the Pi Extension

pi install pi-comment-checker

git clone https://github.com/djdembeck/pi-comment-checker.git ~/.pi/agent/extensions/pi-comment-checker

How It Works

The extension monitors write, edit, and multiedit before execution, blocking those tool calls when it detects unnecessary comments. It also inspects apply_patch results and marks them as errors when comments are detected there.

Allowed exceptions:

• BDD comments (// given, // when, // then)
• Linter directives (// @ts-ignore, // eslint-disable, # noqa)
• Shebangs

False positive override: If the checker flags a comment that is intentional, add skipCommentCheck: true to the tool call input to bypass the check for that single invocation:

{
  "path": "src/config.ts",
  "content": "// RFC 4180: CSV fields must be quoted when containing commas",
  "skipCommentCheck": true
}

The error message itself includes this instruction, so the LLM agent knows how to override when it disagrees with the verdict. Note: this override is only available for write, edit, and multiedit tool calls — not apply_patch.

Supported languages: 30+ via tree-sitter (TypeScript, Python, Go, Rust, Java, C/C++, Ruby, Swift, and more).

For full details on comment detection rules, binary configuration, and advanced usage, see the go-claude-code-comment-checker repository.

Commands

/check-comments — Check extension status

Show binary location and setup help:

/check-comments

/check-comments <path> — Scan files for problematic comments

Retroactively check existing files for unnecessary comments:

# Check a single file
/check-comments src/utils.ts

# Check all source files in a directory (recursive)
/check-comments src/

# Check the entire project
/check-comments .

Output includes:

• Files scanned count
• Files with problematic comments
• Total comments found
• Grouped output by file with line numbers

Gitignore support: The extension automatically finds and respects your project's .gitignore file when scanning directories. Patterns like *.log, node_modules/, dist/, and **/vendor are honored to avoid checking files you've already excluded from version control.

Always skipped: .git, .svn, .hg (VCS directories)

Supported file extensions: .js, .jsx, .ts, .tsx, .py, .go, .rs, .java, .kt, .c, .cpp, .h, .rb, .php, .swift, .cs, and many more.

Environment Variables

Related

• go-claude-code-comment-checker — Core comment detection engine
• Pi Coding Agent — The agent this extension works with

License

MIT