Troubleshooting

Resolve install, update, runtime, terminal, notes, browser, project-tool, and diagnostics problems in Cordy Desktop, and send feedback.

This page describes Cordy Desktop 0.6.0 on Windows unless a section names another version. macOS and Linux builds are on 0.5.3; see Install.

Install warnings

  • Windows protected your PC: the Windows installer is not code-signed, so SmartScreen warns. Verify the download, choose More info, check the app name, then choose Run anyway. Do not turn off SmartScreen or Microsoft Defender.
  • Apple could not verify the app (macOS 0.5.3): the macOS build is not notarized. Choose Done, then System Settings → Privacy & Security → Open Anyway.
  • The AppImage does not start (Linux 0.5.3): make it executable with chmod +x. Sandboxed startup and AppImage mounting were not fully verified for 0.5.3; if it still does not start, install the .deb package instead.
  • No build for my machine: there is no Windows-on-ARM build and no Intel Mac build.

See Install for the full steps and how to verify a download.

After an update

Cordy has no automatic updater. Install a new release over the old one; your data is kept.

  • Data conversion: 0.5.4 converted workspaces that used their own checkouts, and 0.5.5 converted Markdown notes to block notes. Each conversion runs once on first launch and keeps a byte copy of the original (.pre-upgrade-<stamp> files) that Cordy never deletes.
  • Going back to an older version is not supported after a conversion. A snapshot written by a newer Cordy that this version cannot read is moved aside intact instead of being overwritten.
  • Something looks missing: check project-workspace/project-workspace-migration.log in the user-data folder. It records each conversion and every snapshot Cordy refused or set aside, with the path of the kept copy. See Privacy & Data for the folder layout.

Runtime states

The runtime status indicator shows Runtime: <state>, and Cordy shows a toast the first time the runtime fails.

  • unresponsive: the runtime is alive but has not answered for some seconds. It returns to ready when it answers. If it stays unresponsive, restart the runtime.
  • binary-missing: the runtime binary was not found; Cordy lists the paths it tried. Reinstall Cordy.
  • incompatible: the app and runtime protocol versions differ. Reinstall Cordy so both come from the same build.
  • crashed: Cordy restarts the runtime with exponential backoff from 1 second up to 30 seconds. Repeated crashes appear in the diagnostics log.

A manual runtime restart stops every running terminal and agent session, so Cordy warns "Restarting the runtime will stop N running agent(s)" first. See Runtime.

Terminal input

  • Shift+Enter submits instead of adding a line: Cordy forwards the keyboard protocol the program requests; whether Shift+Enter inserts a newline is the CLI's choice. Codex and Claude Code treat it as a newline. See Terminal.
  • Copy inside a mouse-aware TUI: hold Shift while dragging, then press Ctrl+C or Ctrl+Shift+C. On macOS, Option-drag also forces selection.
  • Ctrl+C interrupts: with no selection it is an interrupt in a plain shell. In a CLI that requests kitty keyboard mode, the CLI receives and interprets the key event.
  • A shortcut steals a shell key: turn off that shortcut's In terminal switch in Settings → Shortcuts, or rebind it. See Keyboard Shortcuts.
  • Ctrl+Alt+Arrow rotates the screen: some Intel graphics drivers use it for display rotation. Rebind Next tab and Previous tab in Settings → Shortcuts.
  • Chinese IME or dictation: composition and codeless paste are supported. If input is lost, include the IME and the program you typed into when you send feedback.
  • [process exited N - press Enter to restart]: the shell crashed or was killed, or the tab is pinned. Press Enter to restart; earlier output stays above [session restarted].
  • [previous session restored]: after a full quit, this marks locally restored terminal history above a new shell. The prior process is no longer running; start the agent again.

Notes

  • The note stopped saving: a note holds at most 1,100,000 characters and 150,000 elements. Over the limit, your edits stay on screen, a notice says by how much, and Show what's over the limit takes you there. Saving resumes once you are back under it.
  • Send was refused: multi-line code is sent only to a program that enabled bracketed paste; choose Paste first line or Copy instead. Code with control characters is never sent, and sending needs an open terminal whose program is still running.
  • Import added nothing: the import would have taken the note over its limit, so nothing was added.
  • A link does not open: links must start with http:// or https:// and carry no user name or password.

See Notes.

Browser

  • Permission denied: Cordy asks only for clipboard read/write and fullscreen. Camera, microphone, geolocation, and unlisted permissions are denied by policy.
  • A site stayed signed in: use Settings → Site data → Sign out for that host, or clear all browser data.
  • Password fill unavailable: activate a built-in browser tab whose scheme, host, and port exactly match the saved credential.
  • Download went to the wrong folder: check Settings → Downloads, including Ask where to save each time.

Project tools

  • Search tool not available: ripgrep is bundled with Cordy. If search reports it missing, reinstall Cordy.
  • Commit is disabled: stage at least one file, resolve every merge conflict (Mark resolved), enter a commit message, and wait for any running Git operation to finish. The reason is shown under the button.
  • Changes list is truncated: the list shows at most 2,000 rows. Hidden rows cannot be staged or discarded from the panel; use Git in a terminal or reduce the working set.
  • History moved while loading: choose Refresh history in Graph to restart from the current branch tip.

Diagnostics

The compact performance overview offers 2-minute, 10-minute, and 1-hour charts and a View details action. The Workload half is Windows-only.

Open Settings → Diagnostics for logs and storage usage. Export log bundle creates a ZIP from a selected time range (Last hour, Last 24 hours, Last 7 days, or Everything) and any selected main log, runtime log, diagnostic events, and system information.

The full performance monitor has a separate Export diagnostics that writes a timestamped local package containing:

  • application and environment information, metrics, and runtime restart history;
  • recent structured events;
  • tails of main.log and runtime.log.

Both exports redact absolute and path-like values. Cordy does not upload either package. Attach one to a report yourself after reviewing its contents. Logs live under logs/, events under diagnostics/, and native crash dumps under Crashpad/ in the user-data directory.

Feedback

Report security issues through the private security advisory form, not in public issues.