# How to Use and Disable the Worktree Redirect Feature in Understand Anything

> Master the worktree redirect feature in Understand Anything. Learn how to use it to prevent data loss and when and how to disable it for your git worktrees.

- Repository: [Yuxiang Lin/Understand-Anything](https://github.com/Lum1104/Understand-Anything)
- Tags: how-to-guide
- Published: 2026-05-22

---

**The worktree redirect feature automatically redirects knowledge graph output from a git worktree to the main repository root to prevent data loss in ephemeral environments, and you can disable this behavior by setting `UNDERSTAND_NO_WORKTREE_REDIRECT=1` before invoking the analysis.**

Understand Anything analyzes repositories and writes knowledge graphs to `.understand-anything/` directories under the `PROJECT_ROOT` path. When running inside a git worktree, the tool's worktree redirect feature redirects `PROJECT_ROOT` to the main repository root unless explicitly disabled. This ensures persistent storage across temporary Claude Code sessions while providing an escape hatch for isolated analysis workflows.

## How the Worktree Redirect Feature Detects Worktrees

The detection logic resides in the Bash snippets within [`understand-anything-plugin/skills/understand/SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/skills/understand/SKILL.md) and [`understand-anything-plugin/skills/understand-domain/SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/skills/understand-domain/SKILL.md). The script determines whether the current directory is a worktree by comparing Git's common directory and git directory paths.

### Detecting Worktree Status via Git Commands

The feature runs two Git commands to establish directory 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)

```

In a standard repository checkout, both variables resolve to identical paths. In a worktree configuration, they differ because `--git-common-dir` points to the shared `.git` folder of the main repository, while `--git-dir` points to the worktree's own `../.git` metadata file.

### Canonical Path Comparison

The script converts both paths to absolute form and performs an inequality test:

```bash
[ "$COMMON_ABS" != "$GIT_ABS" ]

```

When this test succeeds, the code identifies the location as a worktree rather than the main checkout, triggering the redirect logic.

## How the Redirection Logic Works

Upon detecting a worktree, the script checks the `UNDERSTAND_NO_WORKTREE_REDIRECT` environment variable. If unset or not equal to `1`, the code calculates the main repository root and reassigns `PROJECT_ROOT`:

```bash
MAIN_ROOT=$(dirname "$COMMON_ABS")
echo "[understand] Detected git worktree at $PROJECT_ROOT"
echo "[understand] Redirecting output to main repo root: $MAIN_ROOT"
echo "[understand] (Set UNDERSTAND_NO_WORKTREE_REDIRECT=1 to keep PROJECT_ROOT as the worktree.)"
PROJECT_ROOT="$MAIN_ROOT"

```

This reassignment ensures all subsequent phases write the knowledge graph to `.understand-anything/` under the main repository root, preventing writes to the ephemeral worktree directory.

## Why the Redirect Is Enabled by Default

The default redirection behavior serves two critical purposes in Claude Code environments.

**Ephemeral worktree protection:** Claude Code creates temporary worktrees for each analysis session. Any data written to these directories—including knowledge graphs—is deleted when the session terminates. Redirecting to the main repository ensures the graph persists across sessions.

**Cross-agent consistency:** Multiple analysis agents (project-scanner, file-analyzer, etc.) read from and write to the same graph file. Maintaining a single, stable location prevents race conditions and data duplication across concurrent operations.

## When to Disable the Worktree Redirect

Disable the worktree redirect feature by setting `UNDERSTAND_NO_WORKTREE_REDIRECT=1` when you require isolated analysis output. Consider disabling redirection in the following scenarios:

- **Testing custom graphs:** When experimenting with temporary checkouts where you want to avoid overwriting the main repository's shared knowledge graph.
- **Concurrent isolated analyses:** In CI pipelines or parallel jobs comparing different analysis results, where each worktree requires its own distinct `.understand-anything/` directory.
- **Debugging worktree-specific behavior:** When verifying that issues reproduce only in worktree contexts or testing the redirect logic itself without affecting the main repository's data.

### Disabling Redirect via Environment Variable

Export the variable for the entire shell session:

```bash
export UNDERSTAND_NO_WORKTREE_REDIRECT=1
cd /path/to/worktree
/understand --full

```

Or prefix a single command without affecting the broader environment:

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

```

## Testing the Worktree Detection Logic

The test suite in `understand-anything-plugin/src/__tests__/worktree-redirect.test.mjs` validates both behaviors using the `runResolve` function. When called without the override, `runResolve(worktree)` returns the main repository path. When invoked with `runResolve(worktree, { UNDERSTAND_NO_WORKTREE_REDIRECT: "1" })`, the function returns the worktree path itself, confirming the environment variable successfully disables the redirect.

## Summary

- The worktree redirect feature detects git worktrees by comparing `--git-common-dir` and `--git-dir` outputs in [`understand-anything-plugin/skills/understand/SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/skills/understand/SKILL.md).
- By default, it redirects `PROJECT_ROOT` to the main repository root to prevent data loss in ephemeral Claude Code worktrees.
- Set `UNDERSTAND_NO_WORKTREE_REDIRECT=1` to keep analysis output within the worktree directory for isolated testing or concurrent analysis scenarios.
- The `understand-domain` skill implements identical logic in [`understand-anything-plugin/skills/understand-domain/SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/skills/understand-domain/SKILL.md).
- Tests in `understand-anything-plugin/src/__tests__/worktree-redirect.test.mjs` verify both enabled and disabled states using the `runResolve` function.

## Frequently Asked Questions

### What happens if I don't disable the worktree redirect?

If you run `/understand` from inside a git worktree without setting `UNDERSTAND_NO_WORKTREE_REDIRECT=1`, the tool automatically redirects output to the main repository's root directory. This prevents your knowledge graph from being deleted when the temporary worktree is cleaned up, but means all worktrees share the same graph file.

### How do I temporarily disable the redirect for a single command?

Prefix your command with the environment variable assignment: `UNDERSTAND_NO_WORKTREE_REDIRECT=1 /understand --full .`. This disables the redirect for that specific invocation without modifying your shell's environment variables or affecting subsequent commands.

### Does the understand-domain skill also use worktree redirection?

Yes, the [`understand-anything-plugin/skills/understand-domain/SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/skills/understand-domain/SKILL.md) file contains identical Bash logic for detecting worktrees and redirecting `PROJECT_ROOT` to the main repository root. Both skills respect the `UNDERSTAND_NO_WORKTREE_REDIRECT` environment variable.

### Can I have different knowledge graphs for different worktrees of the same repository?

Only if you disable the redirect by setting `UNDERSTAND_NO_WORKTREE_REDIRECT=1` before running the analysis. With the default behavior enabled, all worktrees write to the main repository's `.understand-anything/` directory, creating a single shared graph. Disabling the redirect isolates each worktree's output to its own directory structure.