Git worktree في Claude Code: جلسات متوازية

تجد في الوثائق معلومات عملية حول العمل باستخدام Ailoot.

ما هو git worktree في Claude Code#

تشغيل عدة وكلاء بالتوازي في المجلد نفسه هو المشكلة الأساسية في vibe coding بسرعة عام 2026. تكتب وكلاء الذكاء الاصطناعي الشيفرة أسرع مما يستطيع الشخص متابعة من يعمل على ماذا. ومن دون عزل الملفات، ينتهي تشغيل جلستين متوازيتين من Claude Code في دليل واحد بأن تكتب إحداهما فوق عمل الأخرى.

يحل Git worktree هذه المشكلة على مستوى نظام الملفات. لديك دليل رئيسي واحد تعمل فيه. ينشئ الأمر claude --worktree feature-auth المجلد .claude/worktrees/feature-auth/ على فرع منفصل ويبدأ Claude Code داخله. الملفات معزولة. ولا تظهر تغييرات إحدى الجلستين للأخرى حتى تدمجها صراحةً.

تشرح وثائق Anthropic الرسمية الأمر على النحو الآتي:

إشارة تساعدك على التحقق بنفسك: إذا سبق أن حصلت على commit كان نصف ملفاته من عمل شخص آخر، فأنت بحاجة إلى worktree.

كيف يختلف git worktree عن الفرع العادي#

في تدفق Git المعتاد، تكون على فرع main ثم تشغّل git checkout feature-x، فيكتب Git فوق ملفات نسخة العمل. ويتعطل npm run dev قيد التشغيل لأن package.json تغيّر من تحته. تحفظ تغييراتك غير الملتزم بها مؤقتًا باستخدام stash وتنتظر حتى يعيد IDE فهرسة الملفات. ثم تعود، فيُكتب فوق كل شيء مجددًا، فتضطر إلى stash وpop مرة أخرى.

يمنحك Git worktree خيارًا آخر: بدل تبديل مجلد واحد بين الفروع، تنشئ مجلدًا ثانيًا لفرع آخر. ينشئ الأمر git worktree add ../project-feature-x feature-x الدليل ../project-feature-x/ وفيه ملفات الفرع feature-x. يبقى main في المجلد الأصلي ويواصل خادم التطوير عمله.

في السابق، كان يجب إعداد وضع worktree في Claude Code يدويًا: git worktree add، ثم cd، ثم claude، وتكرار ذلك في كل طرفية. ينفّذ الخيار --worktree (أو -w) الخطوات الثلاث كلها بأمر واحد.

تشغيل أول جلسة متوازية: الخيار --worktree#

مثال بسيط. افتح الطرفية الأولى عند جذر المشروع:

claude --worktree feature-auth

ينفّذ Claude Code ثلاثة أمور:

1. ينشئ .claude/worktrees/feature-auth/ بلقطة من origin/HEAD (وهو عادةً فرعك الافتراضي).
2. ينشئ فرعًا جديدًا باسم worktree-feature-auth.
3. يبدأ الجلسة في هذا المجلد.

افتح طرفية ثانية في مجلد جذر المستودع نفسه:

claude --worktree bugfix-123

هذا كل شيء. جلستا Claude Code، وملفات مختلفة على القرص، وفرعا Git مختلفان. إذا كتبت الشيفرة الخاصة بالمصادقة في الأولى وأصلحت اختبارًا فاشلًا في الثانية، فلن تتمكنا ماديًا من إعاقة إحداهما الأخرى.

إذا لم ترغب في كتابة اسم، فسيختار Claude اسمًا:

claude --worktree
# → ينشئ شيئًا مثل .claude/worktrees/bright-running-fox/

نصيحة للمبتدئين في Git: أضف .claude/worktrees/ إلى .gitignore. وإلا، فعند تشغيل git status في المجلد الرئيسي سترى محتويات جميع worktrees كملفات غير متعقبة:

# .gitignore
.claude/worktrees/

خطأ ينبغي تجنبه: قبل أول تشغيل لـ--worktree في دليل جديد، ادخله بتشغيل claude عاديًا (من دون الخيار) ووافق على مربع حوار الوثوق بمساحة العمل. وإلا سيفشل الخيار مع خطأ “trust not accepted”، حتى عند دمجه مع -p للوضع عديم الواجهة.

أين توجد worktrees وكيفية العثور عليها#

الموقع الافتراضي ثابت: .claude/worktrees/<value>/ عند جذر المستودع. إذا كان مشروعك في ~/dev/my-app/، فسيكون worktree المسمى feature-auth في ~/dev/my-app/.claude/worktrees/feature-auth/.

