Graft: coding agents کے لیے codebase map کیا ہے

کوڈنگ ایجنٹس کے لیے codebase map کیا ہے

کوڈنگ ایجنٹس کے لیے codebase map آپ کی repository کا ایک مستقل index ہے۔ نیا session شروع ہونے پر ایجنٹ ہر بار ابتدا سے grep کے ذریعے تلاش کرنے کے بجائے اسی index سے مطلوبہ معلومات حاصل کرتا ہے۔ Graft اس تصور کی ایک implementation ہے۔ یہ tree-sitter کے ذریعے آپ کے code کو parse کرتا ہے، linked markdown nodes پر مشتمل ایک folder اور ہر symbol کے درمیان روابط کا graph لکھتا ہے، اور MCP (model context protocol، وہ standard interface جسے coding agents بیرونی tools کو call کرنے کے لیے استعمال کرتے ہیں) کے ذریعے retrieval tools فراہم کرتا ہے۔

Graft نہ proxy ہے اور نہ gateway۔ آپ کے agent اور model API کے درمیان کوئی درمیانی component موجود نہیں ہوتا۔ map ڈسک پر موجود ایک folder ہوتا ہے جسے agent پڑھتا ہے۔ یہ فرق طے کرتا ہے کہ آپ کون سا مسئلہ حل کر رہے ہیں: self-hosted token gateway ان requests کی پیمائش اور routing کرتا ہے جو آپ پہلے ہی بھیجتے ہیں، جبکہ map اس بات کو تبدیل کرتا ہے کہ آپ کو مجموعی طور پر کتنی requests بھیجنے کی ضرورت ہے۔

یہ تکنیک اس tool سے پرانی ہے اور اس tool کے بعد بھی برقرار رہے گی۔ پہلے تکنیک سمجھیں، پھر اس کے عملی طریقۂ کار کو سیکھیں۔

کوڈنگ ایجنٹس ساخت دوبارہ دریافت کرنے میں context کیوں ضائع کرتے ہیں

کسی ایسے repository پر ایجنٹ کو کام شروع کرتے دیکھیں جسے وہ پہلے پچاس بار دیکھ چکا ہے۔ وہ directories کی فہرست بناتا ہے۔ کسی symbol کے لیے grep کرتا ہے۔ یہ معلوم کرنے کے لیے تین files کھولتا ہے کہ function کہاں define ہے، پھر یہ جاننے کے لیے چوتھی file کھولتا ہے کہ اسے کون call کرتا ہے۔ ان میں سے کوئی بھی اصل task نہیں ہے۔ یہ صرف orientation ہے، اور ہر session میں اس کی قیمت input tokens سے ادا ہوتی ہے۔

وجہ سادہ ہے۔ ایک model کو sessions کے درمیان memory حاصل نہیں ہوتی۔ ایجنٹ نے آپ کے layout کے بارے میں جو کچھ سیکھا تھا، وہ سب ایک context window میں تھا، جو session ختم ہونے پر ضائع ہو گئی۔ اس لیے وہی discovery دوبارہ صفر سے شروع ہوتی ہے، اور ہر بار پوری قیمت ادا ہوتی ہے۔ بڑے repository میں orientation phase کی لاگت edit سے زیادہ ہوتی ہے: code تلاش کرنے کے لیے دس tool calls، اور اسے تبدیل کرنے کے لیے ایک۔ یہ لاگت دو حصوں پر مشتمل ہے، اسی لیے ایسی skill جو ایجنٹ کو کام کرنے والی کم سے کم تبدیلی تک محدود رکھتی ہے کو map کے ساتھ استعمال کرنا، ان دونوں میں سے کسی ایک کا انتخاب کرنے سے بہتر ہے۔

