Troubleshooting
First-launch warnings, terminal edge cases, runtime failure states, and reading or exporting diagnostics.
This page collects the rough edges worth knowing about — first-launch warnings, a few terminal quirks, the runtime failure states, and how to read or export diagnostics when you need to file a report.
First-launch security warnings
Because builds are unsigned, your OS warns the first time you run Cordy: Windows SmartScreen ("More info → Run anyway") and macOS Gatekeeper (right-click the app → Open → confirm Open). Full per-OS steps are in Install. If macOS still refuses after a right-click → Open, make sure you moved the app into Applications first and try again.
Runtime problems
The runtime is the background process that owns your terminals and agents. Its status shows as a small chip in the bottom-right corner; click it to expand a "Runtime Monitor" panel. The first time the runtime enters a failure state, Cordy also shows a "Runtime unavailable" toast.
Runtime: binary missing
The chip reads Runtime: binary missing, and the expanded panel lists every path it tried.
- Source build? Build the runtime:
pnpm runtime:build(orpnpm dist, which bundles it). See Install. - Packaged build? Reinstall a complete build, or point the app at a runtime binary with
CORDY_RUNTIME_BIN. See Runtime for the resolution order.
Runtime: incompatible
The chip reads Runtime: incompatible, with detail like "expected X, got Y" — the runtime's protocol version doesn't match this app build. This happens when the app and the runtime binary come from different versions. Rebuild the runtime from matching source, or reinstall a matching app build.
Runtime: crashed (and crash loops)
The chip reads Runtime: crashed with the exit code and signal. Cordy automatically restarts the runtime with exponential backoff (1s, 2s, 4s… capped at 30s), and resets that backoff once the runtime has been healthy for a minute. A genuine crash loop shows as crashed recurring with an increasing restart count rather than a separate state. If it will not stabilize, export a diagnostics package (below) and check runtime.log — the restart history is recorded there and survives a relaunch.
Restarting the runtime
The Runtime Monitor panel has a Restart button. If agents or terminals are live, it confirms first ("Restarting the runtime will stop N running agents and all terminal sessions"), because restarting the runtime ends those sessions.
Terminal edge cases
A handful of terminal behaviors are known and worth understanding. Except where noted, these are being tracked for future fixes.
A scrambled terminal after a full relaunch
Symptom. After fully quitting and relaunching Cordy (not closing to the tray), a restored terminal may show a [previous session restored] banner with a scrambled layout — blank space at the top, an agent's input box drawn above the shell prompt, or an overlapped line.
Why. Closing to the tray keeps the runtime and your PTYs alive, so returning that way reattaches cleanly. A full relaunch has no live session to reattach to, so the renderer replays a locally saved snapshot of the last screen, and that cold replay does not perfectly reconstruct full-screen (alternate-screen) TUI layouts.
What to do. The terminal is still functional — the scramble is cosmetic. Run clear (or press Ctrl+L) to repaint, or open a fresh terminal tab. To avoid it entirely, prefer closing to the tray over a full quit when you want to resume the same agent layout.
Chinese IME (Pinyin) input
Reliable Chinese IME input in terminals shipped in 0.1.2: long Pinyin sentences no longer drop or duplicate characters, and the candidate window stays anchored instead of chasing a full-screen TUI's repaints. This fix is always on.
Two narrow cases with Microsoft Pinyin inside a full-screen agent TUI can still drop a character and are being tracked: typing an English word, then a space, then Chinese (the boundary character can be swallowed); and picking an English candidate out of the Chinese candidate window. These stem from the underlying terminal component. If you hit one, retyping the affected character is the workaround.
Voice or dictation input not reaching the terminal
Symptom. A third-party dictation tool types fine into Cordy's own inputs (notes, settings) but its text doesn't reach an agent terminal.
Why. Some dictation tools inject text via a non-keyboard "paste" path that Cordy's terminal doesn't recognize as a paste, so the keystroke is encoded to the shell instead of pasted.
What to do. Enable the tool's "simulate keyboard input" (or equivalent) mode. In that mode the input is delivered as real key events and reaches the terminal normally.
Ctrl+C: copy vs. interrupt
In a terminal, Ctrl+C copies only when there is a selection; with no selection it is always sent as an interrupt (SIGINT). That rule is intentional and will not change.
There is a wrinkle while a full-screen agent is running: agent TUIs often enable mouse reporting, which disables ordinary click-drag selection — so Ctrl+C has nothing selected to copy and always interrupts. To copy in that situation, hold Shift while dragging to force a selection, then press Ctrl+C. (Ctrl+Shift+C is not currently wired to copy, so use Shift-drag then Ctrl+C.)
Diagnostics
Cordy keeps local logs and a rolling metrics history you can inspect and export — useful when filing a bug report.
The performance monitor
Open the performance monitor from the CPU icon in the top bar. It shows live CPU and memory charts, a per-process breakdown, the runtime status, activity counters, and an Export button. Sampling runs for the whole lifetime of the app, so history is already there when you go looking.
Where logs and crash dumps live
Everything is written under Cordy's user-data directory (see Privacy for the exact per-OS location):
| Item | Location | Notes |
|---|---|---|
| App log | logs/main.log | Console output, diagnostic events, and crash stacks. Rotates at 2 MiB, 3 kept. |
| Runtime log | logs/runtime.log | The Rust runtime's output stream. Same rotation. |
| Structured events | diagnostics/events.jsonl | Machine-readable event history. |
| Crash minidumps | Crashpad/ | Native crash dumps. Never uploaded — no server is configured. |
Exporting a diagnostics package
Click Export in the performance monitor. Cordy writes a timestamped folder under diagnostics/exports/ containing:
diagnostics.json— app and environment info, metrics history, and the runtime restart history;events.jsonl— the most recent structured events; andmain.logandruntime.log— the tail of each log.
Paths are redacted before they are written into the export: absolute file paths become [redacted-path], and path-like metadata becomes [redacted]. The export is a local file write only — nothing is transmitted anywhere. The panel shows you the folder's path on disk; attach that folder to a bug report yourself. Cordy keeps the ten most recent exports and prunes older ones.