للتخطيطات غير المعتادة (مثل وضع worktree خارج المستودع)، يوجد الخطاف WorktreeCreate، وسنتحدث عنه لاحقًا في قسم SVN وMercurial.

يمكنك التبديل إلى worktree موجود آخر ضمن جلسة Claude واحدة. قل في المحادثة: «انتقل إلى .claude/worktrees/bugfix-123»، وسيستدعي Claude أداة EnterWorktree. سيبقى المجلد الحالي دون تغيير، ويمكنك الرجوع بالطريقة نفسها.

يعرض أمر Git القياسي قائمة بجميع worktrees، بما فيها الرئيسية وتلك التي أُنشئت يدويًا:

git worktree list

سيبدو الناتج على النحو الآتي:

/home/user/dev/my-app                  abc1234 [main]
/home/user/dev/my-app/.claude/worktrees/feature-auth  def5678 [worktree-feature-auth]
/home/user/dev/my-app/.claude/worktrees/bugfix-123    9876fed [worktree-bugfix-123]

نسخ .env والأسرار: ملف .worktreeinclude#

عندما ينشئ --worktree مجلدًا جديدًا، لا يحصل إلا على ما أُودع في Git. يوجد .env الذي يحتوي مفاتيح API و.env.local الذي يتضمن الإعدادات المحلية في .gitignore، ولذلك لا يظهران في worktree. ويفشل أول تشغيل لـnpm run dev برسالة “MISSING DATABASE_URL”.

الحل اليدوي هو نسخ .env بعد كل تشغيل لـ--worktree. ينجح ذلك مرة، ثم يُنسى. أما حل Anthropic فهو ملف .worktreeinclude في جذر المشروع يسرد الملفات التي يتجاهلها Git وينبغي نسخها تلقائيًا إلى كل worktree جديد.

أنشئ ملف .worktreeinclude في جذر المستودع:

.env
.env.local
config/secrets.json

الصياغة مطابقة لـ.gitignore. ويمكنك استخدام أنماط glob:

