Diagnostics Dock

Diagnostics Dock

The Diagnostics Dock is a resizable panel that sits at the bottom of the Daintree window. It puts three diagnostic views behind a single set of tabs: Problems, Logs, and Events. One place to watch errors, log output, and IPC events.

The toolbar carries an AlertCircle badge button. It turns red with a dot indicator when there are undismissed errors. Clicking it toggles the dock open or closed. You can also open the dock from a keyboard shortcut or the action palette.

All four actions are also in the action palette (Cmd+Shift+P): search for "Toggle Diagnostics", "Show Problems", "Show Logs", or "Show Events". For the full shortcut reference, see Keyboard Shortcuts.

Problems Tab

The Problems tab lists active app errors in a table with columns for time, type, message, source, and actions. Every error gets a type: Git, Process, File, Network, Config, or Other.

Click any row to expand it. The full error shows in a preformatted block, with a Copy button that puts the complete error text on your clipboard: message, type, timestamp, source, details, and context.

Some errors come with a recovery hint, marked by a lightbulb icon, that suggests how to fix the issue. Transient errors also get a Retry button that re-runs the failed operation. Every row has a Dismiss button (×) to drop it from the active list.

Render-time exceptions caught by an Error Boundary surface here too, each with a copyable correlation ID that matches the Sentry event ID. See When Parts of the UI Fail for the full flow.

The Problems tab toolbar has two actions:

• Open Logs opens the raw log file in your system text editor
• Clear All dismisses every active error at once

Logs Tab

The Logs tab streams a virtualized, real-time view of the Electron main process logs. The filter bar at the top has a search input (200 ms debounced), four severity buttons (Debug, Info, Warn, Error) each carrying a count badge, and a Sources dropdown listing every module that has emitted a log this session, with multi-select and per-source counts. A Clear button shows up whenever any filter is active.

Each entry shows the timestamp as HH:MM:SS (the full ISO timestamp is in a tooltip), a colored severity badge, the source module in monospace brackets, and the message. Consecutive duplicates collapse behind an ×N count badge so a noisy producer doesn't flood the view. Hover an entry to reveal a Copy button that copies a formatted markdown block with app version, Electron version, and platform context attached, ready to paste into a bug report. Entries that carry a context payload get a chevron that expands to show the structured data.

Auto-scroll keeps the view pinned to the latest entry by following the Virtuoso output. Scroll up and the boundary freezes; a floating ↓ N new button appears showing how many entries arrived while you were reading older lines. Click it to re-enable auto-scroll, jump to the bottom, and reset the boundary.

Daintree's log rotation keeps a tail of the previous session in the buffer. After a restart, the Logs tab inserts a Previous session header card at the boundary, with the prior session's tail readable above it. That lets you line up a current-session symptom against whatever fired just before the last shutdown, without leaving the dock.

The Logs tab toolbar has these actions:

• Auto-scroll toggle (highlighted when active)
• Open File opens the log file in your system editor
• Clear clears the log buffer. A confirmation dialog gates it so a stray click doesn't wipe the history

For the full guide to accessing logs on disk, verbose logging, and the previous-session tail, see Performance & Logs.

Events Tab

The Events tab shows a live IPC event timeline in a split layout. The left side lists events in chronological order; the right side shows the full detail of the selected event. A filter bar at the top narrows the stream.

It's the tab to reach for when you're debugging timing issues between processes, inspecting event payloads, or working out how parts of the app talk to each other.

The toolbar has a Clear action that wipes the event buffer. A confirmation dialog appears first so you don't lose the buffer by accident.

Resizing the Dock

The dock has a drag handle along its top edge. Drag it up to grow the dock, down to shrink it. The default height is 256 px, the minimum is 128 px, and the maximum is 50% of the viewport height.

For keyboard access, tab to the resize handle and use ArrowUp/ArrowDown to adjust the height in 10 px steps. Daintree saves your preferred height and restores it the next time you open the dock.

Download Diagnostics

When you're filing a bug report or chasing a tricky issue, a diagnostics bundle hands whoever's helping a full snapshot of your system state. Go to Settings > Troubleshooting and click Download Diagnostics.

In v0.12 the bundle is a ZIP, not a single JSON file, and the flow runs through a review dialog before anything lands on disk. Clicking Download Diagnostics collects the payload in memory and opens the Review Diagnostics dialog. The file is only written when you click Save Bundle.

The review dialog lists 12 collection sections, all checked by default, with a Select All / Deselect All toggle:

