Explain --debug-file in messaging warning
CHANGELOG · original
Improved the cross-session messaging startup warning to explain that --debug-file writes a debug log to a path you choose Open official changelog ↗ Documentation
Documentation excerpt
Debug hooks
Hook execution details are written to the debug log file. Start Claude Code with claude --debug-file <path> to write the log to a known location, or run claude --debug and read the log at ~/.claude/debug/<session-id>.txt. The --debug flag doesn't print to the terminal.
For example, a PostToolUse hook on Write whose command prints hook-ran produces entries like:
2026-07-19T02:03:24.382Z [DEBUG] Hook output does not start with {, treating as plain text
2026-07-19T02:03:24.382Z [DEBUG] "Hook PostToolUse:Write (PostToolUse) success:\nhook-ran"
To find a slow hook, search the log for Hooks: lines that end in a duration. In Claude Code v2.1.296 or later, each command hook on a tool event, UserPromptSubmit, SessionStart, Stop, and several other events leaves one when it finishes, whatever it printed. The line gives the event name, joined by a colon to the tool name or other value the hook matched on, then the hook's command in brackets, the plugin it came from if any, how the run ended, and how long it took, as in Hooks: PostToolUse:Write [.claude/hooks/log-write.sh] finished with status 0 (31ms). A run can also end as timed out after <N>ms, cancelled, moved to the background, or failed to start. On some events, such as Notification, SessionEnd, and PreCompact, a command hook leaves a completed with status line without a duration instead.
For more granular hook matching details, set CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose to see additional log lines such as hook matcher counts and query matching.
For troubleshooting common issues like hooks not firing, Stop hooks that keep blocking, or configuration errors, see Limitations and troubleshooting in the guide. For a broader diagnostic walkthrough covering /context, /doctor, and settings precedence, see Debug your config.
Documentation snapshot · 2026-11-20