CodeGraph در Claude Code: نصب، دستورها و ایندکس محلی کد

CodeGraph در Claude Code (کلاد کد) یک ایندکس محلی از کد شماست: نمادها، فراخوانی‌ها و وابستگی‌ها. به‌جای این‌که Claude Code فایل‌ها را یکی‌یکی بخواند، با یک پرسش سورس مرتبط و مسیر فراخوانی را می‌گیرد. این راهنما نصب و استفادهٔ آن را مطابق README رسمی colbymchenry/codegraph می‌گوید؛ ستارهٔ ریپو در ۴ نوامبر ۲۰۲۶ حدود ۷۶٫۵ هزار و لایسنس آن MIT است.

در ادامه می‌خوانید CodeGraph دقیقاً چه می‌سازد، سه مرحلهٔ نصب چیست، کدام دستورهای CLI به درد می‌خورند، ادعاهای کارایی را چطور باید خواند، حریم خصوصی چه شکلی است و در چه شرایطی نصب نکردنش عاقلانه‌تر است. اگر مشکل‌تان API منسوخ کتابخانه‌هاست و نه ساختار ریپو، Context7 در Claude Code را بخوانید. نقشهٔ کل ابزارها هم در آموزش Claude Code آمده است.

CodeGraph را با Claude Code خودتان امتحان کنید

Claude Code را از داخل ایران با کلید نقطه وصل کنید؛ بدون فیلترشکن و کارت خارجی، با پرداخت ریالی و راه‌اندازی حدود ۵ دقیقه.

آموزش اتصال Claude Code به نقطه

پیش از نصب ابزارها، راهنمای استفاده از Claude بدون بن شدن را هم ببینید.

CodeGraph چیست و چه مشکلی را حل می‌کند؟

وقتی یک عامل هوش مصنوعی باید کدی را بفهمد، ساختار را به روش کند کشف می‌کند: grep، glob و خواندن فایل‌ها یکی‌یکی، و ساختن دستیِ مسیر فراخوانی‌ها و وابستگی‌ها. این یعنی تعداد زیادی فراخوانی ابزار و رفت‌وبرگشت قبل از این‌که کار اصلی شروع شود.

CodeGraph این مرحله را از پیش انجام می‌دهد. طبق README، یک گراف دانش از همهٔ نمادها، یال‌های فراخوانی و وابستگی‌های کد شما می‌سازد؛ پس عامل یک پرسش می‌پرسد و سورس مرتبط، مسیر فراخوانی بین آن نمادها و خلاصهٔ «محدودهٔ تأثیر» یک تغییر را یک‌جا می‌گیرد. تفاوت آن با خواندن تصادفی فایل‌ها «دقت» است، نه صرفاً سرعت.

CodeGraph چطور کار می‌کند؟

ایندکس در پوشهٔ .codegraph/ داخل پروژه ذخیره می‌شود و داخلش یک پایگاه SQLite با جست‌وجوی متنی کامل (FTS5) است. README چهار مرحله را شرح می‌دهد: استخراج نمادها و یال‌ها با parserهای tree-sitter، ذخیره در SQLite، حل ارجاع‌ها (فراخوانی به تعریف، import به فایل مبدأ، وراثت) و همگام‌سازی خودکار.

همگام‌سازی خودکار به‌طور پیش‌فرض روشن است: یک watcher با رویدادهای سیستم‌عامل تغییر فایل‌ها را می‌بیند، بعد از یک پنجرهٔ آرام کوتاه (پیش‌فرض ۲ ثانیه) ایندکس را تازه می‌کند، و هنگام اتصال دوباره‌ی سرور هم تغییرهای بین دو نشست را جبران می‌کند. پس بعد از ساختن ایندکس لازم نیست دوباره ایندکس کنید. ابزار MCP پیش‌فرض یکی است: codegraph_explore، که کد مرتبط، مسیر فراخوانی و خلاصهٔ «محدودهٔ تأثیر» را برمی‌گرداند. ابزارهای ریزتر مثل codegraph_callers و codegraph_impact هنوز هستند ولی به‌طور پیش‌فرض در فهرست نیامده‌اند، چون خروجی‌شان از قبل داخل codegraph_explore می‌آید.

زبان‌ها و فریم‌ورک‌ها