Map discovery کو model سے ہٹا کر disk پر منتقل کرکے اس چکر کو توڑ دیتا ہے۔ ایک parser repository کو ایک بار scan کرتا ہے، یہ record کرتا ہے کہ کون سا symbol کہاں define ہے اور کون سا symbol کس کو call کرتا ہے، پھر code تبدیل ہونے کے ساتھ اس record کو تازہ رکھتا ہے۔ ایجنٹ ایک سوال پوچھتا ہے اور اسے file اور line کے ساتھ جواب مل جاتا ہے۔ بار بار exploration کرنا ایک سستی lookup میں بدل جاتا ہے۔

آپ پہلے ہی اس کا ایک کمزور version استعمال کرتے ہیں۔ ایک AGENTS.md جو آپ کے conventions بیان کرتی ہے ایجنٹ کو ہر بار آپ کے conventions دوبارہ اخذ کرنے سے روکتی ہے۔ Generated map اسے آپ کی structure دوبارہ اخذ کرنے سے روکتا ہے۔ فرق یہ ہے کہ اسے کون لکھتا ہے۔ آپ instruction file خود لکھتے ہیں، اس لیے وہ مختصر رہتی ہے۔ Parser map generate کرتا ہے، اس لیے وہ دس ہزار files کا احاطہ کر سکتا ہے۔ Session کے اندر budget حقیقتاً کہاں خرچ ہوتا ہے، اس کی تفصیل کے لیے Claude Code اپنی context window کیسے استعمال کرتا ہے accounting پیش کرتا ہے۔

Graft اصل میں کیا بناتا ہے

دو artefacts، دونوں repository root میں موجود ایک ہی graft/ folder کے اندر۔

پہلا artefact linked markdown کی صورت میں node graph ہے، جس میں ہر node کے لیے ایک file ہوتی ہے۔ ہر node میں سادہ انگریزی خلاصہ، source سے اخذ کی گئی اہم logic lines کا "crux"، content hash کے ساتھ exact source files، دوسرے nodes کے typed wikilinks (depends_on، part_of، uses، implements)، اور notes section شامل ہوتا ہے۔ یہ notes regeneration کے بعد بھی برقرار رہتا ہے، تاکہ آپ وہ context درج کر سکیں جس کا parser خود اندازہ نہیں لگا سکتا۔

دوسرا artefact graft/.graph/wiring.json ہے، یعنی ہر symbol کا structural graph جسے tree-sitter extract کرتا ہے: definitions، references اور ان کے درمیان call edges۔

یہ تقسیم اس لیے اہم ہے کہ صرف ایک حصے کو model درکار ہوتا ہے۔ graft build مکمل طور پر tree-sitter پر مبنی ہے اور کبھی LLM (large language model) کو call نہیں کرتا، اس لیے اس کا نتیجہ deterministic ہوتا ہے اور کوئی لاگت نہیں آتی۔ graft build --deep تحریری summaries اور ہر symbol کے cruxes شامل کرتا ہے، اور ان کے لیے model calls درکار ہوتی ہیں جن کی آپ ادائیگی کرتے ہیں۔

Language support درجات میں تقسیم ہے، اور tier سے معلوم ہوتا ہے کہ call graph پر کس حد تک اعتماد کیا جا سکتا ہے۔ TypeScript، JavaScript، Python، Go اور Java کو scope-aware cross-file resolution حاصل ہوتی ہے۔ Rust، C، C++، C#، Ruby، PHP، Kotlin، Scala، Swift، Elixir، Solidity، OCaml، Zig اور Dart کو symbols اور generic call edges حاصل ہوتے ہیں۔ اس کا مطلب ہے کہ کوئی edge resolved reference کے بجائے name match بھی ہو سکتا ہے۔ Compiler-grade edges کے لیے --lsp اور کسی language server جیسے rust-analyzer یا gopls کو opt-in طور پر فعال کرنا ضروری ہے۔

Graft انسٹال کریں اور ورژن کو مقرر کریں

Graft کے لیے Node.js 20 یا اس کے بعد کا ورژن درکار ہے، اور اس کا لائسنس MIT ہے۔ August 2026 تک موجودہ release 0.10.1 ہے، جبکہ پہلی شائع شدہ version 0.1.0، July 2026 کی ہے۔ اسے نیا software سمجھ کر استعمال کریں۔

