جلوگیری از تمام شدن سریع سهمیه Claude Code با ابزار agent-usage-guard

معرفی پروژه agent-usage-guard

ابزار agent-usage-guard یک ماد کاربردی برای ابزار توسعه Claude Code است که برای حل یک مشکل آزاردهنده طراحی شده است: تمام شدن پنجره استفاده ۵ ساعته (Usage Window) تنها در چند دقیقه به دلیل اجرای موازی و کنترل‌نشده ساب‌آنت‌ها (Subagents). این ابزار با نظارت دقیق بر وضعیت سهمیه، تعداد ساب‌آنت‌ها در تمام نشست‌های سیستم و حجم کانتکست ارسالی، پیش از اینکه درخواست‌ها اعتبار شما را بسوزانند، جلوی آن‌ها را می‌گیرد.

پس‌زمینه و مشکل

بسیاری از توسعه‌دهندگان هنگام استفاده از دستورات پیچیده یا کارهای پژوهشی با Claude Code تجربه کرده‌اند که مدل به‌طور خودکار صدها ساب‌آنت موازی را راه‌اندازی کرده و میلیون‌ها توکن کانتکست را در چند دقیقه پردازش می‌کند. این اتفاق منجر به پیام آزاردهنده «Claude usage limit reached» و مسدود شدن دسترسی تا پایان بازه زمانی می‌شود. توسعه‌دهنده این پروژه (rbartoli) نیز پس از اینکه یک پرامپت پژوهشی ساده ۳۹۴ ساب‌آنت و ۸۴ میلیون توکن در ۱۰ دقیقه مصرف کرد و او را قفل نمود، تصمیم به ساخت این محافظ گرفت.

نحوه کار و ویژگی‌های فنی

این ابزار با زبان TypeScript نوشته شده و به عنوان یک ماد بومی در داخل Claude Code اجرا می‌شود. از ویژگی‌های فنی برجسته آن می‌توان به موارد زیر اشاره کرد:

• آگاهی از سهمیه (Plan-aware): میزان مصرف ۵ ساعته و هفتگی را از پاسخ‌های API می‌خواند و پیش از بحرانی شدن شرایط مداخله می‌کند.
• محافظت ماشین‌محور: تعداد ساب‌آنت‌ها و توکن‌های پردازش‌شده را در تمام نشست‌های (Sessions) فعال روی سیستم شما ردیابی می‌کند.
• حفظ حریم خصوصی: کاملاً به صورت محلی اجرا می‌شود، هیچ داده‌ای به شبکه ارسال نمی‌کند و متن پرامپت‌ها یا خروجی ابزارها را ذخیره نمی‌کند.
• شکست باز (Fails open): اگر هوک‌های این ابزار دچار خطا شوند، رویداد اصلی متوقف نمی‌شود تا کار شما مختل نگردد.

نحوه نصب و استفاده

برای نصب این ماد در نسخه‌های ۲.۱.۲۸۷ به بعد Claude Code، دستورات زیر را در ترمینال اجرا کنید:

/plugin marketplace add rbartoli/agent-usage-guard
/plugin install agent-usage-guard@agent-usage-guard
/reload-plugins

سپس با دستور /agent-guard می‌توانید وضعیت فعلی و گزارش‌های نظارتی آن را مشاهده کنید.

چرا این ابزار در Hacker News مطرح شده است؟

این پروژه با استقبال خوب مهندسان در هکرنیوز روبه‌رو شده است زیرا بسیاری از توسعه‌دهندگان با مشکل مشابهی در مصرف بی‌رویه توکن‌ها توسط ایجنت‌های هوش مصنوعی دست‌و‌پنجه نرم می‌کنند. در بحث‌های هکرنیوز، کاربران به این نکته اشاره کرده‌اند که استفاده از چنین محافظی توانسته تعداد ساب‌آنت‌های سرکش را به شدت کاهش دهد و کنترل فرآیندها را دوباره به دست برنامه‌نویس بازگرداند.

در یک نگاه

• زبان اصلی: TypeScript
• مجوز (License): MIT
• مالک/توسعه‌دهنده: rbartoli
• پلتفرم: Claude Code (ماد/پلاگین)
• هدف اصلی: جلوگیری از مصرف زودهنگام سهمیه و مدیریت ساب‌آنت‌های موازی