Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Diagnostics

Diagnostics are off by default. Enable them only when debugging or preparing a useful issue report because verbose logs can grow quickly.

Logging

Enable runtime diagnostics with a named preset:

claude-rs --enable-logs --diagnostics-preset session
claude-rs --enable-logs --diagnostics-preset render

Available presets:

PresetUse when
runtimeDebugging general app, bridge, session, tool, permission, network, and update flow.
sessionDebugging session startup, permission, and command flow.
renderDebugging rendering, cache, input, paste, and perf-adjacent UI behavior.
bridgeDebugging Agent SDK bridge lifecycle, protocol, SDK, permission, and MCP behavior.
fullCapturing the broadest diagnostic trace.

Use an explicit log path when you want the file somewhere predictable:

claude-rs --enable-logs --diagnostics-preset bridge --log-file claude-rs.log

Use an explicit tracing filter for targeted debugging:

claude-rs --log-filter "info,app.render=trace,bridge.protocol=debug"

--log-filter overrides --diagnostics-preset. If --log-file is omitted but logging is enabled through --enable-logs, --diagnostics-preset, --log-filter, --log-append, or RUST_LOG, the app writes to the default diagnostics path.

The default path is under the platform local data directory:

  • Windows: %LOCALAPPDATA%\claude-code-rust\logs\claude-rs.log
  • Linux: usually $XDG_DATA_HOME/claude-code-rust/logs/claude-rs.log or ~/.local/share/claude-code-rust/logs/claude-rs.log
  • macOS: the platform data directory reported by the dirs crate, under claude-code-rust/logs/claude-rs.log

Logs rotate at 10 MB and keep up to five rotated files.

Bridge Diagnostics

When runtime logging is active, bridge diagnostics are enabled and bridge stderr is captured into the structured log. This is useful for Agent SDK startup, authentication, MCP, permission, and protocol issues.

The bridge script can be overridden with:

claude-rs --bridge-script /path/to/agent-sdk/dist/bridge.js

or:

CLAUDE_RS_AGENT_BRIDGE=/path/to/agent-sdk/dist/bridge.js

The bridge Node runtime can be overridden with:

CLAUDE_RS_AGENT_BRIDGE_NODE=/path/to/node

Perf Telemetry

Perf telemetry is a separate JSON-lines sidecar intended for high-frequency render and layout samples. It requires a binary built with the perf feature.

From source:

cargo run --features perf -- --enable-perf
cargo run --features perf -- --perf-log claude-rs-perf.log

For an already-built perf-enabled binary:

claude-rs --enable-perf
claude-rs --perf-log claude-rs-perf.log

If the binary was not built with --features perf, perf flags are rejected at startup.

Useful Issue Reports

Include:

  • claude-rs --version
  • OS and terminal.
  • Install method: npm package, source build, fork build, or manual binary.
  • The exact command used to launch the app.
  • Whether a custom bridge script or Node runtime was used.
  • A short reproduction.
  • Relevant log snippets, not full secrets or private conversation content.