npm install -g @nanonets/graft@0.10.1
npm ls -g @nanonets/graft

npm ls -g کو @nanonets/graft@0.10.1 دکھانا چاہیے۔ اس version کو جان بوجھ کر مقرر کریں۔ سادہ npm install -g @nanonets/graft، اسے چلانے کے وقت latest tag resolve کرتا ہے۔ اگر کوئی project ہر ماہ کئی minor releases جاری کرتا ہو، تو اس صورت میں منگل کو آپ کے پاس وہ tool ہوگا جو آپ کے ساتھی نے پیر کو انسٹال نہیں کیا تھا۔ مقررہ version سے سب کے لیے CLI flags اور graph format یکساں رہتے ہیں۔ اس طرح upgrade آپ کے فیصلے کے مطابق ہوتا ہے۔

اب اسے اپنی ملکیت والی repository کے ساتھ مربوط کریں:

cd /path/to/your/repo
graft init --dry-run
graft init

graft init آپ سے پوچھتا ہے کہ آپ کے coding agents میں سے کن agents کو مربوط کرنا ہے، پھر graph بناتا ہے۔ پہلے --dry-run چلائیں اور ان files کی فہرست پڑھیں جنہیں یہ تبدیل کرنے کا ارادہ رکھتا ہے، کیونکہ ان میں سے کچھ repository سے باہر بھی ہو سکتی ہیں۔ graft init idempotent ہے اور موجودہ configs کو overwrite نہیں کرتا، اس لیے اسے دوسری بار چلانا محفوظ ہے۔

August 2026 تک یہ wiring Claude Code، Cursor، Codex، GitHub Copilot، Google Gemini، Kiro، Windsurf اور AdaL کو support کرتی ہے۔ Claude Code کو سب سے گہری integration ملتی ہے: ایک MCP server entry، graph کے سائز اور پرانے پن کو دکھانے والی statusline، graph دوبارہ بنانے والے post-edit hooks، اور .claude/ کے تحت ایک skill file۔ باقی agents کو ایک instruction یا rule file ملتی ہے جو agent کو بتاتی ہے کہ یہ tools موجود ہیں۔ اس لیے "Supported" کا مطلب یہ ہے کہ Graft wiring لکھتا ہے۔ اگر کوئی agent اپنی rule file کو نظرانداز کرے، تو وہ map کو بھی نظرانداز کرے گا۔ یہی عام وجہ ہے کہ agents آپ کی لکھی ہوئی ہدایات کو نظرانداز کرتے ہیں، اور یہاں بھی یہی اصول لاگو ہوتا ہے۔

آپ کی repository میں کیا شامل ہوتا ہے، اور git سے باہر کیا رہتا ہے

graft init کے بعد آپ کو یہ چیزیں نظر آئیں گی:

• graft/: markdown node graph اور graft/.graph/wiring.json۔ یہ آپ کے لیے .gitignore میں شامل کر دی جاتی ہے۔
• .mcp.json: graft MCP server کو register کرتا ہے تاکہ Claude Code اسے شروع کرے۔
• .claude/settings.json: موجودہ جگہ پر merge کیا جاتا ہے اور statusline اور post-edit hooks شامل کرتا ہے۔
• AGENTS.md، GEMINI.md، .github/copilot-instructions.md، .cursor/rules/graft.mdc، .kiro/steering/graft.md، .windsurf/rules/graft.md اور .adal/skills/graft/SKILL.md: marker-fenced sections، جو آپ کے منتخب کردہ agents کے مطابق متعلقہ files کے آخر میں شامل کیے جاتے ہیں۔
• ~/.codex/config.toml، ~/.codex/hooks.json اور ~/.codex/hooks/graft/graft-hooks.cjs: پورے machine کے لیے ہوتے ہیں اور صرف اس وقت لکھے جاتے ہیں جب آپ Codex منتخب کریں۔ graft init --no-global انہیں چھوڑ دیتا ہے، جبکہ graft init --no-hooks صرف hook shim کو چھوڑتا ہے۔

