# How the Understand-Anything Plugin Handles Git Worktree Redirects

> Learn how the Understand Anything plugin redirects Git worktrees to the main repository root automatically. Discover the logic behind this feature and its environment variable override.

- Repository: [Egonex/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything)
- Tags: how-to-guide
- Published: 2026-06-23

---

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

```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"

```

## 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:

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

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