Troubleshooting
Most problems come down to Claude Code not being found, or the panel not opening. Here’s how to fix the common ones.
The chat panel won’t open
Section titled “The chat panel won’t open”Press Cmd+Shift+H (Mac) or Ctrl+Shift+H (Windows). If nothing happens, open the command palette (Cmd+P / Ctrl+P) and search for “Hyo” to open it from there.
Claude isn’t working, or nothing happens when you send a message
Section titled “Claude isn’t working, or nothing happens when you send a message”Everything to do with Claude lives in one place: Settings → Hyo Claude Code Agent → Setup.
Open it and read the status line at the top. Hyo checks by actually running Claude, so it tells you what’s really going on:
- “Ready” — Claude’s installed and you’re signed in. If a message still does nothing, start a new conversation tab.
- “Not signed in” — click Sign in to Claude. A browser tab opens to approve, and you’re done.
- “Not installed” / can’t find it — click Install Claude, then Sign in to Claude.
If the status looks wrong, click Auto-detect — it re-runs Claude and sorts out which install to use.
“Claude process exited unexpectedly (code 1)”
Section titled ““Claude process exited unexpectedly (code 1)””This means Hyo started Claude and it crashed straight away. The chat will tell you to start a new conversation — do that first, as a broken conversation can cause it on its own.
If it keeps happening, go to Settings → Hyo Claude Code Agent → Setup and click Auto-detect. It runs Claude to check it really works and tells you what’s wrong — usually that you need to Sign in to Claude (a signed-out Claude exits immediately), or that the install is broken and you should click Install Claude to set it up fresh.
Auto-detect didn’t find Claude Code
Section titled “Auto-detect didn’t find Claude Code”Auto-detect asks your own shell where Claude is, the same way your terminal does, and checks the common install locations too — so it finds Claude even when it’s installed through a version manager like nvm or fnm. If it still comes up empty, Claude probably isn’t installed: click Install Claude in the Setup tab and Hyo installs it for you.
If you know Claude is installed in an unusual spot, you can paste the full path into the Claude Code path box in the Setup tab (run which claude on Mac, or where claude on Windows, to find it).
Hyo shows a setup screen about installing Claude Code
Section titled “Hyo shows a setup screen about installing Claude Code”That’s expected when Claude isn’t set up yet. Click Install Claude, then Sign in to Claude — Hyo does both for you, and a browser tab opens only to approve the sign-in. See Install Claude Code.
The usage bars are empty
Section titled “The usage bars are empty”Usually this sorts itself out — Hyo reads your usage from your Claude account and occasionally needs a moment, especially just after installing or if you haven’t signed in to Claude Code yet. If it stays empty, make sure you’re signed in to Claude Code.
The plugin won’t update
Section titled “The plugin won’t update”Hyo updates through BRAT. Go to Settings → BRAT and check for updates. If it’s stuck, remove the plugin from BRAT and add it again with the repo URL — you won’t lose your settings.
Something else
Section titled “Something else”If a conversation gets into a broken state, starting a new tab is the quickest reset. Your past conversations are still saved. For anything that looks like a real bug, the GitHub repository is the place to raise it.