یہ graph ایک cache ہے، بالکل node_modules کی طرح۔ اسے commit نہ کریں۔ یہ code سے چند seconds میں دوبارہ بن جاتا ہے، تقریباً ہر edit کے بعد تبدیل ہوتا ہے، اور اسے commit کرنے سے ایک سطر کی fix کئی سو files کے diff میں بدل جاتی ہے جسے کوئی reviewer نہیں پڑھے گا۔ اس کے بجائے wiring کو commit کریں، جس میں AGENTS.md اور .mcp.json بھی شامل ہیں۔ کوئی teammate repository clone کر کے graft build چلاتا ہے اور اپنا local graph حاصل کر لیتا ہے۔

پہلے commit سے قبل تصدیق کریں کہ ignore rule شامل ہو چکا ہے:

grep -n graft .gitignore
git status --short

grep کو ایسی line دکھانی چاہیے جس میں graft/ شامل ہو، جبکہ git status --short کو graft/ کے تحت کچھ بھی list نہیں کرنا چاہیے۔ اگر اس output میں graft/ کے تحت files نظر آئیں تو اس کا مطلب ہے کہ ignore entry موجود نہیں یا کہیں اور override ہو رہی ہے۔ commit کرنے سے پہلے اسے درست کریں، کیونکہ git کسی file کو add کیے جانے کے بعد track کرتا رہتا ہے، اور بعد میں .gitignore کو edit کرنے سے وہ file untrack نہیں ہوتی۔

اگر آپ MCP server کو ہاتھ سے register کرنا چاہتے ہیں، یا اسے اسی version تک محدود رکھنا چاہتے ہیں جو آپ نے install کیا ہے، تو entry مختصر ہے:

{
  "mcpServers": {
    "graft": {
      "command": "npx",
      "args": ["-y", "@nanonets/graft@0.10.1", "mcp"]
    }
  }
}

وہ retrieval tools جنہیں آپ کا agent grep کے بجائے استعمال کرتا ہے

Graft، MCP کے ذریعے چھ tools فراہم کرتا ہے۔ graft_find_code کسی task description کے لیے file اور line کے ساتھ ranked nodes واپس کرتا ہے۔ graft_file_api کسی file میں موجود ہر signature کو bodies کے بغیر واپس کرتا ہے۔ graft_trace_calls callers یا callees کو کئی levels تک traverse کرتا ہے۔ graft_find_all regex matches کو symbol کے لحاظ سے group کر کے واپس کرتا ہے۔ graft_repo_map کسی نامانوس repository کا ابتدائی جائزہ فراہم کرتا ہے۔ graft_check_freshness بتاتا ہے کہ graph اب بھی code سے مطابقت رکھتا ہے یا نہیں۔

ہر tool کا ایک CLI twin بھی ہے۔ اسی سے آپ جانچتے ہیں کہ آپ کے agent کو حقیقت میں کیا فراہم کیا جا رہا ہے:

graft map .
graft ask "where do we validate the refresh token"
graft skeleton src/auth/session.ts
graft callers validateRefreshToken
graft callers validateRefreshToken --direction out
graft grep "refresh_token" --json

graft ask کو file:line references کے ساتھ ranked nodes print کرنے چاہییں، file contents نہیں۔ یہی پورا mechanism ہے: agent کو ایک pointer ملتا ہے اور وہ درست file کھولتا ہے، بجائے اس کے کہ صحیح file تلاش کرنے کے لیے دس files پڑھے۔ اگر آپ خود graph دیکھنا چاہیں تو graft viz localhost پر interactive viewer کھولتا ہے۔ اگر کسی ایسے سوال کے لیے، جس کا جواب آپ تیس seconds میں دے سکتے ہیں، graft ask کوئی مفید نتیجہ واپس نہ کرے تو graph stale ہے یا آپ کی language broad tier میں شامل ہے، اور یہ map آپ کے agent کی بھی مدد نہیں کرے گا۔

