Notify Before Watcher

Displays a notification before any Bash command execution, providing visibility into when system commands are about to run during Claude Code sessions.

When to Use This Hook

Attach this hook when you need to:

• Maintain awareness of every shell command Claude executes for security auditing
• Create a log trail of command execution timing for compliance or debugging
• Provide a visual checkpoint before potentially impactful system commands run

Consider alternatives when:

• You have comprehensive logging at the shell level (e.g., auditd or shell history logging)
• The notification noise outweighs the security benefit for your workflow

Quick Start

Configuration

Copy
name: notify-before-watcher
type: hook
trigger: PreToolUse
category: pre-tool

Example Trigger

Copy
# Hook triggers before any Bash command execution
claude> Run npm install
# Notification appears before the command runs

Example Output

About to run bash command...
Command: npm install
Working directory: /home/user/project
Timestamp: 2026-03-15T10:23:45Z

Core Concepts

Notification Scope Overview

Aspect	Details
Trigger	Every Bash tool invocation
Timing	Pre-execution (before command runs)
Output	Simple echo notification to stdout
Blocking	Non-blocking, does not prevent execution
Overhead	Negligible (single echo command)

Notification Workflow

Bash Tool Invoked
       |
  Echo Notification
       |
  Command Executes
       |
  Output Returned

Configuration

Parameter	Type	Default	Description
matcher	string	"Bash"	Tool type that triggers the notification
show_command	boolean	false	Include the actual command in the notification
show_timestamp	boolean	false	Add ISO timestamp to the notification
show_directory	boolean	false	Show working directory in notification
log_to_file	string	""	Optional file path to append notifications

Best Practices

1. Keep Notifications Minimal - The default single-line notification adds awareness without clutter. Only enable extra details (command, timestamp, directory) when actively auditing or debugging.

2. Log to File for Audit Trails - For compliance environments, configure log_to_file to append every command notification to a persistent log. This creates an auditable record independent of terminal scrollback.

3. Combine with Dangerous Command Blocker - Use the notification hook alongside a command blocker for a two-layer defense: notification gives visibility, blocker prevents harmful commands. Together they provide awareness and protection.

4. Extend to Other Tool Types - While Bash is the primary security concern, consider adding matchers for Write and Edit to see all file system modifications, not just command executions.

5. Use Color Coding for Severity - Enhance the notification with ANSI color codes to distinguish routine commands (green) from potentially impactful ones (yellow for installs, red for deletions).

Common Issues

1. Notification Fatigue - In active sessions, dozens of Bash invocations create repetitive notifications. Use silent_pass or filter to only notify on commands matching specific patterns.

2. Terminal Buffer Pollution - Excessive notifications push useful output out of the visible terminal buffer. Keep messages to a single line and consider a compact format for high-frequency sessions.

3. Missing Command Context - The default notification does not show what command is about to run. Enable show_command to make the notification actionable rather than just informational.