Troubleshooting

Common issues and how to fix them.

App Won't Open (“Apple could not verify…”)

If macOS blocks the first launch of a downloaded build:

  1. Open System Settings → Privacy & Security.
  2. Scroll down to the message about Orcha and click Open Anyway.
  3. Launch Orcha again and confirm.

This happens once per download; after that Orcha opens normally.

Dictation Not Working

If holding ⌥Space doesn't dictate into the terminal:

  1. Ensure Orcha has microphone access in System Settings → Privacy & Security → Microphone.
  2. Verify speech recognition is available — dictation uses the on-device macOS speech engine, so check System Settings → Siri & Spotlight.
  3. Make sure a terminal is focused — dictation types into the active session.

Projects Not Showing

If Orcha doesn't show any projects:

  1. Orcha scans ~/.claude/ on launch. Make sure this directory exists and contains project data.
  2. Run claude in at least one directory to create session data, then restart Orcha.
  3. Verify Claude Code is installed: claude --version

Session Status Looks Wrong

Live status (working / waiting on you) comes from Claude Code's native hooks, which Orcha registers on first launch. If statuses never update:

  1. Restart Orcha — it re-checks its hook registration on launch.
  2. Check that ~/.claude/settings.json exists and is valid JSON (a syntax error there prevents hooks from firing).
  3. Sessions started before Orcha was installed won't report status until their next event.

App Crashes

If Orcha crashes:

  1. Use Report a bug in Settings — it prefills a GitHub issue and can attach a diagnostics export.
  2. Check crash reports in ~/Library/Logs/DiagnosticReports/ — look for files starting with "Orcha".
  3. Make sure you're on the latest build from the download page.

Terminal Issues

Terminal is blank or unresponsive

Close and reopen the tab. If the issue persists, quit and relaunch Orcha — running terminals are restored per workspace.

Colors or formatting look wrong

Orcha uses SwiftTerm which supports most ANSI escape sequences. If you see rendering issues, ensure your TERM environment variable is set to xterm-256color.

Download Issues

Re-download anytime from the download page— sign in with the same email you used originally and it serves the latest build. There are no license keys and nothing to activate. Locked out? Email support@orcha.build.

Getting Help

Still stuck? Reach out:

← PreviousKeyboard Shortcuts