รัน Session คู่ขนานด้วย Worktrees

แยก Session Claude Code คู่ขนานออกจากกันใน git worktrees แยกต่างหากเพื่อไม่ให้การเปลี่ยนแปลงชนกัน ครอบคลุม flag --worktree, การแยก subagent, .worktreeinclude, การทำความสะอาด และ hook สำหรับ VCS ที่ไม่ใช่ git

git worktree คือ working directory แยกต่างหากที่มีไฟล์และ branch ของตัวเอง โดยแชร์ประวัติ repository และ remote เดียวกันกับ checkout หลักของคุณ การรัน session Claude Code แต่ละ session ใน worktree ของตัวเองหมายความว่าการแก้ไขใน session หนึ่งไม่ไปสัมผัสไฟล์ใน session อื่น ดังนั้นคุณสามารถให้ Claude สร้าง feature ใน terminal หนึ่ง ในขณะที่แก้ bug ใน terminal ที่สองได้

หน้านี้ครอบคลุมการแยก worktree ใน CLI โดยทุกอย่างด้านล่างสมมติว่าเป็น git repository สำหรับระบบควบคุม version อื่นๆ ดู Non-git version control desktop app สร้าง worktree ให้กับทุก session ใหม่โดยอัตโนมัติ

Worktrees เป็นหนึ่งในหลายวิธีในการรัน Claude แบบ parallel โดย Worktrees แยกการแก้ไขไฟล์ ในขณะที่ subagents และ agent teams ประสานการทำงานเอง ดู Run agents in parallel เพื่อเปรียบเทียบแนวทาง หรือข้ามไปที่ Isolate subagents with worktrees เพื่อใช้ worktrees และ subagents ร่วมกัน

เริ่มต้น Claude ใน Worktree

ส่ง --worktree หรือ -w เพื่อสร้าง worktree แยกต่างหากและเริ่ม Claude ใน worktree นั้น โดยค่าเริ่มต้น worktree จะถูกสร้างภายใต้ .claude/worktrees/<value>/ ที่ root ของ repository ของคุณ บน branch ใหม่ชื่อ worktree-<value>:

claude --worktree feature-auth

เพื่อวาง worktrees ที่อื่น ให้กำหนด hook WorktreeCreate รันคำสั่งอีกครั้งด้วยชื่ออื่นใน terminal อื่นเพื่อเริ่ม session แยกที่สอง:

claude --worktree bugfix-123

หากคุณละเว้นชื่อ Claude จะสร้างชื่อเช่น bright-running-fox:

claude --worktree

คุณยังสามารถขอให้ Claude "work in a worktree" ระหว่าง session และมันจะสร้างหนึ่งด้วยเครื่องมือ EnterWorktree เมื่ออยู่ใน worktree แล้ว Claude สามารถสลับไปยัง worktree อื่นภายใต้ .claude/worktrees/ ได้โดยตรงโดยการเรียก EnterWorktree พร้อม path เป้าหมาย worktree ก่อนหน้าจะอยู่บน disk โดยไม่ถูกแตะต้อง

ก่อนใช้ --worktree แบบ interactive ใน directory เป็นครั้งแรก ให้ยอมรับ workspace trust dialog โดยการรัน claude ครั้งหนึ่งใน directory นั้น หาก trust ยังไม่ได้รับการยอมรับ --worktree จะออกพร้อมข้อผิดพลาดและแจ้งให้คุณรัน claude ใน directory นั้นก่อน การรัน non-interactive ด้วย -p จะข้ามการตรวจสอบ trust ดังนั้น claude -p --worktree จะดำเนินการโดยไม่ต้องตรวจสอบ

เคล็ดลับ: เพิ่ม .claude/worktrees/ ใน .gitignore ของคุณเพื่อไม่ให้เนื้อหา worktree ปรากฏเป็นไฟล์ที่ไม่ได้ติดตามใน checkout หลักของคุณ

เลือก Base Branch

