pi-comment-checker

Pi extension that enforces self-documenting code by detecting and blocking unnecessary comments

Package details

← Back
extension

Install pi-comment-checker from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:pi-comment-checker
Package
pi-comment-checker
Version
0.4.1
Published
Apr 27, 2026
Downloads
578/mo · 161/wk
Author
djdembeck
License
MIT
Types
extension
Size
51.8 KB
Dependencies
0 dependencies · 1 peer
Pi manifest JSON
{
  "extensions": [
    "./extensions"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

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

  • Homebrew: brew tap code-yeongyu/tap && brew install comment-checker
  • Release binary: Download from GitHub Releases
  • Build from source: Clone and go build ./cmd/comment-checker

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

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

Variable Default Description
PI_COMMENT_CHECKER_DEBUG unset Set to 1 to enable debug logging to stderr ([comment-checker] prefix)
PI_COMMENT_CHECKER_NOTIFY unset Set to 1 to show terminal notifications when AI comments are detected. By default, detections are passed silently to the agent via tool return values

Related

License

MIT