How the Understand-Anything Plugin Handles Git Worktree Redirects

The Understand-Anything plugin automatically detects Git worktrees during Phase 0 pre-flight and redirects the project root from the ephemeral worktree directory to the main repository root by comparing git rev-parse --git-common-dir and --git-dir paths, unless the UNDERSTAND_NO_WORKTREE_REDIRECT environment variable is set to 1.

When using the /understand skill in the Egonex-AI/Understand-Anything repository, the plugin must ensure that generated knowledge graphs persist in the correct location. Because worktrees created by Claude Code are typically temporary, the plugin implements a redirect mechanism that automatically switches the project root to the main repository checkout to prevent data loss.

Detecting Git Worktrees in Phase 0 Pre-flight

The worktree detection logic executes during Phase 0 – Pre-flight, one of the first steps when the /understand skill starts. The plugin determines the initial PROJECT_ROOT from either a user-supplied path or the current working directory.

Comparing Git Directory Paths

A Git worktree shares the same .git directory with the main repository but maintains a separate working tree. The plugin exploits this architectural difference by comparing two Git commands:

• git rev-parse --git-common-dir returns the shared common directory
• git rev-parse --git-dir returns the worktree-specific .git directory

In a standard repository checkout, these paths are identical. In a worktree, they differ.

The Worktree Redirect Implementation

The redirect logic is embedded in the Worktree-Redirect snippet located in skills/understand/SKILL.md (lines 52-70).

Redirect Logic Flow

The implementation follows these steps:

1. Execute both git rev-parse commands within $PROJECT_ROOT
2. Resolve both paths to absolute forms (COMMON_ABS and GIT_ABS)
3. Compare the absolute paths; if they differ, the current directory is a worktree
4. Calculate MAIN_ROOT as the parent directory of the common directory (dirname "$COMMON_ABS")
5. Unless UNDERSTAND_NO_WORKTREE_REDIRECT is set to 1, replace PROJECT_ROOT with MAIN_ROOT

This ensures the generated .understand-anything folder writes to the main repository root rather than the ephemeral worktree location.

Bash Implementation

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
      PROJECT_ROOT="$MAIN_ROOT"
    fi
  fi
fi
echo "$PROJECT_ROOT"

Configuring Worktree Redirect Behavior

Disabling Redirects for Per-Worktree Graphs

To maintain separate knowledge graphs for each worktree, set the environment variable before invoking the skill:

export UNDERSTAND_NO_WORKTREE_REDIRECT=1
understand

When this variable equals 1, the plugin preserves the original PROJECT_ROOT and writes the .understand-anything folder to the worktree directory.

Test Coverage and Verification

The worktree redirect behavior is validated by the test suite at understand-anything-plugin/src/__tests__/worktree-redirect.test.mjs. The tests create temporary Git repositories and worktrees to verify:

• Normal checkouts: PROJECT_ROOT remains unchanged
• Worktree directories: Automatically redirects to the main repo root
• Subdirectories within worktrees: Correctly resolves to the main repository root
• Opt-out configuration: Respects UNDERSTAND_NO_WORKTREE_REDIRECT=1 and prevents redirection

Test Examples

it("redirects PROJECT_ROOT to the main repo when started in a worktree", () => {
  expect(runResolve(worktree)).toBe(mainRepo);
});

it("redirects from a subdirectory inside a worktree", () => {
  expect(runResolve(subdir)).toBe(mainRepo);
});

it("respects UNDERSTAND_NO_WORKTREE_REDIRECT=1", () => {
  expect(runResolve(worktree, { UNDERSTAND_NO_WORKTREE_REDIRECT: "1" }))
    .toBe(worktree);
});

Summary

• The plugin detects Git worktrees during Phase 0 by comparing git rev-parse --git-common-dir and --git-dir outputs
• When paths differ, it calculates the main repository root as the parent of the common Git directory
• By default, PROJECT_ROOT redirects to the main repository to prevent knowledge graph loss in ephemeral worktrees
• Set UNDERSTAND_NO_WORKTREE_REDIRECT=1 to maintain per-worktree knowledge graphs
• Implementation resides in skills/understand/SKILL.md with comprehensive tests in worktree-redirect.test.mjs

Frequently Asked Questions

How does the plugin detect if it's running inside a Git worktree?

The plugin executes git rev-parse --git-common-dir and git rev-parse --git-dir within the project root. If the resolved absolute paths differ, the current directory is identified as a worktree rather than the main repository checkout.

Can I disable the worktree redirect feature?

Yes. Set the environment variable UNDERSTAND_NO_WORKTREE_REDIRECT to 1 before running the /understand skill. This preserves the worktree directory as the project root and stores the .understand-anything folder within the worktree instead of the main repository.

Why does Understand-Anything redirect from worktrees by default?

Worktrees created by Claude Code are typically ephemeral and destroyed when the session ends. Redirecting to the main repository ensures the generated knowledge graph persists in a permanent location where the user expects to find it, preventing data loss.

Where is the worktree detection logic implemented?

The core detection and redirect logic is implemented in the bash snippet within skills/understand/SKILL.md (lines 52-70). The behavior is verified by the test suite located at understand-anything-plugin/src/__tests__/worktree-redirect.test.mjs.

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