# How to Run Egonex AI Analysis on a Specific Subdirectory in Monorepos

> Efficiently run Egonex AI analysis on specific monorepo subdirectories. Discover how to target your analysis and manage output with simple commands.

- Repository: [Egonex/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything)
- Tags: how-to-guide
- Published: 2026-06-20

---

**Change into the target subdirectory and execute the `understand` command; the skill automatically discovers the repository root via Git and writes the knowledge graph to [`.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json) in the root, or set `UNDERSTAND_ROOT` to keep output local to the subdirectory.**

The `understand-anything` tool from the Egonex-AI/Understand-Anything repository analyzes codebases by inspecting the **project root** (`PROJECT_ROOT`) from the directory where it is launched. In monorepo architectures containing multiple packages or services, you can scope analysis to individual subdirectories by leveraging the tool's Git-based root detection and environment variable overrides.

## How Project Root Detection Works

According to the implementation in [`understand-anything-plugin/src/index.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/src/index.ts), the entry point resolves `PROJECT_ROOT` by invoking `git rev-parse --show-toplevel`. This Git command identifies the top-level directory of the current repository, ensuring the tool maintains full monorepo context for dependency resolution while allowing execution from nested subdirectories.

The scanner pipeline, documented in [`understand-anything-plugin/agents/project-scanner.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/agents/project-scanner.md), uses this root detection to index files relative to the repository base. When you run the skill from a subdirectory, it discovers the repository root automatically but limits the analysis scope to the current working directory's contents.

## Running Analysis on a Subdirectory

### Basic Workflow

To analyze a single package within a monorepo, navigate to the subdirectory and invoke the skill:

```bash
cd packages/api
understand

```

The command generates the knowledge graph for `packages/api` while storing the output in `<repo-root>/.understand-anything/knowledge-graph.json`.

### Local Output Configuration

To write the knowledge graph alongside the subdirectory rather than the repository root, export `UNDERSTAND_ROOT` before execution:

```bash
cd packages/web
UNDERSTAND_ROOT=$(pwd) understand

```

This overrides the default output location defined in [`understand-anything-plugin/skills/understand/SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/skills/understand/SKILL.md).

## Command Examples for Monorepo Workflows

1. **Analyze a single package**  
   Change to the package directory and run the skill. The tool detects the repository root via Git but scopes analysis to the current directory:
   ```bash
   cd packages/api
   understand
   ```

2. **Keep output local to the subdirectory**  
   Set the `UNDERSTAND_ROOT` environment variable to the current working directory:
   ```bash
   cd packages/web
   UNDERSTAND_ROOT=$(pwd) understand
   ```

3. **CI pipeline targeting with disabled auto-update**  
   Run analysis in continuous integration environments without auto-updating the graph on commit:
   ```bash
   PROJECT_ROOT=packages/lib pnpm exec understand -- --no-auto-update
   ```

## Key Implementation Details

### Entry Point and Root Resolution

The file [`understand-anything-plugin/src/index.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/src/index.ts) contains the main entry point that resolves `PROJECT_ROOT` and launches the scanner pipeline. It handles the Git-based root detection and initializes the environment variables that control output behavior.

### Skill Configuration

[`understand-anything-plugin/skills/understand/SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/skills/understand/SKILL.md) documents the CLI flags and environment variables, including `UNDERSTAND_ROOT` and the `--no-auto-update` flag for CI environments.

### Scanner Logic

[`understand-anything-plugin/agents/project-scanner.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/agents/project-scanner.md) explains how the scanner discovers the repository root and selects files for analysis based on the current working directory relative to the Git top-level.

### Output Schema

[`understand-anything-plugin/packages/core/src/schema.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/core/src/schema.ts) defines the JSON structure of the generated knowledge graph, which is consumed by the dashboard at `/understand-dashboard`. The dashboard reads the graph from the repository-wide `.understand-anything` folder regardless of where you launch it.

## Summary

- The `understand` command analyzes code from the current working directory while resolving the repository root via `git rev-parse --show-toplevel`
- Run `cd <subdirectory> && understand` to scope analysis to a specific monorepo package
- Set `UNDERSTAND_ROOT=$(pwd)` to store the knowledge graph locally instead of the repository root
- The tool requires Node.js version 22 or higher and pnpm version 10 or higher according to the repository README
- Generated graphs follow the schema defined in [`schema.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/schema.ts) and can be visualized with the dashboard

## Frequently Asked Questions

### How does Egonex AI detect the repository root?

The tool executes `git rev-parse --show-toplevel` via the entry point in [`understand-anything-plugin/src/index.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/src/index.ts) to identify the repository root, allowing it to maintain monorepo context regardless of which subdirectory you run the command from.

### Can I run analysis on multiple subdirectories separately?

Yes. Run the `understand` command from each subdirectory independently. Each execution generates a knowledge graph; use `UNDERSTAND_ROOT` to organize outputs in separate locations if you want to avoid overwriting the default file in the repository root.

### Where is the knowledge graph stored by default?

By default, the graph writes to `<repo-root>/.understand-anything/knowledge-graph.json`. This location is determined by the Git root detection and is documented in [`understand-anything-plugin/skills/understand/SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/skills/understand/SKILL.md).

### What are the prerequisites for running the analysis?

According to the repository README, you need Node.js version 22 or higher and pnpm version 10 or higher. Install dependencies with `pnpm install` and build the core engine with `pnpm --filter @understand-anything/core build` before running the skill.