خط لوله هوک

باینری precc-hook هسته PRECC است. بین Claude Code و شل قرار می‌گیرد و هر دستور bash را در کمتر از ۵ میلی‌ثانیه پردازش می‌کند.

نحوه فراخوانی هوک توسط Claude Code

Claude Code از هوک‌های PreToolUse پشتیبانی می‌کند – برنامه‌های خارجی که می‌توانند ورودی‌های ابزار را قبل از اجرا بررسی و تغییر دهند. وقتی Claude قصد اجرای دستور bash را دارد، JSON را به precc-hook از طریق stdin ارسال و پاسخ را از stdout می‌خواند.

مراحل خط لوله

Claude Code
    |
    v
+---------------------------+
| 1. Parse JSON stdin       |  Read the command from Claude Code
+---------------------------+
    |
    v
+---------------------------+
| 2. Skill matching         |  Query heuristics.db for matching skills (Pillar 4)
+---------------------------+
    |
    v
+---------------------------+
| 3. Directory correction   |  Resolve correct working directory (Pillar 1)
+---------------------------+
    |
    v
+---------------------------+
| 4. GDB check              |  Detect debug opportunities (Pillar 2)
+---------------------------+
    |
    v
+---------------------------+
| 5. RTK rewriting          |  Apply command rewrites for token savings
+---------------------------+
    |
    v
+---------------------------+
| 6. Emit JSON stdout       |  Return modified command to Claude Code
+---------------------------+
    |
    v
  Shell executes corrected command

مثال: ورودی و خروجی JSON

ورودی (از Claude Code)

{
  "tool_input": {
    "command": "cargo build"
  }
}

PRECC تشخیص می‌دهد که دایرکتوری فعلی Cargo.toml ندارد، اما ./myapp/Cargo.toml وجود دارد.

خروجی (به Claude Code)

{
  "hookSpecificOutput": {
    "updatedInput": {
      "command": "cd /home/user/projects/myapp && cargo build"
    }
  }
}

اگر نیازی به تغییر نباشد، updatedInput.command خالی است و Claude Code از دستور اصلی استفاده می‌کند.

جزئیات مراحل

مرحله ۱: تجزیه JSON

شیء JSON کامل را از stdin می‌خواند. tool_input.command را استخراج می‌کند. اگر تجزیه شکست بخورد، هوک فوراً خارج می‌شود و Claude Code از دستور اصلی استفاده می‌کند (طراحی fail-open).

مرحله ۲: تطبیق مهارت‌ها

پایگاه داده اکتشافی SQLite را برای مهارت‌هایی که الگوی فعال‌سازی آنها با دستور مطابقت دارد جستجو می‌کند. مهارت‌ها به ترتیب اولویت بررسی می‌شوند.

مرحله ۳: اصلاح دایرکتوری

برای دستورات ساخت (cargo، go، make، npm، python و غیره)، بررسی می‌کند که آیا فایل پروژه مورد انتظار در دایرکتوری فعلی وجود دارد. اگر نه، دایرکتوری‌های نزدیک را برای نزدیک‌ترین تطابق اسکن و cd <dir> && را در ابتدا اضافه می‌کند.

اسکن دایرکتوری از یک شاخص سیستم فایل کش شده با TTL پنج ثانیه‌ای برای حفظ سرعت استفاده می‌کند.

مرحله ۴: بررسی GDB

اگر احتمال دارد دستور باعث خرابی شود (مثلاً اجرای باینری debug)، PRECC می‌تواند wrapper‌های GDB را پیشنهاد یا تزریق کند تا خروجی debug ساختاریافته به جای لاگ‌های خرابی خام ثبت شود.

مرحله ۵: بازنویسی RTK

قوانین RTK (جعبه ابزار بازنویسی) را اعمال می‌کند که دستورات طولانی را کوتاه، خروجی‌های پر سر و صدا را سرکوب یا دستورات را برای بهره‌وری توکن بازسازی می‌کند.

مرحله ۶: ارسال JSON

دستور تغییریافته را به JSON سریال‌سازی کرده و روی stdout می‌نویسد. اگر تغییری ایجاد نشده باشد، خروجی به Claude Code سیگنال می‌دهد که از دستور اصلی استفاده کند.

عملکرد

کل خط لوله در کمتر از ۵ میلی‌ثانیه (p99) تکمیل می‌شود. بهینه‌سازی‌های کلیدی:

• SQLite در حالت WAL برای خواندن همزمان بدون قفل
• الگوهای regex از پیش کامپایل شده برای تطبیق مهارت‌ها
• اسکن‌های سیستم فایل کش شده (TTL پنج ثانیه‌ای)
• بدون فراخوانی شبکه در مسیر اصلی
• Fail-open: هر خطایی به دستور اصلی بازمی‌گردد

تست دستی هوک

می‌توانید هوک را مستقیماً فراخوانی کنید:

$ echo '{"tool_input":{"command":"cargo build"}}' | precc-hook
{"hookSpecificOutput":{"updatedInput":{"command":"cd /home/user/myapp && cargo build"}}}