[FEATURE] Per-worktree Python venv isolation

Open 💬 0 comments Opened Jun 26, 2026 by avalatea

Preflight Checklist

  • [x] I have searched existing requests and this feature hasn't been requested yet
  • [x] This is a single feature request (not multiple features)

Problem Statement

When running multiple Claude Code instances across git worktrees of the same repository, Python virtual environments bleed between worktrees. Worktrees share the same .venv directory from the main checkout, so packages installed or modified in one worktree affect all others. This makes it impossible to safely run parallel Claude Code sessions that involve Python dependency changes — one session can corrupt the environment another session is actively using.

Proposed Solution

Add a worktree.isolateDirectories setting (complementary to the existing worktree.symlinkDirectories) that causes Claude Code to create fresh copies of listed directories per worktree rather than sharing them.

{
  "worktree": {
    "isolateDirectories": [".venv", "jobs/.venv", "api/.venv"]
  }
}

Alternatively, Claude Code could detect .venv directories and isolate them by default when creating a worktree, since shared Python environments are almost never the desired behavior.

Alternative Solutions

The existing worktree.symlinkDirectories goes in the opposite direction — it symlinks directories to save disk space. That's correct for node_modules but wrong for Python venvs where isolation is the point.

Currently working around this by maintaining separate full clones of the repository in different directories instead of using worktrees. This works but loses all the benefits of worktrees (shared git history, no disk duplication of source files) and introduces its own problems — tools like ruff and IDEs see duplicate files when clones share a parent directory.

Priority

High - Significant impact on productivity

Feature Category

Configuration and settings

Use Case Example

  1. A Python monorepo has multiple services, each with its own .venv (e.g. interfaces/.venv, services/.venv)
  2. Developer creates two worktrees — one to work on a feature branch, one to run the current staging environment for E2E comparison
  3. Claude Code session in worktree A installs a new package into interfaces/.venv
  4. Claude Code session in worktree B now has a different environment than expected, silently breaking its E2E test run
  5. With isolated venvs per worktree, each session gets its own clean environment and parallel sessions can't interfere

Additional Context

_No response_

View original on GitHub ↗