# 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](https://github.com/harrisoncramer/komrad/issues/new?template=bug_report.yml) through the form there. I will not address issues that skip the form.

> Komrad is a very new piece of software and likely will undergo breaking changes. I’ll do my best to not break backward compatibility, and opting into a new version will always involve downloading and running a new binary.

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](https://github.com/harrisoncramer/komrad/discussions) instead, since komrad is [focused on stability](https://komrad.dev/latest/guides/philosophy.md) for the time being.

Search the [open issues](https://github.com/harrisoncramer/komrad/issues) before filing a new ticket.

## Checking for common issues

Run doctor before filing an issue to confirm your komrad comes up healthy:

```sh
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>`](https://komrad.dev/latest/cli/log.md) line.

Run that command and paste what it prints. If you missed the id, [`komrad log --recent`](https://komrad.dev/latest/cli/log.md) 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`](https://komrad.dev/latest/config.md#debug.frames) under [`[debug]`](https://komrad.dev/latest/config.md#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](https://pkg.go.dev/net/http/pprof) profiles on its own port to debug performance issues.

> Slowness usually comes from outside komrad, for example old Docker containers left over from your worktrees, or too many Claude agents running at once. The profiler covers only komrad’s own Go code, so it won’t show those.

To use the profiler, turn it on in your configuration file for either process or both:

```toml
[debug.pprof.server]
enabled = true

[debug.pprof.panel]
enabled = true
```

The server serves on [`localhost:6060`](https://komrad.dev/latest/config.md#debug.pprof.server.address) and the panel on [`localhost:6061`](https://komrad.dev/latest/config.md#debug.pprof.panel.address). Both read your configuration only when komrad starts, so run [`komrad stop`](https://komrad.dev/latest/cli/stop.md) 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:

```sh
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.
