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

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:

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

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:

# 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 lines 52-66.

Opting Out of the Redirect

To disable the redirect and write data to the worktree:

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:

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 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}