If something breaks

The session list is empty

Check that CLAUDE_HOME points at the host's real ~/.claude and that there is a projects/ inside. ./scripts/detect-claude-homes.sh can suggest the path, and in the app clauder --print-config prints the directories the server actually reads.

A chat won't start

Most likely there is no live OAuth token in the mounted ~/.claude — sign in to Claude Code on the host. The directory is mounted for writing for a reason: the SDK refreshes the token there and writes sessions.

With the app the cause is usually different: an installed claude wasn't found. The path is set explicitly — CLAUDE_BIN or the "Agent" section in the settings.

EADDRINUSE in the api logs

Hot-reload didn't manage to release the port after an edit: docker compose restart api.

The api container has no java, gh or curl

The image has fallen behind api/Dockerfile. docker compose build api rebuilds it, but the running container stays on the old layer until docker compose up -d api.

An old chat returns 404

The api was restarted, and agent sessions live in memory. Just send the message again — the client will resume.

A 410 means something else: the session was ended with a button and has to be continued as a new one.

Messages from a foreign session appear only after its reply finishes

The UserPromptSubmit hook isn't connected — the api simply doesn't know about them. See Hooks.

"Continue in chat" is unavailable

The session is from another source — Windows, say, while running in WSL. For it the reply through the host bridge works, if that is set up.

The spend numbers lag behind or are empty

The index catches up by scanning and runs into a budget on the first visit — a repeated request picks up the rest. A thoroughly broken index is cured by deleting clauder.db next to the sessions directory: it will be rebuilt (favourites, titles and "read" marks go with it).

The bot shows 409 Conflict

One token, one polling loop. Clauder in docker and the same Clauder in the app cannot run one bot between them.

There are no notifications in the browser

Web Push requires https (or localhost). Over http on a local network notifications exist only in the app, on Android and in the bot — see Notifications.

The projects split in two

Usually that is WORKSPACE_ROOT passed into the container at a different path than on the host: Claude Code generates a different directory slug, and the chat's sessions drift apart from the host ones.

The terminal works line by line

That is by design on Windows: Bun has no pty there yet, so the shell runs through pipes. What doesn't work because of that is in Terminal.