Sentinel Console Guard

Intercepts and blocks console.log, console.debug, and other debugging statements from being committed to production code files.

When to Use This Hook

Attach this hook when you need to:

• Prevent debug logging statements from reaching production code in JavaScript/TypeScript projects
• Enforce a clean logging discipline where only structured logger calls are permitted
• Catch accidental console statements that Claude might introduce during development sessions

Consider alternatives when:

• Your project intentionally uses console methods for user-facing output (CLI tools, Node.js scripts)
• You have ESLint's no-console rule already enforced with auto-fix in your pipeline

Quick Start

Configuration

Copy
name: sentinel-console-guard
type: hook
trigger: PreToolUse
category: pre-tool

Example Trigger

Copy
# Hook triggers before Claude writes code containing console statements
claude> Edit src/services/paymentService.ts
# Guard checks if the new content contains console.log or similar

Example Output

Sentinel Console Guard: Scanning edit content...
  BLOCKED: console.log() detected on line 47
  BLOCKED: console.debug() detected on line 83
  Suggestion: Use logger.info() or logger.debug() instead
Edit blocked. Remove console statements and retry.

Core Concepts

Detection Scope Overview

Aspect	Details
console.log	Blocked in all production source files
console.debug	Blocked, should use structured logger
console.warn	Optionally blocked (configurable)
console.error	Optionally allowed for error boundaries
console.trace	Blocked, reserved for development debugging only

Guard Workflow

Edit Requested
      |
  Is JS/TS File?
   /          \
  No          Yes
  |            |
Allow     Scan Content
           for console.*
              |
         ┌────┴────┐
         |         |
       Clean    Detected
         |         |
       Allow    Check Allowlist
                   |
              ┌────┴────┐
              |         |
           Allowed   Blocked
              |         |
           Allow     Reject +
                     Suggest
                     Logger

Configuration

Parameter	Type	Default	Description
blocked_methods	string[]	["log","debug","trace"]	Console methods to block
allowed_methods	string[]	["error"]	Console methods to permit
file_patterns	string[]	["*.ts","*.js","*.tsx","*.jsx"]	File patterns to scan
exclude_dirs	string[]	["__tests__","scripts"]	Directories exempt from checking
suggest_replacement	string	"logger"	Recommended alternative in error messages

Best Practices

1. Allow console.error Selectively - Error boundaries and catch blocks legitimately use console.error. Allow it by default but require a structured logger for informational and debug output.

2. Exempt Test Files - Test files often use console.log for debugging and console.error for expected error testing. Exclude __tests__, *.test.ts, and *.spec.ts from the guard.

3. Provide Clear Replacement Guidance - When the guard blocks a console statement, suggest the exact logger method to use (e.g., logger.info(), logger.debug()) so developers can fix the issue immediately.

4. Scan Both Old and New Content - When checking edits, scan the new content being written rather than the existing file. This prevents blocking edits that are actually removing console statements.

5. Configure a Project Logger First - Before enabling this guard, ensure your project has a structured logging library configured. Blocking console without an alternative frustrates the development workflow.

Common Issues

1. False Positives in String Literals - Code containing the string "console.log" in documentation or error messages triggers false positives. Use AST-level parsing or regex that excludes quoted strings.

2. Blocking Intentional CLI Output - Node.js CLI tools and build scripts legitimately use console for output. Add these files to exclude_dirs or use a file-level // sentinel-ignore comment.

3. Incomplete Pattern Matching - Simple regex may miss console["log"] or const {log} = console patterns. For thorough detection, consider using a JavaScript parser instead of string matching.