ایک لاگت آسانی سے نظرانداز ہو جاتی ہے۔ پورے session کے دوران ہر request کے system prompt میں چھ tool definitions inject کی جاتی ہیں۔ agent map استعمال کرے یا نہ کرے، یہ لاگت ادا کرنا پڑتی ہے۔ اگر repository اتنی چھوٹی ہو کہ context میں سما جائے تو یہ fixed charge اس exploration سے زیادہ ہو سکتا ہے جسے map کم کرتا ہے۔

کوڈ تبدیل ہونے پر گراف کے ساتھ کیا ہوتا ہے

ساختی refresh سستا اور خودکار ہے۔ Graft git کے بجائے آپ کی working tree پڑھتا ہے، اس لیے ایسی edit جو آپ نے commit نہیں کی اور ایسی edit جو آپ نے stage کر دی ہے، دونوں اسے یکساں طور پر نظر آتی ہیں۔ کوئی query صرف ان files کو دوبارہ parse کرتی ہے جن کا stat تبدیل ہوا ہو۔ Project documentation کے مطابق اس اضافی عمل میں تقریباً 3 ms لگتے ہیں۔ turn-end rebuild صرف ان files کو process کرتا ہے جہاں code منتقل ہوا ہو۔ GRAFT_NO_REFRESH=1 set کریں یا --no-refresh pass کریں تاکہ دوبارہ parse کیے بغیر disk پر موجود graph سے جواب دیا جائے۔ ہر چیز کو مکمل طور پر دوبارہ parse کرنے کے لیے --no-reuse pass کریں۔ Graft کو خود upgrade کرنے کے بعد یہی طریقہ استعمال کرنا چاہیے۔

Model کی تیار کردہ معلومات کا حصہ مختلف انداز میں کام کرتا ہے، اور خاموشی سے خرابی عموماً اسی حصے میں آتی ہے۔ Summaries اور cruxes cache کی جاتی ہیں۔ ہر node اپنے sources کا content hash محفوظ کرتا ہے۔ اس لیے source file تبدیل ہونے پر node کو موجودہ حالت میں دکھانے کے بجائے stale mark کیا جاتا ہے۔ یہ flag صرف اسی وقت مفید ہے جب کوئی اس پر عمل کرے۔ graft build --deep سے refresh کریں۔ اس عمل میں model tokens دوبارہ خرچ ہوتے ہیں۔

Staleness کو نمایاں کریں:

graft check .
echo $?

Exit status 0 کا مطلب ہے کہ graph code سے مطابقت رکھتا ہے۔ Exit status 1 کا مطلب ہے کہ drift موجود ہے۔ اسے pre-push hook سے، یا CI میں branch پر، چلائیں تاکہ چھ ماہ پرانا map مارچ میں دوبارہ لکھے گئے code کے بارے میں اعتماد کے ساتھ جواب نہ دے۔

شائع کردہ benchmark اعداد کو احتیاط سے پڑھیں

Graft کا مرکزی دعویٰ ہے: "up to 4x cheaper and 3x faster, with better or no loss of correctness"۔ یہ اعداد project کے اپنے benchmarks سے لیے گئے ہیں، جو اس کے README میں شائع ہوئے ہیں۔ ذیل میں اس کی رپورٹ کردہ دونوں runs مکمل طور پر دی گئی ہیں۔

[
  {
    "label": "Controlled sweep",
    "run_count": 162,
    "token_saving_pct": 42,
    "tool_call_saving_pct": 46,
    "correctness_pct": 93,
    "baseline_correctness_pct": 93
  },
  {
    "label": "SWE-bench Verified",
    "run_count": 50,
    "token_saving_pct": 23,
    "tool_call_saving_pct": 25,
    "correctness_pct": 66,
    "baseline_correctness_pct": 54
  }
]

