How Worktree Detection Redirects Output to the Main Repository Root in Egonex-AI

The Egonex-AI Understand-Anything skill detects Git worktrees by comparing git rev-parse --git-dir against git rev-parse --git-common-dir, and when these paths differ, it automatically rewrites PROJECT_ROOT to point to the main repository root instead of the ephemeral worktree directory.

When using Claude Code with Git worktrees, isolated checkouts are often deleted when sessions end, risking the loss of generated knowledge graphs. The Egonex-AI/Understand-Anything repository implements intelligent worktree detection that redirects output to the persistent main repository root. This ensures that critical files like .understand-anything/knowledge-graph.json survive even when temporary worktrees are destroyed (see issue #133).

Understanding Git Worktree Detection

A Git worktree is a secondary checkout of a repository that shares the same underlying Git metadata but exists in a separate directory. When the /understand skill initializes, it sets PROJECT_ROOT to the directory from which the command is invoked. If this directory resides inside a worktree, the skill must distinguish between the working directory (the worktree) and the main repository root (where the primary .git folder lives).

The detection logic relies on two distinct Git commands that expose the relationship between the current checkout and the shared repository metadata.

Comparing Git Directory Paths

The script captures and compares two specific paths to identify worktree status:

• git rev-parse --git-dir: Returns the absolute path to the working Git directory for the current checkout. In a worktree, this points to a location like .git/worktrees/<name> rather than the main .git folder.
• git rev-parse --git-common-dir: Returns the absolute path to the shared Git directory that all worktrees reference, typically located at the main repository root.

When these two paths differ, the current location is confirmed to be inside a worktree rather than the main repository.

Resolving the Main Repository Root

Upon detecting divergent paths, the redirection logic executes a sequence of Bash commands to locate and validate the main root:

1. Resolve absolute paths: Both COMMON_DIR and GIT_DIR are converted to absolute paths using cd and pwd -P to eliminate symlinks and relative references.
2. Extract parent directory: The script uses dirname on the common Git directory to identify the main repository root.
3. Verify existence: It confirms the calculated main root directory exists before proceeding.
4. Reassign PROJECT_ROOT: Unless explicitly disabled, the script updates PROJECT_ROOT to point to the main repository root.

Implementation in skills/understand/SKILL.md

The worktree detection and redirect logic is implemented as a Bash snippet embedded in the skill documentation at skills/understand/SKILL.md. This code executes immediately when the skill starts, ensuring the correct working directory is established before any analysis begins.

# Embedded Bash snippet – see the skill documentation for the full context

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)
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
      echo "[understand] Detected git worktree at $PROJECT_ROOT"
      echo "[understand] Redirecting output to main repo root: $MAIN_ROOT"
      echo "[understand] (Set UNDERSTAND_NO_WORKTREE_REDIRECT=1 to keep PROJECT_ROOT as the worktree.)"
      PROJECT_ROOT="$MAIN_ROOT"
    fi
  fi
fi
echo "$PROJECT_ROOT"

Running this snippet from within a worktree automatically prints the main repository path:

# Assume you are inside a worktree at /tmp/ua-wt-wt

PROJECT_ROOT="/tmp/ua-wt-wt" ./understand …   # The snippet will print the main root path

Disabling Worktree Redirection

You can prevent the automatic redirect to the main repository root by setting the environment variable UNDERSTAND_NO_WORKTREE_REDIRECT to 1. This forces the skill to treat the worktree directory as the legitimate PROJECT_ROOT, which is useful when you intentionally want to analyze code in isolation or store outputs within the worktree itself.

UNDERSTAND_NO_WORKTREE_REDIRECT=1 PROJECT_ROOT="/tmp/ua-wt-wt" ./understand …

When this variable is set, the detection logic still identifies the worktree status but skips the reassignment of PROJECT_ROOT, keeping the output in the worktree directory.

Testing the Worktree Detection Logic

The worktree redirect behavior is validated by the test suite in src/__tests__/worktree-redirect.test.mjs. This test file creates a temporary Git repository with a secondary worktree, then verifies that the detection logic correctly identifies the main repository root and redirects output accordingly. These tests ensure that the worktree detection remains reliable across different Git configurations and edge cases.

Summary

• Worktree detection compares git rev-parse --git-dir against git rev-parse --git-common-dir to identify secondary checkouts.
• Path resolution converts both Git directories to absolute paths and extracts the parent of the common directory to locate the main repository root.
• Automatic redirection rewrites PROJECT_ROOT to the main root unless UNDERSTAND_NO_WORKTREE_REDIRECT=1 is set.
• Implementation resides in skills/understand/SKILL.md as a Bash snippet executed at skill startup.
• Validation occurs in src/__tests__/worktree-redirect.test.mjs, ensuring robust detection across Git versions.

Frequently Asked Questions

How does the Understand-Anything skill detect if it's running inside a Git worktree?

The skill executes git rev-parse --git-dir to get the current checkout's Git metadata path and git rev-parse --git-common-dir to get the shared Git directory. If these paths differ, the current directory is inside a worktree. The script resolves both to absolute paths and compares them to confirm the worktree status before redirecting output.

Why redirect output to the main repository root instead of keeping it in the worktree?

Claude Code and similar tools often create ephemeral worktrees that are deleted when the session ends. If the knowledge graph were stored in the worktree directory, it would be lost when the worktree is cleaned up. Redirecting to the main repository root ensures persistent storage of the .understand-anything/knowledge-graph.json file and other generated artifacts.

Can I disable the automatic worktree redirection?

Yes. Set the environment variable UNDERSTAND_NO_WORKTREE_REDIRECT to 1 before running the skill. This prevents the reassignment of PROJECT_ROOT, allowing you to analyze the worktree directory directly and store outputs there. This is useful for testing or when you specifically want to isolate analysis to the worktree contents.

Where is the worktree detection logic maintained in the codebase?

The core detection logic is embedded in the documentation file skills/understand/SKILL.md as a Bash code snippet. The corresponding test suite that validates this behavior is located at src/__tests__/worktree-redirect.test.mjs, which programmatically verifies the redirect mechanism using temporary Git repositories.

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