Troubleshooting & FAQ

Something is wrong

npm i fails on node-pty (Linux, WSL)

The terminal panel needs a C++ toolchain. On Debian or Ubuntu:

sudo apt install build-essential python3

The browser keeps asking to pair

Open the pairing link the daemon printed at start (it ends in #token=…). On an iPhone Home Screen app, paste that link into Pairing link or token and tap Pair. iOS can clear the app's storage after weeks without use; pair again then.

"This daemon does not accept that token"

The token changed (the token file was deleted, or you use a different config folder). Copy the link the daemon printed last.

Port in use

Start on another port: claude-ui --port 4281.

WSL or Docker side "stopped (exit code 1)"

In 0.5.0 every WSL and Docker side stops about 15 seconds after it starts. This is a known bug: #263. Retry starts it again, but it stops again. Windows and local projects are not affected.

The side needs Node.js or build tools

The Open project dialog says what is missing. A WSL distro or Docker container with glibc (Debian, Ubuntu, ...) needs only sh, tar and gzip (a WSL distro also bash): claude-code-ui uses a Node.js 22+ found there, else brings its own. A WSL distro that installs with npm (musl, see below) needs Node.js 22+, make, python3 and g++. Open What this container needs in the dialog for the list with a ✓ or ✗ per item. The dialog does not check the Claude login: a session started without one says so. See WSL & Docker.

A Docker container or WSL distro installs with npm, not the bundle

The dialog says why. Causes:

• The container or distro uses musl (Alpine) or a CPU other than x86_64 and arm64, has glibc older than 2.28, or has no libstdc++. Use a glibc image or distro, or install Node.js 22+, make, python3 and g++ there.

• Your computer could not download a part (Node.js from nodejs.org, only for a target without Node.js 22+; node-pty, the Claude Agent SDK or Claude Code from the npm registry) and has no checked copy in ~/.cache/claude-ui/side. Check the network or set CLAUDE_UI_UPDATE_REGISTRY to a registry mirror, then retry.

• docker exec could not run in the container (stopped meanwhile, no sh, runtime error): the reason quotes the error.

Parts of an older claude-ui version stay in the cache for 7 days after their last use, then are removed.

A downloaded or cached part that does not match its checksum is never used: it is downloaded again.

Push notifications do not work

• The page must be on HTTPS (or localhost). Use --tailscale.
• On iPhone/iPad: iOS 16.4+, and the app must be on the Home Screen.
• Without HTTPS, the daemon's computer shows desktop notifications instead (Linux needs notify-send, package libnotify-bin).

A new version does not start

claude-code-ui falls back to the previous version and says so. See Updates.

--tailscale exits right away

It prints what is missing: Tailscale not installed or not logged in, MagicDNS or HTTPS certificates off, the machine not approved, or Funnel on. On Linux without root, run sudo tailscale set --operator=$USER once. On Windows with WSL, run --tailscale on Windows, not inside WSL.

FAQ

Do sessions stop when I close the browser?

No. They run in the daemon. Open the page again to catch up.

Do sessions stop when I stop the daemon?

The running turn stops. The session and its history stay, and you can continue it after the next start.

Does it work with sessions from the claude CLI?

Yes. Both read and write the same history in ~/.claude. A session started in one shows up in the other.

How do I unpair all browsers?

Delete the token file in the config folder and restart. Every browser must pair again.