الـ mods في Claude Code: ما هي، والـ mod الذي نُرفقه بكل وكيل

في 1 أكتوبر 2026، صدر Claude Code 2.1.287 مع سطر واحد في سجل التغييرات: «Added Claude Mods». وبعد أربعة أيام، بدأ AgentsRoom يحمّل واحدًا من الـ mods الخاصة بنا في وكلاء Claude التي يشغّلها.

يشرح هذا المقال ما هو الـ mod، وما الذي يستطيع فعله ولم تكن نقاط التوسعة الأقدم تستطيعه، وكيف تكتبه وتحمّله وتختبره، وما تعلّمناه حين أرفقنا mod بكل وكيل Claude يشغّله AgentsRoom. المعلومات عن Claude Code مأخوذة من توثيقه وسجل تغييراته، كما قرأناها في 9 نوفمبر 2026، مع تثبيت Claude Code 2.1.318.

الجواب المختصر. الـ mod إضافة لـ Claude Code تحتوي على hooks module: ملف JavaScript أو TypeScript يستدعي Claude Code دواله من داخل عمليته الخاصة حين يقع حدث. تستطيع الدالة أن تمرّر الحدث، أو تعدّله، أو ترد عليه بدلًا من Claude Code. هكذا يرسم الـ mod لوحة، أو يضيف أمرًا، أو يوقف أمر shell قبل أن يعمل.

ما هو الـ mod

كانت لدى Claude Code إضافات (plugins) من قبل: مجلد فيه ملف تعريف (manifest) في .claude-plugin/plugin.json يجمع مهارات ووكلاء فرعيين وخطافات إعدادات وخوادم MCP لتُثبَّت كوحدة واحدة. والـ mod شيء آخر يمكن أن تحتويه الإضافة. حين يسمّي ملف hooks/hooks.json الخاص بالإضافة ملف كود تحت مفتاح modules، يحمّل Claude Code ذلك الملف ويستدعي الدالة register التي يصدّرها. عندئذ تُسمّى الإضافة mod.

داخل register، يربط كل استدعاء لـ on(event, hook) دالةً بحدث: tool.call قبل أن تعمل أداة، وprompt.submit حين ترسل موجّهًا، وsession.start، وcommand.run لأمر slash، وui.render حين يرسم Claude Code جزءًا من شاشته، وغيرها. يتلقى كل خطاف ثلاثة أشياء:

• $، واجهة برمجة الـ mods: كل ما يستطيع الـ mod فعله خارج كوده الخاص، مثل $.ui أو $.command أو $.fs أو $.process أو $.http.
• e، الحدث، كبيانات بسيطة: في استدعاء أداة، اسم الأداة ووسائطها.
• next، التي تمرّر الحدث إلى الـ mods الأخرى ثم إلى سلوك Claude Code نفسه، وتعيد النتيجة.

ما يفعله الخطاف بـ next يحدّد ما سيحدث. أعِد next(e) وتكون قد اكتفيت بالمراقبة. استدعِ next بنسخة معدّلة من e وتكون قد أعدت كتابة الحدث. أعِد نتيجتك الخاصة دون استدعاء next وتكون قد رددت عليه: لا تعمل الأداة أبدًا، أو لا يرسم Claude Code نسخته الخاصة أبدًا.

يسمّي التوثيق هذه الدوال خطافات أيضًا. لكنها ليست الخطافات التي تكتبها في settings.json، والتي صار Claude Code يسمّيها الآن settings hooks، أي خطافات الإعدادات.

الـ mod أم خطاف الإعدادات أم المهارة أم خادم MCP

تتداخل الأربعة، والـ mod أثقلها. اختر الأخف الذي يؤدي المهمة.

يمكن للإضافة أن تحتوي الأربعة كلها، لذا يمكن أن يُرفق الـ mod بجوار المهارة وخادم MCP اللذين يعمل معهما.

ملفات الـ mod الثلاثة

my-mod/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.ts

plugin.json هو ملف التعريف المعتاد لأي إضافة: اسم، وإصدار، ووصف. يشير hooks.json إلى الكود، { "modules": ["./register.ts"] }، مسار واحد نسبي إلى ذلك الملف. أما register.ts فهو الـ hooks module. يحمّل Claude Code ملفات .js و.ts مباشرة، دون أداة تجميع (bundler) ودون خطوة بناء، والاستيراد المجرد الوحيد المسموح به هو claude-code، للأنواع وبعض الأدوات المساعدة.

الـ mod الذي نُرفقه: من غيّر هذا الملف؟

