Troubleshooting & feedback

What the errors mean, where the logs are, how to report a bug.

The agent will not start

The tab shows one error naming the agent and where to get it, with a Retry. Kumo checks that the CLI is there and runnable before starting a conversation, and that check is the only place a missing agent is reported.

Usually it is one of: not installed, installed but not on the PATH the app inherits, or installed and too old to have the mode Kumo needs. Settings → Agents shows the version it found.

The agent starts but refuses to work

That is a sign-in problem, and it belongs to the CLI. Open a terminal, sign in there (see Set up an agent for the command) and press Retry. Kumo has no login of its own for agents, holds no API key, and cannot fix this for you.

A turn failed

The failed turn gets its own bubble with the agent’s own reason under your message. Send again, or rephrase. If the agent’s process crashed, Kumo restarts it by itself a few times (after 1, 4 and 16 seconds) on the same session.

A tab is stuck

Right-click the tab → Reopen Agent (⇧⌘R). It stops the process and starts the same session again. The tab, its name and its history stay; queued messages do not, and the confirmation says so. If the agent’s CLI cannot restore a session, the confirmation says that instead: the history stays on screen, but the agent will not remember it.

Runtime is down

The window lost the runtime. A banner appears with a button to start it again; Kumo does not retry in a loop on its own.

Agents are not lost when this happens. Their processes are held outside the runtime, so once it is back it reconnects to everything still alive and picks up where it was. Anything that really died goes grey and comes back when you click the tab or send a message.

Restart runtime to finish the upgrade

The window and the runtime are on different protocol versions, normally after an update where the old runtime still holds the socket. Kumo usually swaps it silently; when it cannot, the banner asks. Restarting the runtime does not stop your agents.

An agent is grey and says asleep

Expected. An agent idle for 30 minutes has its process closed to save memory; the conversation is still there. Send a message and it wakes up in a few seconds, shown as Waking up · 3s. Change or turn off the timeout in Settings → General.

After the Mac restarts, every agent is grey until you click its tab or send it something. Kumo will not start twenty processes at boot.

Free is full here

After the beta, Free has limits (see Plans). The refused action says which one; everything already open keeps working. Close something you no longer need, or move to Personal.

The phone says Linked and the tabs are empty

The page you have is older than the runtime it is talking to. The phone page is updated with each release; a page cached from before an upgrade gets every request refused as a protocol mismatch. Reload the page (a hard reload, since it is a Home Screen app) and, if it persists, pair again.

Offline means something different: the link really is not answering, and it is reconnecting. Subscription ended means this Mac’s plan does not include Remote Control.

Notifications never arrive

macOS asks the first time Kumo needs to post one, not at first launch. If you said no, Settings → General has a line saying so and a button straight to the right place in System Settings. An app cannot grant itself that permission.

On the phone, notifications only work for a page added to the Home Screen. iOS will not even ask in a Safari tab.

Logs

~/Library/Logs/kumo-runtime.log
~/Library/Logs/kumo-gui.log

Starts, stops, method names, errors, and sometimes a short excerpt of a prompt or a bubble when something failed. Not logged: whole conversations, protocol frames, terminal output, attachments.

Quitting

• Close the window (⌘Q, the red dot, Dock → Quit): the window only. Agents keep running and the menu bar icon stays.
• Menu bar → Quit Kumo: everything: agents, terminals, runtime, window. It asks first.

Report a bug

Issues live in the public release repository: github.com/wiseria-ai-labs/kumo-release/issues.

The quickest way in is Report a bug in Settings → About, or in the app menu. It gathers both logs into one file and puts that file on your clipboard, then opens the issue form with your version, your macOS version and the end of the log already filled in. Paste into the form and the file is attached.

There is a bounty during the beta. Every issue we label confirmed earns you one month of Kumo Personal, up to 12 months per account, granted when the beta ends. Feature requests are welcome but don’t count.

Useful things to include: what you did, what you expected, which agent CLI you were using, and the logs if something crashed or hung. Feature ideas go to Request a feature, next to it in About.