Understanding the Worktree Redirect Feature in Understand Anything

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, the script executes:

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

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

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 – Core implementation and Bash logic
• 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:

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 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 files. This ensures consistent behavior across all analysis modes when running in worktree environments.

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