Troubleshooting

Troubleshooting

When Clayo crashes, it writes the exception to %LOCALAPPDATA%\Clayo\crash.log before it goes (App.LogFatal). Look there first.

Installing and starting

Typing clayo in Explorer does nothing.

• Check that the publish folder is on your user PATH, and open a new Explorer window after changing it. See Install.
• Clayo may already be running with its window hidden (closing only hides it). A second clayo hands its folder over and the window should come forward with a new session.
• If an old clayo.exe is stuck in the background, it still holds the single-instance mutex and every new clayo hands its folder to it and exits. End clayo.exe in Task Manager and try again. Clayo exits its process hard on quit to avoid this (App.OnExit), so it should be rare.

SmartScreen warns about an unrecognized app. Clayo builds aren't code-signed. A build you made yourself usually won't trigger it; a downloaded clayo.exe can. Choose More info › Run anyway if you trust where it came from.

The terminal pane is blank or Clayo closes when a session opens.

• The WebView2 runtime may be missing. Install the Evergreen runtime from Microsoft, then check crash.log.
• Assets\ must sit next to clayo.exe. Publish the whole folder, not just the exe.
• xterm.js is vendored in Assets\xterm\ and loaded from the local https://ccx.assets/ virtual host. Nothing loads from a CDN, so working offline is fine. (The old README said it loaded from jsDelivr; that is no longer true.)

"Couldn't start the shell: …" in the pane. Clayo couldn't start PowerShell under ConPTY. The message is the Windows error.

claude is not recognized. Each pane types claude ... into PowerShell. Make sure claude runs from a new PowerShell window. Clayo uses pwsh.exe if it is on your PATH, otherwise powershell.exe, so check the one it picks.

Inside a pane

Box-drawing characters come out as mojibake. Add this to your PowerShell profile:

[Console]::OutputEncoding = [Text.Encoding]::UTF8

The first characters of the claude command go missing. Clayo waits 400 ms after starting the shell before typing the command, because PowerShell drops input sent before its prompt is up. A slow profile can take longer than that. Trim your profile, or retype the command. Sniffing for the prompt in the output would be the real fix.

The pane shows [shell exited]. The PowerShell in that pane ended (you typed exit, or it crashed). Close the pane with ✕ and open the session again.

The status light is wrong. Status is read from the output alone: "Do you want to" means needs you, "API Error:" means an error, sustained output means running, and 1.5 s of quiet means done. A prompt worded differently won't show as needs you. A needs-you or error light stays until output picks up again.

Ctrl+C cleared my input instead of copying. Ctrl+C copies only when there is a selection in the terminal; otherwise it is the usual interrupt. Select first, then Ctrl+C.

Sidebar

"No transcripts found under ~.claude\projects." Claude Code hasn't saved a session on this machine yet. Start one and it shows up.

A session I started isn't in the list. It appears as soon as its transcript is on disk; until then a session started in Clayo shows under Open with a placeholder name. If you started Clayo from inside a Claude Code session, the inherited session markers would switch off transcript saving, so Clayo clears them at start-up (SessionLauncher.ScrubInheritedSession).

A branch shows at the top level. Clayo only knows a branch's parent if the branch was made with Branch from here. Branches made outside Clayo, or whose parent transcript is gone, show as top-level sessions. See Sessions and Branching.

Status bar and limits

The pane header strip is empty.

• Claude hasn't refreshed its status line in that pane yet.
• The session was started outside Clayo, so it has no relay.
• Show in the pane header is off, or every field is unticked. See Settings.

The limits never show. Clayo only shows limits Claude Code hands its status line. Some accounts get none; then Clayo can only read a cache file your own status line script saves. See Status Bar and Limits.

A limit looks dimmed. Its reset time has passed and Claude hasn't reported since, so the number is the old window's.

For developers

These are the places the low-level code is most likely to break. Each is still how the code works today.

• InitializeProcThreadAttributeList size probe (ConPty.cs). lpSize is a SIZE_T, declared here as ref IntPtr. That is right on x64, but check it first if CreateProcess fails with error 87.
• PtyProcess.Dispose order. ClosePseudoConsole can block while the client is still attached and the output pipe isn't drained. The order is: terminate the process, close the pseudoconsole, then dispose the streams. If closing a pane hangs, look here.
• Resize storms. Calling ResizePseudoConsole on every resize makes the TUI redraw garbage. Assets/terminal.html coalesces resizes to 60 ms; raise it if dragging the splitter looks bad. TerminalPane also skips a resize to the same size or while the window is minimized.
• The 400 ms typing delay in TerminalPane.StartPty, above.
• DevTools. F12 in a terminal pane opens the WebView2 DevTools (AreDevToolsEnabled is on).