.env*
*.local
config/*.json
.vscode/settings.json

تقدم Anthropic قاعدة واضحة لتجنّب الحوادث:

بعبارة أخرى، لا يمكنك نسخ package.json عن طريق الخطأ عبر .worktreeinclude؛ فهو ليس مدرجًا في .gitignore. ومن الآمن وضع أي أنماط في الملف.

يعمل ملف .worktreeinclude نفسه في ثلاثة أوضاع: --worktree اليدوي، وworktrees الوكلاء الفرعيين التلقائية (انظر أدناه)، والجلسات من تطبيق Claude لسطح المكتب.

إنشاء worktree من طلب سحب لمراجعة الشيفرة#

سيناريو مراجعة شائع: أرسل إليك زميل PR، وتحتاج إلى فحص الشيفرة وتشغيل الاختبارات وترك تعليق. باستخدام git checkout pull/1234/head العادي، ستبدّل نسخة العمل مجددًا وتعطّل جلستك النشطة.

باستخدام الخيار --worktree، يكفي أمر واحد:

claude --worktree "#1234"

ما يحدث هو أن Claude Code يشغّل git fetch origin pull/1234/head، وينشئ worktree في .claude/worktrees/pr-1234/، ثم ينتقل إلى فرع PR. وتبدأ الجلسة. يمكنك أن تطلب منه فورًا «قراءة diff وتشغيل الاختبارات والعثور على الأخطاء المنطقية»؛ وفي أثناء عمل Claude، تواصل جلستك الرئيسية على main عملها.

والصياغة البديلة هي عنوان URL الكامل لطلب السحب:

claude --worktree https://github.com/OWNER/REPO/pull/1234

في مشروع حقيقي، يؤدي الجمع بين claude --worktree "#N" ووكيل فرعي خاص بمراجعة الشيفرة إلى مراجعة تلقائية خلال دقيقة أو دقيقتين. شغّله في الخلفية، وواصل عملك في النافذة الرئيسية، ثم ارجع إلى النتيجة عبر claude agents.

الفرع الأساسي: worktree.baseRef مع fresh أو head#

الإعداد الافتراضي هو أن يبدأ كل worktree جديد من origin/HEAD. ميزته أنه يوفر بداية نظيفة مضمونة التطابق مع ما ستراه CI. أما عيبه فهو أن التغييرات غير الملتزم بها أو عدة commits محلية تتجاوز المستودع البعيد على فرعك الحالي لن تُضمّن في worktree الجديد.

لبدء worktree من commit ‏HEAD المحلي الحالي، أضف ما يلي إلى .claude/settings.json (أو إلى الإعدادات العامة):

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

يبدأ الآن claude --worktree experimental-feature من HEAD المحلي الحالي. يفيد ذلك عندما تملك الميزة commits محلية لم تُدفع بعد. لا يشمل تعديلات الملفات المتتبعة التي لم تُثبت. إذا احتاجها الوكيل الفرعي، فاحفظ التغييرات المطلوبة وانقلها صراحة ثم افحص الفروق في الوجهة؛ ولا تخلط هذا النقل بـ .worktreeinclude الذي يعالج الملفات المحلية المتجاهلة.

يقبل الإعداد قيمتين بالضبط: "fresh" (= origin/HEAD) و"head" (= HEAD المحلي). لا تُقبل مراجع عشوائية مثل "feature-branch" أو hash لالتزام؛ وهذا قيد مقصود لمنع الانفجار التوافقي للخيارات.

عزل الوكلاء الفرعيين تلقائيًا: isolation: worktree#

عندما تقول لـClaude: «أطلق ثلاثة وكلاء فرعيين: يقرأ أحدهم قاعدة البيانات، ويفحص الثاني API، ويتحقق الثالث من الاختبارات»، فسيعمل الثلاثة افتراضيًا في نسخة العمل نفسها. وإذا كتب اثنان منهم في الملف نفسه في الوقت ذاته، فسيحدث تعارض. والحل هو منح كل واحد منهم worktree خاصًا به تلقائيًا.

الطريقة 1: اطلب ذلك شفهيًا. اكتب إلى Claude في المحادثة:

استخدم worktrees لوكلائك.

سيطبّق Claude العزل على كل الوكلاء الفرعيين اللاحقين في هذه الجلسة.

الطريقة 2: اضبطه صراحةً في الوكيل الفرعي نفسه. أضف حقلًا إلى frontmatter في ملف الوكيل الفرعي (مثل .claude/agents/code-reviewer.md):

---
name: code-reviewer
description: يقرأ diff ويكتب تعليقات مراجعة الشيفرة
isolation: worktree
---

أنت مراجع دقيق. اقرأ diff وابحث عن أخطاء منطقية...

سيحصل كل تشغيل لهذا الوكيل الفرعي الآن على worktree مؤقت في .claude/worktrees/. إذا لم يكتب الوكيل الفرعي أي شيء، فسيُحذف المجلد تلقائيًا عند انتهائه. وإذا كانت هناك تغييرات غير ملتزم بها، فسيسأل Claude إن كنت تريد الاحتفاظ بها أو إزالتها.

الفرع الأساسي لـworktrees الوكلاء الفرعيين هو نفسه المستخدم مع --worktree: origin/HEAD افتراضيًا، أو HEAD المحلي عند ضبط worktree.baseRef: head.

مصفوفة اتخاذ القرار: worktree أم /bg أم وكيل فرعي أم Agent View#

تركيبات شائعة:

• «ميزتان بالتوازي، يدويًا» — طرفيتان، وفي كل واحدة claude --worktree. الحالة الأبسط.
• «ابدأ إعادة هيكلة ليلية؛ سأغلق التطبيق» — /bg + /goal مع شرط اكتمال. تعمل الجلسة باستقلال عن نافذتك.
• «موجّه واحد وثلاثة تحقيقات متوازية» — ثلاثة وكلاء فرعيين مع isolation: worktree. يعمل كل منهم في بيئة معزولة خاصة به.
• «ما الذي يعمل الآن؟» — claude agents. لوحة لكل الجلسات مع مرشحات “running” و“blocked” و“done”.

5 أخطاء شائعة عند العمل باستخدام worktrees#

1. شغّلت worktree، لكن .env غير موجود ولا يعمل شيء. هذه المشكلة الأكثر شيوعًا. worktree هو checkout جديد بلا ملفات يتجاهلها Git. أضف ملف .worktreeinclude يتضمن .env* والإعدادات المحلية اللازمة عند إعداد وضع worktree لحل المشكلة. تأكد أن الملف في جذر المستودع، لا في .claude/.

2. تريد الانتقال إلى الفرع الرئيسي، فتشغّل cd إلى الجذر وتفقد تغييراتك غير الملتزم بها في worktree. المجلد الجذر وworktree نسختا عمل مختلفتان. عدت إلى الجذر باستخدام cd، وبقيت تغييرات worktree في مكانها ولم تختفِ. لكن إذا اختلط عليك الأمر وشغّلت git stash في المجلد الرئيسي معتقدًا أنك في worktree، فسيُنشأ stash على الفرع الرئيسي، لا على الفرع الذي توقعته.

3. شغّلت 5 جلسات متوازية ولم تعد تتذكر ما تفعله كل واحدة. تحذّر وثائق Anthropic صراحةً من أن معظم المطورين لا يستطيعون التعامل ذهنيًا مع أكثر من 2–3 جلسات. ومن علامات الحمل الزائد فتح Agent View والعجز عن تحديد ما يفعله كل وكيل فورًا. اقتصر على جلستين متزامنتين. وإذا تطلبت المهمة أكثر من ذلك، فمن الأفضل تنسيقها عبر /goal والوكلاء الفرعيين بدلًا من إدارتها يدويًا.

4. لا تُنظّف worktrees التي أُطلقت باستخدام -p (وضع عديم الواجهة) تلقائيًا. لا يعرض الأمر claude --worktree feature-x -p "do thing" مطالبة تفاعلية عند الخروج، لذلك لا تأتي لحظة يسأل فيها Claude: «أأزيل worktree؟». تتراكم هذه worktrees. نظّفها يدويًا: git worktree remove .claude/worktrees/feature-x. أو استخدم نصًا برمجيًا لـcron يزيل كل ما تجاوز عمره 7 أيام.

5. مربع حوار الوثوق في مجلد جديد. إذا فتحت المستودع لأول مرة وشغّلت فورًا claude --worktree، فسيفشل الأمر. شغّل claude من دون خيارات، ووافق على الوثوق بمساحة العمل، ثم اخرج. بعد ذلك سيعمل --worktree. هذا مقصود كيلا يحصل Claude على إمكانية الوصول إلى مشروع شخص آخر من دون موافقة المستخدم.

التنظيف: ما الذي يُحذف تلقائيًا#

يعتمد منطق التنظيف على ما فعلته في worktree وكيف بدأت الجلسة. تسرد وثائق Anthropic ثلاثة سيناريوهات:

السيناريو 1: دخلت ولم تفعل شيئًا ثم خرجت؛ فأُزيلت worktree.

السيناريو 2: أنجزت بعض العمل ولم تودعه. عند الخروج سيسأل Claude: «الاحتفاظ أم الإزالة؟». يحفظ خيار «الاحتفاظ» المجلد والفرع لاستخدامهما لاحقًا. أما «الإزالة» فتحذف الدليل مع التغييرات غير الملتزم بها والـcommits الجديدة. هذا إجراء مدمّر؛ فلا تنقر على «الإزالة» بدافع العادة.

السيناريو 3: شغّلت الأمر باستخدام -p (وضع عديم الواجهة) ثم انتهى الأمر وخرج. تبقى worktree. نظّفها يدويًا:

git worktree remove .claude/worktrees/feature-x

إضافةً إلى ذلك، تُزال worktrees الوكلاء الفرعيين وجلسات /bg تلقائيًا بواسطة التنظيف في الخلفية إذا تجاوز عمرها cleanupPeriodDays يومًا (وهو إعداد تكون قيمته الافتراضية عادةً 30 يومًا) ولم يكن فيها عمل غير محفوظ. ولا يشمل التنظيف التلقائي worktrees التي أُنشئت باستخدام --worktree؛ فتقع مسؤولية إدارتها عليك.

بدائل SVN وPerforce وMercurial: الخطاف WorktreeCreate#

إذا كان المستودع يستخدم Subversion أو Mercurial، فلن يعمل الخيار --worktree مباشرةً. توفر Anthropic نقطة تمديد عبر خطافين: WorktreeCreate (لإنشاء نسخة معزولة) وWorktreeRemove (لإزالتها).

مثال خطاف SVN من الوثائق الرسمية:

{
  "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\"'"
          }
        ]
      }
    ]
  }
}

يقرأ الخطاف اسم worktree من stdin ({ "name": "feature-auth" })، وينفّذ svn checkout إلى دليل محسوب مسبقًا، ثم يطبع المسار على stdout. ويستخدم Claude Code ذلك الدليل بوصفه دليل العمل للجلسة الجديدة.

تنبيه مهم: عند استخدام خطافك الخاص، لا يُستخدم .worktreeinclude. إذا احتجت إلى .env أو ملفات أخرى يتجاهلها Git في المجلد الجديد، فانسخها داخل نص الخطاف البرمجي.

ما التالي: ثلاث آليات متجاورة للعمل بالتوازي#

يوفر worktree عزل الملفات. ويوفر /bg عزل السياق. وتوفر الوكلاء الفرعيون عزل المهام. تحل كل آلية مشكلة بمفردها. وباجتماعها، تتيح لك العمل على ثلاث إلى خمس مهام بالتوازي من دون انهيار ذهني. هذه هي مجموعة المهارات الكامنة وراء vibe coding المتقدم في 2026.

يتواصل هذا الموضوع طبيعيًا مع ثلاثة موضوعات ذات صلة: كيفية إعداد وكيل مستقل باستخدام /goal وAgent View، وكيفية إنشاء وكلاء فرعيين خاصين بمهامك، وكيفية إطلاق مئات الوكلاء عبر Dynamic Workflows.

افتح Ailoot.