Worktrees จะแตก branch จาก default branch ของ repository ของคุณคือ origin/HEAD ดังนั้นจึงเริ่มจาก clean tree ที่ตรงกับ remote หากไม่มีการกำหนด remote หรือการ fetch ล้มเหลว worktree จะ fallback ไปยัง local HEAD ปัจจุบันของคุณ เพื่อ branch จาก local HEAD เสมอ ให้ตั้ง worktree.baseRef เป็น "head" ใน settings

การตั้ง baseRef เป็น "head" ทำให้ worktrees ใหม่พา unpushed commits และ feature-branch state ของคุณมาด้วย ซึ่งมีประโยชน์เมื่อแยก subagents ที่ต้องการทำงานกับงานที่กำลังดำเนินอยู่ การตั้งค่ายอมรับเฉพาะ "fresh" หรือ "head" ไม่ใช่ arbitrary git refs:

{
  "worktree": {
    "baseRef": "head"
  }
}

เพื่อ branch จาก pull request เฉพาะ ส่ง PR number นำหน้าด้วย # หรือ GitHub pull request URL แบบเต็ม Claude Code จะ fetch pull/<number>/head จาก origin และสร้าง worktree ที่ .claude/worktrees/pr-<number>:

claude --worktree "#1234"

สำหรับการควบคุมเต็มรูปแบบว่า worktrees ถูกสร้างอย่างไร ให้กำหนด hook WorktreeCreate ซึ่งแทนที่ logic git worktree ค่าเริ่มต้นทั้งหมด

คัดลอกไฟล์ที่ Gitignored เข้า Worktrees

Worktree คือ fresh checkout ดังนั้นไฟล์ที่ไม่ได้ติดตามเช่น .env หรือ .env.local จาก repository หลักของคุณจะไม่อยู่ใน worktree เพื่อคัดลอกไฟล์เหล่านี้โดยอัตโนมัติเมื่อ Claude สร้าง worktree ให้เพิ่มไฟล์ .worktreeinclude ที่ root ของ project

ไฟล์ใช้ syntax ของ .gitignore มีเพียงไฟล์ที่ตรงกับ pattern และเป็น gitignored เท่านั้นที่จะถูกคัดลอก ดังนั้นไฟล์ที่ติดตามจะไม่ถูก duplicate

.worktreeinclude นี้คัดลอกไฟล์ env สองไฟล์และ secrets config เข้า worktree ใหม่แต่ละอัน:

.env
.env.local
config/secrets.json

สิ่งนี้ใช้กับ worktrees ที่สร้างด้วย --worktree, subagent worktrees และ parallel sessions ใน desktop app

แยก Subagents ด้วย Worktrees

Subagents สามารถรันใน worktrees ของตัวเองเพื่อไม่ให้การแก้ไขแบบ parallel ขัดแย้งกัน ขอให้ Claude "use worktrees for your agents" หรือตั้งค่าถาวรบน custom subagent โดยเพิ่ม isolation: worktree ใน frontmatter Subagent แต่ละตัวได้รับ worktree ชั่วคราวที่ถูกลบโดยอัตโนมัติเมื่อ subagent เสร็จสิ้นโดยไม่มีการเปลี่ยนแปลง

Subagent worktrees ใช้ base branch เดียวกับ --worktree ดังนั้นจึง branch จาก default branch ของ repository ของคุณ เว้นแต่ worktree.baseRef จะถูกตั้งเป็น "head"

ทำความสะอาด Worktrees

เมื่อคุณออกจาก worktree session การทำความสะอาดขึ้นอยู่กับว่าคุณทำการเปลี่ยนแปลงหรือไม่:

• ไม่มี uncommitted changes, ไม่มีไฟล์ที่ไม่ได้ติดตาม และไม่มี commits ใหม่: worktree และ branch ถูกลบโดยอัตโนมัติ หาก session มี ชื่อ Claude จะแจ้งแทนเพื่อให้คุณเก็บ worktree ไว้ใช้ทีหลัง
• มี uncommitted changes, ไฟล์ที่ไม่ได้ติดตาม หรือ commits ใหม่: Claude แจ้งให้คุณเก็บหรือลบ worktree การเก็บจะรักษา directory และ branch ไว้เพื่อให้คุณกลับมาได้ในภายหลัง การลบจะลบ worktree directory และ branch ของมัน โดย discard uncommitted changes, ไฟล์ที่ไม่ได้ติดตาม และ commits ทั้งหมด
• Non-interactive runs: worktrees ที่สร้างด้วย --worktree พร้อมกับ -p จะไม่ถูกทำความสะอาดโดยอัตโนมัติเนื่องจากไม่มี exit prompt ให้ลบด้วย git worktree remove

