Start the Understand Anything dashboard to visualize the knowledge graph for the current project.
-
Determine the project directory and data directory:
- If
$ARGUMENTS contains a path, use that as the project directory
- Otherwise, use the current working directory
- Prefer the legacy
.understand-anything/ data directory when it exists, otherwise use .ua/
Use the Bash tool to resolve:
PROJECT_ARG="$ARGUMENTS"
if [ -n "$PROJECT_ARG" ]; then
PROJECT_DIR=$(cd "$PROJECT_ARG" 2>/dev/null && pwd -P)
else
PROJECT_DIR=$(pwd -P)
fi
if [ -z "$PROJECT_DIR" ] || [ ! -d "$PROJECT_DIR" ]; then
echo "Error: Project directory not found: ${PROJECT_ARG:-$PWD}"
exit 1
fi
if [ -d "$PROJECT_DIR/.understand-anything" ]; then
UA_DIR="$PROJECT_DIR/.understand-anything"
else
UA_DIR="$PROJECT_DIR/.ua"
fi
-
Check that $UA_DIR/knowledge-graph.json exists in the project directory. If not, tell the user:
No knowledge graph found. Run /understand first to analyze this project.
Use the Bash tool to check:
if [ ! -f "$UA_DIR/knowledge-graph.json" ]; then
echo "No knowledge graph found. Run /understand first to analyze this project."
exit 1
fi
-
Find the dashboard code. The dashboard is at packages/dashboard/ relative to this plugin's root directory. Check these paths in order and use the first that exists:
${CLAUDE_PLUGIN_ROOT}/packages/dashboard/ (Claude Code runtime root, highest priority)~/.understand-anything-plugin/packages/dashboard/ (universal symlink, all installs)- Two levels up from
~/.agents/skills/understand-dashboard real path (self-relative fallback)
- Two levels up from
~/.copilot/skills/understand-dashboard real path (Copilot personal skills fallback)
- Common clone-based install roots:
~/.codex/understand-anything/understand-anything-plugin/packages/dashboard/~/.opencode/understand-anything/understand-anything-plugin/packages/dashboard/~/.pi/understand-anything/understand-anything-plugin/packages/dashboard/~/understand-anything/understand-anything-plugin/packages/dashboard/
Use the Bash tool to resolve:
SKILL_REAL=$(realpath ~/.agents/skills/understand-dashboard 2>/dev/null || readlink -f ~/.agents/skills/understand-dashboard 2>/dev/null || echo "")
SELF_RELATIVE=$([ -n "$SKILL_REAL" ] && cd "$SKILL_REAL/../.." 2>/dev/null && pwd || echo "")
COPILOT_SKILL_REAL=$(realpath ~/.copilot/skills/understand-dashboard 2>/dev/null || readlink -f ~/.copilot/skills/understand-dashboard 2>/dev/null || echo "")
COPILOT_SELF_RELATIVE=$([ -n "$COPILOT_SKILL_REAL" ] && cd "$COPILOT_SKILL_REAL/../.." 2>/dev/null && pwd || echo "")
PLUGIN_ROOT=
candidate \
\
\
\
\
\
\
\
;
[ -n ] && [ -d ];
PLUGIN_ROOT=;
[ -z ];
1
DASHBOARD_DIR=
-
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.
-
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
-
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.
-
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.
-
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.