طبق README، پوشش زبانی CodeGraph گسترده است: بیش از ۲۰ زبان از جمله TypeScript، JavaScript، Python، Go، Rust، Java، C#، PHP، Ruby، Swift و Kotlin، و چند قالب مثل Vue و Svelte. بخش «Framework-aware Routes» هم می‌گوید الگوهای مسیر (route) در ۱۷ فریم‌ورک وب شناسایی و به handler مربوط وصل می‌شود، یعنی پرسش «این URL به کدام تابع می‌رسد؟» هم در محدودهٔ کار است. قبل از نصب، فهرست کامل زبان‌ها را در README نگاه کنید؛ اگر زبان اصلی پروژه‌تان آنجا نیست، ایندکس ارزشی نمی‌دهد.

قبل از codegraph install، Claude Code وصل باشد

codegraph install فقط Claude Codeِ نصب‌شده را پیدا می‌کند. اگر هنوز راهش نینداخته‌اید، اول با کلید نقطه وصلش کنید.

راه‌اندازی Claude Code با نقطه

نصب CodeGraph در Claude Code (سه مرحله)

مرحلهٔ ۱: نصب CLI

یک اسکریپت نصب (پیش از اجرا بخوانیدش، چون از اینترنت می‌آید و اجرا می‌شود):

curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

README می‌گوید این روش به Node.js نیاز ندارد، runtime خودش را همراه دارد و چیزی build نمی‌شود. بعد از نصب، ترمینال تازه باز کنید تا codegraph در PATH بیاید. اگر Node دارید، جایگزین رسمی npm i -g @colbymchenry/codegraph است. به‌روزرسانی هم با codegraph upgrade انجام می‌شود (با --check فقط بررسی می‌کند).

مرحلهٔ ۲: اتصال به عامل‌ها (یک بار برای همهٔ پروژه‌ها)

codegraph install

نصب‌کننده Claude Code و عامل‌های دیگر را تشخیص می‌دهد، پیکربندی MCP می‌نویسد و یک بخش کوچک در CLAUDE.md می‌گذارد تا زیرعامل‌ها دستور codegraph explore را بشناسند. برای Claude Code مجوزهای خودکار هم تنظیم می‌کند (با --no-permissions می‌توان رد کرد). README تأکید می‌کند این مرحله فقط عامل را وصل می‌کند و هیچ کدی را ایندکس نمی‌کند. بعد از آن Claude Code را دوباره باز کنید تا سرور MCP بارگذاری شود.

مرحلهٔ ۳: ایندکس هر پروژه

cd your-project
codegraph init

این یک دستور هم .codegraph/ را می‌سازد و هم گراف را کامل می‌کند. این مرحله را برای هر پروژه یک‌بار انجام می‌دهید، در حالی که مرحلهٔ ۲ فقط یک‌بار برای همهٔ پروژه‌هاست.

دستورهای مفید CLI

از CLI Reference رسمی:

codegraph status              # آمار ایندکس
codegraph query <search>      # جست‌وجوی نمادها
codegraph explore <query>     # همان خروجی ابزار MCP
codegraph callers <symbol>    # چه کسی این تابع را صدا می‌زند
codegraph callees <symbol>    # این تابع چه چیزهایی را صدا می‌زند
codegraph impact <symbol>     # تغییر این نماد چه چیزهایی را تحت تأثیر می‌گذارد
codegraph affected [files...] # تست‌های متأثر از تغییر
codegraph upgrade --check     # بررسی نسخهٔ جدید

codegraph init --local-only پوشهٔ .codegraph/ را از گیت دور نگه می‌دارد. در غیر این صورت خودتان آن را در .gitignore بگذارید.

دستور affected و تست‌های مرتبط

یکی از کاربردی‌ترین دستورها codegraph affected است: وابستگی‌های import را به‌صورت تعدی دنبال می‌کند و می‌گوید کدام فایل‌های تست از تغییر شما اثر می‌پذیرند. README آن را حتی در قالب یک اسکریپت CI یا hook نشان می‌دهد که فقط تست‌های مرتبط را اجرا می‌کند:

git diff --name-only | codegraph affected --stdin
codegraph affected src/auth.ts --filter "e2e/*"

اگر مجموعهٔ تست‌های پروژه‌تان بزرگ است، این دستور می‌تواند نتیجهٔ سریع‌تری بدهد؛ ولی خروجی آن بر پایهٔ تحلیل import است و ممکن است وابستگی‌های پویا را کامل نبیند، پس برای انتشار نهایی همچنان مجموعهٔ کامل تست‌ها را اجرا کنید.

