AgentHub/plugins/agenthub/commands/agenthub-doctor.md

description

description
Diagnose a plugin-installed AgentHub — Node, npm, disk, bootstrap, server, hooks, CLI, systemd, tmux, UI build — and offer to fix what it finds

1. Diagnose

Every command here runs from the plugin build that is installed NOW (ROOT): a session not restarted after an update still names the old build in ${CLAUDE_PLUGIN_ROOT}, which would warn about itself forever. The shell does not keep ROOT between commands, so each command block below resolves it again:

ROOT=$(node -e 'console.log(require(process.argv[1]).supersededBy() || "")' \
  "${CLAUDE_PLUGIN_ROOT}/scripts/plugin-bootstrap.js")
ROOT="${ROOT:-${CLAUDE_PLUGIN_ROOT}}"
node "$ROOT/scripts/plugin-doctor.js"

Print the output verbatim. If every row is OK, stop there — no summary of things that passed.

2. Offer to fix

If any row is FAIL or WARN, say in one line per row what is wrong (use the guide below), then ask with AskUserQuestion: "Tự động sửa các lỗi trên?" (answer in the user's language) — options "Có, cho tôi xem danh sách việc sẽ làm" and "Không". On "Không", stop.

3. Show the plan, get approval

Build the plan from the table below: only the rows that are not OK, in the table's order, each with the EXACT command you will run. Merge duplicates — one plugin-bootstrap.js --force covers every row marked bootstrap. Rows marked report only go in a separate "cannot fix automatically" list. Print the plan as a numbered list, then ask with AskUserQuestion: "Thực hiện các bước trên?" — "Đồng ý" / "Không". Do nothing until the user agrees.

Detect what the commands need before printing them: the OS (uname -s), the package manager (apt-get, dnf, pacman, brew), a Node version manager (nvm, fnm, volta — check with command -v or ~/.nvm/nvm.sh), the user's shell rc file from $SHELL, and whether sudo -n true works.

Row	Fix
FAIL Node / FAIL npm	Install Node ≥ 22.5 (it ships npm). Prefer the user's version manager (nvm install 22 && nvm alias default 22, fnm install 22 && fnm default 22, volta install node@22); else brew install node (macOS) or the distro's package (sudo apt-get install -y nodejs only when it is ≥ 22.5 — otherwise propose nvm). Then run the bootstrap step with THAT node's absolute path, since the agenthub CLI launcher pins the node that ran the bootstrap.
FAIL Disk	Report only. Show what is large (du -sh "<Data dir>"/* 2>/dev/null, the Data dir row's path); never delete user data.
FAIL Runtime deps	rm -rf "<Data dir>/runtime/node_modules" (the Data dir row's path), then bootstrap — reinstalling over the broken tree is what lets it survive.
WARN Runtime deps, WARN Bootstrap, FAIL Server, FAIL Hooks, WARN agenthub CLI "no launcher", WARN systemd "previous plugin version"	bootstrap (it reinstalls deps, removes the duplicate hook entries after backing up settings.json as settings.json.agenthub-bak, rewrites the CLI launcher and the unit, and restarts the server).
WARN agenthub CLI "not on PATH"	Append the exact export PATH=... line from the row to the shell rc file — only if that file does not already contain it.
WARN systemd "not running"	systemctl --user start agenthub (Linux) / agenthub service install (macOS LaunchAgent).
WARN systemd "not written by AgentHub"	Report only — it is the user's unit.
WARN tmux "not found"	sudo apt-get install -y tmux / sudo dnf install -y tmux / sudo pacman -S --noconfirm tmux / brew install tmux.
WARN tmux older than 3.7	macOS: brew upgrade tmux. Linux: report only — building tmux from source is the user's call; quote the row's instructions.
WARN tmux "running tmux server is"	Report only — it clears once every tmux session has closed. Never run tmux kill-server.
WARN Dashboard UI	the bootstrap step's ROOT lines, then node "$ROOT/scripts/plugin-open.js" --force, as ONE command — skip it when this doctor run was started by /agenthub-open (it re-runs the build itself).

The bootstrap step, run as ONE command so ROOT survives (it runs from the plugin build that is installed now — an older build's bootstrap refuses):

ROOT=$(node -e 'console.log(require(process.argv[1]).supersededBy() || "")' \
  "${CLAUDE_PLUGIN_ROOT}/scripts/plugin-bootstrap.js")
ROOT="${ROOT:-${CLAUDE_PLUGIN_ROOT}}"
node "$ROOT/scripts/plugin-bootstrap.js" --force

4. Fix, then verify

Run the approved steps in order, one at a time, and stop at the first one that fails: quote its decisive error line (for the bootstrap, from <Data dir>/runtime/bootstrap.log) and ask how to continue.

• Run nothing that is not in the approved plan. If a step turns out to need something else, ask again first.
• A sudo command when sudo -n true failed cannot be typed from here: ask the user to run it themselves as ! <command>, wait, then continue.
• A shell rc change only reaches new terminals — say so.

Finish by running the diagnosis again (step 1's command, ROOT lines included) and printing it verbatim, then at most three lines on what is still not OK and why.