Worktree UX: session keying, multi-repo isolation, and gitignored files

[JefStat]

Summary

/worktree is great when a task fits cleanly inside a single git repo, but several rough edges make it painful in common real-world workflows. Filing as a bundle since they share a theme.

The pain points

1. Sessions are keyed by cwd, so worktrees fragment session history.
   Starting a session in the repo root and then spawning a worktree means claude --resume from either location sees only half the history. There's no obvious way to follow a session across the cwd change.

2. No way to change a running session's cwd.
   Once you realize mid-session you wanted to be in a worktree, you can't move the session into it. You either abandon context or abandon the worktree.

3. /worktree requires a git repo.
   Useful when you're working in ~/scratch/, a docs-only dir, or any non-repo workspace and want the same isolation guarantee. Today you have to git init just to get a worktree.

4. Worktrees don't extend to sibling repos touched during the task.
   My tasks routinely edit repo A while consulting/modifying repo B next to it. The worktree isolates A but the agent still reads/writes the real checkout of B, which defeats the "safe sandbox" promise of worktrees.

5. Gitignored local config (.env, decrypted secrets, local symlinks) isn't copied into the worktree.
   First run of pnpm dev / tests inside the worktree fails because every gitignored dev-time file is missing. An opt-in copy list (or a documented convention) would unblock this.

Why this matters

Worktrees are the main mechanism for parallel agent work and safe experimentation. The current shape biases users toward single-repo, git-repo-only, dev-server-free tasks — a narrow slice of what people actually do.

Suggestions (not prescriptive)

• Session metadata could be keyed by session ID with cwd tracked as a mutable property.
• Allow /worktree in non-repo dirs via a plain directory copy (opt-in).
• Let /worktree accept additional repo paths to also worktree.
• A settings key for "files to copy into each worktree" (.env*, *.local, etc.) with sensible defaults.

Environment

• Claude Code on macOS (darwin 24.6.0)
• Worktrees created via /worktree into .claude/worktrees/<name>

[ilanp-ob]

Directly addressing point 1 (sessions keyed by cwd, worktrees fragment history) — I built a userland fix and wanted to share it here in case it's useful to others, and to propose a minimal upstream change.

Plugin repo: https://github.com/ilanp-ob/claude-git-aware-history
Plugin PR: #58646

---

Root cause

Claude Code slugifies the raw CWD to compute the project history directory. git rev-parse --git-common-dir solves this cleanly: it returns the same .git path for any worktree of a repo, making the git root a stable, repo-scoped identity.

Userland fix (3 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.

#!/usr/bin/env bash
if [[ -f "$HOME/.claude/git-aware-history.enabled" ]]; then
  if git_common=$(git rev-parse --git-common-dir 2>/dev/null); then
    [[ "$git_common" != /* ]] && git_common="$PWD/$git_common"
    git_root="${git_common%/.git}"
    cwd_slug="${PWD//[\/.]/-}"
    root_slug="${git_root//[\/.]/-}"
    if [[ "$cwd_slug" != "$root_slug" ]]; then
      mkdir -p "$HOME/.claude/projects/$root_slug"
      ln -sfn "$HOME/.claude/projects/$root_slug" "$HOME/.claude/projects/$cwd_slug"
    fi
  fi
fi
exec /real/path/to/claude "$@"

Key detail: ln -sfn not ln -sf — -n prevents nesting a symlink inside an existing directory when the destination already exists as a real dir.

2. Consolidation script — retroactive migration

For history already accumulated: consolidate-git-history.sh (bash, ~430 lines, 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, fzf --multi or numbered fallback

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

3. /consolidate-history Claude Code 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. Available as a plugin (PR linked above).

---

Proposed upstream fix

Two parts:

A. New setting in settings.json

{
  "gitAwareHistory": true
}

Default true (strictly better for worktree users, no-op outside git repos). Users who prefer strict per-folder isolation can set it to false.

B. One function change in the project-path computation

import { execFile } from 'child_process';
import { promisify } from 'util';
import * as path from 'path';

const execFileAsync = promisify(execFile);

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); // parent of .git = repo root
  } catch {
    return cwd; // not a git repo or git unavailable — no behaviour change
  }
}

Called only when settings.gitAwareHistory !== false. Non-git users are completely unaffected. Uses execFile (fixed argument array, no shell injection risk).

Migration path for existing users: run the consolidation script once to merge pre-existing history.

---

The plugin PR above adds this to the official plugins directory. Happy to comment on the specific file that needs changing for the upstream fix if that helps.