یک مثال پرسش در Claude Code

در Claude Code بپرسید: «ورود کاربر از کدام فایل شروع می‌شود و به کدام توابع می‌رسد؟» اگر CodeGraph فعال باشد، Claude باید به‌جای grep چندمرحله‌ای، codegraph_explore را صدا بزند و سورس نمادهای مرتبط را یک‌جا بگیرد. اگر ابزار صدا زده نشد، در CLAUDE.md بنویسید که برای پرسش دربارهٔ ساختار کد از CodeGraph استفاده کند. (دربارهٔ CLAUDE.md در مستندات رسمی Claude Code بخش «memory» را ببینید؛ فایل شما هر نشست خوانده می‌شود، پس کوتاه و دقیق بنویسید.)

چه پرسش‌هایی بهتر جواب می‌گیرند؟

پرسش‌هایی که چند فایل و چند لایه را می‌پوشانند: «این endpoint چه چیزهایی را صدا می‌زند؟»، «اگر این تابع را عوض کنم چه چیزی می‌شکند؟» (codegraph impact)، «کدام تست‌ها به این تغییر مربوط‌اند؟» (codegraph affected). پرسش‌های بسیار محلی («این خط چه می‌کند؟») به ایندکس نیاز ندارند و خواندن مستقیم فایل کافی است.

مقایسه: با CodeGraph یا بدون آن؟

ادعاهای کارایی: با احتیاط بخوانید

README اندازه‌گیری ۵ اوت ۲۰۲۶ روی ۷ ریپوی متن‌باز را گزارش می‌کند (میانهٔ ۴ اجرا، یک پرسش معماری، عامل Claude Code) و می‌گوید در همهٔ ریپوها تعداد فراخوانی ابزار، زمان و توکن کمتر شد؛ مثلاً ۸۸٪ فراخوانی کمتر، ۶۲٪ توکن کمتر و ۴۴٪ ارزان‌تر، و تفاوت هزینه به‌شدت به نوع پرسش بستگی داشت (در یکی از ریپوها فقط حدود ۱۳٪). همان README می‌پذیرد که بعد از پاسخ، context بیشتری اشغال می‌شود.

این‌ها نتیجهٔ خود سازنده است، نه آزمون مستقل. دو نکتهٔ مهم برای تفسیر: اول، فقط یک نوع پرسش (معماری) سنجیده شده است؛ دوم، هزینهٔ «رسیدن به جواب» با «فضای باقی‌مانده در context بعد از جواب» دو چیز متفاوت‌اند. روی پروژهٔ خودتان با یک پرسش واقعی قبل و بعد مقایسه کنید. اگر هدفتان کم‌کردن مصرف در کل است، راهنمای کاهش مصرف توکن روش‌های دیگری هم دارد.

تنظیمات و فایل‌های نادیده‌گرفته‌شده

README می‌گوید CodeGraph «تقریباً بدون پیکربندی» کار می‌کند. پوشه‌های وابستگی و build مثل node_modules و dist را به‌طور پیش‌فرض کنار می‌گذارد، هر چیزی را که در .gitignore باشد رعایت می‌کند و فایل‌های بزرگ‌تر از ۱ مگابایت را ایندکس نمی‌کند. اگر پوشه‌ای در گیت هست ولی نمی‌خواهید در گراف بیاید (مثلاً یک theme یا SDK کپی‌شده)، فایل codegraph.json کلید exclude را دارد. در مقابل، اگر کد واقعی‌ای عمداً در .gitignore است، با include برش می‌گردانید.

حریم خصوصی و telemetry

README می‌گوید CodeGraph آمار استفادهٔ ناشناس جمع می‌کند (کدام ابزار یا دستور استفاده شد، کدام زبان‌ها ایندکس شدند) و هرگز کد، مسیر، نام فایل یا نماد، پرسش یا IP را نمی‌فرستد. نصب‌کننده از شما می‌پرسد؛ هر زمان می‌توانید خاموش کنید:

codegraph telemetry off

(یا متغیر CODEGRAPH_TELEMETRY=0 / DO_NOT_TRACK=1.) برای کار روی کد محرمانه، همین را فعال کنید. خود ایندکس همیشه محلی است و در README تأکید شده که کدتان از دستگاه بیرون نمی‌رود.

