Bugs
What to check first, what to include, and how to write steps someone else can follow to see the bug.
Please file issues on GitHub through the form there. I will not address issues that skip the form.
Usability problems count as bugs. A confusing screen, an unclear error, a bad default, or a gap in the docs is worth reporting. Feature requests go in Discussions instead, since komrad is focused on stability for the time being.
Search the open issues before filing a new ticket.
Checking for common issues#
Run doctor before filing an issue to confirm your komrad comes up healthy:
komrad doctor
It checks dependencies like tmux and your database. Include its output in your report.
Logs and recordings#
When a request fails, the panel shows its trace ID as a komrad log <id> line.
Run that command and paste what it prints. If you missed the id, komrad log --recent lists the latest ones.
The server also writes a log file, komrad.log, in your cache directory. That’s ~/Library/Caches/komrad/ on macOS and ~/.cache/komrad/ on Linux. It records failures to launch, reconcile, or index. Paste only the lines from around the time of the bug, and filter by the agent’s id if one was involved. The panel writes its own log beside it, komrad-panel.log. When the server won’t start at all, komrad-serve.out holds what it printed on the way down.
Finally, if an agent shows the wrong state, such as thinking when its pane has stopped, the recorded pane frames help a lot. Set frames = true under [debug] in your config, replicate the issue, and attach the frame file. By default the files live in komrad-frames/<agent id>/ in the same cache directory.
For anything visual, such as UI flicker or regressions, attach a screenshot or a short screen recording.
Performance problems#
Komrad runs two processes: the server, which runs the agents and answers the API, and the panel, which draws the screen. Each can serve Go’s pprof profiles on its own port to debug performance issues.
To use the profiler, turn it on in your configuration file for either process or both:
[debug.pprof.server]
enabled = true
[debug.pprof.panel]
enabled = true
The server serves on localhost:6060 and the panel on localhost:6061. Both read your configuration only when komrad starts, so run komrad stop and restart the panel after changing it.
Turning profiling on records nothing by itself. It only opens a port that answers questions about the running process. For instance, these commands dump information about the running server once profiling is on:
curl -o heap.pb.gz 'http://localhost:6060/debug/pprof/heap'
curl -o goroutine.pb.gz 'http://localhost:6060/debug/pprof/goroutine'
curl -o cpu.pb.gz 'http://localhost:6060/debug/pprof/profile?seconds=30'
To look at a profile yourself, go tool pprof -http=:8080 heap.pb.gz opens it in a browser. You can attach these profiles to your bug report.