understand-dashboard

---
name: understand-dashboard
description: >-
  Launch an interactive web dashboard to visualize a codebase as a knowledge graph. Use when:
  exploring project architecture visually, seeing file/function dependencies, understanding
  code structure at a glance.
license: MIT
compatibility: "Claude Code, Cursor, any AI coding agent"
metadata:
  author: terminal-skills
  version: "1.0.0"
  category: development
  tags: [codebase, knowledge-graph, visualization, dashboard, architecture]
---

# /understand-dashboard

## Overview

Launch an interactive web dashboard that visualizes a codebase's knowledge graph as a force-directed node graph. The dashboard provides layer views, dependency exploration, complexity heatmaps, and search filtering, all served locally via Vite.

## Instructions

1. Determine the project directory:
   - If `$ARGUMENTS` contains a path, use that as the project directory
   - Otherwise, use the current working directory

2. Check that `.understand-anything/knowledge-graph.json` exists in the project directory. If not, tell the user:
   ```
   No knowledge graph found. Run /understand first to analyze this project.
   ```

3. Find the dashboard code. The dashboard is at `packages/dashboard/` relative to this plugin's root directory. Use the Bash tool to resolve the path:
   ```bash
   PLUGIN_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
   ```
   Or locate it by checking these paths in order:
   - `${CLAUDE_PLUGIN_ROOT}/packages/dashboard/`
   - The parent directory of this skill file, then `../../packages/dashboard/`

4. Install dependencies and build if needed:
   ```bash
   cd <dashboard-dir> && pnpm install --frozen-lockfile 2>/dev/null || pnpm install
   ```
   Then ensure the core package is built (the dashboard depends on it):
   ```bash
   cd <plugin-root> && pnpm --filter @understand-anything/core build
   ```

5. Start the Vite dev server pointing at the project's knowledge graph:
   ```bash
   cd <dashboard-dir> && GRAPH_DIR=<project-dir> npx vite --open
   ```
   Run this in the background so the user can continue working.

6. Report to the user:
   ```
   Dashboard started at http://localhost:5173
   Viewing: <project-dir>/.understand-anything/knowledge-graph.json

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

## Examples

**Example 1: Launching the dashboard for the current project**

User: `/understand-dashboard`

The agent verifies `.understand-anything/knowledge-graph.json` exists in the current directory, resolves the dashboard package path at `packages/dashboard/`, installs dependencies with `pnpm install`, builds the core package, and starts the Vite dev server with `GRAPH_DIR=$(pwd) npx vite --open`. The browser opens to `http://localhost:5173` showing the interactive graph with 47 nodes across 5 architectural layers.

**Example 2: Launching the dashboard for a specific project path**

User: `/understand-dashboard ~/projects/my-api`

The agent checks that `~/projects/my-api/.understand-anything/knowledge-graph.json` exists, then starts the dashboard with `GRAPH_DIR=~/projects/my-api`. The user sees the knowledge graph for their API project rendered in the browser, with nodes color-coded by layer and sized by complexity score.

## Guidelines

- Always verify the knowledge graph file exists before attempting to start the dashboard
- Run the Vite server in the background so the user can continue working in the terminal
- If port 5173 is occupied, Vite automatically picks the next available port; report the actual URL
- Ensure the core package is built before starting the dashboard since it depends on `@understand-anything/core`
- The `GRAPH_DIR` environment variable tells the dashboard where to find the knowledge graph file