عیب‌یابی رایج

• «CodeGraph not initialized». در پوشهٔ پروژه codegraph init را اجرا کنید.
• سرور MCP وصل نمی‌شود. مطمئن شوید پروژه ایندکس شده (codegraph status) و اگر لازم شد دوباره codegraph install بزنید تا پیکربندی بازنویسی شود. بعد Claude Code را ببندید و باز کنید؛ داخل آن هم با /mcp وضعیت سرورها را ببینید.
• نمادی در نتیجه نیست. چند ثانیه صبر کنید تا همگام‌سازی تمام شود؛ لازم شد codegraph sync بزنید و بررسی کنید فایل در پوشهٔ نادیده‌گرفته‌شده یا .gitignore نباشد.
• خطای قفل پایگاه یا کندی روی دیسک شبکه‌ای. README می‌گوید پروژه (و پوشهٔ .codegraph/) را روی دیسک محلی بگذارید، نه share شبکه‌ای.

حذف CodeGraph

codegraph uninstall تنظیمات را از همهٔ عامل‌ها و خود CLI را حذف می‌کند (--keep-cli برای نگه‌داشتن CLI). ایندکس پروژه‌ها دست نمی‌خورد؛ هر پروژه را با codegraph uninit پاک کنید.

چک‌لیست پس از نصب

1. codegraph status را در ریشهٔ پروژه اجرا کنید و ببینید ایندکس ساخته شده.
2. Claude Code را دوباره باز کنید و بپرسید «ساختار پوشه‌ها و ورودی اصلی پروژه چیست؟».
3. ببینید codegraph_explore صدا زده شد یا نه.
4. .codegraph/ را در .gitignore بگذارید یا با --local-only init کنید.
5. تصمیم دربارهٔ telemetry را ثبت کنید.

CodeGraph کنار بقیهٔ ابزارها

CodeGraph فقط «فهم ساختار ریپو» را پوشش می‌دهد. برای این‌که مدل API منسوخ ننویسد، به مستندات نسخه‌دار نیاز دارید که کار یک ابزار دیگر است (مقایسهٔ Context7 و CodeGraph). برای کوتاه‌کردن خروجی دستورهای ترمینال می‌توانید RTK را ببینید. این ابزارها مستقل‌اند و هر کدام را می‌توانید جدا امتحان کنید. نصب همهٔ آن‌ها در راهنمای نصب ابزارهای Claude Code یک‌جا آمده، و تصویر کلی از اکوسیستم در راهنمای کامل Claude Code است.

جمع‌بندی

CodeGraph اگر روی ریپوی بزرگ و پرسش‌های ساختاری استفاده شود می‌تواند تعداد گام‌های عامل را کم کند؛ برای فایل‌های کوچک و پرسش‌های ساده لازم نیست. سه دستور (install یک‌بار، init برای هر پروژه) همهٔ نصب است و ایندکس خودش تازه می‌ماند. ادعاهای درصدی را مال سازنده بدانید و با یک پرسش واقعی خودتان بسنجید.

کلید API نقطه با پلن پرو باز می‌شود

یک کلید برای Sonnet و Opus، با داشبورد مصرف زنده؛ همان چیزی که برای سنجیدن CodeGraph روی ریپوی واقعی لازم دارید.

دیدن پلن‌های پرو

این مقاله چگونه بررسی شد؟

دستورهای نصب و ویژگی‌ها از README رسمی ابزار (و برای مفاهیم Claude Code از مستندات code.claude.com) برداشته شد و در ۱۳ آبان ۱۴۰۵ (۴ نوامبر ۲۰۲۶) دوباره با نسخهٔ فعلی ریپو مقایسه شد. ستاره‌ها و لایسنس از API گیت‌هاب همان روز آمده است. هر جا ادعایی از خود سازنده است («۸۸٪ فراخوانی کمتر»، «۴۴٪ ارزان‌تر») همین را نوشته‌ایم و آن را اندازه‌گیری مستقل نمی‌دانیم. اگر دستوری در نسخهٔ شما فرق داشت، README همان نسخه معتبرتر است.

← فهم کد و مستندات · راهنمای کامل

---

منابع: README رسمی CodeGraph، مستندات MCP در Claude Code. تاریخ بررسی: ۱۳ آبان ۱۴۰۵ (۴ نوامبر ۲۰۲۶).