Troubleshooting
Runtime problems
Blank terminals, thin traces, the MCP "Not Built" state, sync, SSH host keys, and your local data.
These are the problems you might run into while working: a terminal that is not responding, traces that look thinner than expected, a status that looks alarming but is not, sync that does not show up elsewhere, a remote session that will not connect, and questions about where your data lives. Each section is a single problem and its real fix.
The terminal is blank or not responding
Operon runs its embedded terminals through a persistent background terminal daemon that lives under your ~/.operon directory. The daemon deliberately survives app restarts so your sessions stay alive. Almost always, if a terminal is stuck, blank, or not accepting input, restarting the app re-establishes the connection to the daemon and brings the terminal back.
- 1
Quit Operon fully
Close the app completely rather than just closing the window. On macOS use Quit; on Windows and Linux exit the app entirely.
- 2
Reopen it
Launch Operon again. On restart it reconnects to the running terminal daemon and restores your session state, including terminal history for the session you were in.
- 3
Reopen the session
Return to the session whose terminal was stuck. The terminal re-attaches and should accept input again.
Traces look thin or have no rich tool data
Operon captures the richest data — individual tool calls, sub-agents, and full response context — through hooks. For Claude Code, this runs through a hook receiver that Claude Code reports events to in real time. If your traces are missing that detail, the most likely cause is that hooks are not registered for the tool or scope you are working in.
- 1
Open Hooks in Settings
Go to Settings and open the Hooks section. It shows the Hook Receiver status (Running or Not Running) and the registration scope.
- 2
Check the receiver is running
If the Hook Receiver shows Not Running, rich capture cannot arrive. Confirm it is running before troubleshooting anything else.
- 3
Match the scope to where you work
Hooks register at one of two scopes. Global applies to all projects; Project only applies to the current workspace. If your traces are thin in one project, make sure hooks are registered at a scope that covers it, then use Re-register Hooks to apply the change.
Note
Even without hooks, Operon still builds traces from what it observes in the terminal — you never lose your session. Hooks add depth (precise tool calls and sub-agent detail); their absence means less detail, not no data.
The MCP Server shows "Not Built"
In Settings, under MCP Server, you may see the status read Not Built. This is an expected state in some builds and is not an error. The MCP Server is an optional component that exposes Operon data to MCP-compatible clients like Claude Desktop or Cursor; when it has not been compiled in your build, the status simply reports that. Nothing about your sessions, traces, or the rest of the app is affected.
Note
"Not Built" for the MCP Server is a valid, benign status — not a failure. If you are not using Operon as an MCP data source for another client, you can ignore it entirely.
Sync is not showing on my other device
Sync mirrors session metadata — traces, decisions, and tasks — to the cloud so it appears on your other devices. It never syncs your code. If your work is not appearing on a second machine, walk through the checks below.
| Check | Why it matters |
|---|---|
| You are signed in on both devices with the same account | Sync only runs for a signed-in account; local mode never touches the cloud, so a device in local mode will never receive synced data. |
| Sync is not turned Off | The Sync section in Settings has a Sync Level with an Off option. If it is Off on either device, nothing mirrors in that direction. |
| The sync level covers what you expect to see | Levels range from Full down to Decisions and Observe. A narrower level syncs less, so metadata you expected may simply be outside the chosen level. |
| You expected only metadata to sync | By default, sync includes prompt text, tool inputs/outputs, and code diffs, not just metadata — turn off the per-project code-content toggle if you want to sync metadata only. Your repository itself is never uploaded as files. |
An SSH remote session fails to connect
Operon can drive sessions on a remote machine over SSH, with hosts managed in Settings under SSH Hosts. The most common surprising failure is a host-key mismatch. On the first successful connection to a host, Operon pins that host's key fingerprint. On every later connection it checks the presented key against the pinned one, and if the key has changed it refuses to connect — reporting a host-key mismatch — to protect you from connecting to an impostor.
- 1
Confirm the key change is legitimate
A changed host key can mean the server was rebuilt or rekeyed for a good reason — or that something is impersonating it. Do not proceed until you are sure the change is expected and trusted. If you are not sure, treat the mismatch as a real warning and stop.
- 2
Forget the old pinned key
Once you have verified the new key is legitimate, forget the previously pinned key for that host so Operon stops comparing against the stale fingerprint.
- 3
Reconnect to re-pin
Connect again. Because there is no longer a pinned key on file, Operon trusts and pins the new key on this first connection, and the session proceeds. Subsequent connections check against the new key.
Where is my data, and how do I reset it
Operon stores everything locally under your ~/.operon directory — this is where your local database and app configuration live. You control that data directly from Settings, under Data.
- Export: download all your sessions, traces, and decisions as JSON — useful for a backup or before a reset.
- Clear: permanently delete all local sessions and traces. This is destructive and asks you to confirm first, so a stray click will not wipe your history.
- Location: everything lives under ~/.operon, so a full reset is a matter of exporting first (if you want a backup), then clearing.
Important
Clear All Data is permanent and cannot be undone. Export first if there is anything you want to keep.