docs: document the system prerequisites, and report tmux in both doctors
The READMEs never said tmux was needed, so a fresh install only found out when Start Run failed with nothing explaining why. Both doctors were silent about it too. - README/README.vi: a prerequisites table (node, npm, git, tmux, claude, codex, gh, systemd) and per-OS tmux install + verify steps; the feature list is regrouped into observe/drive/configure and now covers analytics, alerts, import, remote sources, the config explorer and Update all. - INSTALL: Step 0 for the system packages, plus a troubleshooting entry separating "tmux missing" from "the server has a different PATH". - SETUP/docs/README: the same troubleshooting entry and a pointer to Step 0. - plugin-doctor: a tmux row, WARN and never FAIL - the run console and `lanes shell` break without it, nothing else does. Reuses tmux.js's own isTmuxAvailable(). - agenthub doctor: asks GET /api/run/tmux instead, because the PATH that decides whether a run starts is the server's, not the caller's shell's.
This commit is contained in:
@@ -324,6 +324,26 @@ The SQLite database uses WAL mode with a 5-second busy timeout. If you see lock
|
||||
|
||||
---
|
||||
|
||||
### The run console won't start a run / the terminal never attaches
|
||||
|
||||
Runs are tmux-backed: the server executes the `tmux` binary and has no fallback.
|
||||
|
||||
```bash
|
||||
tmux -V # missing → sudo apt install tmux
|
||||
curl -s http://localhost:4820/api/run/tmux # {"available":true}
|
||||
curl -s "http://localhost:4820/api/run/binary?tool=claude" # {"found":true,"path":"…"}
|
||||
```
|
||||
|
||||
`{"available":false}` while your own shell finds tmux means the **server's**
|
||||
`PATH` differs from yours — typically a systemd `--user` service, which never
|
||||
reads your shell profile. Install tmux system-wide (`/usr/bin/tmux`) and
|
||||
re-run `agenthub service uninstall && agenthub service install`. The same
|
||||
applies to `claude` / `codex`: a run launches them by name.
|
||||
|
||||
Install instructions per OS: [INSTALL.md → Step 0](./INSTALL.md#step-0--system-packages).
|
||||
|
||||
---
|
||||
|
||||
### No sessions appearing after starting Claude Code
|
||||
|
||||
**Check 1 — Is the server running?**
|
||||
|
||||
Reference in New Issue
Block a user