Skip to content

Diagnostics and debug logs

This page owns the diagnostics/debug-log side of the ops layer: debug flags, debug log files, startup profiling marks, event-loop stall diagnostics, crash/error reporting, and support-oriented local evidence.

Use Telemetry and tracing for traffic/telemetry/OTEL export behavior, Feature gates reference for GrowthBook and tengu_* feature gates, and Updater and doctor for the user-facing doctor and updater command paths.

Source anchors

Semantic alias	Source	Approximate location	String or symbol	Meaning
DebugLogsDirEnv	`cli.js`	line ~62, byte `0x311ea`	`CLAUDE_CODE_DEBUG_LOGS_DIR`	Debug-log directory override.
DebugLogLevelEnv	`cli.js`	line ~62, byte `0x31362`	`CLAUDE_CODE_DEBUG_LOG_LEVEL`	Debug-log level override.
DebugFileFlagParser	`cli.js`	line ~62, byte `0x31599`	`--debug-file`	Specific debug-log path flag parser.
DebugFilterFlag	`cli.js`	line ~19525, byte `0xdbf757`	`-d, --debug [filter]`	Debug mode with category filtering.
RootDebugFlag	`cli.js`	line ~19525, byte `0xdbf764`	`--debug [filter]`	Root debug flag/filter.
DoctorDiagnosticsScreen	`cli.js`	line ~605, byte `0x38fcfe`	`/doctor diagnostics screen`	Interactive diagnostics surface.
EventLoopStallDetector	`cli.js`	line ~19294, byte `0xd9426a`	`startEventLoopStallDetector`	Optional event-loop stall diagnostic.
StartupProfilingMarkers	`cli.js`	line ~64, byte `0x33865`	`import_time`, `cli_entry`, `main_tsx_imports_loaded`	Startup profiling markers.
ShutdownErrorFlushCoordinator	`cli.js`	line ~1676, byte `0x4fb763`	`recordUncaughtAndCheckBreaker`, `gracefulShutdown`, `flushAnalyticsSinks`	Error/crash recording and shutdown flush coordination.

Diagnostic map

flowchart TD
    Runtime[Claude Code runtime] --> DebugFlags[--debug / --debug-file]
    Runtime --> StartupMarks[startup profiling marks]
    Runtime --> Stall[event-loop stall detector]
    Runtime --> Errors[uncaught/error reporter]
    DebugFlags --> Logs[debug log files]
    StartupMarks --> Logs
    Stall --> Logs
    Errors --> Logs
    Logs --> Support[support/debug evidence]

Debug-log controls

Surface	Runtime role
`--debug [filter]` / `-d`	Enables debug logging, optionally filtered by categories such as `api,hooks` or negated filters.
`--debug-to-stderr` / `-d2e`	Sends debug logs to stderr instead of only file-backed output.
`--debug-file <path>`	Writes debug logs to a specific file and implicitly enables debug mode.
`DEBUG`, `DEBUG_SDK`	Environment switches that can also enable debug behavior in selected paths.
`CLAUDE_CODE_DEBUG_LOGS_DIR`	Overrides the default debug-log directory.
`CLAUDE_CODE_DEBUG_LOG_LEVEL`	Sets the log-level threshold when recognized.
`latest` symlink	The debug writer updates a `latest` symlink next to log files.

Startup and runtime diagnostics

Diagnostic family	Evidence	Meaning
Startup marks	`import_time`, `cli_entry`, `main_tsx_imports_loaded`, `cli_before_main_import`	Gives support a boot timeline before the main loop starts.
Event-loop stalls	`startEventLoopStallDetector`	Adds a runtime liveness diagnostic around bootstrap/session execution.
Doctor diagnostics screen	`/doctor diagnostics screen`	Interactive diagnostics entry; command-level ownership is in Updater and doctor.
Crash/error recording	`recordUncaughtAndCheckBreaker`	Centralizes uncaught exception/breaker classification before shutdown.
Shutdown flush	`gracefulShutdown`, `flushAnalyticsSinks`	Gives logs/telemetry sinks a final best-effort drain.

Error reporting boundary

Error reporting is related to diagnostics but gated separately from debug logs. DISABLE_ERROR_REPORTING and traffic policy determine whether error reports are sent externally; local debug logs can still exist depending on debug settings. For the traffic and external sink behavior, see Telemetry and tracing.

Interpretation rules

Treat debug logs as local support evidence, not as public API.
Do not log credential/token values from env vars or settings.
Keep debug-log controls here; keep traffic/telemetry/OTEL controls in Telemetry and tracing.
Use Environment variables reference for canonical env-var names.

Created and maintained by Yingting Huang.