feat(plugin): git-aware-history — fix session fragmentation across git worktrees

[ilanp-ob]

Problem

Claude Code keys session history by the raw CWD path (~/.claude/projects/<slug>/). When you use git worktrees, each worktree gets its own isolated history directory. Deleting a worktree orphans its history — /resume can't find it, and there is no way to see all sessions for a repo in one place.

Active worktree users end up with dozens of orphaned history directories after a sprint.

Solution

git rev-parse --git-common-dir returns the same .git path for any worktree of a repo. This plugin uses that as the canonical project identity, so all worktrees of a repo share one history directory.

Components

1. PATH wrapper script — ongoing routing

A claude wrapper script installed to ~/.local/bin/claude (before the real binary on PATH). No shell function, no .zshrc sourcing, no alias needed — works in every shell, terminal, and IDE integration out of the box.

Gated by a flag file (~/.claude/git-aware-history.enabled) so users can disable it without removing the script.

2. Consolidation script — retroactive migration

consolidate-git-history.sh (~430 lines, bash, macOS/Linux, no extra deps beyond git and python3).

• Phase 1: auto-merges project dirs from live worktrees into their git-root dir
• Phase 2: interactive — handles orphaned dirs from already-deleted worktrees, shows metadata (session count, size, dates, branch names) per inferred repo group

Dry-run by default; --execute to apply.

3. /consolidate-history command

End-to-end setup in one command: installs the PATH wrapper, creates the flag file, shows dry-run preview, runs migration, verifies PATH ordering.

Proposed upstream fix (for reference)

Two parts:

A. New setting

{ "gitAwareHistory": true }

Default true (strictly better for worktree users, no-op outside git repos).

B. One function change in project-path computation

async function resolveProjectRoot(cwd: string): Promise<string> {
  try {
    const { stdout } = await execFileAsync('git', ['rev-parse', '--git-common-dir'], { cwd });
    const gitCommonDir = stdout.trim();
    const absCommonDir = path.isAbsolute(gitCommonDir)
      ? gitCommonDir
      : path.join(cwd, gitCommonDir);
    return path.dirname(absCommonDir);
  } catch {
    return cwd;
  }
}

Uses execFile (fixed argument array, no shell injection risk). Non-git users are completely unaffected.

Test plan

• Install plugin, run /consolidate-history from a worktree
• Verify ~/.local/bin/claude is created and executable
• Verify ~/.claude/git-aware-history.enabled flag file is created
• Start claude from two different worktrees of the same repo — confirm both land in the same ~/.claude/projects/<root-slug>/ directory
• Disable by removing flag file; confirm wrapper passes through with no symlink operations
• Test consolidate-git-history.sh --dry-run against existing history (no changes written)
• Test --execute in a temp dir: PROJECTS_DIR=$(mktemp -d) bash consolidate-git-history.sh --execute

Tracked in: #52113

🤖 Generated with Claude Code