Claude Code: Worktree-Aware Project Configs and Auto-Memory

The Worktree Isolation Problem

Git worktrees allow developers to check out multiple branches of the same repository into separate directories simultaneously, which is especially valuable for multi-agent workflows where each agent operates on its own branch. However, prior to v2.1.63, Claude Code treated each worktree as an entirely separate project. Each worktree had its own .claude/ directory with its own project configuration, auto-memory files, and session history. This meant that any customizations — model preferences, allowed tools, project-specific instructions, or accumulated memory — had to be manually duplicated into every new worktree.

For teams running parallel agents (for example, one agent per feature branch), this isolation was particularly painful. Each agent would start with a blank memory slate, losing all the project context that had been built up in the main worktree. Configuration drift between worktrees was also common, leading to inconsistent behavior across agents working on the same codebase.

Shared Configuration and Memory

v2.1.63 resolves this by detecting when a directory is a git worktree and resolving the configuration and memory paths back to the main repository's .claude/ directory. All worktrees derived from the same repository now share:

• Project configuration (.claude/settings.json): Model preferences, allowed/denied tools, custom slash commands, and hook definitions.
• Auto-memory (.claude/memory/): All auto-memory files that Claude Code accumulates during conversations, including codebase patterns, architecture notes, and user preferences.
• CLAUDE.md project instructions: The project-level instruction file is read from the shared location.

Session history remains worktree-specific by design, since each worktree typically represents a different line of work and mixing session histories would create confusion.

Impact on Multi-Agent Workflows

This change significantly improves the multi-agent development pattern where a lead agent spawns sub-agents in separate worktrees. Previously, each sub-agent had to re-discover project conventions, re-learn architectural patterns, and operate without the benefit of accumulated memory. Now, a sub-agent spun up in a fresh worktree immediately inherits all the project knowledge and configuration from the main worktree.

The shared memory layer also means that insights discovered by one agent — for example, a gotcha about a particular API or a preferred code pattern — are immediately available to all other agents working on the same repository. This creates a collaborative knowledge effect where the collective understanding of the project improves with every agent interaction, regardless of which worktree the interaction occurs in.