يمثل hook في Claude Code أمرًا يشغله التطبيق عند نقطة محددة في الجلسة. يضيف هذا الدليل hook واحدًا خاصًا بالمشروع من نوع SessionStart يقرأ فرع Git الحالي ويوفر سطر سياق قصيرًا عند بدء المحادثة أو استئنافها. وهو يتبع مرجع Anthropic الحالي لآليات hook، الذي راجعناه في 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 لاستخدام البيانات يوضح كيفية تعامل الخدمة مع البيانات؛ طبّق أيضًا أذونات مشروعك.

تعمل أوامر 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.

  1. افتح ملفك الحالي .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

  1. قبل فتح Claude Code، شغّل السكربت في طرفية المشروع وقارن خرجه مع Git. في PowerShell:
PowerShell
$env:CLAUDE_PROJECT_DIR = (Get-Location).Path
node .claude/hooks/session-context.cjs
git branch --show-current

في Bash:

Terminal
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 في المصدر، لكننا لم نشغّل هاتين الحالتين.

  1. ابدأ عملية Claude Code جديدة تفاعلية داخل المشروع الموثوق باستخدام claude --debug-file STARTUP_PRIVATE_LOG، مع مسار خاص تتحكم فيه. راجع آليات hook للمشروع والمستخدم قبل قبول الثقة بمساحة العمل. افحص سجل التصحيح بحثًا عن حدث SessionStart ذي المصدر startup، ومسار السكربت المختار وحالة خروجه ومعالجة خرجه. اسأل Claude عن سياق الفرع الذي تلقاه دون السماح له باستخدام أداة أو قراءة Git مستقلًا. قارن الإجابة وسجل التصحيح بالنتيجة المباشرة. يدخل stdout الخاص بـhook إلى سياق Claude؛ ولا يوجد وعد بعرضه رسالة في الواجهة المرئية.
  2. اخرج من تلك الجلسة. استأنفها في عملية منفصلة باستخدام 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 الشروط الحالية. لا يحدد هذا الدليل سعرًا ثابتًا ولا يبلّغ عن اختبار جلسة مدفوعة.

لمهمة منفصلة بعد بدء المحادثة، يتناول دليلنا لفحص السياق ومتابعة جلسة Claude Code فحص السياق والمتابعة. ولا يضبط hook البدء هذا.

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

  • Anthropic، مرجع Claude Code hook — المواصفة الأولية الحالية التي روجعت في 19 أكتوبر 2026. توثّق SessionStart المصادر وmatcher، وصيغة exec args وعناصر المسار النائبة وسياق stdout وإعادة تحميل الإعدادات والثقة وسجلات التصحيح والفشل غير الحاجب. هذا توثيق وليس تنفيذ hook بواسطة BIG CHANGE.
  • Anthropic، أتمتة الإجراءات باستخدام hook — شرح رسمي لإعداد hook واختباره. السكربت والإعدادات المحددان أعلاه مثال BIG CHANGE محدود راجعناه لهذا الدليل، وليسا نتيجة اختبار منسوخة من المورّد.
  • Anthropic، إعداد Claude Code — متطلبات التثبيت والبيئة. تحقق من تعليمات منصتك الحالية قبل استخدام المثال.
  • Anthropic، استخدام بيانات Claude Code — شروط المزوّد الحالية لمعالجة البيانات، لمراجعتها قبل إرسال معلومات الفرع إلى سياق النموذج؛ وتبقى صلاحية المشروع قرارًا منفصلًا.
  • Anthropic، إدارة التكاليف بفاعلية — إرشادات الحساب والاستخدام الحالية للفحوص التفاعلية. سكربت Git المحلي نفسه لا يجري طلبًا للنموذج أو الشبكة.