‏ساخت اولین mod برای Claude Code از صفر

Addy Osmani تو این راهنما توضیح می‌ده که mod توی Claude Code (از نسخهٔ 2.1.287 به بعد) چیه و چطور اولینش رو بسازی. mod یه فایل کوچیک JavaScript یا TypeScript هست که داخل سشن اجرا می‌شه و هر رویداد سشن رو می‌بینه. می‌تونه رفتار Claude Code رو عوض کنه یا یه UI اختصاصی توی ترمینال یا اپ دسکتاپ بکشه. در اصل mod همون hookهایی هست که داخل plugin بسته‌بندی شدن.

ساختارش ساده‌ست: یه پوشهٔ plugin معمولی با plugin.json، یه hooks/hooks.json که به یه ماژول اشاره می‌کنه، و ماژولی که تابع register(on, options) رو export می‌کنه. هر hook یه شکل ثابت داره:

on("tool.call", { tool: "Bash" }, async ($, e, next) => {
  // $    the mods API: ui, session, state, store, fs, process, clock, http, tool, command, model, ...
  // e    this event's input, as plain data
  // next passes e to the other plugins and then to Claude Code's own behavior
  return next(e);
});

hookها مثل middleware زنجیر می‌شن. یه hook سه کار می‌تونه بکنه: مشاهده (اول next(e) رو صدا بزنه و بعد نتیجه رو نگاه کنه)، بازنویسی (یه نسخهٔ تغییریافته از رویداد رو به next بده) یا جواب دادن مستقیم (مثلاً بدون صدا زدن next یه tool call رو رد کنه). ماژول توی sandbox خودش اجرا می‌شه، بدون DOM و Node، و همه‌چی از طریق $ می‌گذره.

فرقش با hookهای settings اینه که اونا برای هر رویداد یه دستور shell اجرا می‌کنن و JSON رد و بدل می‌کنن، ولی mod یه بار لود می‌شه و توی سشن می‌مونه. یعنی می‌تونه state نگه داره، UI زنده بکشه، slash command یا ابزار جدید برای مدل ثبت کنه. خود تیم Claude Code هم بعضی قابلیت‌ها مثل پشتیبانی AGENTS.md و پنل /diff رو به شکل mod ساخته.

mod نمونهٔ این راهنما Token Weather هست: بعد از هر turn پر بودن context window (یعنی حافظه‌ای که مدل جواب رو روش می‌سازه) رو می‌خونه و توی کامپوننت AbovePrompt یه خط نشون می‌ده؛ از ☀ Clear زیر ۲۵٪ تا ↯ Compact soon بالای ۹۰٪، همراه با یه نمودار کوچیک از ۱۲ turn آخر. داده‌ها از $.session.usage() میان.

نکتهٔ مهم اینه که تاریخچه باید توی $.state نگه داشته بشه، نه متغیر ماژول، چون با هر hot reload متغیرها صفر می‌شن. این state باید توی فایل types/index.d.ts اعلام بشه، وگرنه claude plugin validate خطا می‌ده. در عوض هر $.state.set خودش نوار رو دوباره می‌کشه.

به گفتهٔ نویسنده، راه میانبر اینه که اصلاً API رو یاد نگیری: claude رو اجرا کنی و mod مورد نظرت رو توصیف کنی. Claude کد رو می‌نویسه و با اجازهٔ hot reload، mod همون موقع ظاهر می‌شه. ولی این mod فقط توی همون سشن لود می‌شه و برای نگه داشتنش باید پوشه‌ش رو کپی کنی و مثل یه plugin نصبش کنی.

نکات کلیدی:

• mod از Claude Code نسخهٔ 2.1.287 به بعد به‌صورت پیش‌فرض فعاله.
• هر hook با on(event, matcher?, hook) ثبت می‌شه و با next(e) رویداد رو به بقیهٔ زنجیره می‌ده.
• state باید توی $.state بمونه چون متغیرهای ماژول با hot reload پاک می‌شن.
• mod نمونهٔ Token Weather حدود ۸۰ خط کده و توی کامپوننت AbovePrompt نمایش داده می‌شه.
• قابلیت‌های AGENTS.md و /diff خود Claude Code هم به شکل mod ساخته شدن و سورسشون توی پوشهٔ mods/ مخزن عمومی هست.