05 - Logs and Diagnostics#
Helmor writes structured logs for both the Rust backend and the Bun sidecar. Use these to diagnose issues that aren't obvious from the UI.
Log file locations#
| File | Purpose |
|---|---|
~/.helmor/logs/rust.jsonl | Rust/Tauri backend logs (active) |
~/.helmor/logs/rust.jsonl.1 | Previous backend log (rotated) |
~/.helmor/logs/sidecar.jsonl | Sidecar process logs (active) |
~/.helmor/logs/sidecar.jsonl.1 | Previous sidecar log (rotated) |
Each file is bounded at 10 MB with automatic rotation. Dev builds log to ~/.helmor-dev/logs/ instead.
Log format#
Logs are structured JSONL — one JSON object per line with timestamp, level, module, and message fields. Pipe through jq for readable output:
cat ~/.helmor/logs/rust.jsonl | jq '.'
tail -f ~/.helmor/logs/sidecar.jsonl | jq '.message'
Adjusting verbosity#
Set the HELMOR_LOG environment variable before launching:
# Full debug output
HELMOR_LOG=debug bun run dev
# Target a specific module
HELMOR_LOG=helmor::sidecar=trace bun run dev
# Multiple modules
HELMOR_LOG=helmor::pipeline=debug,helmor::workspace=trace bun run dev
Default levels:
- Dev builds:
debug - Release builds:
info
What to look for#
| Symptom | Log to check | Search for |
|---|---|---|
| Session hangs | sidecar.jsonl | Heartbeat gaps, timeout events |
| Workspace creation fails | rust.jsonl | workspace, worktree, error codes |
| Git operations fail | rust.jsonl | git, branch names, path errors |
| Agent auth issues | sidecar.jsonl | 401, 403, credential errors |
Sharing logs for bug reports#
When filing an issue at github.com/dohooo/helmor/issues, include:
- The relevant section of
rust.jsonland/orsidecar.jsonl. - Steps to reproduce.
- Your Helmor version and OS version.
Redact API keys or personal tokens before sharing.
Related#
- Debugging Guide — full troubleshooting methodology.
- Agent Not Responding — specific sidecar/agent diagnosis.