Docs: Linux host setup gaps — bunx silent failure, PATH for hooks, tmux persistence

[prefrontalsys]

Context

Setting up moshi-hooks on two Linux hosts (Ubuntu VPS aarch64, Ubuntu desktop x86_64) with bun 1.3.13 and Claude Code. Both hosts had tmux, mosh-server, and bun already installed. The moshi-best-practices skill guided the setup, but three issues required manual fixes beyond what's documented.

1. bunx moshi-hooks setup silently fails without global install

Expected: bunx moshi-hooks setup fetches from the registry and runs (like npx does).

Actual: bunx exits with code 1 and produces no output — no error message, no stderr. This is because bunx doesn't auto-install missing packages the way npx does; it only resolves locally installed scripts.

Workaround: bun install -g moshi-hooks first, then bunx moshi-hooks setup works. Alternatively, npx moshi-hooks setup works without pre-installation.

Suggestion: Either document that bun i -g moshi-hooks is required before bunx commands (the README does mention this but the skill's §6 leads with bunx moshi-hooks setup as if it's self-sufficient), or detect the failure and print a helpful error message.

2. ~/.bun/bin not in PATH for non-interactive shells (hooks fail at runtime)

The hooks registered in settings.json invoke bunx moshi-hooks via non-interactive shell execution. On Linux, ~/.zshrc is only sourced for interactive shells — so even if ~/.bun/bin is in the zshrc PATH, the hooks can't find bunx at runtime.

Fix: Add ~/.bun/bin to ~/.profile (or equivalent login shell config) so non-interactive hook invocations inherit the correct PATH.

Suggestion: The skill's host-readiness checks (§1) verify tmux and mosh-server resolve in login shells — the same check should apply to bunx/moshi-hooks since hooks run in the same non-interactive context.

3. tmux sessions don't survive reboot

The skill (§4) creates a detached tmux session, but doesn't mention that it vanishes on reboot. For always-on hosts (VPS, home servers) this means Moshi's tmux selector is empty after any restart until someone manually recreates the session.

Fix: A systemd user service with Type=oneshot, RemainAfterExit=yes, and WantedBy=default.target (plus loginctl enable-linger) recreates the session at boot.

Suggestion: Add an optional §4.1 covering systemd (Linux) or launchd (macOS) persistence for the tmux session, or at minimum note that the session is ephemeral and won't survive reboot.

Environment

• moshi-hooks 1.1.1
• bun 1.3.13 (installed via npm)
• Ubuntu 24.04 (aarch64 + x86_64)
• Claude Code with moshi-best-practices skill