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

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 and 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:

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 uses the following conditional check:

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:

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:

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

Output:

[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:

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

Output:

[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:

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 and 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.

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