Troubleshooting & Bug Reporting

When OpenClacky misbehaves (crashes, hangs, wrong replies, tool-call errors), sending us the session bundle + today's log is the fastest way for us to find the root cause.

Why both files matter
- Session bundle — full conversation history, tool calls, and model parameters. Lets us reproduce the exact state you saw.
- Today's log — internal errors, network failures, and subprocess output that happened at the same time. This is where the real root cause usually lives.

Fast Path: One Click

The OpenClacky Web UI's "Download session files" action now bundles session + today's log into a single zip. You don't need to hunt for the log file by hand.

Steps:

  1. Open the OpenClacky Web UI and enter the session where the bug happened (the chat page).
  2. Look at the status bar at the bottom of the chat area — the row right above the message input shows the run state, the current session ID (a short hash like 7fd88060), working directory, model, task count, and cost.
  3. Click that session ID and your browser will download clacky-session-7fd88060.zip.

Zip contents:

clacky-session-xxxxxxxx.zip
├── session.json               # session metadata (messages, tool calls, config)
├── chunk-1.md                 # archived conversation chunks (if any)
├── chunk-2.md
├── ...
└── logs/
    └── clacky-2026-05-16.log  # today's full log

If there's no logs/ directory in the zip, today's log file simply hasn't been written yet (rare — usually only right after startup, before any tool ran). In that case, see the manual fallback below.

Manual Log Attachment (Fallback)

If you're on an older OpenClacky build whose zip does not contain a logs/ directory, please attach the log file manually:

  • macOS / Linux: ~/.clacky/logger/clacky-YYYY-MM-DD.log
  • Windows: C:\Users\<your-username>\.clacky\logger\clacky-YYYY-MM-DD.log

There's one log file per day, and we keep at most 7 days. The file from the day the bug happened is the one we need.

What to Include in Your Bug Report

The zip alone isn't enough. Please also tell us:

  1. OpenClacky version — clacky --version in a terminal, or check the "About" page in the Web UI.
  2. Operating system — e.g. macOS 14.5 / Ubuntu 22.04 / Windows 11.
  3. Reproduction steps — what you did → what you expected → what actually happened.
  4. Approximate time — when the bug occurred (minute precision is fine), so we can locate the right window in the log.
  5. Screenshot or screen recording (optional, but very helpful).

Privacy Notes

session.json and the log files may contain:

  • Every prompt and file content you fed to the AI
  • Tool inputs and outputs (file snippets read, command output, etc.)
  • The model base URL and model name you configured
  • Local file paths surfaced in error stack traces

They will not contain:

  • Your API key (redacted in both session and logs)
  • System passwords / SSH private keys (we never read these)

If your conversation involved sensitive content, before sending the zip you can:

  1. Unzip it and open session.json and logs/*.log in a text editor;
  2. Replace any sensitive snippets with [REDACTED], then re-zip and send.

Where to Send the Report

Send the zip + the info above to any of:

  • GitHub Issues: openclacky/openclacky (preferred — easier to track)
  • Enterprise customers: your dedicated support channel

Don't paste the zip's raw contents into a public issue body — use GitHub's file-attachment feature so search engines won't index sensitive bits.

Session Management
Web Server