کنٹرول شدہ sweep میں دو repositories پر 162 runs شامل ہیں، جن میں سے ایک خود Graft کی repository ہے، اور ہر task کے لیے تین trials کیے گئے ہیں۔ اس میں 42% کم tokens اور 46% کم tool calls رپورٹ کیے گئے ہیں۔ SWE-bench Verified run میں 50 instances شامل ہیں، دونوں arms میں ایک ہی model استعمال کیا گیا ہے، اور اس میں کم بچت رپورٹ ہوئی: tokens میں 23% اور tool calls میں 25%۔ ایک تیسرے run میں پانچ merged PocketBase pull requests دوبارہ چلائی گئیں۔ اس کی لاگت 11.02 US dollars تھی، جبکہ baseline کی لاگت 13.91 تھی۔

ان تمام نتائج کو vendor benchmark سمجھیں۔ دو باتیں اس سے اخذ کیے جانے والے نتائج کو محدود کرتی ہیں۔ کنٹرول شدہ sweep میں Graft کی اپنی repository شامل ہے، یعنی وہ codebase جس کے مطابق اس کے مصنفین نے tool کو tune کیا۔ SWE-bench Verified معروف open-source Python projects کے issues پر مشتمل ایک public dataset ہے، اور public datasets وہی ہوتے ہیں جن کے لیے tools optimize کیے جاتے ہیں، چاہے یہ جان بوجھ کر نہ بھی کیا گیا ہو۔ ان میں سے کوئی بھی نتیجہ آپ کے private monorepo کے بارے میں بیان نہیں ہے، کیونکہ اس کے naming conventions اور dead code اپنی نوعیت کے ہو سکتے ہیں۔

Correctness کو دوبارہ غور سے دیکھنا چاہیے۔ کنٹرول شدہ sweep میں یہ تبدیل نہیں ہوئی: map کے ساتھ 93%، جبکہ map کے بغیر 93%۔ 66% تک اضافہ صرف SWE-bench Verified میں نظر آتا ہے، جہاں baseline نتیجہ 54% تھا۔ جو tool آپ کا token bill کم کرے اور quality کو برقرار رکھے، وہ پھر بھی ایک اچھا تبادلہ ہے۔ لیکن SWE-bench کی correctness کو sweep کے token نتیجے پر لاگو نہ کریں اور دونوں کو ایک ہی دعوے کے طور پر پیش نہ کریں۔

اپنے token delta کی پیمائش کریں، پھر اس نتیجے پر یقین کریں

اہم واحد عدد آپ کے repository سے حاصل ہونے والا عدد ہے۔ اس طریقے میں ایک دوپہر لگتی ہے۔

ایسا task منتخب کریں جسے آپ بالکل اسی طرح دوبارہ چلا سکیں۔ سوال، edit سے بہتر ہے، کیونکہ edit repository کو تبدیل کر دیتا ہے اور دوسری run پھر وہی experiment نہیں رہتی۔ "login route پر rate limit نافذ کرنے والا module کون سا ہے؟" سوال کی درست ساخت ہے۔

telemetry فعال کریں اور اسے اپنے terminal پر بھیجیں:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
claude

console exporter metric records کو collect ہوتے ہی print کرتا ہے۔ آپ کو claude_code.token.usage درکار ہے، جس میں type attribute کی قدر input، output، cacheRead یا cacheCreation ہوتی ہے۔ Orientation، input اور cacheRead میں ظاہر ہوتی ہے، کیونکہ file contents وہیں آتے ہیں۔ ان دونوں کو جمع کریں۔

map کو wired رکھتے ہوئے task کو تین بار چلائیں، ہر بار fresh session میں۔ پھر .mcp.json سے graft entry ہٹا کر مزید تین بار چلائیں۔ single runs کے بجائے medians کا موازنہ کریں، کیونکہ agent runs میں بہت زیادہ فرق ہوتا ہے اور ایک unlucky run آپ کو حقیقت کے برعکس نتیجہ دے سکتی ہے۔ tool-call count بھی record کریں: tool calls mechanism ہیں اور tokens effect ہیں۔ اس لیے tool calls میں کمی کے بغیر token saving کا مطلب ہے کہ کوئی اور چیز تبدیل ہوئی ہے۔

