diff --git a/cmux-tui/README.md b/cmux-tui/README.md
index 8b21e0acf847..4c8833b8e57e 100644
--- a/cmux-tui/README.md
+++ b/cmux-tui/README.md
@@ -90,6 +90,8 @@ ssh -T dev@buildbox cmux relay --session agents
 
 The Unix-only `machine-agent` shares an existing local session through one outbound SSH registration with cmux.cloud. It prints a one-time pairing code and opens no listener. The final command is a low-level raw JSON-lines diagnostic. Use the machine rail or `cmux ssh` for the managed remote lifecycle.
 
+If `npx cmux@latest` fails with an npm `ENOTEMPTY: directory not empty, rename` error, the npx package cache is stale; see [Troubleshooting npx installs](docs/getting-started.md#troubleshooting-npx-installs).
+
 Use `--term <value>` to set `TERM` for child PTYs. Without it, children get `xterm-256color`; `CMUX_TUI_TERM` can override the terminal runtime default, with `CMUX_MUX_TERM` retained as a legacy fallback.
 
 ## Browser ownership
diff --git a/cmux-tui/dist/npm/cmux/bin/cmux.js b/cmux-tui/dist/npm/cmux/bin/cmux.js
index f8a0c63dfb51..abee99008e9e 100755
--- a/cmux-tui/dist/npm/cmux/bin/cmux.js
+++ b/cmux-tui/dist/npm/cmux/bin/cmux.js
@@ -35,7 +35,9 @@ try {
 } catch {
   console.error(
     `cmux: platform package ${pkg} is not installed. Reinstall cmux, ` +
-      `or set npm to install optional dependencies (--include=optional).`
+      `or set npm to install optional dependencies (--include=optional). ` +
+      `Under npx, a stale cache can also cause this (or an ENOTEMPTY rename ` +
+      `error during install): run \`rm -rf ~/.npm/_npx\` and retry.`
   );
   process.exit(1);
 }
diff --git a/cmux-tui/docs/getting-started.md b/cmux-tui/docs/getting-started.md
index 5e315aa00e4d..9e2bde648cad 100644
--- a/cmux-tui/docs/getting-started.md
+++ b/cmux-tui/docs/getting-started.md
@@ -108,6 +108,26 @@ npx cmux machine-agent --session agents
 
 Run this command from an interactive terminal with `/dev/tty`; the agent fails closed without a controlling terminal, including on reconnects. The first registration prints the one-time code used by `+ ssh host` on cmux.cloud.
 
+## Troubleshooting npx installs
+
+`npx cmux@latest` can fail inside npm before cmux runs:
+
+```text
+npm error code ENOTEMPTY
+npm error syscall rename
+npm error path ~/.npm/_npx/<hash>/node_modules/cmux-tui-darwin-arm64
+npm error ENOTEMPTY: directory not empty, rename ...
+```
+
+This is a long-standing npm bug in the `npx` package cache, not a cmux failure. It triggers when the cache holds an older cmux version and npm upgrades it in place, and it hits packages with per-platform binary dependencies (cmux ships `cmux-tui-<platform>` optional dependencies) most often. Clear the npx cache and rerun:
+
+```bash
+rm -rf ~/.npm/_npx
+npx cmux@latest
+```
+
+A global install avoids the npx cache entirely: `npm install -g cmux`, then run `cmux` and upgrade with `npm install -g cmux@latest`.
+
 ## Sessions and sockets
 
 The default socket path is: