How to Run the Egonex-AI Dashboard Locally: Complete Development Setup

Clone the Egonex-AI/Understand-Anything repository, install dependencies with pnpm ≥ 10, build the core package with pnpm --filter @understand-anything/core build, then launch the dashboard using GRAPH_DIR=../.. npx vite --host 127.0.0.1 --open to serve the UI on http://127.0.0.1:5173.

The Egonex-AI Understand-Anything dashboard is a React-based visualization tool that displays knowledge graphs generated by the core analysis engine. To run the Egonex-AI dashboard locally for development purposes, you must build the core package first to generate required TypeScript types, then serve the UI using Vite with the GRAPH_DIR environment variable pointing to a project containing a .understand-anything graph folder. This setup enables hot-reload development while the dashboard proxies graph data requests to your local filesystem.

Prerequisites and System Requirements

Before starting, ensure your environment meets the requirements specified in the monorepo configuration. You need Node.js ≥ 22 and pnpm ≥ 10 installed globally to handle the workspace dependencies and lock-file format. Additionally, you must have a project directory containing a .understand-anything/knowledge-graph.json file, which the dashboard will visualize.

Step-by-Step Local Development Setup

Follow these steps to build and run the dashboard from the source code.

Clone the Repository and Install Workspace Dependencies

First, clone the monorepo and install the shared dependencies at the root level. According to the README quick-start section (lines 48-55), this establishes the workspace foundation.

git clone https://github.com/Egonex-AI/Understand-Anything.git
cd Understand-Anything
pnpm install

This creates the necessary lock-file and installs shared tooling across the monorepo.

Build the Core Package

The dashboard depends on compiled types and schemas from the core package. As documented in the understand-dashboard skill file (lines 22-33), you must build the core before running the UI.

pnpm --filter @understand-anything/core build

This command generates the TypeScript output required by the dashboard's import statements.

Install Dashboard-Specific Dependencies

Navigate to the dashboard package directory and install its local dependencies using the frozen lock-file to ensure exact versions of React, Vite, Tailwind CSS v4, and Zustand.

cd understand-anything-plugin/packages/dashboard
pnpm install --frozen-lockfile

The dependencies are declared in understand-anything-plugin/packages/dashboard/package.json, which includes scripts for dev and build operations.

Launch the Vite Development Server

Set the GRAPH_DIR environment variable to point to the folder containing your .understand-anything graph data, then start the Vite dev server. As specified in the skill documentation (lines 73-82), use the following command:

GRAPH_DIR=../../.. npx vite --host 127.0.0.1 --open

By default, this serves the dashboard on http://127.0.0.1:5173 and opens your browser automatically. The GRAPH_DIR path is relative to the dashboard directory and should target the root of the project you want to visualize.

Key Configuration and Environment Variables

The dashboard relies on specific environment variables to locate graph data and configure the development server.

• GRAPH_DIR: Required. Points to the directory containing the .understand-anything/knowledge-graph.json file. The server proxies /file-content.json requests to this location.
• VITE_PORT: Optional. Changes the default development server port from 5173.
• VITE_OPEN: Optional. Set to false to prevent the browser from opening automatically on server start.

When running, the dashboard injects an access token automatically to validate requests between the UI and the local graph data, handled by the TokenGate component.

Core Architecture and Source Files

Understanding the key source files helps navigate the codebase for custom development.

• understand-anything-plugin/packages/dashboard/src/App.tsx: The entry component that wires the layout, graph view, and side panels.
• understand-anything-plugin/packages/dashboard/src/store.ts: Implements the Zustand store holding graph state, search queries, selected nodes, and tour data.
• understand-anything-plugin/packages/dashboard/src/components/TokenGate.tsx: Validates the access token before rendering the graph view, ensuring secure access to the local data.
• understand-anything-plugin/packages/dashboard/src/components/GraphView.tsx: Renders the ELK-based force-directed graph, handling node interactions and hover tooltips.
• understand-anything-plugin/skills/understand-dashboard/SKILL.md: Contains the canonical commands used to launch the dashboard, serving as the source of truth for the development workflow.

Development Workflow Tips

For efficient local development, run the core /understand command after code changes to regenerate the knowledge-graph.json file; the Vite dev server automatically picks up these updates without requiring a restart. If the graph layout appears broken, check the browser console for ELK errors, which are surfaced through the src/components/WarningBanner.tsx component. To create a production build, run pnpm --filter @understand-anything/dashboard build, which outputs an optimized static bundle to the dist/ directory.

Summary

• Install Node.js ≥ 22 and pnpm ≥ 10, then clone the Egonex-AI/Understand-Anything repository.
• Build the core package using pnpm --filter @understand-anything/core build before running the dashboard.
• Configure the GRAPH_DIR environment variable to point to your project folder containing .understand-anything/knowledge-graph.json.
• Launch the development server with GRAPH_DIR=../.. npx vite --host 127.0.0.1 --open to serve the UI on http://127.0.0.1:5173.
• Reference the key source files in understand-anything-plugin/packages/dashboard/src/ for UI customization and state management using Zustand.

Frequently Asked Questions

What are the minimum version requirements for running the dashboard locally?

You need Node.js version 22 or higher and pnpm version 10 or higher to install dependencies and run the build commands successfully. These versions ensure compatibility with the monorepo workspace configuration and the Vite build tooling.

Why must I build the core package before starting the dashboard?

The dashboard imports TypeScript types and schema definitions from the core package. Running pnpm --filter @understand-anything/core build generates these compiled outputs in the core package's dist directory, which the dashboard's module resolution depends on. Without this step, the dashboard will fail to start due to missing type definitions.

How do I connect the dashboard to a different project folder?

Set the GRAPH_DIR environment variable to the absolute or relative path of the target directory containing the .understand-anything folder. For example, if your project is at /home/user/projects/my-app, launch the server with GRAPH_DIR=/home/user/projects/my-app npx vite --host 127.0.0.1, ensuring the path includes the knowledge-graph.json file.

What port does the development server use by default?

The Vite development server defaults to port 5173 on 127.0.0.1 as specified by the --host 127.0.0.1 flag. You can override this by setting the VITE_PORT environment variable to your desired port number before running the launch command.

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