I've known for months that Git worktrees are essential for running AI coding agents like Claude Code and Codex in parallel. However, my early attempts to integrate them into my workflow failed multiple times.

The problem wasn't Git itself-creating a worktree and a new branch via the CLI or Magit is trivial. The real obstacle lies in the .gitignore'd parts of your project. Things like .env files containing environment variables, or your Python .venv directory, don't carry over to new directories. Naively creating a Git worktree results in an incomplete environment, causing agentic tools to fail when trying to run standard development commands like linting, compiling, or testing.

Setting up direnv

direnv is the perfect solution to this problem. If you aren't already using it to manage your environment variables, I highly recommend giving it a try. Because direnv allows us to execute arbitrary Bash in an .envrc file, we can dynamically load environment variables and activate virtual environments from the main worktree into any newly created worktree.

Here is how you can share the main repository's Python virtual environment across all worktrees:

  _main_venv="$(git worktree list --porcelain | awk 'NR==1{print $2}')/.venv"
  export VIRTUAL_ENV="$_main_venv"
  PATH_add "$_main_venv/bin"

Note: This correctly activates the virtual environment whether you are in the main worktree or a secondary one.

Similarly, here is how you can load shared secrets and configurations from the main worktree's .env file:

  _main_worktree="$(git worktree list --porcelain | awk 'NR==1{print $2}')"
  dotenv_if_exists "$_main_worktree/.env"
  dotenv_if_exists ".env"

With this .envrc setup, you can launch Claude Code using claude -w to spin up a new worktree. The agent will now have full access to your tools, dependencies, and environment variables, seamlessly interacting with the new directory as if it were the main repository.

Merging a worktree into Main

Merging worktree changes back into the main branch usually just requires a simple commit and merge. However, if you have multiple agents running in parallel worktrees, conflicts are inevitable.

This is a great opportunity to delegate conflict resolution to the agent itself. In my experience, if you simply ask the agent to "commit and merge to the master branch," it occasionally stumbles (e.g., trying to check out the master branch from inside the secondary worktree), though it usually figures it out eventually. To make this smoother, it's highly worthwhile to write a custom agent "skill" or tool specifically designed to handle this worktree-to-main merge workflow.

Differences between Claude Code and Codex

Claude Code handles worktrees elegantly. Running claude -w automatically creates a new worktree and branch. Once the task is complete and merged, exiting the session automatically cleans up the worktree and deletes the branch. This ephemeral approach is incredibly helpful because the next time you run claude -w, you start fresh from the latest HEAD.

The Codex CLI, on the other hand, currently lacks native worktree generation from the command line (though the desktop app supports it). Using worktrees with the Codex CLI requires manual management. While it's easy enough to manually spin up multiple worktrees, keeping those branches synced with HEAD after merges becomes tedious. Hopefully, OpenAI will add native CLI worktree support soon.

Conclusion

Git worktrees are a game-changer for parallelizing AI coding agents. By pairing them with direnv, you can effortlessly bridge the gap with ignored files and unlock the true potential of parallel agentic programming. I hope this setup streamlines your workflow as much as it has mine.