# How to Run the Lum1104/Understand-Anything Dashboard Locally for Development and Testing

> Learn to run the Lum1104/Understand-Anything dashboard locally. Follow simple steps to install dependencies, build the core package, and start the Vite dev server for efficient development and testing.

- Repository: [Yuxiang Lin/Understand-Anything](https://github.com/Lum1104/Understand-Anything)
- Tags: how-to-guide
- Published: 2026-05-31

---

**To run the Understand-Anything dashboard locally, install dependencies in `packages/dashboard/`, build the core package with `pnpm --filter @understand-anything/core build`, then start the Vite dev server with `GRAPH_DIR=<project-path> npx vite --host 127.0.0.1` and open the generated token-protected URL.**

The **Lum1104/Understand-Anything** repository provides an interactive knowledge-graph visualization tool for codebases. Running the dashboard locally enables developers to iterate on plugin changes, test new skills, and visualize analysis results in real-time without deploying to production.

## Prerequisites: Generate the Knowledge Graph

Before starting the dashboard, ensure your target project contains a valid knowledge graph file at [`.understand-anything/knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json). If this file is missing, run the analysis command (`/understand` in Claude Code or the CLI equivalent) to generate it. The dashboard reads this JSON file to render the interactive graph, file contents, and guided tours.

## Step-by-Step Local Setup

### Locate the Dashboard Directory

The dashboard resides in `packages/dashboard/` within the plugin structure. According to the skill definition in [`understand-anything-plugin/skills/understand-dashboard/SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/skills/understand-dashboard/SKILL.md), the system searches common installation paths (Claude Code runtime, user-level symlinks, and platform-specific directories) to resolve the plugin root. For manual development, navigate directly to:

```bash
cd understand-anything-plugin/packages/dashboard

```

### Install Dependencies

Use **pnpm** to install the dashboard dependencies. The `--frozen-lockfile` flag prevents accidental lock-file modifications during development:

```bash
cd understand-anything-plugin/packages/dashboard
pnpm install --frozen-lockfile 2>/dev/null || pnpm install

```

### Build the Core Analysis Engine

The dashboard imports browser-safe sub-path exports from `@understand-anything/core` (`./search`, `./types`, `./schema`). Because these are compiled exports, you must build the core package before starting the dev server:

```bash
cd understand-anything-plugin
pnpm --filter @understand-anything/core build

```

Rebuild this package whenever you modify the core analysis logic, as the dashboard consumes the compiled output defined in [`packages/core/package.json`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/core/package.json).

### Start the Development Server

Launch the Vite dev server with the `GRAPH_DIR` environment variable pointing to your target project:

```bash
cd understand-anything-plugin/packages/dashboard
GRAPH_DIR=/path/to/your/project npx vite --host 127.0.0.1

```

As configured in [`vite.config.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/vite.config.ts), the server binds strictly to `127.0.0.1` for security. The console outputs a one-time access token:

```

🔑  Dashboard URL: http://127.0.0.1:5173/?token=4c9f2e1a7b...

```

Copy the complete URL (including the `?token=` query parameter) into your browser. The token is mandatory for accessing protected endpoints such as [`/knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main//knowledge-graph.json) and [`/file-content.json`](https://github.com/Lum1104/Understand-Anything/blob/main//file-content.json), enforced by the custom Vite plugin in [`vite.config.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/vite.config.ts).

## Development Workflow for Plugin Changes

Once the server is running, you can iterate on plugin code efficiently:

- **Keep the Vite server running** while editing agent logic or skill definitions in the plugin directory. The dashboard will maintain its connection to the graph data.
- **Rebuild the core package** when modifying analysis algorithms in `@understand-anything/core`, then refresh the browser to see changes.
- **Leverage hot-module replacement (HMR)** for UI modifications in the dashboard itself; Vite automatically updates the React components without full page reloads.
- **Test against multiple projects** by stopping the server with **Ctrl+C**, changing the `GRAPH_DIR` value, and restarting.

Press **Ctrl+C** in the terminal to stop the development server when finished.

## Understanding the Security Model

The dashboard implements two critical security mechanisms defined in [`packages/dashboard/vite.config.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/dashboard/vite.config.ts):

- **One-time access tokens** prevent unauthorized access to sensitive file content. Because the dashboard can serve any file within the project directory, the token ensures that only the developer who started the server can access the endpoints.
- **Host binding restriction** (`server.host: '127.0.0.1'`) ensures the dev server only accepts local connections, mitigating risks if the server is accidentally exposed on a network.

The `GRAPH_DIR` environment variable provides flexibility by decoupling the dashboard code location from the project data location, allowing you to test multiple repositories without moving the dashboard installation.

## Summary

- **Generate the graph** first: Ensure [`.understand-anything/knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json) exists in your target project.
- **Install dependencies** in `packages/dashboard/` using `pnpm install`.
- **Build the core** package with `pnpm --filter @understand-anything/core build` before starting the server.
- **Start the server** with `GRAPH_DIR=<project-path> npx vite --host 127.0.0.1` and copy the token-protected URL.
- **Develop iteratively**: Keep the server running for plugin changes, rebuild core for engine updates, and use HMR for UI changes.
- **Reference key files**: [`understand-anything-plugin/skills/understand-dashboard/SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/skills/understand-dashboard/SKILL.md) for path resolution logic, and [`packages/dashboard/vite.config.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/dashboard/vite.config.ts) for server configuration and token generation.

## Frequently Asked Questions

### What is the GRAPH_DIR environment variable used for?

`GRAPH_DIR` specifies the absolute path to the project directory containing the [`.understand-anything/knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json) file. As implemented in [`packages/dashboard/vite.config.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/dashboard/vite.config.ts), this variable allows the dashboard to locate and serve the knowledge graph and associated source files. It decouples the dashboard installation from the data source, enabling you to analyze multiple repositories without reinstalling the dashboard or moving your plugin code.

### Why does the dashboard require a one-time access token?

The token is a security measure enforced by the Vite configuration in [`packages/dashboard/vite.config.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/dashboard/vite.config.ts). Because the dashboard exposes endpoints that can read arbitrary files from your project ([`/knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main//knowledge-graph.json), [`/file-content.json`](https://github.com/Lum1104/Understand-Anything/blob/main//file-content.json)), the token prevents unauthorized access if the dev server is accidentally exposed. The token is generated at startup and must be included in the URL query parameter to access protected resources.

### Can I run the dashboard without building the core package first?

No. The dashboard imports specific sub-path exports from `@understand-anything/core` (such as `./search`, `./types`, and `./schema`) defined in [`packages/core/package.json`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/core/package.json). These are compiled exports pointing to the `dist/` directory. Attempting to run the dashboard without building the core package first will result in module resolution errors. Always run `pnpm --filter @understand-anything/core build` before starting the dev server.

### Which files should I edit to test plugin changes?

For **skill logic** and **agent behavior**, edit files within `understand-anything-plugin/skills/` and the associated agent definitions. For **core analysis engine** changes (parsing, search algorithms), modify `packages/core/` and rebuild with the filter command. For **UI changes** to the dashboard itself, edit files in `packages/dashboard/src/`; Vite's HMR will update the browser automatically without restarting the server. The [`SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/SKILL.md) file in `understand-anything-plugin/skills/understand-dashboard/` contains the high-level orchestration logic for launching the dashboard across different AI coding platforms.