कोडिंग एजेंट्स के लिए Graft codebase map कैसे बनाएं
Graft का उपयोग करके अपनी रिपॉजिटरी का स्थायी इंडेक्स कैसे बनाएं। यह टूल tree-sitter और MCP का उपयोग करता है ताकि कोडिंग एजेंट्स को बार-बार कोड स्ट्रक्चर न खोजना पड़े।
कोडिंग एजेंट्स के लिए codebase map क्या है
कोडिंग एजेंट्स के लिए codebase map आपके रिपॉजिटरी का एक स्थायी इंडेक्स होता है। एजेंट हर नए सेशन में शुरुआत से grepping करने के बजाय इसमें जानकारी खोजता है। Graft इस विचार का एक कार्यान्वयन (implementation) है। यह tree-sitter का उपयोग करके आपके कोड को पार्स करता है, लिंक्ड markdown नोड्स का एक फोल्डर और प्रति-सिंबल वायरिंग ग्राफ बनाता है, और MCP (model context protocol, वह मानक इंटरफ़ेस जिसका उपयोग कोडिंग एजेंट्स बाहरी टूल्स को कॉल करने के लिए करते हैं) के माध्यम से रिट्रीवल टूल्स प्रदान करता है।
Graft न तो कोई प्रॉक्सी है और न ही कोई गेटवे। आपके एजेंट और मॉडल API के बीच कुछ भी नहीं होता है। मैप डिस्क पर स्थित एक फोल्डर है जिसे एजेंट पढ़ता है। यह अंतर तय करता है कि आप किस समस्या का समाधान कर रहे हैं: एक self-hosted token gateway उन अनुरोधों को मापता और रूट करता है जिन्हें आप पहले से भेज रहे हैं, जबकि एक मैप यह बदल देता है कि आपको कुल कितने अनुरोध भेजने की आवश्यकता है।
यह तकनीक इस टूल से पुरानी है और इसके बाद भी बनी रहेगी। पहले तकनीक को समझें, फिर उसकी कार्यप्रणाली को।
कोडिंग एजेंट्स संदर्भ को फिर से खोजने में कॉन्टेक्स्ट क्यों बर्बाद करते हैं
एक एजेंट को उस रिपॉजिटरी पर काम शुरू करते हुए देखें जिसे वह पचास बार देख चुका है। वह डायरेक्टरी की सूची बनाता है। वह किसी सिंबल के लिए grep चलाता है। वह यह पता लगाने के लिए तीन फाइलें खोलता है कि फंक्शन कहाँ परिभाषित है, फिर यह जानने के लिए चौथी फाइल खोलता है कि उसे कौन कॉल करता है। इनमें से कोई भी मुख्य कार्य नहीं है। यह ओरिएंटेशन है, और हर सेशन में इसके लिए इनपुट टोकन के रूप में भुगतान करना पड़ता है।
इसका कारण सरल है। एक मॉडल के पास सेशन के बीच कोई मेमोरी नहीं होती। एजेंट ने आपके लेआउट के बारे में जो कुछ भी सीखा, वह उस कॉन्टेक्स्ट विंडो में था जिसे सेशन समाप्त होने पर हटा दिया गया था। इसलिए वही खोज फिर से शून्य से शुरू होती है, और आप इसके लिए फिर से भुगतान करते हैं। प्रॉम्प्ट कैशिंग केवल पिछले पांच मिनट के भीतर देखे गए समान प्रॉम्प्ट प्रीफिक्स पर छूट देती है, या अतिरिक्त लागत पर पिछले एक घंटे के लिए, इसलिए यह कल की खोज को आज के सेशन में नहीं ला सकती। एक बड़ी रिपॉजिटरी पर ओरिएंटेशन चरण की लागत संपादन (edit) से अधिक होती है: कोड खोजने के लिए दस टूल कॉल, और उसे बदलने के लिए एक। ओरिएंटेशन उस बिल का केवल आधा हिस्सा है और संपादन दूसरा, यही कारण है कि एक ऐसा कौशल जो एजेंट को सबसे छोटे प्रभावी बदलाव तक सीमित रखता है को किसी एक को चुनने के बजाय एक मैप के साथ जोड़ना बेहतर है।
एक मैप इस लूप को तोड़ता है क्योंकि यह खोज को मॉडल से हटाकर डिस्क पर ले आता है। एक पार्सर रिपॉजिटरी को एक बार स्कैन करता है, रिकॉर्ड करता है कि कौन सा सिंबल कहाँ परिभाषित है और कौन सा सिंबल किसे कॉल करता है, फिर कोड बदलने पर उस रिकॉर्ड को अपडेट रखता है। एजेंट एक सवाल पूछता है और फाइल और लाइन के साथ उत्तर प्राप्त करता है। बार-बार की जाने वाली खोज एक सस्ता लुकअप बन जाती है।
आप पहले से ही इसका एक कमजोर संस्करण उपयोग कर रहे हैं। एक AGENTS.md जो आपके कन्वेंशन बताता है एजेंट को हर बार आपके कन्वेंशन को फिर से समझने से रोकता है। एक जनरेट किया गया मैप उसे आपकी संरचना को फिर से समझने से रोकता है। अंतर यह है कि इसे लिखता कौन है। आप इंस्ट्रक्शन फाइल खुद लिखते हैं, इसलिए यह छोटी रहती है। एक पार्सर मैप जनरेट करता है, इसलिए यह दस हजार फाइलों को कवर कर सकता है। जहाँ तक सेशन के भीतर बजट खर्च होने की बात है, Claude Code अपनी कॉन्टेक्स्ट विंडो कैसे खर्च करता है इसका हिसाब देता है।
Graft वास्तव में क्या बनाता है
दो आर्टिफैक्ट्स, दोनों रिपॉजिटरी रूट पर एक graft/ फोल्डर के अंतर्गत।
पहला एक नोड ग्राफ है जिसे लिंक्ड मार्कडाउन के रूप में लिखा गया है, प्रति नोड एक फाइल। प्रत्येक नोड में एक सरल-अंग्रेजी सारांश, स्रोत से निकाली गई महत्वपूर्ण लॉजिक लाइनों का एक "क्रक्स" (सार), कंटेंट हैश के साथ सटीक स्रोत फाइलें, अन्य नोड्स के लिए टाइप्ड विकिलिंक्स (depends_on, part_of, uses, implements), और एक नोट्स सेक्शन होता है जो रीजेनरेशन के बाद भी बना रहता है ताकि आप वह संदर्भ रिकॉर्ड कर सकें जिसे पार्सर अनुमानित नहीं कर सकता।
दूसरा graft/.graph/wiring.json है, जो प्रति-प्रतीक (per-symbol) संरचनात्मक ग्राफ है जिसे tree-sitter निकालता है: परिभाषाएँ, संदर्भ और उनके बीच कॉल एजेस।
यह विभाजन महत्वपूर्ण है क्योंकि केवल आधे हिस्से को ही मॉडल की आवश्यकता होती है। graft build पूरी तरह से tree-sitter है और कभी भी LLM (लार्ज लैंग्वेज मॉडल) को कॉल नहीं करता है, इसलिए यह डिटरमिनिस्टिक है और इसकी कोई लागत नहीं है। graft build --deep लिखित सारांश और प्रति-प्रतीक क्रक्स को जोड़ता है, और वे मॉडल कॉल हैं जिनके लिए आप भुगतान करते हैं।
भाषा समर्थन को टियर में विभाजित किया गया है, और टियर आपको बताता है कि कॉल ग्राफ पर कितना भरोसा करना है। TypeScript, JavaScript, Python, Go, Java, Kotlin, PHP, Swift और R को स्कोप-अवेयर क्रॉस-फाइल रिज़ॉल्यूशन मिलता है। Rust, C, C++, C#, Ruby, Scala, Elixir, Solidity, OCaml, Zig, Dart, Clojure, Nix और Lua को सिंबल और जेनेरिक कॉल एजेस मिलते हैं, जिसका अर्थ है कि एक एज एक रिज़ॉल्व्ड संदर्भ के बजाय नाम का मिलान हो सकता है। कंपाइलर-ग्रेड एजेस --lsp और rust-analyzer या gopls जैसे लैंग्वेज सर्वर के साथ ऑप्ट-इन हैं।
Graft को इंस्टॉल करें और वर्ज़न पिन करें
Graft के लिए Node.js 20 या उससे नया वर्ज़न आवश्यक है और यह MIT लाइसेंस के अंतर्गत आता है। 17 अक्टूबर 2026 तक, वर्तमान release 0.23.0 है, जिसे 15 अक्टूबर 2026 को प्रकाशित किया गया था, और पहला प्रकाशित वर्ज़न, 0.1.0, जुलाई 2026 का है। इसे एक नया सॉफ्टवेयर मानें। Release 0.22.0, जिसे 14 अक्टूबर 2026 को प्रकाशित किया गया, ने प्रोजेक्ट का नाम बदलकर Trail-code कर दिया: वही कोड अब @trailhq/trail-code के रूप में भी आता है जिसमें trail कमांड है, जबकि @nanonets/graft में graft कमांड बरकरार है।
यह गाइड 0.21.1 वर्ज़न को पिन करती है, जिसे 29 सितंबर 2026 को प्रकाशित किया गया था और यह नाम बदलने से पहले का अंतिम release था, क्योंकि 0.22 और 0.23 ने उन कमांड्स को बदल दिया है जिन पर यह गाइड निर्भर करती है। 0.22 से, graft check आपके branch के diff की तुलना repo के team learnings से करता है और conflict होने पर 1 exit code देता है, drift detection को graft build --check में स्थानांतरित कर दिया गया है, और MCP टूल्स का नाम trail_* है (सर्वर अभी भी पुराने graft_* नामों का उत्तर देता है)। 0.23.0 changelog यह भी कहता है कि trail के साथ सेटअप की गई repo में map .trail/cache/ पर चला जाता है और Claude Code को अब MCP सर्वर नहीं मिलता, जबकि README अभी भी graft/ और .mcp.json का वर्णन करता है। पिन बदलने से पहले changelog पढ़ें और --dry-run चलाएं।
npm install -g @nanonets/graft@0.21.1
npm ls -g @nanonets/graftnpm ls -g को @nanonets/graft@0.21.1 प्रिंट करना चाहिए। उस वर्ज़न को जानबूझकर पिन करें। एक साधारण npm install -g @nanonets/graft उस समय latest टैग को resolve करता है जब आप इसे चलाते हैं, और एक ऐसे प्रोजेक्ट पर जो महीने में कई minor releases जारी करता है, यह आपको मंगलवार को वह टूल देगा जो आपके सहकर्मी ने सोमवार को इंस्टॉल किया था। एक पिन किया गया वर्ज़न सभी के लिए CLI flags और graph format को समान रखता है, इसलिए आप तब अपग्रेड करते हैं जब आप निर्णय लेते हैं।
फिर इसे अपनी किसी रिपॉजिटरी से जोड़ें:
cd /path/to/your/repo
graft init --dry-run
graft initgraft init पूछता है कि आपके किन कोडिंग एजेंट्स को जोड़ना है, फिर graph बनाता है। पहले --dry-run चलाएं और उन फाइलों की सूची पढ़ें जिन्हें यह छूने की योजना बना रहा है, क्योंकि उनमें से कुछ रिपॉजिटरी के बाहर स्थित होती हैं। graft init idempotent है और मौजूदा configs को ओवरराइट नहीं करता है, इसलिए इसे दूसरी बार चलाना सुरक्षित है। वापस जाने के लिए, graft uninstall उन सभी फाइलों और config entries को हटा देता है जिन्हें Graft ने लिखा था, और यह तब तक dry run रहता है जब तक आप -y पास नहीं करते।
उसी प्रॉम्प्ट में telemetry का एक चेकबॉक्स होता है। Release 0.12.0 से Graft डिफ़ॉल्ट रूप से एक anonymous usage ping भेजता है: bucketed counts और fixed labels, कभी भी आपका कोड, फाइल पाथ या रिपॉजिटरी का नाम नहीं। इवेंट्स दिन में अधिकतम एक बार पोस्ट किए जाते हैं, एक अपवाद के साथ: install इवेंट, जिसे npm का postinstall hook तुरंत बैकग्राउंड सेंडर को सौंप देता है। graft init के दौरान बॉक्स को अनटिक करें, graft telemetry disable चलाएं, या इसे बंद करने के लिए DO_NOT_TRACK=1 सेट करें (यह CI में भी खुद को बंद कर लेता है), और graft telemetry debug उस बैच को प्रिंट करता है जिसे वह बिना भेजे भेजता।
0.21.1 में वायरिंग Claude Code, Cursor, Codex, GitHub Copilot, Google Gemini, Kiro, Windsurf, Grok (xAI), AdaL, Hermes Agent और Google Antigravity को कवर करती है। Hermes Agent release 0.13.0 के बाद से एक प्रथम श्रेणी का graft init होस्ट रहा है, और पिन किए गए वर्ज़न पर graft init --agents hermes और graft init --agents antigravity किसी अन्य होस्ट की तरह उन दोनों का चयन करते हैं। Grok release 0.13.0 में शामिल हुआ और इसे graft init --agents grok के साथ चुना जाता है। Claude Code को सबसे गहरा इंटीग्रेशन मिलता है: एक MCP सर्वर एंट्री, एक statusline जो graph का आकार और staleness दिखाती है, post-edit हुक्स जो graph को फिर से बनाते हैं, और .claude/ के अंतर्गत एक skill फाइल। बाकी को एक instruction या rule फाइल मिलती है जो एजेंट को बताती है कि टूल्स मौजूद हैं (Hermes Agent और Antigravity दोनों AGENTS.md सेक्शन को पढ़ते हैं), और Grok को अपनी config में एक MCP ब्लॉक भी मिलता है। इसलिए "Supported" का मतलब है कि Graft वायरिंग लिखता है, इसलिए जो एजेंट अपनी खुद की rules फाइल को छोड़ देता है, वह map को भी छोड़ देगा। यही वह सामान्य कारण है कि एजेंट आपके द्वारा लिखे गए निर्देशों को अनदेखा क्यों करते हैं, और यह यहाँ भी उतना ही लागू होता है जितना कहीं और।
आपके रिपॉजिटरी में क्या आता है, और क्या git से बाहर रहता है
graft init के बाद, इनकी अपेक्षा करें:
graft/: मार्कडाउन नोड ग्राफ औरgraft/.graph/wiring.json। आपके लिए.gitignoreमें जोड़ा गया।.mcp.json: graft MCP सर्वर को रजिस्टर करता है ताकि Claude Code इसे शुरू कर सके।.claude/settings.json: यथास्थान मर्ज किया गया, जो statusline और post-edit हुक्स को जोड़ता है।AGENTS.md,GEMINI.md,.github/copilot-instructions.md,.cursor/rules/graft.mdc,.kiro/steering/graft.md,.windsurf/rules/graft.md,.grok/skills/graft/SKILL.mdऔर.adal/skills/graft/SKILL.md: आपके द्वारा चुने गए एजेंट्स से मेल खाने वाली फाइलों में मार्कर-फेंस्ड सेक्शन जोड़े गए।.grok/config.toml: एक रिपो-लेवल[mcp_servers.graft]ब्लॉक, जिसे केवल तब लिखा जाता है जब आप Grok चुनते हैं।~/.codex/config.toml,~/.codex/hooks.jsonऔर~/.codex/hooks/graft/graft-hooks.cjs: मशीन-वाइड, जिन्हें केवल तब लिखा जाता है जब आप Codex चुनते हैं और~/.codex/पहले से मौजूद होता है।graft init --no-globalइन्हें छोड़ देता है, औरgraft init --no-hooksहुक शिम को अपने आप छोड़ देता है।
ग्राफ एक कैश है, जैसे node_modules। इसे कमिट न करें। यह कोड से कुछ ही सेकंड में फिर से बन जाता है, यह लगभग हर बदलाव पर बदलता है, और इसे कमिट करने से एक लाइन का फिक्स कई सौ फाइलों के डिफ (diff) में बदल जाता है जिसे कोई भी रिव्यूअर नहीं पढ़ेगा। इसके बजाय वायरिंग को कमिट करें, जिसमें AGENTS.md और .mcp.json शामिल हैं। एक टीम का सदस्य रिपॉजिटरी को क्लोन करता है, graft build चलाता है, और अपना स्थानीय ग्राफ प्राप्त कर लेता है।
जांचें कि आपके पहले कमिट से पहले इग्नोर नियम लागू हो गया है:
grep -n graft .gitignore
git status --shortgrep को graft/ वाली एक लाइन प्रिंट करनी चाहिए, और git status --short को graft/ के अंतर्गत कुछ भी लिस्ट नहीं करना चाहिए। उस आउटपुट में graft/ के अंतर्गत फाइलों के दिखने का मतलब है कि इग्नोर एंट्री गायब है या कहीं और ओवरराइड हो गई है। इसे कमिट करने से पहले ठीक करें, क्योंकि git एक बार फाइल को ट्रैक करने के बाद उसे ट्रैक करना जारी रखता है, और बाद में .gitignore का संपादन उसे अनट्रैक नहीं करेगा।
यदि आप MCP सर्वर को मैन्युअल रूप से रजिस्टर करना चाहते हैं, या इसे उसी वर्जन पर पिन करना चाहते हैं जिसे आपने इंस्टॉल किया है, तो एंट्री छोटी है:
{
"mcpServers": {
"graft": {
"command": "npx",
"args": ["-y", "@nanonets/graft@0.21.1", "mcp"]
}
}
}वे रिट्रीवल टूल्स जिन्हें आपका एजेंट grep के बजाय कॉल करता है
Graft, MCP के माध्यम से छह टूल्स उपलब्ध कराता है। graft_find_code किसी टास्क विवरण के लिए रैंक किए गए नोड्स लौटाता है, जिसमें फाइल और लाइन की जानकारी होती है। graft_file_api बिना बॉडी के फाइल में मौजूद हर सिग्नेचर को लौटाता है। graft_trace_calls कॉलर्स या कैलीज (callees) को कई स्तरों तक गहराई से ट्रैक करता है। graft_find_all सिंबल के आधार पर समूहीकृत (grouped) regex हिट्स लौटाता है। graft_repo_map किसी अपरिचित रिपॉजिटरी की पहली झलक प्रदान करता है। graft_check_freshness यह रिपोर्ट करता है कि क्या ग्राफ अभी भी कोड से मेल खाता है।
हर टूल का एक CLI समकक्ष (twin) है, जिससे आप यह देख सकते हैं कि आपके एजेंट को वास्तव में क्या दिया जा रहा है:
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" --jsongraft ask को फाइल कंटेंट के बजाय file:line रेफरेंस के साथ रैंक किए गए नोड्स प्रिंट करने चाहिए। पूरी कार्यप्रणाली यही है: एजेंट को एक पॉइंटर मिलता है और वह सही फाइल खोजने के लिए दस फाइलें पढ़ने के बजाय केवल एक फाइल खोलता है। यदि आप स्वयं ग्राफ देखना चाहते हैं, तो graft viz localhost पर एक इंटरैक्टिव व्यूअर खोलता है। यदि graft ask किसी ऐसे प्रश्न के लिए उपयोगी परिणाम नहीं देता है जिसका उत्तर आप तीस सेकंड में दे सकते हैं, तो उसे दोबारा न लिखें और न ही फिर से पूछें। रैंक की गई रिट्रीवल कभी-कभी चूक सकती है, और प्रोजेक्ट की अपनी स्किल फाइल कहती है कि कमजोर हिट्स मिलने का मतलब है कि आपको graft grep, graft skeleton या graft callers पर स्विच करना चाहिए। यदि वे भी विफल रहते हैं, तो ड्रिफ्ट (graft check ., 0.21.1 पिन किए गए वर्जन पर, या 0.22 से graft build --check) की जाँच करें और पुष्टि करें कि आपकी भाषा किस टियर में है, क्योंकि पुराना ग्राफ या ब्रॉड-टियर एजेस आपके एजेंट को उसी तरह विफल कर देंगे।
एक लागत ऐसी है जिसे नजरअंदाज करना आसान है। पूरे सेशन के दौरान हर रिक्वेस्ट के सिस्टम प्रॉम्प्ट में छह टूल डेफिनिशन इंजेक्ट की जाती हैं। आप इसकी कीमत चुकाते हैं, चाहे एजेंट मैप का उपयोग करे या न करे। ऐसी रिपॉजिटरी पर जो कॉन्टेक्स्ट में फिट होने के लिए पर्याप्त छोटी है, यह फिक्स्ड चार्ज उस एक्सप्लोरेशन से अधिक हो सकता है जिसे यह बचाता है।
कोड बदलने पर ग्राफ का क्या होता है
स्ट्रक्चरल रिफ्रेश सस्ता और स्वचालित है। Graft git के बजाय आपकी वर्किंग ट्री को पढ़ता है, इसलिए आपके द्वारा किया गया ऐसा बदलाव जिसे आपने commit नहीं किया है और जिसे आपने stage किया है, दोनों ही इसे समान रूप से दिखाई देते हैं। प्रत्येक क्वेरी पहले वर्किंग ट्री का stats लेती है और केवल उन फाइलों को फिर से पार्स करती है जो बदली हैं। 0.21.1 के दस्तावेज़ों के अनुसार जब कुछ भी नहीं बदलता है, तो यह जांच लगभग 3 ms लेती है; वर्तमान README में इसे कुछ दस मिलीसेकंड बताया गया है, जो प्रोजेक्ट की अपनी रिपॉजिटरी पर लगभग 50 ms है। टर्न-एंड रीबिल्ड केवल उन फाइलों को प्रभावित करता है जहाँ कोड बदला गया है। डिस्क पर मौजूद ग्राफ से बिना दोबारा पार्स किए उत्तर पाने के लिए GRAFT_NO_REFRESH=1 सेट करें या --no-refresh पास करें। सब कुछ फिर से पार्स करने के लिए --no-reuse पास करें, जो कि Graft को अपग्रेड करने के बाद आवश्यक होता है।
मॉडल द्वारा लिखा गया हिस्सा अलग तरह से व्यवहार करता है, और यही वह हिस्सा है जो चुपचाप गलत हो सकता है। सारांश (summaries) और मुख्य बिंदु (cruxes) कैश किए जाते हैं। प्रत्येक नोड अपने स्रोतों का कंटेंट हैश रिकॉर्ड करता है, इसलिए जब कोई स्रोत फ़ाइल बदलती है, तो नोड को वर्तमान के बजाय पुराना (stale) चिह्नित कर दिया जाता है। वह फ्लैग केवल तभी मदद करता है जब कोई उस पर कार्रवाई करे। graft build --deep के साथ रिफ्रेश करें, जो फिर से मॉडल टोकन का उपयोग करता है।
पुरानेपन (staleness) को दृश्यमान बनाएं:
graft check .
echo $?पिन किए गए 0.21.1 संस्करण पर, एग्जिट स्टेटस 0 का अर्थ है कि ग्राफ कोड से मेल खाता है और एग्जिट स्टेटस 1 का अर्थ है ड्रिफ्ट। 0.22 से, graft check टीम लर्निंग के साथ संघर्ष होने पर 1 के साथ एग्जिट होता है, और ड्रिफ्ट गेट graft build --check है, इसलिए पिन बदलते समय कमांड को भी बदलें। इसे pre-push हुक से चलाएं, ताकि छह महीने पुराना मैप मार्च में फिर से लिखे गए कोड के बारे में आत्मविश्वास से उत्तर न दे सके। 0.21.1 का README graft check को एक स्थानीय फ्रेशनेस सिग्नल के रूप में वर्णित करता है, और वर्तमान README CI के लिए build --check को सूचीबद्ध करता है। किसी भी स्थिति में graft/ को git-ignored रखा जाता है, इसलिए एक नया CI चेकआउट बिना ग्राफ के शुरू होता है जब तक कि जॉब उसे बिल्ड न करे।
प्रकाशित बेंचमार्क आंकड़ों को ध्यान से पढ़ें
0.21.1 README की शुरुआत में लिखा था "4 गुना तक सस्ता और 3 गुना तेज, सटीकता में कोई कमी नहीं या बेहतर परिणाम"। वर्तमान README में उस पंक्ति को हटा दिया गया है और छोटे आंकड़ों के साथ शुरुआत की गई है: "समान कार्यों पर एक ही एजेंट के 162 रन के आधार पर: 32% कम लागत, 42% कम अनकैश्ड इनपुट टोकन, 60% कम समय, और सही उत्तरों का समान अनुपात।" ये आंकड़े प्रोजेक्ट के अपने बेंचमार्क से लिए गए हैं, जो इसके README में प्रकाशित हैं। यहाँ वे दो रन दिए गए हैं जिन्हें यह पूरी तरह से रिपोर्ट करता है।
इस चार्ट के पीछे का डेटा
[
{
"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
}
]नियंत्रित स्वीप (controlled sweep) में 162 रन शामिल हैं जो दो रिपॉजिटरी पर किए गए हैं, जिनमें से एक स्वयं Graft है, और प्रत्येक कार्य के लिए तीन ट्रायल किए गए हैं। यह 42% कम अनकैश्ड इनपुट टोकन और 46% कम टूल कॉल की रिपोर्ट करता है। SWE-bench Verified रन 50 इंस्टेंस का है जिसमें दोनों तरफ एक ही मॉडल का उपयोग किया गया है, और यह कम बचत की रिपोर्ट करता है: 23% टोकन और 25% टूल कॉल। 15 PocketBase कार्यों का तीसरा रन, जिसमें दस डेवलपर प्रश्न और पांच पुनरुत्पादित मर्ज किए गए पुल रिक्वेस्ट शामिल थे, की कुल लागत 11.02 US डॉलर रही, जबकि बेसलाइन के लिए यह 13.91 US डॉलर थी।
इन सभी को वेंडर बेंचमार्क के रूप में देखें। दो चीजें इसकी जानकारी की सीमा तय करती हैं। नियंत्रित स्वीप में Graft की अपनी रिपॉजिटरी शामिल है, जो वह कोडबेस है जिसके आधार पर इसके लेखकों ने इसे ट्यून किया है। SWE-bench Verified प्रसिद्ध ओपन-सोर्स Python प्रोजेक्ट्स की समस्याओं का एक सार्वजनिक डेटासेट है, और सार्वजनिक डेटासेट वे होते हैं जिनके लिए टूल्स को ऑप्टिमाइज़ किया जाता है, चाहे कोई ऐसा करना चाहे या न चाहे। इनमें से कोई भी आपकी निजी monorepo के बारे में कोई दावा नहीं है, जिसकी अपनी नामकरण आदतें और अपना मृत कोड (dead code) होता है।
सटीकता (correctness) को दोबारा पढ़ने की आवश्यकता है। नियंत्रित स्वीप पर इसमें कोई बदलाव नहीं हुआ: मैप के साथ 93% बनाम बिना मैप के 93%। 54% से 66% तक की उछाल केवल SWE-bench Verified पर दिखाई देती है। एक ऐसा टूल जो आपके टोकन बिल को कम करता है और गुणवत्ता को स्थिर रखता है, वह अभी भी एक अच्छा सौदा है। बस SWE-bench के सटीकता परिणाम को स्वीप के टोकन परिणाम के साथ न जोड़ें और दोनों को एक ही दावे के रूप में उद्धृत न करें।
किसी भी दावे पर विश्वास करने से पहले अपने स्वयं के टोकन डेल्टा (token delta) को मापें
केवल वही संख्या मायने रखती है जो आपके रिपॉजिटरी से आती है। इस विधि में एक दोपहर का समय लगता है।
कोई ऐसा कार्य चुनें जिसे आप बिल्कुल सटीक रूप से दोहरा सकें। एक प्रश्न पूछना संपादन (edit) करने से बेहतर है, क्योंकि संपादन रिपॉजिटरी को बदल देता है और दूसरा रन अब समान प्रयोग नहीं रहता। "लॉगिन रूट पर रेट लिमिट कौन सा मॉड्यूल लागू करता है" सही प्रकार का प्रश्न है।
टेलीमेट्री चालू करें और इसे अपने टर्मिनल पर भेजें:
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
claudeकंसोल एक्सपोर्टर मीट्रिक रिकॉर्ड्स को वैसे ही प्रिंट करता है जैसे वे एकत्र किए जाते हैं। आपको जिस रिकॉर्ड की आवश्यकता है वह claude_code.token.usage है, जिसमें input, output, cacheRead या cacheCreation का type एट्रिब्यूट होता है। ओरिएंटेशन input और cacheRead में दिखाई देता है, क्योंकि फाइल की सामग्री वहीं पहुँचती है। उन दोनों को जोड़ें।
कार्य को तीन बार चलाएं, प्रत्येक बार एक नए सत्र (session) में, मैप को कनेक्ट करके। फिर .mcp.json से ग्राफ्ट एंट्री को हटा दें और इसे तीन बार और चलाएं। एकल रन के बजाय मेडियन (medians) की तुलना करें, क्योंकि एजेंट रन काफी भिन्न होते हैं और एक खराब रन आपको सच्चाई के विपरीत परिणाम दे सकता है। टूल-कॉल की संख्या भी रिकॉर्ड करें: टूल कॉल एक तंत्र (mechanism) है और टोकन उसका प्रभाव है, इसलिए टूल कॉल में बिना किसी कमी के टोकन की बचत का मतलब है कि कुछ और बदल गया है।
फिर उन लागतों को घटाएं जिन्हें बेंचमार्क नहीं दिखाता है। graft build --deep हर पूर्ण रिफ्रेश पर मॉडल टोकन खर्च करता है। छह टूल स्कीमा हर अनुरोध के साथ चलते हैं। यदि आपके एजेंट आपके द्वारा किराए पर लिए गए सर्वर पर चलते हैं, तो एजेंट खर्च पर एक कठोर सीमा निर्धारित करना इसे एक आश्चर्य से बदलकर एक बजट बना देता है, और कोडिंग एजेंट की टेलीमेट्री वास्तव में क्या रिपोर्ट करती है इस बात को कवर करता है कि एक्सपोर्टर को सक्षम करने के बाद मशीन से क्या बाहर जाता है।
कोडबेस मैप कब मदद करना बंद कर देता है?
- रिपॉजिटरी पहले से ही कॉन्टेक्स्ट में फिट बैठती है। एक छोटी सर्विस को मैप की आवश्यकता नहीं होती है, और आप अभी भी हर रिक्वेस्ट पर छह टूल स्कीमा के लिए भुगतान कर रहे होते हैं। यदि आपका एजेंट आज एक या दो टूल कॉल में कोई भी फाइल ढूंढ लेता है, तो इसे छोड़ दें।
- आपकी भाषा ब्रॉड टियर में है। जेनेरिक कॉल एज का मतलब है कि
graft callersकिसी कॉलर को मिस कर सकता है, या नाम के टकराव (name collision) से एक गलत कॉल बना सकता है। ब्लास्ट रेडियस पर भरोसा करने से पहलेgraft grepके साथ पुष्टि करें। - ग्राफ पुराना हो गया है और किसी ने ध्यान नहीं दिया। 0.21.1 पर
graft checkड्रिफ्ट होने पर 1 के साथ एग्जिट होता है (0.22 से,graft build --checkऐसा करता है), जो केवल तभी उपयोगी है जब कोई इसे चलाता है। यह एक आदत नहीं, बल्कि एक pre-push हुक होना चाहिए। - मोनोरैपो को स्कोपिंग की आवश्यकता है। एक सिंगल-git मोनोरैपो विभाजित नहीं होता है, लेकिन
graft build,pnpm-workspace.yaml,package.jsonवर्कस्पेस या प्रति-पैकेजgo.mod,pyproject.tomlयाCargo.tomlसे सब-प्रोजेक्ट्स का पता लगाता है और उन्हें रैंकिंग स्कोप के रूप में उपयोग करता है, औरgraft ask "..." --in services/billing/क्वेरी को एक सब-प्रोजेक्ट तक सीमित करता है। वही प्रवृत्ति जो प्रति पैकेज नेस्टेड AGENTS.md फाइलों की ओर ले जाती है, मैप पर भी लागू होती है। - एजेंट वायरिंग को अनदेखा करता है। यह निष्कर्ष निकालने से पहले कि मैप का उपयोग किया जा रहा है, एक वास्तविक सेशन में टूल कॉल्स को देखें। यदि एजेंट अभी भी
grepचला रहा है, तो वह आपको बता रहा है कि उसने कभी रूल्स फाइल नहीं पढ़ी।
FAQ
क्या मुझे graft/ फोल्डर को git में commit करना चाहिए?
नहीं। graft build स्वचालित रूप से graft/ को आपके .gitignore में जोड़ देता है, क्योंकि graph, node_modules की तरह ही एक पुन: उत्पन्न करने योग्य (regenerable) cache है। यह लगभग हर बदलाव पर बदलता है, इसलिए इसे commit करने से वास्तविक diffs सैकड़ों जनरेट की गई फाइलों के नीचे दब जाते हैं। उस wiring को commit करें जो agents को बताती है कि map मौजूद है, जिसमें AGENTS.md और .mcp.json शामिल हैं, और प्रत्येक टीम के सदस्य को स्थानीय रूप से graft build चलाने दें। अपने पहले commit से पहले grep -n graft .gitignore और git status --short के साथ सत्यापित करें, क्योंकि एक बार फाइल add हो जाने के बाद git उसे ट्रैक करना जारी रखता है, और बाद में .gitignore को edit करने से वह untrack नहीं होती है।
क्या Graft को चलाने में पैसे खर्च होते हैं?
संरचनात्मक (structural) हिस्से में कोई खर्च नहीं आता है। graft build, graft ask, graft check और छह MCP retrieval tools ऐसे tree-sitter ऑपरेशन्स हैं जो कभी भी model को कॉल नहीं करते हैं। graft build --deep भुगतान वाला हिस्सा है: यह LLM के माध्यम से सरल अंग्रेजी सारांश और प्रति-प्रतीक (per-symbol) मुख्य बिंदु लिखता है, जिसे GRAFT_PROVIDER, GRAFT_API_KEY और GRAFT_MODEL के साथ कॉन्फ़िगर किया जाता है, साथ ही किसी भी OpenAI-संगत endpoint के लिए GRAFT_BASE_URL का उपयोग किया जाता है। आप केवल संरचना के साथ Graft चला सकते हैं और graph पर एक भी token खर्च किए बिना काम कर सकते हैं।
codebase map वास्तव में मेरे repository पर कितनी बचत करेगा?
मापे बिना कोई भी आपको यह नहीं बता सकता। यह प्रोजेक्ट अपने स्वयं के 162-run sweep पर 42% कम uncached input tokens और SWE-bench Verified पर 23% कम tokens की रिपोर्ट करता है, दोनों ही बिना map वाले baseline के मुकाबले हैं। दोनों vendor benchmarks हैं, जिनमें से एक आंशिक रूप से Graft की अपनी repository पर चलाया गया है, और कोई भी आपके निजी कोड का वर्णन नहीं करता है। CLAUDE_CODE_ENABLE_TELEMETRY=1 और OTEL_METRICS_EXPORTER=console सेट करके, map के साथ तीन बार और बिना map के तीन बार एक ही दोहराने योग्य प्रश्न चलाएं, फिर input और cacheRead प्रकारों के लिए claude_code.token.usage के माध्य (median) की तुलना करें।
refactor करने पर graph का क्या होता है?
संरचना (structure) खुद को फिर से पार्स (re-parse) करती है। Graft working tree की जांच करता है और केवल उन फाइलों को फिर से पार्स करता है जो बदली हैं, इसलिए अगली query पर rename का पता चल जाता है। जब कुछ भी नहीं बदलता है, तो वह जांच 0.21.1 में लगभग 3 ms और वर्तमान release में कुछ दस मिलीसेकंड लेती है, और यह uncommitted काम को भी देखती है क्योंकि यह git history के बजाय फाइलों को पढ़ती है। model द्वारा लिखे गए सारांश पुराने (stale) हो जाते हैं: प्रत्येक node अपने स्रोतों का content hash स्टोर करती है, और एक बदला हुआ स्रोत node को फिर से लिखने के बजाय उसे stale चिह्नित कर देता है। drift की जांच करें (0.21.1 पर graft check ., 0.22 से graft build --check), फिर लिखित हिस्से को रिफ्रेश करने के लिए graft build --deep चलाएं।
आज कौन से कोडिंग agents Graft का उपयोग कर सकते हैं?
pinned 0.21.1 पर, graft init Claude Code, Cursor, Codex, GitHub Copilot, Google Gemini, Kiro, Windsurf, Grok (xAI), AdaL, Hermes Agent और Google Antigravity को जोड़ता है, कुल मिलाकर ग्यारह hosts। changelog में 0.13.0 के बाद से Hermes Agent को प्रथम-श्रेणी host के रूप में सूचीबद्ध किया गया है, और hermes तथा antigravity pinned release पर सामान्य --agents ids हैं। Claude Code को सबसे अधिक मिलता है: .mcp.json में एक MCP server entry, एक statusline, post-edit hooks और .claude/ के तहत एक skill फाइल। Codex को एक AGENTS.md सेक्शन और ~/.codex/ के तहत machine-wide entries मिलती हैं, जिसे graft init --no-global छोड़ देता है। Grok को एक skill फाइल और .grok/config.toml में एक MCP ब्लॉक मिलता है। Hermes Agent और Antigravity AGENTS.md सेक्शन को पढ़ते हैं, और अन्य को rules या steering फाइल प्राप्त होती है। कोई भी अन्य MCP client npx -y @nanonets/graft@0.21.1 mcp कमांड को रजिस्टर करके सीधे server का उपयोग कर सकता है।