نسخة Markdown

AI-translated from English; not yet reviewed by a fluent editor.

# أضف hook محدودًا لسياق المشروع عند بدء جلسة Claude Code

> ثبّت hook صغيرًا من نوع SessionStart خاصًا بالمشروع لإضافة فرع Git الحالي إلى سياق Claude Code. افحص خرجه المباشر والبدء والاستئناف وسلوكه عند الفشل.

By BIG CHANGE Editorial

Published: 2026-10-20T00:22:54.831Z
Updated: 2026-10-20T00:22:54.831Z
Canonical: https://bigchange.ai/blog/claude-code-session-start-branch-context-hook-guide

![Conceptual charcoal illustration of an unbranded desktop monitor with one short orange stroke above two soft charcoal strokes; a keyboard rests in front.](https://bigchange.ai/api/media/file/claude-code-session-start-context-hero-v2.png)
AI-generated conceptual illustration by BIG CHANGE; no actual Claude Code interface, hook execution or model result is depicted.

يمثل hook في Claude Code أمرًا يشغله التطبيق عند نقطة محددة في الجلسة. يضيف هذا الدليل hook واحدًا خاصًا بالمشروع من نوع `SessionStart` يقرأ فرع Git الحالي ويوفر سطر سياق قصيرًا عند بدء المحادثة أو استئنافها. وهو يتبع [مرجع Anthropic الحالي لآليات hook](https://code.claude.com/docs/en/hooks)، الذي راجعناه في 19 أكتوبر 2026. فحص BIG CHANGE السكربت مباشرة باستخدام Node وفحص JSON الإعدادات؛ لم نشغّل hook في Claude Code ولم نختبر استجابة نموذج.

## التغيير الأبرز

- **ما الذي تغيّر:** يوفر hook المشروع من نوع `SessionStart` سطرًا قصيرًا لفرع Git عندما يبدأ Claude Code محادثة أو يستأنفها.
- **لماذا يهم:** يصل الفرع الحالي إلى سياق الجلسة عند البدء أو الاستئناف دون لصقه يدويًا كل مرة.
- **ما الذي تراقبه:** لا يفرض السياق قاعدة ولا يضمن إجابة النموذج. تحقق من وصوله الفعلي عند البدء والاستئناف في مشروعك الموثوق.

## قبل التثبيت

استخدم مشروع Git لديك صلاحية تغييره. تحتاج إلى إتاحة Claude Code وNode.js وGit في الطرفية نفسها، وإذن لتعديل ملف المشروع `.claude/settings.json`. افحص `node --version` و `git --version` و `claude --version`. كان جهاز الإعداد يحتوي على Claude Code 2.1.301 وNode 24.19.0؛ هذان الإصداران المرصودان ليسا حدًا أدنى للمتطلبات.

**راجع اسم الفرع قبل إرساله إلى نموذج.** قد يحتوي الفرع على اسم عميل أو تذكرة أو حادثة. تصفية المحارف وتقصير النص لا يزيلان هذا المعنى. ثبّت المثال فقط إذا كان اسم الفرع معتمدًا لسياق النموذج. وإلا فعدّل السكربت لإخراج حالة معتمدة غير حساسة وراجع التعديل قبل التثبيت. [توثيق Anthropic لاستخدام البيانات](https://code.claude.com/docs/en/data-usage) يوضح كيفية تعامل الخدمة مع البيانات؛ طبّق أيضًا أذونات مشروعك.

تعمل أوامر hook بصلاحيات المستخدم لديك. افحص آليات hook الحالية للمشروع والمستخدم وسياسة المؤسسة والسكربت كاملًا قبل تمكينها. يمكن حفظ إعدادات المشروع في المستودع؛ أما `.claude/settings.local.json` فيبقى محليًا. يستخدم المثال ملف إعدادات المشروع لحصر التهيئة في ذلك المشروع.

## ثبّت الملفين

1. أنشئ `.claude/hooks/` داخل المشروع. احفظ الكتلة كاملة باسم `.claude/hooks/session-context.cjs`:

```javascript
'use strict';

const { execFileSync } = require('node:child_process');

const project = process.env.CLAUDE_PROJECT_DIR;
if (!project) {
  process.stderr.write('CLAUDE_PROJECT_DIR is unavailable\n');
  process.exit(1);
}

try {
  const raw = execFileSync('git', ['-C', project, 'branch', '--show-current'], {
    encoding: 'utf8',
    timeout: 1500,
    maxBuffer: 4096,
    stdio: ['ignore', 'pipe', 'pipe'],
  }).trim();
  const branch = raw ? raw.replace(/[^A-Za-z0-9._/-]/g, '_').slice(0, 80) : 'detached HEAD';
  process.stdout.write(`Current project branch: ${branch}\n`);
} catch {
  process.stderr.write('Could not read the project branch; check Git and project path\n');
  process.exit(1);
}
```

للعملية الفرعية Git مهلة 1.5 ثانية ومخزن خرج قدره 4,096 بايت. تتحول نتيجة الفرع الفارغة، كما في detached HEAD، إلى `detached HEAD`. يؤدي غياب مسار المشروع أو فشل Git إلى رسالة تشخيص قصيرة على stderr ورمز خروج 1.

2. افتح ملفك الحالي `.claude/settings.json`. ادمج إدخال `hooks.SessionStart` أدناه مع الإعدادات ومجموعات hook الأخرى، مع الحفاظ على الإدخالات الموجودة. تعرض الكتلة كامل `settings.example.json` من الحزمة المراجعة. إذا احتوى الملف بالفعل على إدخالات `SessionStart` ، فأضف هذه المجموعة إلى مصفوفتها بدل استبدال المصفوفة.

```json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "node",
            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/session-context.cjs"],
            "timeout": 5
          }
        ]
      }
    ]
  }
}
```

يغطي matcher جلسة جديدة وجلسة مستأنفة. توثّق Anthropic أيضًا `clear` و `compact` و `fork` بوصفها مصادر `SessionStart` ؛ يتعمد المثال استبعادها. يختار حقل `args` صيغة exec: يستدعي Claude Code `node` مع مسار سكربت المشروع المحسوم كوسيط واحد، دون اقتباس أو تحليل بواسطة shell. في Windows، يجب أن يشير `node.exe` إلى ملف تنفيذي؛ ولا يصلح وسيط `.cmd` من نوع shim لصيغة exec. مهلة hook البالغة خمس ثوان منفصلة عن مهلة Git البالغة 1.5 ثانية داخل السكربت.

## افحص السكربت ثم افحص Claude Code

3. قبل فتح Claude Code، شغّل السكربت في طرفية المشروع وقارن خرجه مع Git. في PowerShell:

```powershell
$env:CLAUDE_PROJECT_DIR = (Get-Location).Path
node .claude/hooks/session-context.cjs
git branch --show-current
```

في Bash:

```bash
CLAUDE_PROJECT_DIR="$PWD" node .claude/hooks/session-context.cjs
git branch --show-current
```

توقع سطر stdout واحدًا فقط من السكربت، وهو `Current project branch: BRANCH`، حيث يمثل `BRANCH` نتيجة Git بعد تصفية المحارف وحدّ 80 محرفًا. تطبع حالة detached HEAD `Current project branch: detached HEAD`. يثبت الفحص المباشر فقط أن السكربت المحلي يعمل في هذه الطرفية. في فحص الإعداد لدينا، طابقت نتيجة الفرع العادي Git؛ وأنتج مسارا المشروع المفقود وغير الصالح stdout فارغًا وتشخيصًا على stderr ورمز خروج 1. فحصنا حد الاسم الطويل وبديل detached HEAD في المصدر، لكننا لم نشغّل هاتين الحالتين.

4. ابدأ عملية Claude Code جديدة **تفاعلية** داخل المشروع الموثوق باستخدام `claude --debug-file STARTUP_PRIVATE_LOG`، مع مسار خاص تتحكم فيه. راجع آليات hook للمشروع والمستخدم قبل قبول الثقة بمساحة العمل. افحص سجل التصحيح بحثًا عن حدث `SessionStart` ذي المصدر `startup`، ومسار السكربت المختار وحالة خروجه ومعالجة خرجه. اسأل Claude عن سياق الفرع الذي تلقاه دون السماح له باستخدام أداة أو قراءة Git مستقلًا. قارن الإجابة وسجل التصحيح بالنتيجة المباشرة. يدخل stdout الخاص بـhook إلى سياق Claude؛ ولا يوجد وعد بعرضه رسالة في الواجهة المرئية.
5. اخرج من تلك الجلسة. استأنفها في عملية منفصلة باستخدام `claude --debug-file RESUME_PRIVATE_LOG --resume`، ثم افحص حدث `SessionStart` `resume` وكرر فحص السؤال دون أداة أو إعادة قراءة Git. احتفظ بسجلي التصحيح خاصين؛ فقد يكشفان تفاصيل المشروع. التشغيل غير التفاعلي عبر `-p` أو SDK لا يعرض مطالبة الثقة بمساحة العمل نفسها وقد يشغّل آليات hook في المستودع تلقائيًا، لذا استخدم المسار التفاعلي لهذا الفحص. تقول Anthropic إن مراقب الملفات يلتقط عادة تعديلات إعدادات hook، لكن العملية الجديدة تعطي اختبارًا أوضح للبدء والاستئناف.

إذا غيّر العمل المعتاد لاحقًا الفرع، فأعد الفحص المباشر وجلسة جديدة لمعرفة إن كان السطر يتغير. لا تبدّل الفروع لمجرد الادعاء بأن هذا الدليل اختُبر.

## إذا لم يعمل

ابدأ بنتيجة السكربت المباشرة، ثم افحص دمج JSON وكتابة `SessionStart` وmatcher `startup|resume` ومسار جذر المشروع وتوافر `node` و `git` والثقة بمساحة العمل وأخطاء التصحيح. عند غياب `CLAUDE_PROJECT_DIR` تُطبع `CLAUDE_PROJECT_DIR is unavailable` على stderr. يطبع مسار المشروع الخاطئ أو فشل Git `Could not read the project branch; check Git and project path`. تنتهي الحالتان بالرمز 1 دون طباعة سطر سياق. فشل `SessionStart` تشخيصي وغير حاجب؛ ولا يصلح بوابة لمنع إجراء. توثّق Anthropic `PreToolUse` للتحكم في إجراء أداة، وهو حدث آخر يتطلب تصميمًا منفصلًا خضع للمراجعة.

يشغّل السكربت Git محليًا فقط ولا يجري طلب شبكة أو استدعاء نموذج. بدء Claude Code واستئنافه وفحص الأسئلة قد يستهلك حصة حسابك أو المزوّد أو النموذج؛ يورد [دليل تكاليف Anthropic](https://code.claude.com/docs/en/costs) الشروط الحالية. لا يحدد هذا الدليل سعرًا ثابتًا ولا يبلّغ عن اختبار جلسة مدفوعة.

لمهمة منفصلة بعد بدء المحادثة، يتناول [دليلنا لفحص السياق ومتابعة جلسة Claude Code](https://bigchange.ai/blog/claude-code-session-context-continue-guide) فحص السياق والمتابعة. ولا يضبط hook البدء هذا.

## المصادر وقراءات إضافية

- [Anthropic، مرجع Claude Code hook](https://code.claude.com/docs/en/hooks) — المواصفة الأولية الحالية التي روجعت في 19 أكتوبر 2026. توثّق `SessionStart` المصادر وmatcher، وصيغة exec `args` وعناصر المسار النائبة وسياق stdout وإعادة تحميل الإعدادات والثقة وسجلات التصحيح والفشل غير الحاجب. هذا توثيق وليس تنفيذ hook بواسطة BIG CHANGE.
- [Anthropic، أتمتة الإجراءات باستخدام hook](https://code.claude.com/docs/en/hooks-guide) — شرح رسمي لإعداد hook واختباره. السكربت والإعدادات المحددان أعلاه مثال BIG CHANGE محدود راجعناه لهذا الدليل، وليسا نتيجة اختبار منسوخة من المورّد.
- [Anthropic، إعداد Claude Code](https://code.claude.com/docs/en/setup) — متطلبات التثبيت والبيئة. تحقق من تعليمات منصتك الحالية قبل استخدام المثال.
- [Anthropic، استخدام بيانات Claude Code](https://code.claude.com/docs/en/data-usage) — شروط المزوّد الحالية لمعالجة البيانات، لمراجعتها قبل إرسال معلومات الفرع إلى سياق النموذج؛ وتبقى صلاحية المشروع قرارًا منفصلًا.
- [Anthropic، إدارة التكاليف بفاعلية](https://code.claude.com/docs/en/costs) — إرشادات الحساب والاستخدام الحالية للفحوص التفاعلية. سكربت Git المحلي نفسه لا يجري طلبًا للنموذج أو الشبكة.

## Sources

- [مرجع Claude Code hook](https://code.claude.com/docs/en/hooks) — دليل Anthropic الأولي الحالي، فُحص مقابل اللقطة المعتمدة في 19 أكتوبر 2026 ومرة أخرى أثناء الكتابة. يحدد مصادر SessionStart startup/resume ومعاني matcher وصيغة exec للحقلين command وargs وعنصر جذر المشروع النائب وسياق stdout النصي ومراقب الإعدادات والثقة بمساحة العمل وفحص debug-file وقاعدة الملف التنفيذي الحقيقي في Windows وأخطاء SessionStart غير الحاجبة. يصف سلوك المنتج؛ لم ينفذ BIG CHANGE hook يستدعيه Claude. لم يذكر تاريخ مراجعة ثابت للدليل.
- [أتمتة الإجراءات باستخدام hook](https://code.claude.com/docs/en/hooks-guide) — شرح Anthropic الرسمي للإعداد والاختبار. يدعم عملية التهيئة والتشخيص لدى القارئ، لا ادعاء أن BIG CHANGE شغّل المثال داخل Claude Code. أتى سكربت Node المحدود وإعدادات المقال المحددة من حزمة تنفيذ محلية خضعت لمراجعة منفصلة.
- [الإعداد المتقدم لـClaude Code](https://code.claude.com/docs/en/setup) — مرجع التثبيت والبيئة الرسمي لفحص إعداد Claude Code المحلي. رُصد أثناء الإعداد الإصدار 2.1.301 فقط؛ ولا يجعله المصدر حدًا أدنى مطلوبًا.
- [استخدام بيانات Claude Code](https://code.claude.com/docs/en/data-usage) — شروط معالجة البيانات الرسمية المعتمدة على الحساب. يوجّه المقال القارئ لمراجعتها قبل وضع معلومات فرع Git في سياق النموذج؛ فالتصفية والاقتطاع لا يمنعان اسم الفرع من كشف تفاصيل عميل أو حادثة سرية. لا تُستنتج ضمانة خصوصية شاملة.
- [إدارة التكاليف بفاعلية](https://code.claude.com/docs/en/costs) — إرشادات الحساب واستخدام النموذج الرسمية لفحوص الأسئلة التفاعلية عند البدء والاستئناف. السكربت المحلي نفسه لا يطلب نموذجًا أو شبكة، بينما قد تستهلك جلسات Claude الفعلية حصة الخطة أو المزوّد أو API. لا يُدّعى سعر ثابت أو اختبار مدفوع.
- [كيفية فحص السياق ومتابعة جلسة Claude Code](https://bigchange.ai/blog/claude-code-session-context-continue-guide) — مقال BIG CHANGE السابق 414، استُخدم فقط لرابط داخلي سياقي وتصنيف العلاقة. يتناول فحص محادثة موجودة ومتابعة مهمتها؛ وليس دليلًا لتنفيذ hook هذا أو أصلًا مباشرًا مؤرخًا للقصة نفسها.