How Egonex AI Git Worktree Detection Redirects Output to the Main Repository

Egonex AI detects Git worktrees by comparing git rev-parse --git-common-dir and --git-dir paths, then redirects PROJECT_ROOT to the main repository root unless UNDERSTAND_NO_WORKTREE_REDIRECT is set.

The Egonex-AI/Understand-Anything repository implements a robust worktree-redirect helper that ensures plugins operate against the canonical repository location even when invoked from Git worktrees. This Bash-based detection lives in skill documentation files and is validated by the test suite to guarantee consistent path resolution across different checkout types.

How the Worktree Detection Algorithm Works

The detection logic relies on Git's internal directory structure to distinguish between a main repository checkout and a linked worktree. When running inside a worktree, the .git directory exists as a file pointing to the main repository's metadata, causing the common and git directories to reside at different absolute paths.

Detecting Git Repository Structure

The snippet first queries Git for two critical paths using rev-parse commands executed relative to the current PROJECT_ROOT:

COMMON_DIR=$(git -C "$PROJECT_ROOT" rev-parse --git-common-dir 2>/dev/null)
GIT_DIR=$(git -C "$PROJECT_ROOT" rev-parse --git-dir 2>/dev/null)

These commands return the path to the common Git directory (shared across all worktrees) and the specific git directory for the current checkout.

Comparing Common and Git Directories

The algorithm converts both paths to absolute form and compares them:

COMMON_ABS=$(cd "$PROJECT_ROOT" && cd "$COMMON_DIR" 2>/dev/null && pwd -P)
GIT_ABS=$(cd "$PROJECT_ROOT" && cd "$GIT_DIR"   2>/dev/null && pwd -P)

if [ -n "$COMMON_ABS" ] && [ "$COMMON_ABS" != "$GIT_ABS" ]; then
  # Worktree detected

fi

In a standard checkout, both paths resolve to the same location. Inside a worktree, they diverge because the git directory points to the main repository while the common directory remains under the worktree's .git folder.

Deriving the Main Repository Root

When the paths differ, the snippet calculates the main repository root by taking the parent directory of the common path:

MAIN_ROOT=$(dirname "$COMMON_ABS")

This yields the top-level directory of the original repository, regardless of where the worktree is mounted on the filesystem.

Implementation in the Understand-Anything Plugin

The complete redirect logic guards against accidental redirection and respects user opt-out preferences:

if [ -n "$COMMON_DIR" ] && [ -n "$GIT_DIR" ]; then
  COMMON_ABS=$(cd "$PROJECT_ROOT" && cd "$COMMON_DIR" 2>/dev/null && pwd -P)
  GIT_ABS=$(cd "$PROJECT_ROOT" && cd "$GIT_DIR"   2>/dev/null && pwd -P)

  if [ -n "$COMMON_ABS" ] && [ "$COMMON_ABS" != "$GIT_ABS" ]; then
    MAIN_ROOT=$(dirname "$COMMON_ABS")

    if [ -d "$MAIN_ROOT" ] && [ "${UNDERSTAND_NO_WORKTREE_REDIRECT:-0}" != "1" ]; then
      PROJECT_ROOT="$MAIN_ROOT"
    fi
  fi
fi

echo "$PROJECT_ROOT"

This ensures that knowledge-graph files and other repository-relative assets in .understand-anything/ are always accessed from the main repository location, preventing path resolution failures when skills are invoked from worktree checkouts.

Testing and Validation

The test suite in understand-anything-plugin/src/__tests__/worktree-redirect.test.mjs validates this behavior across multiple scenarios. The TypeScript harness executes the Bash snippet programmatically using Node.js child processes:

import { execFileSync } from "node:child_process";

const RESOLVE_SNIPPET = `...the Bash code above...`;

function runResolve(projectRoot: string, env = {}): string {
  const script = `PROJECT_ROOT=${JSON.stringify(projectRoot)}\n${RESOLVE_SNIPPET}`;
  return execFileSync("bash", ["-c", script], {
    env: { ...process.env, ...env },
    encoding: "utf8",
  }).trim();
}

The test suite verifies five distinct scenarios:

• Normal checkout: Returns the original mainRepo path unchanged
• Inside a worktree: Redirects to mainRepo (the common directory's parent)
• Sub-directory of a worktree: Correctly resolves to mainRepo
• Opt-out enabled: Returns worktree path when UNDERSTAND_NO_WORKTREE_REDIRECT=1
• Outside Git: Returns the input path unchanged for non-Git directories

Disabling the Redirection

Users can prevent the automatic redirection by setting the environment variable before invoking a skill:

UNDERSTAND_NO_WORKTREE_REDIRECT=1 ua-understand …

This override is checked in the final guard condition: [ "${UNDERSTAND_NO_WORKTREE_REDIRECT:-0}" != "1" ]. When set to 1, the snippet preserves the original PROJECT_ROOT even when running inside a worktree.

Summary

• Egonex AI uses a Bash snippet comparing git rev-parse --git-common-dir and --git-dir to detect worktree checkouts.
• When paths differ, the algorithm derives the main repository root via dirname "$COMMON_ABS" and reassigns PROJECT_ROOT.
• The logic resides in skill documentation (e.g., skills/understand/SKILL.md) and is validated by worktree-redirect.test.mjs.
• Set UNDERSTAND_NO_WORKTREE_REDIRECT=1 to disable redirection and operate against the worktree directory instead of the main repository.

Frequently Asked Questions

How does Egonex AI detect if it's running inside a Git worktree?

Egonex AI executes git rev-parse --git-common-dir and git rev-parse --git-dir relative to the current PROJECT_ROOT. It converts both outputs to absolute paths using pwd -P. If the common directory and git directory resolve to different locations, the code identifies the current checkout as a worktree requiring redirection to the main repository root.

What happens when UNDERSTAND_NO_WORKTREE_REDIRECT is set to 1?

When the environment variable UNDERSTAND_NO_WORKTREE_REDIRECT equals 1, the final conditional check [ "${UNDERSTAND_NO_WORKTREE_REDIRECT:-0}" != "1" ] evaluates to false, preventing the reassignment of PROJECT_ROOT. The snippet outputs the original directory path, allowing the skill to operate against the worktree checkout rather than the main repository.

Where is the worktree detection logic documented and tested?

The Bash detection snippet is embedded in skill documentation files such as skills/understand/SKILL.md and skills/understand-domain/SKILL.md. The test suite in understand-anything-plugin/src/__tests__/worktree-redirect.test.mjs exercises the logic across normal checkouts, worktrees, subdirectories, and opt-out scenarios to ensure reliable path resolution.

Why does the algorithm use dirname on the common directory path?

The git rev-parse --git-common-dir command returns the path to .git/common within the main repository. By applying dirname to this absolute path, the code strips the /common suffix and returns the .git directory's parent—the actual root of the main repository where knowledge-graph files and plugin assets are stored.

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