يشغّل AgentsRoom عدة وكلاء برمجة على المستودع نفسه ويعرض، في تبويب التغييرات، أي وكيل غيّر أي ملف، لتتمكن من مراجعة عمل كل وكيل وعمل commit له على حدة. كانت الملفات المكتوبة بأداتي Edit وWrite في Claude سهلة: يبلّغ عنها Claude Code عبر خطاف إعدادات. أما الملفات التي يكتبها أمر shell فلا. فالأمر sed -i أو الـ heredoc أو الـ codemod أو rm لا يمر أبدًا عبر أداة ملفات.

قبل الـ mods، كنا نخمّن. كان AgentsRoom يقرأ سجل جلسة الوكيل ليعرف متى بدأ كل أمر Bash ومتى انتهى، ثم يطابق وقت تعديل الملف مع تلك الفترات. نجح ذلك في أغلب الأحيان، وفشل بثلاث طرق كنا نعرفها بالاسم:

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

الـ mod يُلغي التخمين. يعلّق الـ mod الخاص بنا agentsroom-changes خطافًا على tool.call لأداتي shell. قبيل تشغيل الأمر، يأخذ لقطة للمستودع (git status، إضافة إلى حجم كل مسار معدّل ووقت تعديله). وبعده مباشرة، يأخذ لقطة ثانية. المسارات التي تختلف هي ما غيّره ذلك الأمر، بما في ذلك الحذف، ويرسلها الـ mod إلى تطبيق سطح المكتب AgentsRoom عبر نقطة نهاية HTTP محلية. والاستدعاء الذي يصنّفه Claude Code نفسه للقراءة فقط لا ينسب لنفسه شيئًا.

إليك الخطاف، مختصرًا. الملف الكامل 177 سطرًا، معظمها للّقطة وحدودها.

import type { Register } from 'claude-code';

const SHELL_TOOLS = new Set(['Bash', 'PowerShell']);

export const register: Register = (on) => {
  on('tool.call', async ($, e, next) => {
    if (!SHELL_TOOLS.has(e.tool)) return next(e);
    const ready = await prepare($).catch(() => null); // agent id, repo root, snapshot
    if (!ready) return next(e);                        // outside AgentsRoom: do nothing
    const callId = e.tool_use_id;
    post($, ready.agentId, { kind: 'start', callId });
    const ran = await next(e);                         // the command runs here
    const wroteNothing = ran.deny !== undefined || ran.isReadOnly === true;
    await reportEnd($, { ...ready, callId }, wroteNothing)
      .catch(() => post($, ready.agentId, { kind: 'end', callId, paths: [] }));
    return ran;                                        // Claude sees the normal result
  });
};

ينسخ تطبيق سطح المكتب الـ mod إلى مجلده الخاص ويشغّل كل وكيل Claude باستخدام claude --plugin-dir <that folder>، فقط حين يكون Claude Code المثبّت بالإصدار 2.1.287 أو أحدث. أرفقناه في AgentsRoom 1.201.0 في 5 أكتوبر 2026.

ما تعلّمناه من إطلاقه

يجب ألا يكلّف الـ mod المستخدمَ استدعاء أداة أبدًا. يقف خطافنا أمام كل أمر shell يشغّله Claude. إن رمى خطأً، أو انتظر الشبكة، توقّف عمل Claude. كل خطوة محمية، وكل إرسال إلى تطبيق سطح المكتب ينطلق دون انتظار رد، والانتظار الوحيد الذي نقبله هو لقطتا git status، لكل واحدة منهما حد أقصى قدره 15 ثانية. الإرسال الضائع يكلّف نسبة تغيير واحد إلى وكيله، ولا يكلّف الأمر أبدًا.

لا تفعل شيئًا حين لا يُطلب منك. يقرأ الـ mod متغير بيئة يضبطه AgentsRoom لوكلائه. وحين يغيب، مثلًا لأن أحدهم نسخ المجلد إلى إعداده الخاص، يذهب كل خطاف مباشرة إلى next(e).

المجلد المحمَّل باستخدام --plugin-dir مراقَب. يعيد Claude Code تحميل الـ mod حين يتغير ملف في ذلك المجلد، وإعادة التحميل تشغّل register من جديد. وهذا ما حدّد طريقة تثبيتنا له: لا يكتب تطبيق سطح المكتب ملفًا من ملفات الـ mod إلا إذا تغيّر محتواه، لأن إعادة الكتابة العمياء عند كل تشغيل لوكيل ستعيد تحميل الـ mod في كل طرفية Claude مفتوحة أصلًا.

