Debug Window Watcher

Opens a live-tailing debug log window when Claude Code starts with the debug flag, and automatically closes it when the session ends.

When to Use This Hook

Attach this hook when you need to:

• Automatically open a dedicated terminal window showing real-time debug output when running Claude Code in debug mode
• Monitor hook execution, API calls, and internal state changes in real-time through a separate debug log viewer
• Keep debug output visible in a side window without cluttering the main Claude Code terminal during development

Consider alternatives when:

• You prefer to review debug logs after the session ends rather than watching them in real-time during development
• Your terminal emulator does not support programmatic window creation through the shell scripting methods used by this hook

Quick Start

Configuration

Copy
name: debug-window-watcher
type: hook
trigger: SessionStart, SessionEnd
category: development-tools

Example Trigger

Copy
claude --debug
# Hook detects debug flag and opens tail window:
# New terminal window opens with: tail -f ~/.claude/debug.log

Example Output

Debug Window Watcher: Debug mode detected
Opening debug log viewer in new terminal window...
Terminal: Ghostty (detected)
Log file: ~/.claude/debug.log
Window: Opened successfully
Auto-close: Enabled (will close on session end)

[On session end]
Debug Window Watcher: Closing debug window
Window: Closed

Core Concepts

Debug Window Overview

Aspect	Details
Trigger Events	SessionStart opens window, SessionEnd closes window
Detection Method	Checks for --debug or -d flag in session launch arguments
Platform Support	macOS (osascript), Linux (various terminal emulators), Windows (Git Bash)
Window Content	tail -f on the Claude Code debug log file
Auto-Close	Configurable; set DEBUG_WINDOW_AUTO_CLOSE_DISABLE=1 to keep open
Script Location	.claude/hooks/debug-window.sh handles both open and close

Debug Window Lifecycle

SessionStart
    |
    v
[debug-window.sh invoked]
    |
    v
[Debug flag detected? (--debug or -d)]
    |          |
   No         Yes
    |          |
 [Skip]       v
         [Detect terminal emulator]
              |
         +----+----+----+
         |    |    |    |
       macOS Linux Win  Other
         |    |    |    |
         v    v    v    v
      [Open new terminal window with tail -f]
              |
              v
         [Window tracks debug.log in real-time]
              |
              ... (debug session) ...
              |
SessionEnd
    |
    v
[debug-window.sh invoked]
    |
    v
[AUTO_CLOSE_DISABLE set?]
    |          |
   Yes        No
    |          |
[Leave open]  v
         [Close debug window]

Configuration

Parameter	Type	Default	Description
DEBUG_WINDOW_AUTO_CLOSE_DISABLE	string	(unset)	Set to 1 to keep the debug window open after session ends
debug_log_path	string	~/.claude/debug.log	Path to the debug log file that the window tails
terminal_emulator	string	(auto-detect)	Override the auto-detected terminal emulator preference
window_position	string	right	Preferred position for the debug window relative to the main terminal
tail_lines	integer	50	Number of existing log lines to display when the window first opens

Best Practices

1. Use a tiling window manager for best results - The debug window works best alongside the main Claude Code terminal in a tiled layout. Window managers like i3, Sway, or macOS split view keep both windows visible without manual resizing.

2. Keep the debug window open for complex debugging - Set DEBUG_WINDOW_AUTO_CLOSE_DISABLE=1 when debugging persistent issues that require reviewing log output after the session ends. The log remains available for analysis even after Claude Code exits.

3. Configure Ghostty keybindings for split layout - If using Ghostty terminal, configure super+d for new split right and super+shift+d for new split down. The hook can use these keybindings to create an integrated split view within a single Ghostty window.

4. Filter debug output for specific concerns - Instead of tailing the full debug log, modify the tail command to pipe through grep for specific patterns like hook: or error:. This reduces noise and focuses the debug window on the information you need.

5. Test terminal detection on your system - The hook auto-detects the terminal emulator but may not recognize all emulators. Run the hook script manually to verify it correctly detects your terminal and opens the debug window. Contribute support for unrecognized emulators.

Common Issues

1. Debug window does not open on macOS - The hook uses osascript to open new Terminal windows. If you use a non-default terminal like iTerm2 or Ghostty, the osascript command may open the wrong application. Specify your terminal emulator in the configuration or modify the hook script.

2. Window opens but shows empty log - If Claude Code was not started with the --debug flag, the debug log file may not exist or may be empty. Verify you launched Claude Code with claude --debug to enable debug output.

3. SessionEnd hook does not close the window - On some systems, the process used to close the window may not have the correct permissions or window reference. If the window persists after session end, close it manually. Check that the hook script stores and retrieves the window identifier correctly.