Worktrees ที่ Claude สร้างสำหรับ subagents และ background sessions จะถูกลบโดยอัตโนมัติเมื่อเก่ากว่าการตั้งค่า cleanupPeriodDays ของคุณ โดยมีเงื่อนไขว่าไม่มี uncommitted changes, ไม่มีไฟล์ที่ไม่ได้ติดตาม และไม่มี unpushed commits Worktrees ที่คุณสร้างด้วย --worktree จะไม่ถูกลบโดยการ sweep นี้

ขณะที่ agent กำลังรัน Claude รัน git worktree lock บน worktree ของมันเพื่อให้การทำความสะอาด concurrent ไม่สามารถลบมันได้ lock จะถูกปล่อยเมื่อ agent เสร็จสิ้น เพื่อทำความสะอาด worktree ที่ sweep ยังคงเก็บไว้ ให้รัน git worktree remove โดยเพิ่ม --force หาก worktree มี uncommitted changes หรือไฟล์ที่ไม่ได้ติดตาม

จัดการ Worktrees ด้วยตนเอง

สำหรับการควบคุมเต็มรูปแบบเหนือตำแหน่ง worktree และการกำหนด branch ให้สร้าง worktrees ด้วย Git โดยตรง สิ่งนี้มีประโยชน์เมื่อคุณต้องการ checkout branch ที่มีอยู่แล้วหรือวาง worktree ไว้นอก repository

สร้าง worktree บน branch ใหม่:

git worktree add ../project-feature-a -b feature-a

สร้าง worktree จาก branch ที่มีอยู่:

git worktree add ../project-bugfix bugfix-123

เริ่ม Claude ใน worktree:

cd ../project-feature-a && claude

แสดงรายการ worktrees ของคุณ:

git worktree list

ลบ worktree เมื่อเสร็จแล้ว:

git worktree remove ../project-feature-a

ดู Git worktree documentation สำหรับ command reference แบบเต็ม อย่าลืม initialize development environment ของคุณใน worktree ใหม่แต่ละอัน: ติดตั้ง dependencies, ตั้งค่า virtual environments หรือรัน setup ที่ project ของคุณต้องการ

Non-git Version Control

การแยก Worktree ใช้ git โดยค่าเริ่มต้น สำหรับ SVN, Perforce, Mercurial หรือระบบอื่นๆ ให้กำหนด hook WorktreeCreate และ WorktreeRemove เพื่อให้ logic การสร้างและทำความสะอาด custom เพราะ hook แทนที่พฤติกรรม git ค่าเริ่มต้น .worktreeinclude จะไม่ถูกประมวลผลเมื่อคุณใช้ --worktree คัดลอกไฟล์ configuration local ใน hook script ของคุณแทน

Hook WorktreeCreate นี้อ่านชื่อ worktree จาก stdin, checkout SVN working copy ใหม่ และ print path ของ directory เพื่อให้ Claude Code ใช้เป็น working directory ของ session:

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}

จับคู่กับ hook WorktreeRemove เพื่อทำความสะอาดเมื่อ session สิ้นสุด ดู hooks reference สำหรับ input schema และตัวอย่างการลบ

ดูเพิ่มเติม

Worktrees จัดการการแยกไฟล์ หน้าที่เกี่ยวข้องด้านล่างครอบคลุมการมอบหมายงานเข้า checkouts แยกเหล่านั้นและการสลับระหว่าง sessions ที่คุณสร้าง:

• Subagents: มอบหมายงานให้ agents แยกภายใน session
• Agent teams: ประสาน Claude sessions หลายตัวโดยอัตโนมัติ
• Manage sessions: ตั้งชื่อ, resume และสลับระหว่าง conversations
• Desktop parallel sessions: sessions ที่สนับสนุนด้วย worktree ใน desktop app