# What Is the Worktree Redirect Feature in Understand Anything and When to Disable It

> Learn about the worktree redirect feature in Understand Anything, when to use it, and when to disable it. Keep your knowledge graph intact with this essential guide.

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

---

**The worktree redirect feature in Understand Anything automatically rewrites `PROJECT_ROOT` to point at the main repository root when the tool detects it is running inside a Git worktree, preventing the loss of the `.understand-anything/` knowledge graph when ephemeral worktrees are destroyed; you should disable it only by setting `UNDERSTAND_NO_WORKTREE_REDIRECT=1` when you intentionally need isolated per-worktree analysis data.**

When running Understand Anything inside a Git worktree—particularly the ephemeral worktrees created by Claude Code—the tool must ensure the knowledge graph persists beyond the session. The worktree redirect feature solves this by detecting worktree environments and redirecting output to the main repository root, preventing the destruction of `.understand-anything/` data when temporary directories are removed (as documented in issue #133).

## How the Worktree Redirect Feature Works

Understand Anything writes intermediate data to `.understand-anything/` under the directory specified by `PROJECT_ROOT`. When the tool detects it is running inside a Git worktree, it automatically rewrites `PROJECT_ROOT` to point at the main repository root instead of the ephemeral worktree directory.

The detection mechanism relies on comparing Git directory paths:

```bash
git rev-parse --git-dir          # Returns .git inside the worktree

git rev-parse --git-common-dir   # Returns shared .git directory of the main repo

```

When these paths differ, the script identifies a worktree environment and sets `PROJECT_ROOT` to the parent of `--git-common-dir`. This ensures the knowledge graph is stored in the permanent checkout, preserving continuity across runs and preventing the data loss described in issue #133.

### Implementation in SKILL.md

The core logic resides in [`understand-anything-plugin/skills/understand/SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/skills/understand/SKILL.md), which contains the Bash implementation that performs the directory comparison and redirection. The same redirect logic applies to the domain-specific skill in [`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) to keep domain graphs safe.

## When to Disable the Worktree Redirect

Disable the worktree redirect feature only in rare scenarios where you intentionally want isolated per-worktree knowledge graphs. Set the environment variable:

```bash
export UNDERSTAND_NO_WORKTREE_REDIRECT=1

```

This forces the tool to keep `PROJECT_ROOT` pointing at the worktree directory, causing `.understand-anything/` to be written inside the worktree. According to the source documentation, this is useful only when you need temporary, disposable analysis data that does not need to persist in the main repository.

## Configuration Examples

### Default Behavior (Redirect Enabled)

When running inside a worktree with default settings:

```bash

# Inside a worktree

$ ./understand --full
[understand] Detected git worktree at /tmp/worktree
[understand] Redirecting PROJECT_ROOT to the main repository root

```

The output confirms the system detected the worktree and redirected `PROJECT_ROOT` to the main repository root as implemented in [`SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/SKILL.md) lines 52-66.

### Opting Out of the Redirect

To disable the redirect and write data to the worktree:

```bash
export UNDERSTAND_NO_WORKTREE_REDIRECT=1
./understand --full

# No redirect message appears; output stays in the worktree

```

### Test Verification

The test suite in `understand-anything-plugin/src/__tests__/worktree-redirect.test.mjs` validates both behaviors:

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

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

```

## Summary

- The worktree redirect feature prevents data loss by redirecting `PROJECT_ROOT` from ephemeral worktrees to the main repository root.
- Detection occurs by comparing `git rev-parse --git-dir` and `git rev-parse --git-common-dir`.
- The feature is implemented 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 applies to both the core and domain-specific skills.
- Disable it by setting `UNDERSTAND_NO_WORKTREE_REDIRECT=1` only when you need isolated per-worktree graphs.
- Automated tests in `worktree-redirect.test.mjs` confirm the redirect behavior.

## Frequently Asked Questions

### What triggers the worktree redirect feature?

The feature triggers when the Understand Anything script detects that the current checkout is a Git worktree. This happens automatically when `git rev-parse --git-dir` and `git rev-parse --git-common-dir` return different paths, indicating the presence of a worktree structure rather than the main repository.

### How do I permanently disable the worktree redirect?

Set the environment variable `UNDERSTAND_NO_WORKTREE_REDIRECT=1` before running the tool. You can export this in your shell configuration for permanent disablement, or prefix individual commands with it for temporary opt-out. Without this variable, the tool defaults to redirecting output to the main repository root.

### Where is the knowledge graph stored when the redirect is active?

When the worktree redirect is active, the knowledge graph is stored in `.understand-anything/` at the main repository root (the parent of the Git common directory) rather than inside the worktree directory. This ensures the graph persists even if the ephemeral worktree is deleted.

### Does this feature work with the understand-domain skill?

Yes, the same worktree redirect logic applies to the `understand-domain` skill. According to the source code in [`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), the domain-specific skill implements identical detection and redirection logic to ensure domain graphs are also preserved in the main repository rather than ephemeral worktrees.