How Git Worktree Redirect Affects the Understand Anything Knowledge Graph

When running the understand or understand-domain skills inside a Git worktree, the system automatically redirects PROJECT_ROOT to the main repository directory, ensuring the knowledge graph persists in .understand-anything/ at the canonical repo root rather than being lost in transient worktrees.

The Understand Anything plugin for Claude Code implements a sophisticated Git worktree detection mechanism to determine where to store its generated knowledge graphs. When you execute these skills from within a Git worktree, a Bash snippet embedded in the skill markdown compares Git's common directory and Git directory paths to identify the main repository root. This worktree redirect ensures graph continuity across temporary development environments that Claude Code frequently creates.

How the Worktree Detection Logic Works

Inside the skill execution environment, the system detects worktrees by comparing the absolute paths returned by two Git commands.

The Path Comparison Mechanism

The detection logic relies on the divergence between git rev-parse --git-common-dir and git rev-parse --git-dir. In a standard checkout, these paths are identical; in a worktree, they differ. The script resolves both paths to absolute form and compares them:

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" && pwd -P)
  GIT_ABS=$(cd "$PROJECT_ROOT" && cd "$GIT_DIR" && pwd -P)
  if [ "$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

When the paths differ, the parent directory of --git-common-dir represents the main repository root, and PROJECT_ROOT is rewritten to this location.

The Override Environment Variable

You can disable this behavior by setting UNDERSTAND_NO_WORKTREE_REDIRECT=1. When this variable is set to 1, the script preserves the original PROJECT_ROOT even when running inside a worktree, isolating the knowledge graph to that specific worktree directory.

Impact on Knowledge Graph Storage

The worktree redirect directly determines where the .understand-anything/ directory is created and how the knowledge graph persists across sessions.

Default Behavior (Graph Persistence)

By default, the redirect is active. According to the implementation in understand-anything-plugin/skills/understand/SKILL.md, the analysis engine writes the generated graph into .understand-anything/ under the main repository root rather than the worktree path. This prevents data loss when Claude Code-managed worktrees are discarded at session end, ensuring the knowledge graph aligns with the canonical repository root.

Isolated Mode (Per-Worktree Graphs)

Setting UNDERSTAND_NO_WORKTREE_REDIRECT=1 forces the graph to live inside the worktree's .understand-anything/ directory. This mode is useful only for rare, per-worktree experiments where you want complete isolation between development contexts, though the graph will disappear when the worktree is removed.

Implementation and Verification

The worktree redirect logic is documented in understand-anything-plugin/skills/understand/SKILL.md and verified by the test suite in understand-anything-plugin/src/__tests__/worktree-redirect.test.mjs.

The test harness creates temporary Git repositories with worktrees, executes the detection snippet from various locations, and asserts that PROJECT_ROOT resolves to the main repository root unless the override variable is present. This automated verification ensures the behavior remains consistent across Git versions and edge cases.

Summary

• Git worktree redirect automatically rewrites PROJECT_ROOT to the main repository when running inside a worktree.
• The detection mechanism compares git rev-parse --git-common-dir and git rev-parse --git-dir to identify worktree contexts.
• Default behavior stores the knowledge graph in .understand-anything/ at the canonical repo root, preventing loss when worktrees are deleted.
• Setting UNDERSTAND_NO_WORKTREE_REDIRECT=1 isolates the graph to the worktree for experimental purposes.
• The logic is implemented in the understand skill and verified by worktree-redirect.test.mjs.

Frequently Asked Questions

What happens if I run the understand skill from a Git worktree without any special configuration?

The skill automatically detects the worktree context and redirects PROJECT_ROOT to the main repository root. The knowledge graph is stored in <main-repo>/.understand-anything/, ensuring your analysis persists even after the worktree is removed.

How does the worktree detection mechanism identify that I'm in a worktree versus a normal checkout?

The script compares the absolute paths of Git's common directory (--git-common-dir) and Git directory (--git-dir). In normal checkouts these paths are identical; in worktrees they differ, triggering the redirect logic to calculate the main repository root from the common directory's parent.

Can I keep separate knowledge graphs for different worktrees of the same repository?

Yes, but you must explicitly set UNDERSTAND_NO_WORKTREE_REDIRECT=1 before running the skill. This disables the redirect and keeps the .understand-anything/ directory inside the worktree path, though the graph will be lost when the worktree is deleted.

Where is the worktree redirect logic documented and tested in the source code?

The behavior is documented in understand-anything-plugin/skills/understand/SKILL.md and rigorously tested in understand-anything-plugin/src/__tests__/worktree-redirect.test.mjs, which validates the path comparison logic and the UNDERSTAND_NO_WORKTREE_REDIRECT override mechanism.

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