توقّع أن تتغير الواجهة البرمجية. يمكن أن تتغير الأحداث والدوال بين الإصدارات، والتوثيق نفسه يقول ذلك. حين يُحمَّل mod من --plugin-dir، يكتب Claude Code تعريفات الأنواع الخاصة بالإصدار العامل في .claude-plugin/types/؛ ونحن نتحقق من الأنواع مقابلها، لا مقابل صفحة ويب. وإن لم يعد إصدار ما يحمّل الـ mod الخاص بنا، فلا شيء ينكسر: لا يعلن الـ mod أبدًا أنه جاهز، ويعود AgentsRoom إلى الطريقة القديمة عبر سجل الجلسة.

اكتب الـ mod الخاص بك

لديك طريقان للبدء.

اطلب من Claude. في جلسة Claude Code تفاعلية، صِف الـ mod الذي تريده («اعرض فرع git الحالي فوق الموجّه»). يستعين Claude بمهارة مدمجة، plugin-authoring، ويكتب الـ mod في مجلد خاص بتلك الجلسة، ويسألك Claude Code مرة واحدة هل يفعّل الـ mods التي يكتبها Claude. أجب بنعم فيُحمَّل الـ mod حين تنتهي الدورة، ثم يُعاد تحميله بعد كل دورة تغيّره.

اكتب الملفات الثلاثة بنفسك، ثم:

claude --plugin-dir ./my-mod       # load it for one session, hot reload on save
claude plugin validate ./my-mod    # what Claude Code reads from it, without running it
claude plugin test                 # run the mod's *.test.ts files, no session needed

يطبع claude plugin validate سطر hooks: بالأحداث التي تعالجها وحدتك، وسطر calls: بكل دالة من واجهة برمجة الـ mods تستدعيها. إن غاب حدث كنت تنوي معالجته، فلن يستدعي Claude Code ذلك الخطاف أيضًا. للتحليل الساكن قواعد: اكتب كل استدعاء كاملًا ($.ui.toast(...)، وليس أبدًا const ui = $.ui)، ومرّر أسماء الأحداث كسلاسل نصية حرفية، ولا تستورد إلا ملفاتك الخاصة عبر مسار نسبي.

لمشاركة mod، تعامل معه كما هو، أي كإضافة: أرسل المجلد، أو أدرجه في سوق (marketplace)، وهو مستودع فيه .claude-plugin/marketplace.json، ليثبّته الناس باستخدام /plugin install <name>@<marketplace>.

mods يمكنك قراءتها اليوم

• المدمجة في Claude Code: /plugin، تبويب Installed، قسم Built-in. من بينها لوحة /diff والمحمّل الذي يقرأ AGENTS.md كتعليمات للمشروع، وتنشر Anthropic كودها المصدري في مجلد mods من مستودع anthropics/claude-code، مع اختباراتها. ومدمج أيضًا، ومعطّل إلى أن تفعّله: You should know، وكيل جانبي ينبّه إلى ما قد يكون فاتك أنت أو فات Claude.
• أمثلة Anthropic، في مستودع claude-code-playground: توقّع لنافذة السياق يُرسم فوق الموجّه، وحارس يحتجز أمر shell خطِرًا ويعرض ما كان سيغيّره، وأمر /replay يعيد عرض تعديلات الدورة الأخيرة خطوة بخطوة.
• الـ mod الخاص بنا، الموصوف أعلاه: mod بلا أي واجهة، فيه خطاف tool.call واحد، وهو شكل جيد للنسخ إن كان ما تحتاجه بيانات لا لوحة.

قبل أن تثبّت mod شخص آخر

الـ mod لا يعمل داخل صندوق رمل (sandbox). إنه يعمل بصلاحياتك: يستطيع قراءة ملفاتك وكتابتها، وقراءة متغيرات بيئتك وإعداداتك (بما فيها مفاتيح API)، وتشغيل برامج، وإرسال طلبات شبكة، ورؤية كل موجّه وكل استدعاء أداة، والموافقة على استدعاء أداة قبل أن يُطلب رأيك. وإن فعّلت صندوق الرمل في Claude Code، فهو يغطي أوامر Bash التي يشغّلها Claude، لا العمليات التي يطلقها الـ mod.

لذا اقرأ قبل أن تثبّت. استنسخ الـ mod (clone) وشغّل claude plugin validate على المجلد: يخبرك السطران hooks: وcalls: بما يستمع إليه وما يصل إليه، دون تشغيل أي شيء. الـ mod الذي يرسم شريطًا فوق الموجّه فقط لا سبب لديه لاستدعاء $.http أو $.process. ولإيقاف كل الـ mods التي ثبّتّها، ابدأ باستخدام --safe-mode لجلسة واحدة، أو ضع "disableAllHooks": true في ~/.claude/settings.json.

