---
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:

```bash
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):

```bash
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.