• Metadata: app, Electron, Chrome, and Node.js versions
• Runtime: platform, architecture, paths, environment variables
• Operating System: type, version, CPU, memory, load average
• Display: all monitors with bounds, scale factor, rotation
• GPU: hardware acceleration status, feature flags, ANGLE fallback state
• Process: memory and CPU per Electron process
• Tools: availability and version of git, node, npm, npx, gh
• Git: git configuration with sensitive values redacted
• Configuration: selected store keys, deep-redacted
• Terminals: active PTY sessions with IDs and state
• Logs: recent log entries
• Events: recent IPC events

Below the section list is a Find & Replace editor. Each row is a plain-string match (not a regex) and a replacement, which defaults to [REDACTED]. Rules apply to the JSON payload and to every log file packed into the ZIP, so a path you redact in diagnostics.json stays redacted in the rotated log files too.

Toggle Show Preview to render the filtered, replaced payload in a scrollable preview before you save. Clicking Save Bundle opens a native save dialog with a default filename of daintree-diagnostics-{ISO-timestamp}.zip. The ZIP holds diagnostics.json plus up to six log files: daintree.log and up to five rotated siblings, daintree.log.1 through daintree.log.5. Once the write completes, Daintree reveals the file in your system file manager. On macOS and Linux the file is chmod'd to 0o600 before the dialog returns.

Hardware Acceleration

The Hardware Acceleration toggle is the first setting in Settings > Troubleshooting. Toggling it restarts the app right away with GPU rendering either on or off.

Disabling Manually

If you see blank panels, black screens, or rendering glitches that won't go away, disable hardware acceleration. The setting subtitle reads "Disable if you experience blank panels or rendering issues. App will restart." Toggling it off relaunches Daintree with GPU rendering disabled.

Automatic Disable After GPU Crashes

Daintree tracks GPU process crashes against a sliding window. Three crashes inside five minutes flip hardware acceleration off automatically. The monitor writes gpu-disabled.flag in the user data directory, sets the persisted preference, and relaunches the app. The safe-mode crash-loop guard gates that relaunch, so a hard crash loop won't trigger an infinite restart cycle. Once the flag is set, the setting subtitle changes to "GPU acceleration was disabled due to repeated crashes. Re-enable to restore full performance."

The sliding window means clean operation decays the strike count on its own. There's no explicit reset action. Re-enabling the toggle clears gpu-disabled.flag and restarts the app with hardware acceleration on.

Linux Wayland: ANGLE / Vulkan Fallback

On Linux running under Wayland, Daintree tries a soft fallback before going nuclear. The first GPU crash writes gpu-angle-fallback.flag and relaunches. On the next start, the environment-setup code adds the ANGLE / Vulkan command-line switches so Chromium uses a different GPU backend. Later crashes still count toward the three-in-five-minutes window, and a third crash triggers the full hardware-acceleration disable described above.

On macOS, Windows, and Linux running X11, this soft step is skipped. The first GPU crash there just adds a strike to the sliding window.

While the soft fallback is active and the nuclear disable hasn't fired, the Troubleshooting tab shows a warning subtitle under the toggle: "GPU is running in ANGLE/Vulkan fallback mode after a crash. Performance may be reduced — toggle hardware acceleration off and back on to restore the default backend." This indicator is gated to Linux + Wayland only. macOS, Windows, and Linux + X11 never show it, even if the flag file is left over from a prior session on a different display server.

Cloud-Synced Folder Warning

When you open a project, Daintree checks whether it sits inside a cloud-synced folder. If the project path falls under a known sync location for iCloud Drive, Dropbox, OneDrive, or Google Drive, a persistent warning toast appears titled Cloud Sync Folder Detected. The toast names the specific service and stays up until you dismiss it.

Why this matters

Cloud sync services and git use incompatible file access models. Running a git repository inside a synced folder causes real problems:

• Lock file conflicts: Git uses .git/index.lock for mutual exclusion. Sync daemons grab locks on these files, which produces Unable to create '.git/index.lock': File exists errors during ordinary git operations.
• Index and ref corruption: Sync clients observe intermediate write states and create conflict copies (e.g. index (conflicted copy)). These silently corrupt the repository state, and branch refs can revert with no warning.
• I/O bottlenecks: Operations like git checkout, git rebase, and npm install mutate thousands of files fast. The sync daemon tries to process every filesystem event in real time, which spikes CPU and visibly slows terminal output.

Dismissing the warning

Click Don't Show Again on the toast to suppress the warning for that specific project. Daintree saves the preference to the project's settings, so the warning stays gone when you reopen it.

Detected paths

Daintree checks the following paths to work out whether a project is inside a cloud-synced folder. Entries with * are prefix patterns. The provider may append an account name or organization suffix to the folder name.

If you see the warning, move the project to a local folder outside these paths, somewhere like ~/Projects/ or ~/Developer/. For cross-machine access, use a git remote on GitHub, GitLab, or a similar service instead of filesystem sync.