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

> Discover how the worktree redirect feature in Understand Anything prevents data loss by redirecting PROJECT_ROOT to the main repo root, safeguarding your knowledge graph.

- Repository: [Egonex/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything)
- Tags: internals
- Published: 2026-06-24

---

**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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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:

```bash
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:**

```bash

# 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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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:

```bash
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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand/SKILL.md) and [`understand-domain/SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/skills/understand/SKILL.md) and [`understand-anything-plugin/skills/understand-domain/SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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.