Start with claude-rs doctor. It runs installation, runtime, config path, log path, npm metadata, and credential checks, and it names the failing boundary for most of the problems below.
claude-rs doctor
claude-rs doctor --jsonWhen you need the underlying detail, enable diagnostics and read the log. See Diagnostics for presets, log locations, and debug bundles.
claude-rs logs
claude-rs logs --tail 200The TUI depends on the Agent SDK bridge, which runs as a child process under a private Bun runtime. If the bridge cannot start, the app reports the failing boundary as spawn, initialization, stdout close, SDK or protocol failure, or timeout.
Check what the app actually resolved:
claude-rs doctor --jsonThe bridge_runtime, bridge_runtime_version, and bridge_script checks show which runtime and bridge script the binary picked. A missing or unexpected path there is the usual cause: a source build without the bridge built, a partially extracted install, or a stale CLAUDE_RS_AGENT_BRIDGE override left in the environment.
For a source build, the bridge has to be built before the app can spawn it. See Development.
To capture the bridge's own startup output, run with bridge logging enabled and inspect the log:
claude-rs --enable-logs --diagnostics-preset bridge
claude-rs logs --latestIf startup reports that required organization configuration is temporarily unavailable, check connectivity and retry. If access to organization configuration was refused, sign in with an allowed account or contact your organization administrator.
Authentication is owned by the Claude Code CLI, not by this project. claude-rs reuses the credentials the CLI already holds.
Sign in from inside the app with /login, or from a shell:
claude auth loginIf login appears to succeed but sessions still fail, confirm that the CLI itself works, then re-check the credential state:
claude-rs doctorBilling, model availability, and service limits are controlled by Anthropic and surface here as session errors rather than install problems.
Extra usage being enabled and extra usage being available are separate conditions. A warning offers continued use only when the SDK confirms both; an unavailable allowance is not a promise that work will continue. A refresh failure reported as an invalid request, such as a full disk, remains a request failure and does not trigger login from its error text.
For the authentication and permission flow in the log, use the session preset:
claude-rs --enable-logs --diagnostics-preset sessionThe script install and the npm install use different layouts, and neither owns the other's files. If both are present, PATH order decides which one runs, so an update can appear to do nothing.
Multiple script installations can also coexist after installing into a custom directory. The installer shows the current and other locations, then offers y Yes / N No cleanup for recognized copies after the new installation passes verification. Check the named directory before confirming; a temporary test installation may be offering to remove your normal copy. Unknown copies receive manual guidance instead.
List every claude-rs that is visible on macOS/Linux:
command -v claude-rs
which -a claude-rsOn Windows:
Get-Command claude-rs -AllCompare the resolved path with the install layout reported by:
claude-rs --version
claude-rs doctorIf the wrong one wins, remove the install you do not want, or reorder PATH so the one you want comes first. See Switching Install Methods and Uninstall.
If npm omitted optional dependencies, the launcher cannot find the native platform package. Check your npm config and reinstall:
npm config get omit
npm install -g claude-code-rustIf the resolver reports a missing platform package, npm optional dependencies were likely omitted. Check npm config get omit and reinstall without --omit=optional.
Linux npm packages currently require glibc. On musl-based distributions, build from source until a matching npm package is available.
If claude-rs resolves to an older global shim, ensure your npm global bin directory comes first on PATH or remove the stale shim before retrying.
For install failures, see Reporting Install Problems. For anything else, see Useful Issue Reports and attach a redacted bundle:
claude-rs logs --bundle --yes