پھر وہ costs منہا کریں جو benchmark ظاہر نہیں کرتا۔ graft build --deep ہر full refresh پر model tokens خرچ کرتا ہے۔ چھ tool schemas ہر request کے ساتھ بھیجے جاتے ہیں۔ اگر آپ کے agents کرائے کے server پر چلتے ہیں تو agent کے اخراجات پر سخت حد مقرر کرنا اس صورتِ حال کو اچانک پیش آنے والے خرچ کے بجائے budget میں بدل دیتا ہے، اور coding agent کی telemetry حقیقت میں کیا report کرتی ہے یہ واضح کرتا ہے کہ exporter فعال کرنے کے بعد machine سے کیا باہر جاتا ہے۔

کوڈ بیس کا نقشہ کب مدد دینا بند کر دیتا ہے؟

• ریپوزٹری پہلے ہی context میں سما جاتی ہے۔ ایک چھوٹی single service کو نقشے کی ضرورت نہیں ہوتی، اور ہر request پر آپ کو پھر بھی چھ tool schemas کی لاگت برداشت کرنی پڑتی ہے۔ اگر آپ کا agent آج کسی بھی file کو ایک یا دو tool calls میں تلاش کر لیتا ہے تو اسے چھوڑ دیں۔
• آپ کی language broad tier میں ہے۔ Generic call edges کی وجہ سے graft callers caller کو نظرانداز کر سکتا ہے یا name collision کی وجہ سے غلط caller پیدا کر سکتا ہے۔ Blast radius پر اعتماد کرنے سے پہلے graft grep سے تصدیق کریں۔
• گراف پرانا ہو گیا ہے اور کسی نے نوٹس نہیں کیا۔ Drift کی صورت میں graft check exit code 1 دیتا ہے، لیکن یہ صرف اسی وقت مفید ہے جب کوئی اسے چلا رہا ہو۔ اسے habit نہیں بلکہ hook یا CI step بنائیں۔
• Monorepo کو scoping درکار ہے۔ Single-git monorepo کو workspace file، go.mod، pyproject.toml یا Cargo.toml کے ذریعے خودکار طور پر حصوں میں تقسیم کیا جاتا ہے، اور graft ask "..." --in services/billing/ query کو ایک sub-project تک محدود کرتا ہے۔ وہی اصول جو ہر package کے لیے nested AGENTS.md files بنانے کی طرف لے جاتا ہے، map پر بھی لاگو ہوتا ہے۔
• Agent wiring کو نظرانداز کرتا ہے۔ یہ نتیجہ اخذ کرنے سے پہلے کہ map استعمال ہو رہا ہے، حقیقی session میں tool calls دیکھیں۔ اگر agent اب بھی grep چلا رہا ہے تو اس کا مطلب ہے کہ اس نے rules file پڑھی ہی نہیں۔

FAQ

کیا مجھے graft/ folder کو git میں commit کرنا چاہیے؟

نہیں۔ graft build آپ کے .gitignore میں graft/ خودکار طور پر شامل کر دیتا ہے، کیونکہ graph، node_modules کی طرح دوبارہ بنائے جا سکنے والے cache کی حیثیت رکھتا ہے۔ یہ تقریباً ہر edit پر تبدیل ہوتا ہے، اس لیے اسے commit کرنے سے سینکڑوں generated files کے نیچے حقیقی diffs چھپ جاتے ہیں۔ وہ wiring commit کریں جو agents کو بتاتی ہے کہ map موجود ہے، جن میں AGENTS.md اور .mcp.json شامل ہیں، اور ہر teammate کو مقامی طور پر graft build چلانے دیں۔ پہلے commit سے قبل grep -n graft .gitignore اور git status --short سے تصدیق کریں، کیونکہ git کسی file کو شامل کیے جانے کے بعد اسے track کرتا رہتا ہے، اور اس کے بعد .gitignore میں editing کرنے سے وہ untrack نہیں ہوتی۔

