Get Moshi
deep dive

Debugging Chat View

Chat View becomes available only after three things line up on the host. Each has its own symptom and its own one-line check.

updated 1 week ago6 min readpage 37 / 37

Chat View renders the coding agent already running in your terminal as a conversation. It never starts a second agent, so it can only appear once the host can answer three questions in order:

  1. Which agent is in this pane? — resolved by the gateway from the multiplexer pane's processes.
  2. Which of that agent's sessions is it? — resolved from state the agent's Moshi hook writes.
  3. Where is that session's transcript, and can it be read? — streamed over /v1/transcripts.

Stage 1 failing means no agent icon. Stage 2 failing means the icon appears but Chat View stays unavailable. Stage 3 failing means Chat View opens and then shows nothing, or stops updating. Work out which symptom you have, then jump to that section.

Requirements, briefly

Before debugging, confirm the setup Chat View actually needs:

  • A supported agent running inside tmux or Herdr. An agent started in a plain shell can never be opened as a chat — Chat View sends prompts back through the multiplexer.
  • moshi-hook installed, paired, running, and reasonably current on the host.
  • A live terminal session in the app, so the gateway is reachable over the SSH forward.
  • Enable Chat on, under Settings -> Chat Mode -> Chat View.
  • Moshi Pro, or remaining free Chat View uses.
note

An agent running in a plain SSH shell is the single most common cause of "it never becomes available". Start tmux or Herdr first, then run the agent inside it.

Stage 1 — the agent icon never appears

The toolbar keeps its generic chat icon, meaning the gateway did not recognize a coding agent in the current pane.

Check what the gateway sees. From the host, with a terminal session open in the app:

does the gateway see an agent?
$curl -s http://127.0.0.1:24543/v1/diff/start
# 405 Method Not Allowed proves the gateway is up
$tail -f ~/Library/Application\ Support/Moshi/hook.log | grep "context request resolved"

The resolved-context line carries agent and agentSession. Read it like this:

  • No agent at all — the pane has no recognized agent process. Confirm the agent is running in the focused pane of the session the app is attached to, not a neighbouring one.
  • kind=shell — the terminal is not inside a multiplexer. Chat View is unavailable by design. Start tmux or Herdr.
  • agent=<name> present — detection worked; your problem is stage 2.

For the full /events payload and how to connect to it directly with wscat, see Debugging the gateway.

Stage 2 — the icon appears, Chat View stays unavailable

This is the agent=claude agentSession="" state: the process was recognized, but no session mapping was found for it.

The gateway deliberately refuses to guess here. One agent binary can own several recent or open sessions, so picking the newest transcript file on disk would show the wrong conversation. It needs the agent's own hook to record which session belongs to which pane.

Check that the hook for that specific agent is installed and current:

hook state per agent
$moshi-hook version
$moshi-hook status
# each target should read current, not stale or not found
$moshi-hook install --target claude

Then submit one more prompt to the agent. Hook state is written when the agent emits an event, so a session that has been idle since before the install still has no mapping. If the running process does not pick up new hook config, restart the agent once.

After the next event, the resolved-context log line should show a populated agentSession.

warn

Installing hooks for an agent that is already running usually requires one new prompt, and sometimes a restart of the agent. Reconnecting the terminal alone does not create the mapping.

Stage 3 — Chat View opens but shows nothing

The session was mapped, so the app opened /v1/transcripts, but the stream is empty, errors, or stalls. Probe it directly with the agent and agentSession values from the log:

stream the transcript by hand
$wscat -c "ws://127.0.0.1:24543/v1/transcripts?source=claude&session=<session-id>"
# healthy: a JSON message with type "backlog", then "append" as rows are written

Install wscat first if needed (bun i -g wscat / bunx wscat, or npm i -g wscat / npx wscat).

The source parameter accepts the agent identifiers the gateway can resolve transcripts for: claude, codex, grok, kimi, opencode, pi, and omp. Omitting source makes the gateway try Claude Code and then Codex.

What the responses mean:

  • backlog arrives with entries — the host side is entirely healthy. The problem is in the app: update it, and check Enable Chat and your remaining trial uses.
  • HTTP 404 / transcript not found — the session id is well-formed but its transcript cannot be located on disk. The agent may have been started under a different HOME, or its state directory moved.
  • HTTP 400 / invalid session id — the id is malformed, or belongs to a different agent than the source you passed.
  • Connects, then never appends — the agent is writing to a different session file now. Resuming or restarting an agent creates a new session; Chat View follows the one mapped to the pane.

Never pick a transcript just because it has the newest modification time. The session id mapped to the active pane is the authority.

OpenCode is different

OpenCode transcripts are not files. The daemon proxies the session's own OpenCode server over HTTP instead, using the server URL that the OpenCode plugin records in agent state. So for OpenCode, transcript not found usually means the plugin never wrote a server URL — reinstall the target and start a fresh session:

opencode target
$moshi-hook install --target opencode
$moshi-hook status

A pre-serverUrl version of the plugin produces the same symptom, so make sure moshi-hook itself is current before digging further.

Chat View was working and stopped

  • "Disconnected" banner — the SSH-forwarded gateway was interrupted. Return to the terminal and reconnect; the stream resumes from the host.
  • Restarted the daemon while a terminal was open — brew services restart moshi-hook kills the forward target. Reopen the terminal in the app.
  • The agent finished and you resumed it — that is a new session id. Switch to the terminal once so the gateway re-resolves the pane.
  • Switched panes or windows — Chat View follows the session mapped to the pane the app is attached to. Multi-session panes stay on the main session by design.

Cards render, but not the way you expect

These are presentation limits, not failures — the terminal underneath always has the raw output:

  • A tool card looks incomplete. The parser could not represent that tool's output yet.
  • A question says to answer in the terminal. That agent or prompt type does not expose a response path Chat View can map back safely.
  • Approve/Deny is missing on a permission prompt. Same reason. Approvals differ per agent, and Moshi only offers buttons when the answer can be delivered unambiguously to the live session.

Daemon log lines worth grepping

tail the log
$tail -f ~/Library/Application\ Support/Moshi/hook.log | grep -E "gateway (events|transcripts)"
  • gateway events: context request resolved — pane lookup succeeded; shows agent and agentSession.
  • gateway events: context request failed — session lookup failed, with the error.
  • gateway transcripts: websocket connected — the transcript was resolved and the stream opened.
  • gateway transcripts: read range failed — the transcript was found but could not be read.