أين تعمل الـ mods

على الـ mod الذي يرسم أن يتحقق من مكان تشغيله وأن يرجع إلى النص حيث لا يُرسم شيء.

في AgentsRoom

لا تثبّت أي شيء: بدءًا من Claude Code 2.1.287، يبدأ كل وكيل Claude ومعه الـ mod، ويعرض تبويب التغييرات الملفات التي أنشأها كل أمر shell من أوامره أو عدّلها أو حذفها، بجوار الوكيل الذي فعل ذلك. ومع إصدار أقدم من Claude Code، يواصل AgentsRoom ربط كتابات shell بأصحابها عبر سجل الجلسة، كما من قبل.

الفكرة نفسها تعمل في واجهات CLI أخرى حيث أمكن: يحصل oh-my-pi على امتداد بالعقد نفسه، وتحتفظ واجهات CLI الأخرى بطريقتها السابقة في ربط كتابات shell بأصحابها. وإن أردت التعمق أكثر فيما يكشفه Claude Code في كل خطوة، فإن دليلنا لخطافات Claude Code يغطي خطافات الإعدادات التي يعمل الـ mod بجوارها.

الأسئلة الشائعة

ما هو الـ mod في Claude Code؟

الـ mod إضافة (plugin) لـ Claude Code تحتوي على hooks module: ملف JavaScript أو TypeScript يستدعي Claude Code دواله من داخل عمليته الخاصة حين يحدث شيء ما، مثل استدعاء أداة أو إرسال موجّه أو رسم جزء من الشاشة. تستطيع كل دالة أن تمرّر الحدث، أو تعدّله، أو تتولاه بنفسها. هذا ما يسمح للـ mod برسم لوحة، أو إضافة أمر، أو احتجاز أمر shell خطِر.

ما إصدار Claude Code الذي أحتاجه لتشغيل الـ mods؟

Claude Code 2.1.287 أو أحدث في الطرفية، الصادر في 1 أكتوبر 2026، والذي يقول سجل تغييراته «Added Claude Mods». ويدعمها تبويب Code في تطبيق Claude Desktop منذ الإصدار 2.1.286. في امتداد VS Code تعمل الخطافات، أما ما يرسمه الـ mod فيحتاج إلى الامتداد 2.1.299 أو أحدث. شغّل claude --version للتحقق.

ما الفرق بين الـ mod وخطاف Claude Code؟

الخطاف المكتوب في settings.json يشغّل أمر shell أو طلب HTTP أو موجّهًا حين يقع حدث، خارج Claude Code. أما خطافات الـ mod فهي دوال تعمل داخل Claude Code. وهي تستطيع ما لا يستطيعه خطاف الإعدادات: الرسم في الواجهة، وإضافة أمر slash يعمل دون دورة من Claude، وإعادة كتابة استدعاء أداة أو الرد عليه دون تشغيل الأداة، ومشاركة الحالة بين الخطافات.

هل تثبيت الـ mods في Claude Code آمن؟

الـ mod لا يعمل داخل صندوق رمل (sandbox). إنه يعمل بصلاحياتك، ويستطيع قراءة ملفاتك ومتغيرات بيئتك، وتشغيل برامج، وإرسال طلبات شبكة، والموافقة على استدعاء أداة. لا تثبّت إلا mods من مؤلفين تثق بهم، وشغّل أولًا claude plugin validate على المجلد: فهو يسرد الأحداث التي يعلّق عليها الـ mod خطافاته والاستدعاءات التي يجريها، دون تشغيله.

أين أجد أمثلة على mods لـ Claude Code؟

تنشر Anthropic الكود المصدري لبعض الـ mods المدمجة، مثل لوحة /diff ومحمّل AGENTS.md، في مجلد mods من مستودع anthropics/claude-code، وتنشر mods نموذجية في مستودع anthropics/claude-code-playground. والـ mod الخاص بـ AgentsRoom الموصوف في هذا المقال نوع رابع من الأمثلة: mod بلا واجهة، فيه خطاف tool.call فقط.

هل يمكنني إيقاف الـ mods؟

نعم. عطّل mod واحدًا من تبويب Installed في /plugin، أو ابدأ جلسة واحدة باستخدام --safe-mode، أو اضبط disableAllHooks على true في ~/.claude/settings.json لإيقاف كل الـ mods التي ثبّتّها، ومعها خطافات الإعدادات لديك. يترك --safe-mode وdisableAllHooks الـ mods المدمجة تعمل: هذه تُطفأ واحدًا تلو الآخر في /plugin.