Git Worktree Redirect Feature in Understand-Anything: Preventing Knowledge Graph Loss

The git worktree redirect feature detects when Understand-Anything runs inside a temporary Git worktree and automatically redirects PROJECT_ROOT to the main repository, ensuring the knowledge graph persists in .understand-anything/knowledge-graph.json instead of being lost when the ephemeral worktree is deleted.

When using Claude Code with Git worktrees, analysis sessions often execute in temporary directories that vanish after the session ends. The git worktree redirect feature in the Egonex-AI/Understand-Anything repository solves this by ensuring knowledge graphs are always written to the durable main repository location, preventing accidental data loss.

How the Git Worktree Redirect Feature Works

The mechanism operates by comparing Git directory paths to determine if the current environment is a worktree versus the main repository checkout.

Detecting Ephemeral Worktrees

The feature distinguishes between main repositories and worktrees by comparing the output of two Git commands. In understand-anything-plugin/skills/understand/SKILL.md, the detection logic compares the worktree-specific Git directory against the shared common directory:

git -C "$PROJECT_ROOT" rev-parse --git-dir          # location of the worktree's .git directory

git -C "$PROJECT_ROOT" rev-parse --git-common-dir   # location of the shared common directory

When these paths differ, the script identifies the current directory as a worktree. This detection is critical because worktrees created by Claude Code are ephemeral—they are deleted when the session terminates, taking any files written to .understand-anything/ with them.

Redirecting to the Main Repository

Upon detecting a worktree, the script rewrites PROJECT_ROOT to point to the parent of the common directory—the root of the main repository. This redirection ensures that the knowledge graph is written to a persistent location.

The bash implementation from the source code performs this transformation:

# In understand-anything-plugin/skills/understand/SKILL.md

if [ "$(git -C "$PROJECT_ROOT" rev-parse --git-dir)" != "$(git -C "$PROJECT_ROOT" rev-parse --git-common-dir)" ]; then
  echo "[understand] Detected git worktree at $PROJECT_ROOT"
  PROJECT_ROOT="$(dirname "$(git -C "$PROJECT_ROOT" rev-parse --git-common-dir)")"
  echo "[understand] Redirected output to main repo at $PROJECT_ROOT"
fi

This redirection applies to all subsequent pipeline operations, ensuring that agents like the project-scanner and graph-reviewer read from and write to the same durable graph location regardless of where the command was launched.

Configuration and Disabling the Redirect

While the default behavior protects data, you can disable the git worktree redirect feature by setting the environment variable UNDERSTAND_NO_WORKTREE_REDIRECT=1. This is rarely needed, as most users require a single, long-lived graph for the repository.

To run Understand-Anything from a worktree while preserving the redirect:

cd /tmp/wt
UNDERSTAND_NO_WORKTREE_REDIRECT=0 /usr/local/bin/understand

To disable redirection and keep PROJECT_ROOT as the worktree:

UNDERSTAND_NO_WORKTREE_REDIRECT=1 /usr/local/bin/understand

Automated Testing of the Redirect Logic

The repository includes comprehensive tests to verify this behavior. The file understand-anything-plugin/src/__tests__/worktree-redirect.test.mjs validates both the redirection mechanism and the opt-out functionality:

// understand-anything-plugin/src/__tests__/worktree-redirect.test.mjs
describe("worktree-redirect snippet (issue #133)", () => {
  it("redirects PROJECT_ROOT to the main repo when started in a worktree", () => {
    expect(runResolve(worktree)).toBe(mainRepo);
  });
  it("keeps PROJECT_ROOT when the env flag disables redirection", () => {
    expect(runResolve(worktree, { UNDERSTAND_NO_WORKTREE_REDIRECT: "1" })).toBe(worktree);
  });
});

These tests programmatically create temporary worktrees, execute the redirect logic, and assert that PROJECT_ROOT is correctly rewritten—or preserved when the disable flag is set.

Implementation Across Knowledge Graph Types

The same git worktree redirect feature appears in multiple skill definitions within the repository. The understand-anything-plugin/skills/understand-domain/SKILL.md file mirrors the identical redirection logic for domain-specific knowledge graphs, ensuring consistent behavior across different analysis modes.

Summary

• Persistence: The git worktree redirect feature guarantees that .understand-anything/knowledge-graph.json survives ephemeral worktree deletion by writing to the main repository.
• Consistency: All agents access the same graph location regardless of whether the command originates from a worktree or the main checkout.
• Safety: Prevents data loss when developers experiment with worktrees or when Claude Code automatically spins up temporary worktrees for analysis.
• Control: The UNDERSTAND_NO_WORKTREE_REDIRECT environment variable allows advanced users to opt out when necessary.

Frequently Asked Questions

What is a Git worktree and why does it cause data loss?

A Git worktree is a linked working directory that allows you to check out multiple branches simultaneously. When Claude Code creates worktrees for analysis, they exist in temporary directories that are deleted when the session ends. Any files written inside these directories—including knowledge graphs—disappear permanently unless the git worktree redirect feature intervenes.

How does Understand-Anything detect if it's running in a worktree?

According to the source code in understand-anything-plugin/skills/understand/SKILL.md, the tool compares git rev-parse --git-dir against git rev-parse --git-common-dir. If these paths differ, the directory is a worktree rather than the main repository checkout, triggering the redirection logic.

Can I disable the git worktree redirect feature?

Yes. Set the environment variable UNDERSTAND_NO_WORKTREE_REDIRECT=1 before running Understand-Anything. This keeps PROJECT_ROOT pointing to the worktree directory, which is useful only in rare cases where you specifically want isolated analysis results in a temporary location.

Where is the knowledge graph stored when using a worktree?

When the git worktree redirect feature is active (the default), the knowledge graph is stored in .understand-anything/knowledge-graph.json within the main repository root—the parent directory of the Git common directory. This ensures the graph persists across Claude Code sessions even when the worktree itself is ephemeral.

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