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

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

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:

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:

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.

Start the Development Server

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

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, 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 and /file-content.json, enforced by the custom Vite plugin in 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:

• 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 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 for path resolution logic, and 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 file. As implemented in 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. Because the dashboard exposes endpoints that can read arbitrary files from your project (/knowledge-graph.json, /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. 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 file in understand-anything-plugin/skills/understand-dashboard/ contains the high-level orchestration logic for launching the dashboard across different AI coding platforms.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}