Chat Mode won't start or send

Most Chat Mode problems come from an older Waycar plugin on the Host, a missing opencode step, or a question the agent is waiting on in its terminal. Chat Mode works with Claude Code, Codex, omp, pi and opencode. Other agents open in the terminal as usual.

“Update the Waycar plugin”

Chat Mode needs the latest Waycar plugin on your Host. If a chat shows Update the Waycar plugin, or Update the Waycar plugin on … to see replies here, run the install command again on that Host:

curl -fsSL https://waycar.dev/install.sh | sh

Then open the chat again. See Update Waycar on your Host.

The agent is waiting on a question

A fresh folder can make the agent ask a question before it takes your message, such as Claude Code asking whether you trust the folder. While it’s asking, Waycar won’t send. Tap Show Terminal, answer the question, then send your message again.

“… is still starting. Try again in a moment.”

The agent hasn’t finished starting. Wait a moment and send again. opencode ignores typing until its input box appears, so Waycar waits for that box before sending. If it never shows up, you see OpenCode is still starting and your message isn’t lost.

opencode chats need one more step

• herdr: run this once on the Host:

  herdr integration install opencode

• herdr and tmux: opencode gets the Chat Prompt only through a Waycar extension, which the install command adds when opencode is already installed. Install opencode first, then run the install command. If you installed opencode after Waycar, or used --no-hooks, run the install command again without it. Without the extension, replies don’t follow the Chat Prompt.

“Can’t refresh”

The chat header shows Can’t refresh when Waycar can’t read the conversation. The chat may also say:

Message	What to do
“This Agent can’t show a chat.”	Tap Show Terminal to use the agent in its terminal.
“The conversation couldn’t be read.”	Wait for Waycar to try again, or reopen the chat. Tap Show Terminal to keep working meanwhile.

The chat won’t launch

Message	What to do
“Waycar couldn’t write the Chat Prompt to …” or “…the first message to …”	Check that the Host has free disk space and that your user can write files there, then try again.
“The launch command is … bytes, more than the 1000 a new pane can take.”	Shorten New Agent’s Arguments, the Model, or the Chat Prompt in Settings › Chat Mode.

On tmux: Allow and Cancel do nothing

On tmux, Allow and Cancel, and opencode chats, need Waycar hooks. Run the install command again after installing your agents. See Waycar hooks for tmux.

Replies don’t show up in notifications

Chat Mode replies in notifications work with herdr only for now, not tmux. On herdr, make sure notifications are on for that Host. See Notifications don’t arrive.

Good to know

• Chat Mode is chosen when you start an agent. Turn on Chat Mode in the New Agent sheet, or start one from the Home Screen with New Chat.
• You can always tap Show Terminal to see exactly what the agent is doing.