<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:media="http://search.yahoo.com/mrss/">
  <channel>
    <title>Parallel Development · Jared Lynskey</title>
    <link>https://jared.lynskey.co.nz/en/tags/parallel-development/</link>
    <description>Short stories of value on software engineering and engineering leadership — performance reviews, hiring and scaling teams, CI/CD, DevOps monitoring and agentic AI. Written from Seoul.</description>
    <generator>Hugo</generator>
    <language>en</language>
    <copyright>© 2026 Jared Lynskey</copyright>
    <lastBuildDate>Thu, 19 Nov 2026 00:00:00 +1300</lastBuildDate>
    <atom:link href="https://jared.lynskey.co.nz/en/tags/parallel-development/index.xml" rel="self" type="application/rss+xml" />
    <item>
      <title>Claude Code Worktrees: Running Parallel Agents Without Collisions</title>
      <link>https://jared.lynskey.co.nz/en/posts/2026/claude-code-git-worktrees/</link>
      <guid isPermaLink="true">https://jared.lynskey.co.nz/en/posts/2026/claude-code-git-worktrees/</guid>
      <pubDate>Thu, 19 Nov 2026 00:00:00 +1300</pubDate>
      <dc:creator>Jared Lynskey</dc:creator>
      <category>Claude Code</category>
      <category>AI Agents</category>
      <category>Git</category>
      <category>Git Worktree</category>
      <category>tmux</category>
      <category>Developer Tools</category>
      <category>Parallel Development</category>
      <description>How to use Claude Code worktrees: claude -w, .worktreeinclude for .env, node_modules, base ref and cleanup, and running parallel agents in tmux.</description>
      <content:encoded><![CDATA[<p>To run Claude Code in a git worktree, start it with <code>claude -w &lt;name&gt;</code> (the long form is <code>--worktree</code>). Claude Code creates <code>.claude/worktrees/&lt;name&gt;/</code> at the root of your repository, on a new branch called <code>worktree-&lt;name&gt;</code> cut from your default branch on the remote, and from then on the session can only edit files inside that folder. Run the same command with a different name in a second terminal and you have two agents that can&rsquo;t touch each other&rsquo;s files. The catch is that a worktree is a fresh checkout. Your <code>.env</code>, your <code>node_modules</code> and anything else git ignores aren&rsquo;t there until you copy or install them, and nearly every worktree problem I&rsquo;ve had came from exactly that.</p>
<p>I run a lot of agents in parallel, and I came to worktrees the hard way. This post covers how <code>claude -w</code> behaves (I tested it on version 2.1.328), what <code>.worktreeinclude</code> is for, what to do about <code>node_modules</code>, how I lay the sessions out in tmux, and when I still reach for plain <code>git worktree add</code>.</p>
<figure><div class="film-pair">
  <div class="mc-film film-dark">
  <video
    class="my-0 rounded-md"
    controls playsinline preload="none"
    poster="https://jared.lynskey.co.nz/en/posts/2026/claude-code-git-worktrees/worktrees-film-poster.jpg" style="background:url('data:image/webp;base64,UklGRoQAAABXRUJQVlA4IHgAAABwBQCdASogABIAPw1wq0omIyGYDAQAYxDE9IBn0BuOmrQv+whr1JowkP2GvdEWiylHGHsAAP7r1B494gmKZxYarGSLJSBCQLucUwJnafSMMs2DcN8Xi7b7w/dBQJDESVxNVTjZ96FIOv3VtbbF3xp3++/ULAEhgAA=') center/cover no-repeat"
    width="1280"
    height="720"
    aria-label="A short narrated film of this post">
    <source src="https://jared.lynskey.co.nz/en/posts/2026/claude-code-git-worktrees/worktrees-film.webm" type="video/webm">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/claude-code-git-worktrees/worktrees-film_en.vtt" srclang="en" label="English">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/claude-code-git-worktrees/worktrees-film_ja.vtt" srclang="ja" label="日本語">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/claude-code-git-worktrees/worktrees-film_ko.vtt" srclang="ko" label="한국어">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/claude-code-git-worktrees/worktrees-film_vi.vtt" srclang="vi" label="Tiếng Việt">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/claude-code-git-worktrees/worktrees-film_zh-cn.vtt" srclang="zh-cn" label="简体中文">
  </video>
  </div>
  <div class="mc-film film-light">
  <video
    class="my-0 rounded-md"
    controls playsinline preload="none"
    poster="https://jared.lynskey.co.nz/en/posts/2026/claude-code-git-worktrees/worktrees-film-light-poster.jpg" style="background:url('data:image/webp;base64,UklGRoIAAABXRUJQVlA4IHYAAADQBACdASogABIAPw1uqUemIyIYBABjEMT0gAc4DbW6V3D/YCrZgv8AsVgfEQtYAAD+77ncv/xfKWHnvcUR0S+hsPg7hFdUPAZo9hZKq5p8p/3q6SK+cmbz04KNDvyW45u0Ws/43dQYB5jO2XsnWh2nnV30wAAA') center/cover no-repeat"
    width="1280"
    height="720"
    aria-label="A short narrated film of this post">
    <source src="https://jared.lynskey.co.nz/en/posts/2026/claude-code-git-worktrees/worktrees-film-light.webm" type="video/webm">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/claude-code-git-worktrees/worktrees-film_en.vtt" srclang="en" label="English">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/claude-code-git-worktrees/worktrees-film_ja.vtt" srclang="ja" label="日本語">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/claude-code-git-worktrees/worktrees-film_ko.vtt" srclang="ko" label="한국어">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/claude-code-git-worktrees/worktrees-film_vi.vtt" srclang="vi" label="Tiếng Việt">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/claude-code-git-worktrees/worktrees-film_zh-cn.vtt" srclang="zh-cn" label="简体中文">
  </video>
  </div>
  <script>(function(){if(window.mcFilm)return window.mcFilm();var a={play:'<path d="M8 5.6v12.8a1 1 0 0 0 1.52.85l10.2-6.4a1 1 0 0 0 0-1.7L9.52 4.75A1 1 0 0 0 8 5.6z"/>',pause:'<rect x="6.5" y="5" width="4" height="14" rx="1.2"/><rect x="13.5" y="5" width="4" height="14" rx="1.2"/>',volume:'<path d="M4 9.5v5a1 1 0 0 0 1 1h3l4.4 3.6a.6.6 0 0 0 1-.47V5.37a.6.6 0 0 0-1-.47L8 8.5H5a1 1 0 0 0-1 1z"/><path d="M16.5 8.5a5 5 0 0 1 0 7M19 6a8.5 8.5 0 0 1 0 12" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round"/>',muted:'<path d="M4 9.5v5a1 1 0 0 0 1 1h3l4.4 3.6a.6.6 0 0 0 1-.47V5.37a.6.6 0 0 0-1-.47L8 8.5H5a1 1 0 0 0-1 1z"/><path d="M16.5 9.5l5 5m0-5l-5 5" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round"/>',cc:'<rect x="3" y="5.5" width="18" height="13" rx="3" fill="none" stroke="currentColor" stroke-width="1.8"/><path d="M10.5 10.3a2.2 2.2 0 1 0 0 3.4M17 10.3a2.2 2.2 0 1 0 0 3.4" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/>',full:'<path d="M4.5 9V5.5a1 1 0 0 1 1-1H9M15 4.5h3.5a1 1 0 0 1 1 1V9M19.5 15v3.5a1 1 0 0 1-1 1H15M9 19.5H5.5a1 1 0 0 1-1-1V15" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round"/>',exit:'<path d="M9 4.5V8a1 1 0 0 1-1 1H4.5M19.5 9H16a1 1 0 0 1-1-1V4.5M15 19.5V16a1 1 0 0 1 1-1h3.5M4.5 15H8a1 1 0 0 1 1 1v3.5" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round"/>'},s={en:["Play","Pause","Mute","Unmute","Subtitles","Off","Full screen","Exit full screen","Seek"],ko:["재생","일시정지","음소거","음소거 해제","자막","끄기","전체 화면","전체 화면 종료","탐색"],ja:["再生","一時停止","ミュート","ミュート解除","字幕","オフ","全画面","全画面を終了","シーク"],zh:["播放","暂停","静音","取消静音","字幕","关闭","全屏","退出全屏","进度"],vi:["Phát","Tạm dừng","Tắt tiếng","Bật tiếng","Phụ đề","Tắt","Toàn màn hình","Thoát toàn màn hình","Tua"]},r=(document.documentElement.lang||"en").toLowerCase().slice(0,2),e=s[r]||s.en,t=function(e){return'<svg viewBox="0 0 24 24" aria-hidden="true" focusable="false">'+a[e]+"</svg>"},o={},i=function(e,t){if(o[e]||typeof window.gtag!="function")return;o[e]=!0;var n=(t.currentSrc||(t.querySelector("source")||{}).src||"").split("/").pop();window.gtag("event",e,{film:n.replace(/-light(?=\.)/,"")})},n=function(e){(!isFinite(e)||e<0)&&(e=0),e=Math.floor(e);var t=Math.floor(e/3600),n=Math.floor(e%3600/60),s=String(e%60).padStart(2,"0");return t?t+":"+String(n).padStart(2,"0")+":"+s:n+":"+s};function c(s){var a,r,c,d,u,m,p,g,v,b,j,_,w,O,C,E,k,A,o=s.querySelector("video");if(!o)return;s.classList.add("is-ready"),o.controls=!1,o.removeAttribute("controls"),s.insertAdjacentHTML("beforeend",'<button type="button" class="mc-film__big" aria-label="'+e[0]+'">'+t("play")+'</button><div class="mc-film__bar"><button type="button" class="mc-film__btn" data-act="play" aria-label="'+e[0]+'">'+t("play")+'</button><span class="mc-film__time"><span data-cur>0:00</span><span class="mc-film__of"> / </span><span data-dur>0:00</span></span><input class="mc-film__seek" type="range" min="0" max="1000" step="1" value="0" aria-label="'+e[8]+'"><span class="mc-film__cc"><button type="button" class="mc-film__btn" data-act="cc" aria-label="'+e[4]+'" aria-haspopup="true" aria-expanded="false">'+t("cc")+'</button><span class="mc-film__menu" role="menu" hidden></span></span><button type="button" class="mc-film__btn" data-act="mute" aria-label="'+e[2]+'">'+t("volume")+'</button><button type="button" class="mc-film__btn" data-act="full" aria-label="'+e[6]+'">'+t("full")+"</button></div>"),A=s.querySelector(".mc-film__big"),a=s.querySelector(".mc-film__bar"),j=a.querySelector('[data-act="play"]'),p=a.querySelector('[data-act="mute"]'),u=a.querySelector('[data-act="full"]'),d=a.querySelector('[data-act="cc"]'),r=a.querySelector(".mc-film__menu"),c=a.querySelector(".mc-film__seek"),w=a.querySelector("[data-cur]"),O=a.querySelector("[data-dur]"),g=!1,v=0,b=function(){return Array.prototype.filter.call(o.textTracks,function(e){return e.kind==="subtitles"||e.kind==="captions"})},b().length||(d.parentNode.hidden=!0),_=null;function f(e){var n,i,t=!s.classList.contains("is-idle")&&s.classList.contains("is-started");if(e!==!0&&t===_)return;_=t,n=o.clientHeight,i=n?Math.max(40,100-(a.offsetHeight+22)/n*100):85,b().forEach(function(e){if(e.mode!=="showing"||!e.cues)return;for(var n,s=0;s<e.cues.length;s++)n=e.cues[s],t?(n.snapToLines=!1,n.line=i,n.lineAlign="end"):(n.snapToLines=!0,n.line="auto",n.lineAlign="start")})}m=function(){f(!0)},window.addEventListener("resize",m),Array.prototype.forEach.call(o.querySelectorAll("track"),function(e){e.addEventListener("load",m)});function y(){o.paused||o.ended?o.play().catch(function(){}):o.pause()}function l(){s.classList.remove("is-idle"),f(),clearTimeout(v),v=setTimeout(function(){!o.paused&&r.hidden&&!a.querySelector(":focus-visible")&&(s.classList.add("is-idle"),f())},2600)}function M(){clearTimeout(v),h(),s.classList.add("is-idle"),f()}function h(){r.hidden=!0,d.setAttribute("aria-expanded","false")}function F(){var t=b(),n=t.filter(function(e){return e.mode==="showing"})[0];r.innerHTML="",[null].concat(t).forEach(function(s){var o=document.createElement("button");o.type="button",o.setAttribute("role","menuitemradio"),o.setAttribute("aria-checked",String(s?s===n:!n)),o.textContent=s?s.label||s.language:e[5],o.addEventListener("click",function(){t.forEach(function(e){e.mode=e===s?"showing":"disabled"}),h(),setTimeout(m,0),l()}),r.appendChild(o)}),r.hidden=!1,d.setAttribute("aria-expanded","true")}function x(){var n=!o.paused&&!o.ended;s.classList.toggle("is-playing",n),j.innerHTML=t(n?"pause":"play"),j.setAttribute("aria-label",n?e[1]:e[0]),n||l()}function S(){if(w.textContent=n(o.currentTime),!g&&o.duration){var e=o.currentTime/o.duration*1e3;c.value=e,c.style.setProperty("--p",e/10+"%")}}A.addEventListener("click",function(){o.play().catch(function(){})}),C="mouse",s.addEventListener("pointerdown",function(e){C=e.pointerType}),o.addEventListener("click",function(){if(!s.classList.contains("is-started"))return o.play().catch(function(){});if(C==="mouse")return y();s.classList.contains("is-idle")?l():M()}),j.addEventListener("click",y),o.addEventListener("play",function(){s.classList.contains("is-started")||i("film_play",o),s.classList.add("is-started"),x(),l()}),"IntersectionObserver"in window&&(E=new IntersectionObserver(function(e){if(!e.some(function(e){return e.isIntersecting}))return;E.disconnect(),i("film_view",o)},{threshold:.5}),E.observe(s)),o.addEventListener("pause",x),o.addEventListener("ended",x),o.addEventListener("timeupdate",S),o.addEventListener("durationchange",function(){O.textContent=n(o.duration),S()}),o.addEventListener("loadedmetadata",function(){O.textContent=n(o.duration)}),o.addEventListener("volumechange",function(){p.innerHTML=t(o.muted?"muted":"volume"),p.setAttribute("aria-label",o.muted?e[3]:e[2])}),p.addEventListener("click",function(){o.muted=!o.muted}),c.addEventListener("input",function(){g=!0,c.style.setProperty("--p",c.value/10+"%"),o.duration&&(o.currentTime=c.value/1e3*o.duration,w.textContent=n(o.currentTime))}),c.addEventListener("change",function(){g=!1}),d.addEventListener("click",function(e){e.stopPropagation(),r.hidden?F():h()}),document.addEventListener("click",function(e){!r.hidden&&!r.contains(e.target)&&h()}),u.addEventListener("click",function(){document.fullscreenElement||document.webkitFullscreenElement?(document.exitFullscreen||document.webkitExitFullscreen).call(document):s.requestFullscreen?s.requestFullscreen().catch(function(){}):s.webkitRequestFullscreen?s.webkitRequestFullscreen():o.webkitEnterFullscreen&&o.webkitEnterFullscreen()}),k=function(){var n=(document.fullscreenElement||document.webkitFullscreenElement)===s;s.classList.toggle("is-fullscreen",n),u.innerHTML=t(n?"exit":"full"),u.setAttribute("aria-label",n?e[7]:e[6])},document.addEventListener("fullscreenchange",k),document.addEventListener("webkitfullscreenchange",k),s.addEventListener("pointermove",function(e){e.pointerType==="mouse"&&l()}),s.addEventListener("focusin",l),s.addEventListener("keydown",function(e){if(e.target===c&&/^Arrow/.test(e.key))return;var t=e.key.toLowerCase();if(t==="k"||t===" "&&e.target===o)y();else if(t==="arrowleft")o.currentTime=Math.max(0,o.currentTime-5);else if(t==="arrowright")o.currentTime=Math.min(o.duration||0,o.currentTime+5);else if(t==="m")o.muted=!o.muted;else if(t==="f")u.click();else if(t==="escape"&&!r.hidden)h();else return;e.preventDefault(),l()}),o.tabIndex=0}window.mcFilm=function(){document.querySelectorAll(".mc-film:not(.is-ready)").forEach(c)},window.mcFilm()})()</script></div>
  <script>
  new MutationObserver(() => {
    const dark = document.documentElement.classList.contains("dark");
    document.querySelectorAll(".film-pair").forEach((pair) => {
      const from = pair.querySelector(dark ? ".film-light video" : ".film-dark video");
      const to = pair.querySelector(dark ? ".film-dark video" : ".film-light video");
      if (!from || !to || !from.currentTime) return;
      const playing = !from.paused;
      from.pause();
      to.currentTime = from.currentTime;
      [...from.textTracks].forEach((track, i) => { if (to.textTracks[i]) to.textTracks[i].mode = track.mode; });
      if (playing) to.play().catch(() => {});
    });
  }).observe(document.documentElement, { attributes: true, attributeFilter: ["class"] });
  </script><figcaption>This post as an eight-minute film, if you&rsquo;d rather watch than read. Some footage from Coverr.</figcaption>
</figure>


<h2 class="relative group">Why one checkout doesn&rsquo;t work for parallel agents
    <div id="why-one-checkout-doesnt-work-for-parallel-agents" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#why-one-checkout-doesnt-work-for-parallel-agents" aria-label="Anchor">#</a>
    </span>
    
</h2>
<p>One day in September I had five Claude Code sessions working in the same checkout of my marketplace app, and two things went wrong. A one-line fix to a test config file survived four failed builds and was gone by the time it was ready to commit: <code>git commit</code> said the working tree was clean, and the file held another session&rsquo;s version. Git keeps no record of a lost update like that. No reflog entry, no stash, just an ordinary modification time. The same day, a deploy script that builds from the working tree came close to shipping a different session&rsquo;s unfinished work to production.</p>
<p>In October a third one turned up. A session committed its own files beside another session&rsquo;s unstaged work, and the pre-commit hook stashed <em>everything</em> unstaged for the length of the hook. The other session&rsquo;s edits vanished from disk while the hook ran, the type checker then failed on its new files, and the commit aborted. Every session commits under my name, too, so <code>git log</code> can&rsquo;t tell you which one did what.</p>
<p>That&rsquo;s the case for worktrees in one line: a working tree with several writers is a race, and the loser can&rsquo;t see it happen. Give each agent its own working tree and the race goes away.</p>
<figure class="diagram">
  <div role="img" aria-label="Diagram: one shared .git directory holding commits, branches, config and a small private folder per worktree, connected to three working directories: the main checkout on main with .env and node_modules, a git worktree add checkout on fix-login with neither, and a claude -w checkout on worktree-add-search with .env copied by .worktreeinclude, locked while the session runs"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 700 906" aria-hidden="true" focusable="false">
<path class="d-group" d="M30,267 V735 M30,435.5 H62 M30,578.5 H62 M30,735 H62"></path>
<text class="d-title d-mono" x="2" y="30" font-size="28">.git</text>
<text class="d-sub" x="2" y="57" font-size="18">shared by every worktree</text>
<rect class="d-panel" x="2" y="75" width="696" height="192" rx="22"></rect>
<rect class="d-head" x="25" y="105" width="8" height="8" rx="2"></rect>
<text class="d-label" x="46" y="115.8" font-size="19">commits and objects</text>
<rect class="d-head" x="25" y="137" width="8" height="8" rx="2"></rect>
<text class="d-label" x="46" y="147.8" font-size="19">branches and tags (refs/)</text>
<rect class="d-head" x="25" y="169" width="8" height="8" rx="2"></rect>
<text class="d-label" x="46" y="179.8" font-size="19">config, remotes, hooks</text>
<rect class="d-head" x="25" y="201" width="8" height="8" rx="2"></rect>
<text class="d-label" x="46" y="211.8" font-size="19">worktrees/: a small private folder per linked worktree, holding its</text>
<text class="d-label" x="46" y="239.8" font-size="19">own HEAD and index</text>
<text class="d-title" x="62" y="327" font-size="26">Three working directories</text>
<text class="d-sub" x="62" y="354" font-size="18">each with its own files, HEAD and index</text>
<rect class="d-box" x="62" y="372" width="636" height="127" rx="14"></rect>
<text class="d-label d-mono" x="82" y="409.2" font-size="20">~/code/myapp</text>
<rect class="d-panel" x="82" y="424" width="60.1" height="28" rx="14"></rect>
<text class="d-label d-mono" x="94" y="443.4" font-size="15">main</text>
<text class="d-sub" x="154.1" y="444.1" font-size="17">main checkout</text>
<path class="d-badge" style="fill:none;stroke-width:2.6" d="M83,474 l4.5,4.5 l9.5,-10"></path>
<text class="d-label" x="107" y="479.6" font-size="17">.env</text>
<path class="d-badge" style="fill:none;stroke-width:2.6" d="M168.4,474 l4.5,4.5 l9.5,-10"></path>
<text class="d-label" x="192.4" y="479.6" font-size="17">node_modules 45 MB</text>
<rect class="d-box" x="62" y="515" width="636" height="127" rx="14"></rect>
<text class="d-label d-mono" x="82" y="552.2" font-size="20">~/code/myapp-fix-login</text>
<rect class="d-panel" x="82" y="567" width="105.3" height="28" rx="14"></rect>
<text class="d-label d-mono" x="94" y="586.4" font-size="15">fix-login</text>
<text class="d-sub" x="199.3" y="587.1" font-size="17">made with git worktree add</text>
<path class="d-line" style="fill:none;stroke-width:2.2" d="M85,611.5 l10,10 M95,611.5 l-10,10"></path>
<text class="d-sub" x="107" y="622.6" font-size="17">no .env</text>
<path class="d-line" style="fill:none;stroke-width:2.2" d="M193.4,611.5 l10,10 M203.4,611.5 l-10,10"></path>
<text class="d-sub" x="215.4" y="622.6" font-size="17">no node_modules (84 KB until npm install)</text>
<rect class="d-box" x="62" y="658" width="636" height="154" rx="14"></rect>
<text class="d-label d-mono" x="82" y="695.2" font-size="20">~/code/myapp/.claude/worktrees/add-search</text>
<rect class="d-panel" x="82" y="710" width="195.6" height="28" rx="14"></rect>
<text class="d-label d-mono" x="94" y="729.4" font-size="15">worktree-add-search</text>
<text class="d-sub" x="289.6" y="730.1" font-size="17">made with claude -w add-search</text>
<path class="d-badge" style="fill:none;stroke-width:2.6" d="M83,760 l4.5,4.5 l9.5,-10"></path>
<text class="d-label" x="107" y="765.6" font-size="17">.env, copied by .worktreeinclude</text>
<path class="d-line" style="fill:none;stroke-width:2.2" d="M395.7,754.5 l10,10 M405.7,754.5 l-10,10"></path>
<text class="d-sub" x="417.7" y="765.6" font-size="17">no node_modules</text>
<rect class="d-line" style="fill:none;stroke-width:2" x="84" y="785.5" width="12" height="9" rx="2"></rect>
<path class="d-line" style="fill:none;stroke-width:2" d="M86.5,785.5 v-2.5 a3.5,3.5 0 0 1 7,0 v2.5"></path>
<text class="d-sub" x="107" y="792.6" font-size="17">locked while the session runs</text>
<text class="d-sub" x="2" y="850" font-size="16">Claude Code also shares two things across a repository's worktrees: “don't ask again”</text>
<text class="d-sub" x="2" y="874" font-size="16">approvals (saved in the main checkout's .claude/settings.local.json) and project-scope</text>
<text class="d-sub" x="2" y="898" font-size="16">plugins.</text>
</svg>
</div><figcaption>One repository, three working directories. History is stored once; files, HEAD and index are per worktree.</figcaption>
</figure>


<h2 class="relative group">How claude -w works
    <div id="how-claude--w-works" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#how-claude--w-works" aria-label="Anchor">#</a>
    </span>
    
</h2>
<figure><video
    class="my-0 rounded-md"
    autoplay loop muted playsinline preload="metadata"
    poster="https://jared.lynskey.co.nz/en/posts/2026/claude-code-git-worktrees/claude-worktree.jpg" style="background:url('data:image/webp;base64,UklGRkoAAABXRUJQVlA4ID4AAACQAwCdASogABIAPw16sU+mI6IhKAgAxiGJ6QDC+BPdNCPmtcKAAP7ozOlPLz658ebe527EEQOHuoyZaAAAAA==') center/cover no-repeat"
    width="1280"
    height="720"
    aria-label="Terminal: cat .worktreeinclude shows .env; claude -w add-search answers that it is on worktree-add-search; git worktree list shows the new worktree as locked; ls shows .env copied but no node_modules; git worktree remove refuses because the worktree is locked by a claude session whose process has exited; unlock and remove succeed">
    <source src="https://jared.lynskey.co.nz/en/posts/2026/claude-code-git-worktrees/claude-worktree.mp4" type="video/mp4">
  </video><figcaption>A real run in a throwaway repo. Note the lock that&rsquo;s still there after the session ended.</figcaption>
</figure>

<p>What <a href="https://code.claude.com/docs/en/worktrees"  target="_blank" rel="noreferrer">the worktrees page in the docs</a> says, and what I saw when I tried it:</p>
<ul>
<li><strong>Where and which branch.</strong> <code>claude -w add-search</code> creates <code>.claude/worktrees/add-search/</code> on a new branch <code>worktree-add-search</code>. Leave the name out and you get a generated one like <code>bright-running-fox</code>. Add <code>.claude/worktrees/</code> to your <code>.gitignore</code>, or the main checkout shows it all as untracked.</li>
<li><strong>What it branches from.</strong> By default, <code>worktree.baseRef</code> is <code>&quot;fresh&quot;</code>: the remote&rsquo;s default branch, usually <code>origin/main</code>. Claude Code fetches it if the repository hasn&rsquo;t been fetched in the last 24 hours, capped at five seconds. Set it to <code>&quot;head&quot;</code> and new worktrees start from your current local <code>HEAD</code>, unpushed commits and all. You can&rsquo;t set it to a branch name; for a specific branch, use <code>git worktree add</code> yourself.</li>
<li><strong>Pull requests.</strong> <code>claude --worktree &quot;#1234&quot;</code> fetches that PR&rsquo;s head and creates <code>.claude/worktrees/pr-1234</code>. Quote it, or your shell treats <code>#</code> as a comment.</li>
<li><strong>Trust.</strong> The first time, an interactive <code>claude -w</code> in a folder you&rsquo;ve never opened Claude in fails with &ldquo;Workspace trust not yet accepted&rdquo;. Run plain <code>claude</code> there once and accept the dialog. <code>claude -p -w</code> skips the check.</li>
<li><strong>The fence.</strong> While a session is in a worktree, Claude Code refuses edits to files in the main checkout, commands whose working directory is the main checkout, and git pointed back at it through <code>git -C</code>, <code>--git-dir</code> or <code>GIT_DIR</code>. The docs say plainly what it doesn&rsquo;t catch: a <code>cp</code> or a shell redirect that writes into the main checkout isn&rsquo;t refused by these checks.</li>
</ul>
<p>What a worktree shares with the main checkout matters as much as what it doesn&rsquo;t. Every worktree writes to the same <code>.git</code>, so commits and branches made in one are visible from all of them. Project-scope plugins load everywhere. And a &ldquo;Yes, and don&rsquo;t ask again&rdquo; answered inside a worktree is saved to the <em>main</em> checkout&rsquo;s <code>.claude/settings.local.json</code>, so the approval applies to every worktree and outlives the one it was given in. That&rsquo;s convenient, and also one more reason to keep secrets out of the commands you approve.</p>

<h2 class="relative group">Cleaning up, and the lock that stays behind
    <div id="cleaning-up-and-the-lock-that-stays-behind" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#cleaning-up-and-the-lock-that-stays-behind" aria-label="Anchor">#</a>
    </span>
    
</h2>
<p>When you exit an interactive worktree session, Claude Code checks for anything removal would lose. An unnamed session with a clean worktree is removed automatically, branch and all. A named one asks first. If there&rsquo;s work in it, you&rsquo;re asked whether to keep it, and you can come back later with the <code>claude --worktree &lt;name&gt; --resume</code> command it prints.</p>
<p>Non-interactive runs are different, and it&rsquo;s the one thing that caught me out when I tested this. <code>claude -p</code> has no exit prompt, so it doesn&rsquo;t clean up. Claude Code also holds a <code>git worktree lock</code> on the worktree while the session runs, and after a <code>-p</code> run that lock is still there with a process ID that no longer exists. You can see it in the recording above: <code>git worktree remove</code> refuses with &ldquo;cannot remove a locked working tree, lock reason: claude session add-search&rdquo;. The docs describe exactly this: a later session&rsquo;s stale-lock sweep releases it, or you run <code>git worktree unlock</code> first. It&rsquo;s harmless once you know, and slightly alarming the first time.</p>

<h2 class="relative group">.worktreeinclude: the files a fresh checkout doesn&rsquo;t have
    <div id="worktreeinclude-the-files-a-fresh-checkout-doesnt-have" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#worktreeinclude-the-files-a-fresh-checkout-doesnt-have" aria-label="Anchor">#</a>
    </span>
    
</h2>
<p>A worktree contains tracked files and nothing else. To bring gitignored files along, put a <code>.worktreeinclude</code> in the root of the repository. It uses <code>.gitignore</code> syntax, and Claude Code copies a file only if it matches a pattern <em>and</em> is gitignored, so tracked files are never duplicated:</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl"># .worktreeinclude
</span></span><span class="line"><span class="cl">.env
</span></span><span class="line"><span class="cl">.env.local
</span></span><span class="line"><span class="cl">config/secrets.json</span></span></code></pre></div></div>
<p>It applies to every worktree Claude Code creates with git: <code>claude -w</code>, subagent worktrees and the desktop app&rsquo;s parallel sessions. It doesn&rsquo;t apply to worktrees you make with <code>git worktree add</code>, and it&rsquo;s skipped entirely if you replace worktree creation with a <code>WorktreeCreate</code> hook.</p>
<p>I&rsquo;d put more than <code>.env</code> in it, because the gitignored files you forget are rarely the ones that fail loudly. My app&rsquo;s deploy script was changed to build from a clean worktree, so that other sessions&rsquo; uncommitted edits could never ship. The clean tree didn&rsquo;t have the gitignored signing certificates that one feature needs, the image built anyway, and that feature failed in production for 13 days, until the script was changed to copy the certificates in and warn when one is missing. On another deploy from a worktree, a gitignored theme folder was missing, and the build failed only <em>after</em> a two-minute export had already dirtied the tree. Before you trust a worktree with anything that ships, run <code>git status --short --ignored</code> in your main checkout and ask which of those files the build reads.</p>

<h2 class="relative group">node_modules: the expensive part
    <div id="node_modules-the-expensive-part" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#node_modules-the-expensive-part" aria-label="Anchor">#</a>
    </span>
    
</h2>
<p><code>.worktreeinclude</code> is for small files. It won&rsquo;t help with <code>node_modules</code>, and nothing in Claude Code shares it between worktrees, so every worktree that needs to run your code needs its own.</p>
<figure><video
    class="my-0 rounded-md"
    autoplay loop muted playsinline preload="metadata"
    poster="https://jared.lynskey.co.nz/en/posts/2026/claude-code-git-worktrees/worktree-basics.jpg" style="background:url('data:image/webp;base64,UklGRkgAAABXRUJQVlA4IDwAAADQAwCdASogABIAPw18sk+mI6IhKAgAxiGJ6QC/OBPdOMkqQtYu1AAA/ujR5WBjJmvERft5/vglvvCMAAA=') center/cover no-repeat"
    width="1280"
    height="720"
    aria-label="Terminal: git worktree add creates myapp-fix-login on a new branch and myapp-hotfix detached at origin/main; git worktree list shows all three; the new worktree has no .env and no node_modules; du shows 45M for the main checkout and 84K for the worktree, then 45M for both after npm install">
    <source src="https://jared.lynskey.co.nz/en/posts/2026/claude-code-git-worktrees/worktree-basics.mp4" type="video/mp4">
  </video><figcaption>Plain git worktrees in a demo repo: 84 KB until you install, then the full 45 MB again.</figcaption>
</figure>

<p>On a real project the numbers get serious. My mobile app&rsquo;s repository has 19 worktrees beside the main checkout. I measured 12 of them: they range from 194 MB to 12 GB, and the four biggest were the four with their own <code>node_modules</code>. With my laptop&rsquo;s disk at 96% this week, they&rsquo;re the obvious place to start cleaning.</p>
<p>The options, from simplest to cleverest:</p>
<ol>
<li><strong>Install per worktree.</strong> Ask the agent to run <code>npm install</code> first thing, or do it yourself. Slow, costs disk, never surprises you.</li>
<li><strong>Clone from a checkout with the same lockfile.</strong> On macOS, <code>cp -c -R ../myapp/node_modules .</code> uses APFS clones, which share data blocks until one side changes. Cloning the 45 MB demo took 0.8 seconds. I&rsquo;ve used this for real deploys from worktrees. Only clone when the lockfiles match, and be careful with native build folders: my main checkout&rsquo;s iOS Pods were built for an older SDK than the worktree&rsquo;s branch, so those had to be installed fresh.</li>
<li><strong>Use pnpm.</strong> Its packages live in one store, and on macOS pnpm <a href="https://pnpm.io/settings/node-modules#packageimportmethod"  target="_blank" rel="noreferrer">clones from the store before trying hard links</a> (on Linux and Windows it hard-links first). A second worktree&rsquo;s install of the demo took about five seconds.</li>
<li><strong>Install in a <code>WorktreeCreate</code> hook.</strong> The hook replaces Claude Code&rsquo;s default git logic, so it could run <code>git worktree add</code> and then the install. I haven&rsquo;t tried this one. If you do, remember <code>.worktreeinclude</code> stops being processed and the hook has to copy your <code>.env</code> too.</li>
</ol>

<h2 class="relative group">Parallel agents in tmux
    <div id="parallel-agents-in-tmux" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#parallel-agents-in-tmux" aria-label="Anchor">#</a>
    </span>
    
</h2>
<p>I already live in tmux (the <a href="https://jared.lynskey.co.nz/en/posts/2026/2026-10-22-claude-code-day-to-day/" >day-to-day post</a> has the layout), so worktrees slot straight in: one window, or one pane, per worktree. Here are three agents started at the same moment, each told to change the same file:</p>
<figure><video
    class="my-0 rounded-md"
    autoplay loop muted playsinline preload="metadata"
    poster="https://jared.lynskey.co.nz/en/posts/2026/claude-code-git-worktrees/parallel-agents-tmux.jpg" style="background:url('data:image/webp;base64,UklGRlQAAABXRUJQVlA4IEgAAACQBACdASogABIAPw10rE0mIyIhKAqoxiGJ6QDImBPdLsmKk7T7Naw9bcwBsAAA/ui+5wOzf0YXxkY1UgYA04COTxtokeJAAAA=') center/cover no-repeat"
    width="1280"
    height="720"
    aria-label="tmux with three panes: claude -w add-bye, add-greet and add-tests run at the same time; the pane titles switch to the worktree names while they run; two report a modified src/index.js and one a new test folder; the top pane then shows the main checkout clean and three locked worktrees">
    <source src="https://jared.lynskey.co.nz/en/posts/2026/claude-code-git-worktrees/parallel-agents-tmux.mp4" type="video/mp4">
  </video><figcaption>Three agents, one file, no collisions. The main checkout ends up clean, and each change waits in its own branch.</figcaption>
</figure>

<p>Two of them edited <code>src/index.js</code> at the same time and neither noticed the other, because each one&rsquo;s <code>src/index.js</code> was a different file on disk. The main checkout stayed clean. What you get at the end is three branches to review and merge, which is the work worktrees can&rsquo;t do for you: if two agents change the same lines, you still get a merge conflict. It just arrives in a merge, where you can see it, instead of as a silent overwrite.</p>
<p>In VS Code, a worktree is just a folder: <code>code .claude/worktrees/add-search</code> opens it in its own window, on its own branch.</p>

<h2 class="relative group">A worktree is a snapshot
    <div id="a-worktree-is-a-snapshot" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#a-worktree-is-a-snapshot" aria-label="Anchor">#</a>
    </span>
    
</h2>
<p>Worktrees age. On 19 November an over-the-air update went out from a worktree that had been prepared two or three days earlier, and it quietly reverted two fixes that had shipped from elsewhere in the meantime. It was caught and replaced the same day. The worktree was perfectly isolated, and that was the problem: it never saw those fixes. A git one-liner would have caught it before release:</p>
<figure><video
    class="my-0 rounded-md"
    autoplay loop muted playsinline preload="metadata"
    poster="https://jared.lynskey.co.nz/en/posts/2026/claude-code-git-worktrees/stale-worktree-check.jpg" style="background:url('data:image/webp;base64,UklGRkgAAABXRUJQVlA4IDwAAACwAwCdASogABIAPw16sk+mI6IhKAgAxiGJ6QDEJBPdNJGDbpnawAD+6TSngiBlgQG6+gLgAZ5HH8TQAAA=') center/cover no-repeat"
    width="1280"
    height="720"
    aria-label="Terminal: main has a new commit &#39;Fix sign-in token handling&#39;; an older worktree is still on the initial commit; git merge-base --is-ancestor main HEAD prints &#39;missing the fix: rebase before you ship&#39;; after git rebase main the same check prints &#39;has the fix&#39;">
    <source src="https://jared.lynskey.co.nz/en/posts/2026/claude-code-git-worktrees/stale-worktree-check.mp4" type="video/mp4">
  </video><figcaption>The check to run before shipping from any worktree that isn&rsquo;t freshly cut.</figcaption>
</figure>

<p><code>baseRef: &quot;fresh&quot;</code> keeps new worktrees current. Nothing keeps old ones current, so check before you release from one.</p>

<h2 class="relative group">Subagents and hooks
    <div id="subagents-and-hooks" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#subagents-and-hooks" aria-label="Anchor">#</a>
    </span>
    
</h2>
<p>You don&rsquo;t need a terminal per agent to get this isolation. A custom subagent with <code>isolation: worktree</code> in its front matter always runs in a temporary worktree of its own:</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-markdown" data-lang="markdown"><span class="line"><span class="cl"><span class="nn">---</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">refactorer</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">description</span><span class="p">:</span><span class="w"> </span><span class="l">Applies mechanical refactors across many files</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">isolation</span><span class="p">:</span><span class="w"> </span><span class="l">worktree</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nn">---</span><span class="w">
</span></span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">Apply the requested refactor across every affected file, then run the tests
</span></span><span class="line"><span class="cl">and report the results.</span></span></code></pre></div></div>
<p>That&rsquo;s the example from the <a href="https://code.claude.com/docs/en/worktrees#isolate-subagents-with-worktrees"  target="_blank" rel="noreferrer">docs</a>. The worktree is removed when the subagent finishes without changes. One with changes stays until a periodic sweep can remove it without losing work. One subtlety: a subagent in a worktree under <code>.claude/worktrees/</code> takes its instructions from your main conversation and doesn&rsquo;t load the <code>CLAUDE.md</code> at the worktree&rsquo;s root.</p>
<p><code>WorktreeCreate</code> and <code>WorktreeRemove</code> hooks replace the git logic entirely. They&rsquo;re meant for other version control systems, or for putting worktrees somewhere other than <code>.claude/worktrees/</code>, and they&rsquo;re also the place for setup steps like the install above.</p>

<h2 class="relative group">When plain git worktree add is the better tool
    <div id="when-plain-git-worktree-add-is-the-better-tool" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#when-plain-git-worktree-add-is-the-better-tool" aria-label="Anchor">#</a>
    </span>
    
</h2>
<p>Here&rsquo;s the confession: the <code>.claude/worktrees</code> folder in my app&rsquo;s repository is empty. All 19 of its worktrees were made with plain <code>git worktree add</code>, all of them in the past month, and half of them sit on a detached HEAD. Other repositories on my laptop have 40, 40, 18, 10, 3, 2 and 2 more. And most of the time it isn&rsquo;t me making them: 85 of the 638 Claude Code transcripts on this laptop have an agent running <code>git worktree add</code>, 336 times in all.</p>
<p>Plain git is better when:</p>
<ul>
<li><strong>You need a specific existing branch,</strong> such as a release branch kept for hotfixes. <code>baseRef</code> can&rsquo;t do that.</li>
<li><strong>You want to ship exactly one fix.</strong> Other sessions had committed work to <code>main</code> that hadn&rsquo;t been deployed yet, so a detached worktree at the commit running in production, with my fix cherry-picked into it, was the way to deploy that fix and nothing else.</li>
<li><strong>You&rsquo;re briefing agents yourself.</strong> When I start several agents on one repository, each brief says to work in its own <code>git worktree add --detach &quot;$TMPDIR/&lt;task&gt;-wt&quot; refs/remotes/origin/main</code>, push with <code>git push origin HEAD:main</code>, and rebase on conflict.</li>
<li><strong>You want it kept.</strong> Claude Code&rsquo;s sweep never removes a worktree you created with <code>git worktree add</code>.</li>
</ul>
<p><code>claude -w</code> is better when you&rsquo;re starting a session by hand and want the branch, the <code>.env</code> copy, the fence around the main checkout and the cleanup handled for you. The two mix fine: Claude Code treats any worktree as a worktree, including the main-checkout sharing described above.</p>

<h2 class="relative group">The short version
    <div id="the-short-version" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#the-short-version" aria-label="Anchor">#</a>
    </span>
    
</h2>
<p>Use <code>claude -w &lt;name&gt;</code> for each parallel session, and add <code>.claude/worktrees/</code> to <code>.gitignore</code>. List every gitignored file your build needs in <code>.worktreeinclude</code>, not just <code>.env</code>. Plan for <code>node_modules</code>, whether that means installing per worktree, cloning or pnpm. After a <code>-p</code> run, expect a lock you may need to <code>git worktree unlock</code>. Before you ship from a worktree that isn&rsquo;t new, check it contains what&rsquo;s already live. Worktrees stop agents overwriting each other&rsquo;s files; they don&rsquo;t stop them disagreeing, so you&rsquo;ll still be reviewing three branches at the end.</p>

<h2 class="relative group">Further reading
    <div id="further-reading" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#further-reading" aria-label="Anchor">#</a>
    </span>
    
</h2>
<p><strong>On this site:</strong></p>
<ul>
<li><a href="https://jared.lynskey.co.nz/en/posts/2026/2026-10-22-claude-code-day-to-day/" >How I Run Claude Code Day to Day</a>, on tmux, permission modes and reaching it from my phone</li>
</ul>
<p><strong>Elsewhere:</strong></p>
<ul>
<li><a href="https://code.claude.com/docs/en/worktrees"  target="_blank" rel="noreferrer">Run parallel sessions with worktrees</a> in the Claude Code docs, which is more thorough than most docs pages</li>
<li><a href="https://git-scm.com/docs/git-worktree"  target="_blank" rel="noreferrer">git-worktree</a>, for what&rsquo;s shared and what&rsquo;s per worktree</li>
<li><a href="https://pnpm.io/settings/node-modules#packageimportmethod"  target="_blank" rel="noreferrer">pnpm&rsquo;s <code>packageImportMethod</code></a>, for clones versus hard links</li>
</ul>
]]></content:encoded>
      <media:content url="https://jared.lynskey.co.nz/en/posts/2026/claude-code-git-worktrees/featured.jpg" medium="image" type="image/jpeg" />
    </item>
  </channel>
</rss>