کیا Graft چلانے پر رقم خرچ ہوتی ہے؟

structural حصہ مفت ہے۔ graft build، graft ask، graft check اور چھ MCP retrieval tools، tree-sitter operations ہیں جو کبھی model کو call نہیں کرتے۔ graft build --deep paid حصہ ہے: یہ LLM کے ذریعے plain-English summaries اور ہر symbol کے cruxes لکھتا ہے۔ اسے GRAFT_PROVIDER، GRAFT_API_KEY اور GRAFT_MODEL سے configure کیا جاتا ہے، جبکہ کسی بھی OpenAI-compatible endpoint کے لیے GRAFT_BASE_URL استعمال ہوتا ہے۔ آپ Graft کو صرف structure کے ساتھ چلا سکتے ہیں اور خود graph پر کوئی token خرچ نہیں کریں گے۔

codebase map میرے repository میں حقیقتاً کتنی بچت کرے گا؟

پیمائش کے بغیر کوئی آپ کو یہ نہیں بتا سکتا۔ project کی رپورٹ کے مطابق، اپنے 162-run sweep میں اس نے 42% کم tokens استعمال کیے، جبکہ SWE-bench Verified پر یہ شرح 23% رہی۔ دونوں نتائج ایسے baseline کے مقابلے میں ہیں جس میں map شامل نہیں تھا۔ یہ دونوں vendor benchmarks ہیں، جن میں سے ایک جزوی طور پر Graft کے اپنے repository پر چلایا گیا، اور کوئی بھی آپ کے private code کی نمائندگی نہیں کرتا۔ ایک ہی repeatable question کو map کے ساتھ 3 مرتبہ اور map کے بغیر 3 مرتبہ چلائیں۔ اس دوران CLAUDE_CODE_ENABLE_TELEMETRY=1 اور OTEL_METRICS_EXPORTER=console set ہوں۔ پھر input اور cacheRead types کے لیے claude_code.token.usage کے median کا موازنہ کریں۔

refactor کرنے پر graph کے ساتھ کیا ہوتا ہے؟

structure خود دوبارہ parse ہو جاتا ہے۔ Graft working tree کے stats لیتا ہے اور صرف تبدیل ہونے والی files کو دوبارہ parse کرتا ہے۔ اس لیے rename اگلی query پر تقریباً 3 ms overhead کے ساتھ ظاہر ہو جاتا ہے۔ یہ uncommitted work بھی دیکھ لیتا ہے، کیونکہ یہ git history کے بجائے files پڑھتا ہے۔ Model کے ذریعے لکھی گئی summaries پرانی ہو جاتی ہیں۔ ہر node اپنے sources کا content hash محفوظ کرتا ہے، اور source تبدیل ہونے پر node کو stale نشان زد کیا جاتا ہے، اسے دوبارہ لکھا نہیں جاتا۔ drift دیکھنے کے لیے graft check . چلائیں، پھر written حصہ refresh کرنے کے لیے graft build --deep چلائیں۔

آج Graft کون سے coding agents استعمال کر سکتے ہیں؟

August 2026 تک graft init Claude Code، Cursor، Codex، GitHub Copilot، Google Gemini، Kiro، Windsurf اور AdaL کو wire کرتا ہے۔ Claude Code کو سب سے زیادہ integration ملتی ہے: .mcp.json میں MCP server entry، statusline، post-edit hooks اور .claude/ کے تحت skill file۔ Codex کو AGENTS.md section کے علاوہ ~/.codex/ کے تحت machine-wide entries بھی ملتی ہیں، جنہیں graft init --no-global skip کرتا ہے۔ دیگر agents کو rules یا steering file ملتی ہے۔ کوئی بھی دوسرا MCP client، npx -y @nanonets/graft@0.10.1 mcp command register کر کے server کو براہ راست استعمال کر سکتا ہے۔