How the Worktree Redirect Feature Prevents Data Loss in Understand-Anything

The worktree redirect feature detects when the /understand skill runs inside a Git worktree and automatically redirects PROJECT_ROOT to the main repository root, ensuring that the knowledge graph persists in a stable location rather than being lost when the ephemeral worktree is deleted.

When using Claude Code's temporary sessions, analyses often run inside ephemeral Git worktrees that are deleted after the session ends. The Understand-Anything plugin implements a robust worktree redirect feature that safeguards your architecture data by automatically detecting worktree environments and rerouting file output to the canonical repository directory.

The Risk of Ephemeral Worktrees

Claude Code creates temporary Git worktrees for isolated analysis sessions. These worktrees are ephemeral by design—the entire directory, including any .understand-anything/ folders created within them, is deleted when the session terminates.

If the /understand skill wrote the knowledge-graph.json file directly into a worktree, the complete architecture analysis would vanish upon cleanup. The worktree redirect feature eliminates this risk by ensuring all persistent data lands in the main repository root, where the .understand-anything/ directory survives across sessions.

How Worktree Detection Works

The feature relies on Git's internal metadata to distinguish between a regular checkout and a worktree. In understand-anything-plugin/skills/understand/SKILL.md, the skill embeds a Bash script that compares two Git paths to determine the repository structure.

The Git Metadata Comparison

The detection logic uses two specific Git commands:

• git rev-parse --git-dir: Returns the path to the local .git directory of the current checkout
• git rev-parse --git-common-dir: Returns the shared Git directory that all worktrees of the same repository reference

In a standard repository checkout, these paths are identical. In a worktree, they diverge—the local .git is a file pointing to the common directory, while the common directory resides in the main repository.

The Bash Implementation

The redirect logic implemented in the skill definition compares these paths:

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"

When COMMON_ABS differs from GIT_ABS, the script calculates MAIN_ROOT as the parent of the common directory—this is the canonical repository root. It then reassigns PROJECT_ROOT to this stable location, unless the user has explicitly disabled the feature.

The Redirect Logic in Action

When the /understand skill initializes, it resolves PROJECT_ROOT using the detection script above. If the analysis runs inside a worktree, the variable automatically points to the main repository before any file operations occur.

Default behavior with redirect enabled:

# Inside a Claude Code worktree

cd /tmp/ua-wt-123/wt
understand

# Output written to: /tmp/ua-wt-123/main/.understand-anything/knowledge-graph.json

This ensures that knowledge-graph.json and other generated artifacts persist in the main repository's .understand-anything/ directory, surviving the worktree cleanup process.

Configuring the Behavior

While the redirect is enabled by default to prevent data loss, the feature supports user override for specialized workflows.

Disabling the Redirect

Set the UNDERSTAND_NO_WORKTREE_REDIRECT environment variable to 1 to keep output in the original worktree location:

export UNDERSTAND_NO_WORKTREE_REDIRECT=1
cd /tmp/ua-wt-123/wt
understand

# Output written to: /tmp/ua-wt-123/wt/.understand-anything/knowledge-graph.json

This is rarely recommended because the worktree will be deleted, but it allows per-worktree isolation when explicitly desired.

Validation and Testing

The implementation is validated by understand-anything-plugin/src/__tests__/worktree-redirect.test.mjs, which verifies the redirect behavior across multiple scenarios:

• Normal checkout: PROJECT_ROOT remains unchanged (points to main repo)
• Worktree root: Redirects to mainRepo
• Sub-directory inside worktree: Redirects to mainRepo
• Worktree with opt-out flag: Stays as the worktree path when UNDERSTAND_NO_WORKTREE_REDIRECT=1
• Non-git directory: No redirection occurs

These tests ensure the Bash detection logic correctly identifies worktree boundaries in all edge cases.

Summary

• The worktree redirect feature protects the knowledge graph from deletion by detecting ephemeral Git worktrees before file writes occur
• It compares git rev-parse --git-common-dir and git rev-parse --git-dir to identify worktree status
• When detected, it redirects PROJECT_ROOT from the transient worktree to the main repository root
• Output files land in the persistent .understand-anything/ directory instead of the temporary worktree
• Users can disable the feature by setting UNDERSTAND_NO_WORKTREE_REDIRECT=1, though this risks data loss
• The logic is tested in worktree-redirect.test.mjs and documented in understand/SKILL.md and understand-domain/SKILL.md

Frequently Asked Questions

What happens if I run the skill inside a worktree without the redirect feature?

Without the worktree redirect, the /understand skill would create the .understand-anything/ directory inside the ephemeral worktree. When Claude Code cleans up the temporary session, the entire worktree—including your knowledge-graph.json and all analysis data—is permanently deleted, resulting in complete data loss.

How does the feature know if I'm in a worktree versus a normal repository?

The feature compares the absolute paths of git rev-parse --git-dir (local Git directory) and git rev-parse --git-common-dir (shared Git directory). In a standard repository checkout, these paths are identical. In a worktree, they differ, triggering the redirect to the main repository root calculated from the common directory's parent.

Can I keep analysis output inside a worktree if I need isolation?

Yes, set the environment variable UNDERSTAND_NO_WORKTREE_REDIRECT=1 before running the skill. This disables the redirect and keeps PROJECT_ROOT pointing to the worktree location. However, note that the output will be lost when the worktree is deleted unless you manually copy the files elsewhere.

Is the worktree redirect available in all Understand-Anything skills?

The worktree redirect logic is implemented in both the /understand skill and the /understand-domain skill, as documented in understand-anything-plugin/skills/understand/SKILL.md and understand-anything-plugin/skills/understand-domain/SKILL.md. Both skills use the same Bash detection script and PROJECT_ROOT resolution logic to ensure consistent data persistence across the plugin.

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