# Understanding the Worktree Redirect Feature in Understand Anything

> Learn about the worktree redirect feature in Understand Anything. It prevents data loss by redirecting ephemeral Git worktree output to the main repository root.

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

---

**The worktree redirect feature automatically redirects output from ephemeral Git worktrees to the main repository root to prevent data loss of the knowledge graph when Claude Code sessions end.**

When running **Understand Anything** inside a Git worktree, the tool faces a critical challenge: Claude Code creates ephemeral worktrees that are deleted when sessions end, which would destroy the `.understand-anything/` knowledge graph. The **worktree redirect feature** solves this by detecting worktree environments and rewriting `PROJECT_ROOT` to point at the permanent main repository instead.

## How the Worktree Redirect Feature Works

### Detecting Git Worktree Environments

The detection logic relies on comparing two Git directory paths. According to the implementation 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 script executes:

```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 the current checkout as a worktree.

### Redirecting PROJECT_ROOT

Upon detection, the feature automatically rewrites `PROJECT_ROOT` to the parent of `--git-common-dir` (the main repository root). This ensures that the `.understand-anything/` directory and its knowledge graph are written to a persistent location rather than the temporary worktree directory.

## Why the Worktree Redirect Feature Exists

The feature addresses a specific problem with **Claude Code** worktrees. As noted in the source documentation, these worktrees are ephemeral—the directory and all contents are destroyed when the session ends. Without the redirect, the knowledge graph stored in `.understand-anything/` would be lost, breaking continuity across runs (issue #133).

## Configuring and Disabling the Redirect

Users can override the default behavior using the environment variable `UNDERSTAND_NO_WORKTREE_REDIRECT`.

**Default behavior (automatic redirect):**

```bash

# Inside a worktree

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

```

**Opt-out to keep worktree output:**

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

# No redirect message; output stays in the worktree

```

This override is useful only in rare cases where per-worktree graphs are intentionally desired.

## Implementation in Source Files

The logic is implemented consistently across multiple skill files and validated by automated tests.

**Key source files:**
- [`understand-anything-plugin/skills/understand/SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/skills/understand/SKILL.md) – Core implementation and Bash logic
- [`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) – Domain-specific skill application
- `understand-anything-plugin/src/__tests__/worktree-redirect.test.mjs` – Test suite validation

The test suite validates both the redirect and opt-out 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** detects when Understand Anything runs inside a Git worktree by comparing `git rev-parse --git-dir` and `--git-common-dir`.
- It automatically redirects `PROJECT_ROOT` to the main repository root to prevent loss of the `.understand-anything/` knowledge graph.
- **Claude Code** worktrees are ephemeral and deleted after sessions, making this protection essential for data continuity.
- Set `UNDERSTAND_NO_WORKTREE_REDIRECT=1` to disable the redirect and write outputs to the worktree instead.
- Implementation spans [`SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/SKILL.md) files and is verified by `worktree-redirect.test.mjs`.

## Frequently Asked Questions

### What triggers the worktree redirect feature?

The feature triggers when `git rev-parse --git-dir` returns a different path than `git rev-parse --git-common-dir`. This comparison identifies that the current directory is a linked worktree rather than the main repository checkout.

### Can I use Understand Anything in a worktree without redirecting output?

Yes. Set the environment variable `UNDERSTAND_NO_WORKTREE_REDIRECT=1` before running the command. This forces the tool to use the worktree directory as `PROJECT_ROOT`, though this is only recommended when you intentionally need isolated, per-worktree knowledge graphs.

### Why does Claude Code require this redirect mechanism?

Claude Code creates ephemeral worktrees that are automatically deleted when the session ends. Without the redirect, the `.understand-anything/` directory containing the knowledge graph would be destroyed, causing data loss and forcing regeneration of the graph in subsequent sessions.

### Is the worktree redirect feature applied to all Understand Anything skills?

Yes. The same redirect logic is applied to both the core `understand` skill and the `understand-domain` skill, as implemented in their respective [`SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/SKILL.md) files. This ensures consistent behavior across all analysis modes when running in worktree environments.