understand-dashboard

PLUGIN_ROOT=""

for candidate in \

"${CLAUDE_PLUGIN_ROOT}" \

"$HOME/.understand-anything-plugin" \

"$SELF_RELATIVE" \

"$COPILOT_SELF_RELATIVE" \

"$HOME/.codex/understand-anything/understand-anything-plugin" \

"$HOME/.opencode/understand-anything/understand-anything-plugin" \

"$HOME/.pi/understand-anything/understand-anything-plugin" \

"$HOME/understand-anything/understand-anything-plugin"; do

if [ -n "$candidate" ] && [ -d "$candidate/packages/dashboard" ]; then

PLUGIN_ROOT="$candidate"; break

fi

done

if [ -z "$PLUGIN_ROOT" ]; then

echo "Error: Cannot find the understand-anything plugin root."

echo "Checked:"

echo " - ${CLAUDE_PLUGIN_ROOT:-<unset CLAUDE_PLUGIN_ROOT>}"

echo " - $HOME/.understand-anything-plugin"

echo " - ${SELF_RELATIVE:-<unresolved path derived from ~/.agents/skills/understand-dashboard>}"

echo " - ${COPILOT_SELF_RELATIVE:-<unresolved path derived from ~/.copilot/skills/understand-dashboard>}"

echo " - $HOME/.codex/understand-anything/understand-anything-plugin"

echo " - $HOME/.opencode/understand-anything/understand-anything-plugin"

echo " - $HOME/.pi/understand-anything/understand-anything-plugin"

echo " - $HOME/understand-anything/understand-anything-plugin"

echo "Make sure you followed the installation instructions for your platform."

exit 1

fi

DASHBOARD_DIR="$PLUGIN_ROOT/packages/dashboard"

4. **Fast path — try the prebuilt viewer first (no install, no build).** Each release ships a self-contained viewer tarball; run it pinned to the installed plugin version:

: "${PLUGIN_ROOT:?Run step 3 first so PLUGIN_ROOT is set}"

: "${PROJECT_DIR:?Run step 1 first so PROJECT_DIR is set}"

PLUGIN_VERSION=$(node -p "require('$PLUGIN_ROOT/package.json').version")

VIEWER_URL="https://github.com/Egonex-AI/Understand-Anything/releases/download/v${PLUGIN_VERSION}/understand-anything-viewer.tgz"

npx --yes "$VIEWER_URL" "$PROJECT_DIR"

   Run this in the background. It prints the same `🔑  Dashboard URL` line as the dev server:
   - If the line appears, **skip steps 5-6** and continue at step 7.
   - If the process exits without printing it (no release asset for this version, or no network), fall back to steps 5-6.

5. Fallback: install dependencies and build if needed:

: "${PLUGIN_ROOT:?Run step 3 first so PLUGIN_ROOT is set}"

DASHBOARD_DIR="${DASHBOARD_DIR:-$PLUGIN_ROOT/packages/dashboard}"

cd "$DASHBOARD_DIR" && (pnpm install --frozen-lockfile 2>/dev/null || pnpm install)

   Then ensure the core package is built (the dashboard depends on it):

: "${PLUGIN_ROOT:?Run step 3 first so PLUGIN_ROOT is set}"

cd "$PLUGIN_ROOT" && pnpm --filter @understand-anything/core build

6. Fallback: start the Vite dev server pointing at the project's knowledge graph:

: "${PROJECT_DIR:?Run step 1 first so PROJECT_DIR is set}"

: "${DASHBOARD_DIR:?Run step 5 first so DASHBOARD_DIR is set}"

cd "$DASHBOARD_DIR" && GRAPH_DIR="$PROJECT_DIR" npx vite --host 127.0.0.1

   Run this in the background so the user can continue working.

7. **Capture the access token URL from the server output.** The server (viewer or Vite) prints a line like:

🔑 Dashboard URL: http://127.0.0.1:<PORT>?token=<TOKEN>

   Extract the full URL including the `?token=` parameter. The token is required to access the knowledge graph data — without it the dashboard will show an "Access Token Required" gate.

8. Report to the user, including the full tokenized URL:

Dashboard started at http://127.0.0.1:<PORT>?token=<TOKEN>

Viewing: $UA_DIR/knowledge-graph.json

The dashboard is running in the background. Press Ctrl+C in the terminal to stop it.

   **Important:** Always include the `?token=` parameter in the URL you share. If you omit it, the user will be blocked by the token gate and have to manually find the token in the terminal output.

## Notes

- The fast path (step 4) downloads a version-pinned, self-contained viewer from the GitHub release — nothing is installed into the plugin directory and no build runs
- The dashboard auto-opens in the default browser (both the viewer and Vite's `--open`)
- If port 5173 is already in use, the next available port is picked (both paths)
- In the fallback, the `GRAPH_DIR` environment variable tells the dev server where to find the knowledge graph