# How the Worktree Redirect Feature Works in Egonex-AI Understand-Anything

> Discover how the Egonex-AI worktree redirect feature safeguards your knowledge graph by linking PROJECT_ROOT to the main repository. Learn about automatic detection and opt-out options.

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

---

**The worktree redirect feature automatically detects Git worktrees and redirects the `PROJECT_ROOT` to the main repository directory to prevent loss of the `.understand-anything/` knowledge graph, unless the user opts out via `UNDERSTAND_NO_WORKTREE_REDIRECT`.**

The **worktree redirect feature** in the Egonex-AI/Understand-Anything repository ensures that knowledge graphs persist across ephemeral Git worktree sessions. When you run the `understand` or `understand-domain` commands from within a worktree, the CLI entry-point scripts detect the worktree structure and redirect output to the main repository root. This mechanism safeguards the `.understand-anything/` folder from deletion when temporary worktree sessions end.

## How Worktree Detection Works

The detection logic is embedded in the skill entry-point scripts located in [`understand-anything-plugin/skills/understand/SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/skills/understand/SKILL.md) and [`understand-anything-plugin/skills/understand-domain/SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/skills/understand-domain/SKILL.md). When the tool launches, it executes two Git commands to determine the repository context:

- `git rev-parse --git-dir` – Returns the path to the `.git` directory for the current checkout.
- `git rev-parse --git-common-dir` – Returns the shared Git directory for the entire worktree.

In a standard repository checkout, these commands return identical paths. In a Git **worktree**, they return different paths because the worktree maintains a separate `.git` file pointing to the main repository's object database.

### Identifying the Main Repository Root

When the paths differ, the script extracts the main repository directory by taking the parent directory of the common Git directory:

```bash
MAIN_ROOT=$(dirname "$COMMON_ABS")

```

This `MAIN_ROOT` represents the canonical repository location where the `.understand-anything/` folder should persist.

## Redirect Logic and Environment Controls

The redirect activates only when the script confirms the current directory resides within a worktree **and** the user has not explicitly disabled the feature. The implementation in [`understand-anything-plugin/skills/understand/SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/skills/understand/SKILL.md) uses the following conditional check:

```bash
if [ -d "$MAIN_ROOT" ] && [ "${UNDERSTAND_NO_WORKTREE_REDIRECT:-0}" != "1" ]; then
    echo "[understand] Redirecting output to main repo root: $MAIN_ROOT"
    PROJECT_ROOT="$MAIN_ROOT"
fi

```

This snippet reassigns `PROJECT_ROOT` from the ephemeral worktree path to the stable main repository root.

### The UNDERSTAND_NO_WORKTREE_REDIRECT Opt-Out

Users can force the tool to maintain the worktree as `PROJECT_ROOT` by setting the environment variable:

```bash
export UNDERSTAND_NO_WORKTREE_REDIRECT=1

```

When this variable equals `1`, the redirect is bypassed, and the knowledge graph is stored inside the temporary worktree directory. This is useful for testing or when intentionally isolating analysis data.

## Why the Redirect Prevents Data Loss

Worktrees created by Claude Code are **ephemeral** by design. The `.understand-anything/` directory, which contains the knowledge graph and analysis artifacts, would normally be created inside the worktree's file system. When the worktree session terminates, this entire directory is deleted, resulting in complete data loss.

By redirecting `PROJECT_ROOT` to the main repository checkout, the tool ensures the `.understand-anything/` folder is created in a persistent location. This allows the knowledge graph to survive across multiple temporary worktree sessions, maintaining continuity in your analysis.

## When Is the Worktree Redirect Applied?

The worktree redirect feature is evaluated **on every execution** of the `understand` or `understand-domain` commands. However, the actual redirection occurs only when two specific conditions are met:

1. The current working directory (or any parent directory) is inside a Git worktree, confirmed by the differing Git directory paths.
2. The environment variable `UNDERSTAND_NO_WORKTREE_REDIRECT` is **not** set to `1`.

If either condition fails, `PROJECT_ROOT` remains set to the current directory, and no redirect message is displayed.

## Practical Code Examples

### Example 1: Automatic Redirect in a Worktree

When running from within a worktree with the default settings:

```bash
cd /tmp/wt/src/deep
understand --full

```

Output:

```text
[understand] Detected git worktree at /tmp/wt
[understand] Redirecting output to main repo root: /repo/main

# The .understand-anything/ folder is created under /repo/main

```

### Example 2: Disabling the Redirect

To keep the knowledge graph inside the worktree:

```bash
export UNDERSTAND_NO_WORKTREE_REDIRECT=1
cd /tmp/wt/src/deep
understand --full

```

Output:

```text
[understand] Detected git worktree at /tmp/wt

# No redirect message; graph is stored in /tmp/wt/.understand-anything/

```

### Example 3: Standard Repository Checkout

When running from the main repository outside a worktree:

```bash
cd /repo/main
understand --full

```

No worktree detection occurs, and `PROJECT_ROOT` remains `/repo/main`.

## Summary

- The **worktree redirect feature** detects Git worktrees by comparing `git rev-parse --git-dir` and `git rev-parse --git-common-dir`.
- When detected, it rewrites `PROJECT_ROOT` to the main repository root to prevent deletion of the `.understand-anything/` folder when ephemeral worktrees expire.
- The redirect is controlled by the `UNDERSTAND_NO_WORKTREE_REDIRECT` environment variable; set it to `1` to disable the behavior.
- This logic is implemented in [`understand-anything-plugin/skills/understand/SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/skills/understand/SKILL.md) and [`understand-anything-plugin/skills/understand-domain/SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/skills/understand-domain/SKILL.md).
- Automated tests in `understand-anything-plugin/src/__tests__/worktree-redirect.test.mjs` verify both the redirect and opt-out functionality.

## Frequently Asked Questions

### What triggers the worktree redirect feature?

The feature triggers when the CLI detects that the current directory resides within a Git worktree, specifically when `git rev-parse --git-dir` and `git rev-parse --git-common-dir` return different paths. This indicates the presence of a linked worktree rather than a standard repository checkout.

### How do I disable the worktree redirect?

Set the environment variable `UNDERSTAND_NO_WORKTREE_REDIRECT` to `1` before running the command. This forces the tool to use the worktree directory as `PROJECT_ROOT`, keeping the knowledge graph isolated within the temporary worktree.

### Where is the knowledge graph stored when using a worktree?

By default, the knowledge graph is stored in the `.understand-anything/` directory within the **main repository root**, not inside the ephemeral worktree. This ensures the data persists after the worktree session ends. If you opt out using the environment variable, the graph is stored inside the worktree itself.

### Is the worktree redirect feature tested?

Yes, the behavior is verified by the test suite located at `understand-anything-plugin/src/__tests__/worktree-redirect.test.mjs`. These tests confirm that the redirect correctly identifies worktrees, switches `PROJECT_ROOT` appropriately, and respects the `UNDERSTAND_NO_WORKTREE_REDIRECT` opt-out flag.