07 - Debugging Guide#
When something breaks in Helmor, identify which layer owns the problem. Most issues fall into one of four categories.
Layer model#
| Layer | Symptoms | Where to look |
|---|---|---|
| Frontend (UI) | Blank panels, broken layout, stale state | Browser DevTools console (Cmd+Opt+I in dev mode) |
| Tauri backend | Commands fail silently, data not persisting | Rust logs in the terminal running the app |
| Sidecar (agent process) | Session hangs, no agent response, JSON parse errors | Sidecar stdout/stderr logs |
| Git / filesystem | Wrong branch, missing files, dirty working tree | git status, git log, workspace path on disk |
Quick checks#
- Restart Helmor — clears transient state and reconnects the sidecar.
- Check the terminal — if running in dev mode (
bun run dev), errors print directly. - Verify agent auth — run the agent CLI outside Helmor (e.g.,
claude --version) to confirm it works independently. - Inspect the workspace path — confirm the directory exists and Git reports a clean or expected state.
Development logging#
Increase verbosity with the HELMOR_LOG environment variable:
HELMOR_LOG=debug bun run dev
For narrower output, target a specific module:
HELMOR_LOG=helmor::sidecar=trace bun run dev
Pipeline debugging (streaming messages)#
If agent messages render incorrectly in the UI:
- Compare raw sidecar events (JSON streamed from the agent process).
- Check accumulator output (how Helmor merges partial events).
- Inspect stored database rows (the persisted session data).
- Verify the frontend message shape (what React receives and renders).
A mismatch at any stage points to the bug's layer.
Related#
- Sidecar and CLI Issues — agent process startup failures.
- GitHub Authentication Issues — connection and token problems.