# Logs and bug reports

> Where Hivemind writes what it does on each system, what to collect when something breaks, and how to report a bug.

Source: https://hivemind.griiken.com/guide/logs-and-bug-reports/

When something breaks, collect what Hivemind printed, then report it with the steps that cause it.

<AgentPrompt description="Paste this into your coding agent to collect what a Hivemind bug report needs, without secrets." page="logs-and-bug-reports">{`
Collect what a Hivemind bug report needs from this computer, and draft the report.

1. Ask me what went wrong and the steps that cause it.
2. Record \`hive --version\`, the operating system and its version, and the CPU type (\`uname -sm\` on Linux and macOS).
3. Run \`hive ctl agents --json; echo "exit $?"\`, \`hive agents list\` and \`hive daemon status\`, and keep their output.
4. Read the log files listed on this page for my system, if they exist. Keep only the lines near the time it went wrong.
5. Remove anything secret before showing me: tokens (they start with \`hgr_\`), passwords, private hostnames, and my home folder's name if I ask.
6. Draft an issue for \`https://github.com/dip497/hivemind/issues/new\`: what happened, what I expected, the steps, the version, and the output above in code blocks. Show me the draft; do not post it.
`}</AgentPrompt>

## Where the logs are [#where-the-logs-are]

The app writes no log file of its own. It prints to the terminal it was started from. These files exist once the part that writes them has run.

| What | Linux | macOS | Windows |
|---|---|---|---|
| The app's output | Start it with `hivemind` in a terminal and watch that terminal. | Start it with `hivemind` in a terminal and watch that terminal. | Not shown: `hivemind` starts it detached. |
| The background process, when `hive` started it | `~/.config/hivemind/pty-daemon.log` | `~/Library/Application Support/hivemind/pty-daemon.log` | none |
| A tool's service | `~/.config/hivemind/services/<owner>--<name>.log` | `~/Library/Application Support/hivemind/services/<owner>--<name>.log` | `%APPDATA%\hivemind\services\<owner>--<name>.log` |
| Text that looks blurry | `~/.config/hivemind/render-diag.log` | `~/Library/Application Support/hivemind/render-diag.log` | `%APPDATA%\hivemind\render-diag.log` |
| `hive host`, run as a service | `journalctl --user -u hive-host.service` | none | none |

On Linux, `$XDG_CONFIG_HOME/hivemind` replaces `~/.config/hivemind` when you set it. `HIVEMIND_APP_DATA` names another folder for all of them.

## What to collect [#what-to-collect]

1. To get your version, run `hive --version`.
2. To see what the app holds, run `hive ctl agents --json`. Exit 3 means the app is not running.
3. To see each agent and why any failed to load, run `hive agents list`.
4. To see whether the background process runs, run `hive daemon status`.
5. For a machine, run `hive machine check <name>`. For other devices, run `hive network doctor`.

<Warning>
Remove tokens before you share anything. A token starts with `hgr_` and lets a program drive your workspace.
</Warning>

## Report a bug [#report-a-bug]

Open an issue at [github.com/dip497/hivemind/issues](https://github.com/dip497/hivemind/issues). Include:

- what happened, and what you expected;
- the steps that make it happen again;
- your system, and the output of `hive --version`;
- the commands' output and the log lines from above.

For a security problem, follow [SECURITY.md](https://github.com/dip497/hivemind/blob/main/SECURITY.md) instead of opening a public issue.

## Related [#related]

- [Troubleshooting](https://hivemind.griiken.com/guide/troubleshooting/): fixes by what you see.
- [Changelog](https://hivemind.griiken.com/guide/changelog/): a newer release may already fix it.

<LastValidated />