Graft: coding agents కోసం codebase map
Graft tree-sitter తో repository ను codebase map గా మార్చి, MCP ద్వారా coding agent కు query tools అందిస్తుంది. ప్రతి session లో structure ను మళ్లీ వెతకాల్సిన పని తగ్గుతుంది.
కోడింగ్ ఏజెంట్ల కోసం codebase map అంటే ఏమిటి
కోడింగ్ ఏజెంట్ల కోసం codebase map అనేది మీ repository యొక్క స్థిరమైన index. ప్రతి కొత్త session లో మొదటి నుంచి grep చేయడానికి బదులుగా, agent ఈ index లో అవసరమైన సమాచారాన్ని చూసుకుంటుంది. Graft ఈ ఆలోచనకు ఒక implementation. ఇది tree-sitter తో మీ code ను parse చేసి, పరస్పరం అనుసంధానమైన markdown nodes ఉన్న folder తో పాటు ప్రతి symbol కు సంబంధించిన wiring graph ను రాస్తుంది. తరువాత MCP (model context protocol, coding agents బయట tools ను పిలవడానికి ఉపయోగించే standard interface) ద్వారా retrieval tools ను అందిస్తుంది.
Graft proxy కాదు, gateway కూడా కాదు. మీ agent మరియు model API మధ్య ఏ component కూడా ఉండదు. Map అనేది disk లో ఉన్న ఒక folder; agent దాన్ని చదువుతుంది. ఈ తేడా మీరు పరిష్కరిస్తున్న సమస్యను నిర్ణయిస్తుంది: self-hosted token gateway మీరు ఇప్పటికే పంపుతున్న requests ను కొలిచి route చేస్తుంది, అయితే map ద్వారా అసలు ఎన్ని requests పంపాల్సి ఉంటుందో మారుతుంది.
ఈ technique ఈ tool కంటే పాతది; ఈ tool తర్వాత కూడా కొనసాగుతుంది. ముందుగా technique ను నేర్చుకోండి. తరువాత mechanics ను తెలుసుకోండి.
కోడింగ్ ఏజెంట్లు స్ట్రక్చర్ను మళ్లీ మళ్లీ కనుగొనడంలో కాంటెక్స్ట్ను ఎందుకు వృథా చేస్తాయి
ఇప్పటికే యాభై సార్లు చూసిన రిపోజిటరీపై ఒక ఏజెంట్ పని ప్రారంభించడాన్ని గమనించండి. అది డైరెక్టరీలను లిస్ట్ చేస్తుంది. ఒక సింబల్ కోసం grep చేస్తుంది. ఫంక్షన్ ఎక్కడ నిర్వచించబడిందో తెలుసుకోవడానికి మూడు ఫైళ్లను ఓపెన్ చేస్తుంది, ఆపై దాన్ని ఎవరు పిలుస్తున్నారో తెలుసుకోవడానికి నాలుగో ఫైల్ను ఓపెన్ చేస్తుంది. ఇవేవీ అసలు పని కాదు. ఇది కేవలం ఓరియంటేషన్ మాత్రమే, మరియు ప్రతి సెషన్లోనూ దీని కోసం మీరు ఇన్పుట్ టోకెన్ల రూపంలో డబ్బు చెల్లిస్తున్నారు.
దీనికి కారణం చాలా సరళం. సెషన్ల మధ్య మోడల్కు ఎటువంటి జ్ఞాపకశక్తి ఉండదు. ఏజెంట్ మీ లేఅవుట్ గురించి తెలుసుకున్నదంతా ఒక కాంటెక్స్ట్ విండోలో ఉంటుంది, సెషన్ ముగియగానే అది తొలగించబడుతుంది. కాబట్టి అదే అన్వేషణ మళ్లీ సున్నా నుండి మొదలవుతుంది, మీరు దానికి మళ్లీ చెల్లించాల్సి వస్తుంది. ప్రాంప్ట్ క్యాచింగ్ (Prompt caching) అనేది గత ఐదు నిమిషాల్లో లేదా అదనపు ఖర్చుతో గత గంటలో చూసిన ఒకే విధమైన ప్రాంప్ట్ ప్రిఫిక్స్కు మాత్రమే తగ్గింపును ఇస్తుంది, కాబట్టి ఇది నిన్నటి అన్వేషణను నేటి సెషన్లోకి తీసుకురాలేదు. పెద్ద రిపోజిటరీలలో, ఎడిట్ చేసే పని కంటే ఓరియంటేషన్ దశకే ఎక్కువ ఖర్చవుతుంది: కోడ్ను గుర్తించడానికి పది టూల్ కాల్స్, మార్చడానికి ఒకటి. ఓరియంటేషన్ అనేది బిల్లులో సగం, ఎడిట్ మరొక సగం. అందుకే ఏజెంట్ను అత్యంత చిన్న మార్పుకే పరిమితం చేసే నైపుణ్యం మరియు మ్యాప్ను కలిపి ఉపయోగించడం మంచిది, రెండింటిలో ఒకటి ఎంచుకోవడం కంటే.
ఒక మ్యాప్ ఈ లూప్ను విచ్ఛిన్నం చేస్తుంది, ఎందుకంటే ఇది అన్వేషణను మోడల్ నుండి డిస్క్కు మారుస్తుంది. ఒక పార్సర్ రిపోజిటరీని ఒకసారి స్కాన్ చేసి, ఏ సింబల్ ఎక్కడ నిర్వచించబడిందో మరియు ఏది దేనిని పిలుస్తుందో రికార్డ్ చేస్తుంది, ఆపై కోడ్ మారినప్పుడు ఆ రికార్డును అప్డేట్గా ఉంచుతుంది. ఏజెంట్ ఒక ప్రశ్న అడిగితే, ఫైల్ మరియు లైన్ నంబర్తో సహా సమాధానం వస్తుంది. దీనివల్ల పదేపదే చేసే అన్వేషణ చౌకైన లుకప్గా మారుతుంది.
మీరు ఇప్పటికే దీని యొక్క బలహీనమైన వెర్షన్ను ఉపయోగిస్తున్నారు. మీ కన్వెన్షన్లను వివరించే AGENTS.md ఫైల్, ఏజెంట్ ప్రతిసారీ మీ కన్వెన్షన్లను మళ్లీ కనుగొనకుండా ఆపుతుంది. జనరేట్ చేసిన మ్యాప్, అది మీ స్ట్రక్చర్ను మళ్లీ కనుగొనకుండా ఆపుతుంది. తేడా ఏమిటంటే, ఎవరు రాస్తున్నారు అనేది. మీరు ఇన్స్ట్రక్షన్ ఫైల్ను స్వయంగా రాస్తారు, కాబట్టి అది చిన్నదిగా ఉంటుంది. పార్సర్ మ్యాప్ను జనరేట్ చేస్తుంది, కాబట్టి అది పది వేల ఫైళ్లను కవర్ చేయగలదు. ఒక సెషన్లో బడ్జెట్ ఎక్కడ ఖర్చవుతుందో తెలుసుకోవడానికి, Claude Code తన కాంటెక్స్ట్ విండోను ఎలా ఖర్చు చేస్తుంది అనే అంశం అకౌంటింగ్ను వివరిస్తుంది.
Graft వాస్తవానికి ఏమి నిర్మిస్తుంది
రెండు ఆర్టిఫాక్ట్లు, రెండూ రిపోజిటరీ రూట్లో ఒకే graft/ ఫోల్డర్ కింద ఉంటాయి.
మొదటిది లింక్ చేయబడిన మార్క్డౌన్ రూపంలో ఉన్న నోడ్ గ్రాఫ్, ప్రతి నోడ్కు ఒక ఫైల్ ఉంటుంది. ప్రతి నోడ్ ఒక సాధారణ ఆంగ్ల సారాంశాన్ని, సోర్స్ నుండి సేకరించిన ముఖ్యమైన లాజిక్ లైన్ల "క్రక్స్" (crux) ను, కంటెంట్ హ్యాష్తో కూడిన ఖచ్చితమైన సోర్స్ ఫైళ్లను, ఇతర నోడ్లకు టైప్ చేసిన వికీలింక్లను (depends_on, part_of, uses, implements), మరియు రీజెనరేషన్ తర్వాత కూడా చెరిగిపోని నోట్స్ విభాగాన్ని కలిగి ఉంటుంది, తద్వారా పార్సర్ గుర్తించలేని సందర్భాన్ని మీరు నమోదు చేసుకోవచ్చు.
రెండవది graft/.graph/wiring.json, ఇది tree-sitter సేకరించే ప్రతి-సింబల్ స్ట్రక్చరల్ గ్రాఫ్: డెఫినిషన్లు, రిఫరెన్స్లు మరియు వాటి మధ్య ఉన్న కాల్ ఎడ్జ్లు.
ఈ విభజన ముఖ్యమైనది ఎందుకంటే సగం భాగానికి మాత్రమే మోడల్ అవసరం. graft build పూర్తిగా tree-sitter పై ఆధారపడి ఉంటుంది మరియు ఎప్పుడూ LLM (large language model) ను పిలవదు, కాబట్టి ఇది డిటర్మినిస్టిక్ మరియు ఎటువంటి ఖర్చు ఉండదు. graft build --deep వ్రాతపూర్వక సారాంశాలను మరియు ప్రతి-సింబల్ క్రక్స్లను జోడిస్తుంది, ఇవి మీరు చెల్లించాల్సిన మోడల్ కాల్లు.
భాషా మద్దతు శ్రేణీకృతమైనది (tiered), మరియు ఈ శ్రేణి కాల్ గ్రాఫ్ను ఎంతవరకు నమ్మవచ్చో తెలియజేస్తుంది. TypeScript, JavaScript, Python, Go, Java, Kotlin, PHP, Swift మరియు R భాషలకు స్కోప్-అవేర్ క్రాస్-ఫైల్ రిజల్యూషన్ లభిస్తుంది. Rust, C, C++, C#, Ruby, Scala, Elixir, Solidity, OCaml, Zig, Dart, Clojure, Nix మరియు Lua భాషలకు సింబల్స్ మరియు జనరిక్ కాల్ ఎడ్జ్లు లభిస్తాయి, అంటే ఒక ఎడ్జ్ అనేది రిజాల్వ్ చేయబడిన రిఫరెన్స్ కంటే పేరు సరిపోలిక (name match) కావచ్చు. కంపైలర్-గ్రేడ్ ఎడ్జ్లు --lsp మరియు rust-analyzer లేదా gopls వంటి లాంగ్వేజ్ సర్వర్ ద్వారా ఆప్ట్-ఇన్ చేసుకోవచ్చు.
Graft ఇన్స్టాల్ చేయడం మరియు వెర్షన్ను పిన్ చేయడం
Graft కు Node.js 20 లేదా అంతకంటే కొత్త వెర్షన్ అవసరం మరియు ఇది MIT లైసెన్స్తో లభిస్తుంది. 17 అక్టోబర్ 2026 నాటికి, ప్రస్తుత release 0.23.0, ఇది 15 అక్టోబర్ 2026న విడుదలైంది. మొదటి వెర్షన్ 0.1.0, జూలై 2026 నాటిది. దీన్ని కొత్త సాఫ్ట్వేర్గా పరిగణించండి. 14 అక్టోబర్ 2026న విడుదలైన 0.22.0 వెర్షన్లో, ఈ ప్రాజెక్ట్ పేరును Trail-code గా మార్చారు: అదే కోడ్ ఇప్పుడు @trailhq/trail-code గా కూడా లభిస్తుంది మరియు trail కమాండ్ను కలిగి ఉంటుంది, అయితే @nanonets/graft లో graft కమాండ్ అలాగే ఉంటుంది.
ఈ గైడ్ 0.21.1 వెర్షన్ను పిన్ చేస్తుంది. ఇది 29 సెప్టెంబర్ 2026న విడుదలైంది మరియు పేరు మార్పుకు ముందు వచ్చిన చివరి release. ఎందుకంటే 0.22 మరియు 0.23 వెర్షన్లలో ఈ గైడ్ ఆధారపడే కమాండ్లు మారాయి. 0.22 నుండి, graft check మీ బ్రాంచ్ యొక్క diff ను రిపోజిటరీలోని టీమ్ లెర్నింగ్స్తో పోల్చి, conflict ఉంటే 1 తో exit అవుతుంది. drift డిటెక్షన్ graft build --check కి మారింది మరియు MCP టూల్స్ పేరు trail_* గా మారింది (సర్వర్ ఇప్పటికీ పాత graft_* పేర్లకు స్పందిస్తుంది). 0.23.0 changelog ప్రకారం, trail తో సెటప్ చేసిన రిపోజిటరీలో మ్యాప్ .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 ట్యాగ్ను తీసుకుంటుంది. నెలలో అనేక minor releases విడుదల చేసే ప్రాజెక్ట్లో, ఇలా చేయడం వల్ల మీ సహోద్యోగి సోమవారం ఇన్స్టాల్ చేసుకున్న టూల్కు, మీకు మంగళవారం లభించే టూల్కు తేడా ఉంటుంది. పిన్ చేసిన వెర్షన్ అందరికీ ఒకే విధమైన CLI flags మరియు గ్రాఫ్ ఫార్మాట్ను అందిస్తుంది, కాబట్టి మీరు నిర్ణయించుకున్నప్పుడు మాత్రమే అప్గ్రేడ్ చేసుకోవచ్చు.
ఆ తర్వాత, మీకు చెందిన రిపోజిటరీకి దీన్ని అనుసంధానించండి:
cd /path/to/your/repo
graft init --dry-run
graft initgraft init కమాండ్ ఏ కోడింగ్ ఏజెంట్ను అనుసంధానించాలో అడుగుతుంది, ఆపై గ్రాఫ్ను నిర్మిస్తుంది. ముందుగా --dry-run రన్ చేసి, అది మార్చబోయే ఫైళ్ల జాబితాను చదవండి, ఎందుకంటే వాటిలో కొన్ని రిపోజిటరీ వెలుపల ఉండవచ్చు. graft init అనేది idempotent, అంటే ఇది ఇప్పటికే ఉన్న కాన్ఫిగరేషన్లను ఓవర్రైట్ చేయదు, కాబట్టి దీన్ని రెండోసారి రన్ చేయడం సురక్షితం. వెనక్కి రావాలంటే, graft uninstall కమాండ్ Graft రాసిన ప్రతి ఫైల్ మరియు కాన్ఫిగరేషన్ ఎంట్రీని తొలగిస్తుంది. మీరు -y పాస్ చేసే వరకు ఇది కేవలం dry run గానే పనిచేస్తుంది.
అదే ప్రాంప్ట్లో టెలిమెట్రీ చెక్బాక్స్ ఉంటుంది. 0.12.0 release నుండి, Graft డిఫాల్ట్గా అనామక వినియోగ పింగ్ను పంపుతుంది: ఇందులో బకెట్ కౌంట్లు మరియు స్థిరమైన లేబుల్స్ మాత్రమే ఉంటాయి, మీ కోడ్, ఫైల్ పాత్లు లేదా రిపోజిటరీ పేరు ఎప్పటికీ ఉండవు. ఈ ఈవెంట్లు రోజుకు ఒకసారి మాత్రమే పోస్ట్ చేయబడతాయి, అయితే ఇన్స్టాల్ ఈవెంట్ మినహాయింపు: npm యొక్క postinstall హుక్ దీన్ని వెంటనే బ్యాక్గ్రౌండ్ సెండర్కు పంపుతుంది. 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 0.13.0 release నుండి ఫస్ట్-క్లాస్ graft init హోస్ట్గా ఉంది, మరియు పిన్ చేసిన వెర్షన్లో graft init --agents hermes మరియు graft init --agents antigravity కమాండ్లు ఇతర హోస్ట్ల మాదిరిగానే వీటిని ఎంచుకుంటాయి. Grok 0.13.0 releaseలో చేరింది మరియు దీన్ని graft init --agents grok తో ఎంచుకోవచ్చు. Claude Code అత్యంత లోతైన ఇంటిగ్రేషన్ను కలిగి ఉంది: ఒక MCP సర్వర్ ఎంట్రీ, గ్రాఫ్ పరిమాణం మరియు పాత సమాచారాన్ని చూపే స్టేటస్లైన్, గ్రాఫ్ను తిరిగి నిర్మించే post-edit హుక్స్, మరియు .claude/ కింద ఒక స్కిల్ ఫైల్. మిగిలిన వాటికి టూల్స్ ఉన్నాయని ఏజెంట్కు తెలియజేసే ఇన్స్ట్రక్షన్ లేదా రూల్ ఫైల్ ఉంటుంది (Hermes Agent మరియు Antigravity రెండూ AGENTS.md సెక్షన్ను చదువుతాయి), మరియు Grok తన సొంత కాన్ఫిగరేషన్లో MCP బ్లాక్ను కూడా పొందుతుంది. కాబట్టి "మద్దతు" అంటే Graft వైరింగ్ను రాస్తుందని అర్థం, కాబట్టి ఏ ఏజెంట్ అయితే తన సొంత రూల్స్ ఫైల్ను విస్మరిస్తుందో, అది మ్యాప్ను కూడా విస్మరిస్తుంది. ఏజెంట్లు మీరు రాసిన సూచనలను ఎందుకు విస్మరిస్తాయి అనే దానికి ఇది సాధారణ కారణం, మరియు ఇది ఇక్కడ కూడా వర్తిస్తుంది.
మీ రిపోజిటరీలో ఏమి ఉండాలి, మరియు git లో దేనిని ఉంచకూడదు
graft init తర్వాత, వీటిని ఆశించండి:
graft/: మార్క్డౌన్ నోడ్ గ్రాఫ్ మరియుgraft/.graph/wiring.json. ఇవి మీ కోసం.gitignoreకి జోడించబడతాయి..mcp.json: ఇది గ్రాఫ్ట్ MCP సర్వర్ను రిజిస్టర్ చేస్తుంది, తద్వారా Claude Code దానిని ప్రారంభిస్తుంది..claude/settings.json: ఇది యథాస్థానంలో విలీనం చేయబడుతుంది, స్టేటస్లైన్ మరియు పోస్ట్-ఎడిట్ హుక్స్ను జోడిస్తుంది.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 వంటి ఒక కాష్. దీనిని commit చేయవద్దు. ఇది సెకన్లలో కోడ్ నుండి తిరిగి రూపొందించబడుతుంది, ప్రతి ఎడిట్తో ఇది మారుతుంది. దీనిని commit చేయడం వల్ల ఒక చిన్న మార్పు కూడా వందల ఫైళ్ల diff గా మారుతుంది, దీనిని ఎవరూ సమీక్షించలేరు. దానికి బదులుగా వైరింగ్ను commit చేయండి, ఇందులో AGENTS.md మరియు .mcp.json ఉంటాయి. మీ బృంద సభ్యులు రిపోజిటరీని clone చేసుకుని, graft build రన్ చేసినప్పుడు, వారికి వారి స్వంత లోకల్ గ్రాఫ్ లభిస్తుంది.
మీరు మొదటి commit చేయడానికి ముందే ignore రూల్ అమలైందో లేదో తనిఖీ చేయండి:
grep -n graft .gitignore
git status --shortgrep రన్ చేసినప్పుడు graft/ ఉన్న లైన్ కనిపించాలి, మరియు git status --short రన్ చేసినప్పుడు graft/ కింద ఏమీ కనిపించకూడదు. ఆ అవుట్పుట్లో graft/ కింద ఫైళ్లు కనిపిస్తే, ignore ఎంట్రీ లేదని లేదా వేరే చోట override చేయబడిందని అర్థం. commit చేయడానికి ముందే దీనిని సరిచేయండి, ఎందుకంటే ఒక ఫైల్ 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 కాల్ చేసేవారు (callers) లేదా కాల్ చేయబడేవారిని (callees) పలు స్థాయిల లోతు వరకు పరిశీలిస్తుంది. graft_find_all రెగ్యులర్ ఎక్స్ప్రెషన్ (regex) ద్వారా దొరికిన ఫలితాలను సింబల్ వారీగా గ్రూప్ చేస్తుంది. graft_repo_map కొత్త రిపోజిటరీని ప్రాథమికంగా అర్థం చేసుకోవడానికి ఉపయోగపడుతుంది. graft_check_freshness గ్రాఫ్ ఇంకా కోడ్తో సరిపోలుతుందో లేదో తెలియజేస్తుంది.
ప్రతి టూల్కు ఒక CLI వెర్షన్ ఉంది, మీ ఏజెంట్కు ఏమి అందుతుందో మీరు దీని ద్వారా తనిఖీ చేయవచ్చు:
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 కి మారాలి. అవి కూడా ఫలితాన్ని ఇవ్వకపోతే, డ్రిఫ్ట్ (drift) ఉందేమో తనిఖీ చేయండి (0.21.1 వెర్షన్లో graft check ., 0.22 నుంచి graft build --check ద్వారా) మరియు మీ ప్రోగ్రామింగ్ లాంగ్వేజ్ ఏ టైర్లో ఉందో నిర్ధారించుకోండి, ఎందుకంటే పాతబడిన గ్రాఫ్ లేదా బ్రాడ్-టైర్ ఎడ్జెస్ మీ ఏజెంట్ పనితీరును దెబ్బతీస్తాయి.
ఒక ఖర్చును గమనించడం సులభం. ప్రతి సెషన్ అభ్యర్థనలో ఆరు టూల్ డెఫినిషన్లు సిస్టమ్ ప్రాంప్ట్లో ఇంజెక్ట్ చేయబడతాయి. ఏజెంట్ మ్యాప్ను ఉపయోగించినా, ఉపయోగించకపోయినా మీరు దీనికి చెల్లించాల్సి ఉంటుంది. కాంటెక్స్ట్లో సరిపోయేంత చిన్న రిపోజిటరీ విషయంలో, ఈ స్థిర ఛార్జీ అది ఆదా చేసే సమయం కంటే ఎక్కువగా ఉండవచ్చు.
కోడ్ మారినప్పుడు గ్రాఫ్కు ఏమవుతుంది
స్ట్రక్చరల్ రిఫ్రెష్ తక్కువ ఖర్చుతో కూడుకున్నది మరియు ఆటోమేటిక్. Graft అనేది git కు బదులుగా మీ వర్కింగ్ ట్రీని చదువుతుంది, కాబట్టి మీరు commit చేయని మార్పులు మరియు మీరు stage చేసిన మార్పులు రెండూ దానికి సమానంగా కనిపిస్తాయి. ప్రతి క్వెరీ మొదట వర్కింగ్ ట్రీని stats చేస్తుంది మరియు మారిన ఫైళ్లను మాత్రమే తిరిగి పార్స్ చేస్తుంది. 0.21.1 డాక్యుమెంటేషన్ ప్రకారం, ఏ మార్పు లేనప్పుడు ఈ తనిఖీకి సుమారు 3 ms సమయం పడుతుంది; ప్రస్తుత README ప్రకారం ఇది కొన్ని పదుల మిల్లీసెకన్లు, ప్రాజెక్ట్ సొంత రిపోజిటరీపై అయితే సుమారు 50 ms పడుతుంది. టర్న్-ఎండ్ రీబిల్డ్ కేవలం కోడ్ మారిన ఫైళ్లను మాత్రమే తాకుతుంది. డిస్క్లోని గ్రాఫ్ నుండి తిరిగి పార్స్ చేయకుండా సమాధానం పొందడానికి GRAFT_NO_REFRESH=1 సెట్ చేయండి లేదా --no-refresh ని పాస్ చేయండి. Graft ను అప్గ్రేడ్ చేసిన తర్వాత అవసరమైనట్లుగా, ప్రతిదీ కోల్డ్ రీ-పార్స్ చేయడానికి --no-reuse ని పాస్ చేయండి.
మోడల్-రైటెన్ భాగం భిన్నంగా పనిచేస్తుంది, మరియు ఇది నిశ్శబ్దంగా తప్పులు జరిగే భాగం. సమ్మరీలు మరియు క్రక్స్ (cruxes) క్యాష్ చేయబడతాయి. ప్రతి నోడ్ దాని సోర్స్ల కంటెంట్ హ్యాష్ను రికార్డ్ చేస్తుంది, కాబట్టి సోర్స్ ఫైల్ మారినప్పుడు ఆ నోడ్ ప్రస్తుతమైనదిగా కాకుండా stale (పాతది) గా గుర్తించబడుతుంది. ఏదైనా దానిపై చర్య తీసుకుంటేనే ఆ ఫ్లాగ్ ఉపయోగపడుతుంది. graft build --deep తో రిఫ్రెష్ చేయండి, ఇది మళ్ళీ మోడల్ టోకెన్లను ఖర్చు చేస్తుంది.
Staleness ను కనిపించేలా చేయండి:
graft check .
echo $?పిన్ చేసిన 0.21.1 వెర్షన్లో, ఎగ్జిట్ స్టేటస్ 0 అంటే గ్రాఫ్ కోడ్తో సరిపోలుతుందని, ఎగ్జిట్ స్టేటస్ 1 అంటే డ్రిఫ్ట్ (drift) ఉందని అర్థం. 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 పనులతో కూడిన మూడవ రన్, పది డెవలపర్ ప్రశ్నలు మరియు ఐదు పునరుత్పత్తి చేయబడిన మెర్జ్డ్ పుల్ రిక్వెస్ట్లతో కలిపి, బేస్లైన్ కోసం 13.91 డాలర్లకు బదులుగా మొత్తం 11.02 అమెరికన్ డాలర్ల ఖర్చు అయ్యింది.
వీటన్నింటినీ వెండర్ బెంచ్మార్క్గా పరిగణించండి. ఇది మీకు ఏమి చెప్పగలదో పరిమితం చేసే రెండు విషయాలు ఉన్నాయి. నియంత్రిత స్వీప్లో Graft యొక్క స్వంత రిపోజిటరీ ఉంది, ఇది దాని రచయితలు దేనిపై ట్యూన్ చేశారో అదే కోడ్బేస్. SWE-bench Verified అనేది ప్రసిద్ధ ఓపెన్-సోర్స్ Python ప్రాజెక్ట్ల నుండి సేకరించిన సమస్యల పబ్లిక్ డేటాసెట్, మరియు ఎవరైనా ఉద్దేశపూర్వకంగా చేసినా చేయకపోయినా, టూల్స్ ఈ పబ్లిక్ డేటాసెట్ల కోసమే ఆప్టిమైజ్ చేయబడతాయి. వీటిలో ఏదీ మీ ప్రైవేట్ మోనోరెపో గురించి చెప్పేది కాదు, ఎందుకంటే దానికి దాని స్వంత నామింగ్ అలవాట్లు మరియు డెడ్ కోడ్ ఉంటాయి.
ఖచ్చితత్వం (correctness) గురించి మరోసారి చదవాలి. నియంత్రిత స్వీప్లో అది మారలేదు: మ్యాప్తో 93% మరియు అది లేకుండా 93%. SWE-bench Verified లో మాత్రమే 54% నుండి 66% కి పెరిగినట్లు కనిపిస్తుంది. మీ టోకెన్ బిల్లును తగ్గించి, నాణ్యతను స్థిరంగా ఉంచే టూల్ మంచి ప్రయోజనకరమైనదే. అయితే, SWE-bench ఖచ్చితత్వ ఫలితాన్ని స్వీప్ యొక్క టోకెన్ ఫలితంతో కలిపి ఒకే క్లెయిమ్గా పేర్కొనకండి.
మీ స్వంత token delta ను కొలిచిన తర్వాతే ఈ ఫలితాలను నమ్మండి
ముఖ్యమైన ఏకైక సంఖ్య మీ repository నుంచి వచ్చినదే. ఈ పద్ధతికి ఒక మధ్యాహ్నం సమయం పడుతుంది.
మీరు కచ్చితంగా పునరావృతం చేయగల task ను ఎంచుకోండి. Edit కంటే question మంచిది, ఎందుకంటే edit repository ను మార్చేస్తుంది. అప్పుడు రెండో run అదే experiment గా ఉండదు. "Which module enforces the rate limit on the login route" అనేది సరైన రూపం.
Telemetry ను ప్రారంభించి, మీ స్వంత terminal కు పంపండి:
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
claudeConsole exporter metric records ను సేకరించిన వెంటనే ప్రింట్ చేస్తుంది. మీకు కావాల్సింది claude_code.token.usage. ఇందులో input, output, cacheRead లేదా cacheCreation విలువ కలిగిన type attribute ఉంటుంది. Orientation విలువలు input మరియు cacheRead లో కనిపిస్తాయి, ఎందుకంటే file contents అక్కడే నిల్వ అవుతాయి. ఆ రెండింటినీ కలపండి.
Map అనుసంధానించిన తాజా session లో task ను మూడు సార్లు run చేయండి. తరువాత .mcp.json నుంచి graft entry ను తొలగించి, మరో మూడు సార్లు run చేయండి. ఒక్కో run ను కాకుండా medians ను పోల్చండి. Agent runs లో పెద్ద మార్పులు ఉండవచ్చు. ఒక అననుకూల run వాస్తవానికి విరుద్ధమైన ఫలితాన్ని చూపవచ్చు. Tool-call count ను కూడా నమోదు చేయండి. Tool calls mechanism, tokens effect. కాబట్టి tool calls తగ్గకుండా tokens మాత్రమే తగ్గితే, మరేదో మారి ఉంటుంది.
తరువాత benchmark చూపించని costs ను తీసివేయండి. graft build --deep ప్రతి full refresh లో model tokens ను వినియోగిస్తుంది. ప్రతి request లో ఆరు tool schemas కూడా పంపబడతాయి. మీ agents మీరు అద్దెకు తీసుకున్న server పై నడుస్తుంటే, agent ఖర్చుపై కఠిన పరిమితి పెట్టడం అనుకోని ఖర్చును budget గా మార్చుతుంది. Exporter ను ప్రారంభించిన తర్వాత machine నుంచి నిజంగా ఏ సమాచారం బయటకు వెళ్తుందో coding agent telemetry వాస్తవంగా ఏమి నివేదిస్తుంది వివరిస్తుంది.
కోడ్బేస్ మ్యాప్ ఎప్పుడు సహాయపడదు?
- రిపోజిటరీ ఇప్పటికే కాంటెక్స్ట్లో సరిపోతుంది. ఒక చిన్న సర్వీస్కు మ్యాప్ అవసరం లేదు, కానీ ప్రతి అభ్యర్థనపై మీరు ఆరు టూల్ స్కీమాల కోసం ఖర్చు చేస్తున్నారు. మీ ఏజెంట్ ఏదైనా ఫైల్ను ఒకటి లేదా రెండు టూల్ కాల్స్లోనే కనుగొనగలిగితే, మ్యాప్ను వదిలేయండి.
- మీ ప్రోగ్రామింగ్ లాంగ్వేజ్ బ్రాడ్ టైర్లో ఉంది. జెనరిక్ కాల్ ఎడ్జెస్ (Generic call edges) వల్ల
graft callersఒక కాలర్ను మిస్ అవ్వవచ్చు లేదా పేరులో సారూప్యత (name collision) వల్ల తప్పుడు ఫలితాన్ని ఇవ్వవచ్చు. మీరు బ్లాస్ట్ రేడియస్ను నమ్మే ముందుgraft grepతో నిర్ధారించుకోండి. - గ్రాఫ్ పాతబడిపోయినా ఎవరూ గమనించలేదు. 0.21.1 వెర్షన్లో
graft checkడ్రిఫ్ట్ (drift) ఏర్పడినప్పుడు 1 ఎగ్జిట్ కోడ్ను ఇస్తుంది (0.22 నుంచిgraft build --checkఇలా చేస్తుంది), కానీ దీన్ని ఎవరైనా రన్ చేస్తేనే ఇది ఉపయోగకరం. ఇది అలవాటుగా కాకుండా, ఒక pre-push hook గా ఉండాలి. - మోనోరెపోకు స్కోపింగ్ అవసరం. ఒకే git మోనోరెపో విడదీయబడదు, కానీ
graft buildఅనేదిpnpm-workspace.yaml,package.jsonవర్క్స్పేస్లు లేదా పర్-ప్యాకేజీgo.mod,pyproject.tomlలేదాCargo.tomlనుండి సబ్-ప్రాజెక్ట్లను గుర్తిస్తుంది మరియు వాటిని ర్యాంకింగ్ స్కోప్లుగా ఉపయోగిస్తుంది. అలాగేgraft ask "..." --in services/billing/క్వెరీని ఒక సబ్-ప్రాజెక్ట్కు పరిమితం చేస్తుంది. ప్రతి ప్యాకేజీకి నెస్టెడ్ AGENTS.md ఫైల్స్ ఉంచాలనే ఆలోచన మ్యాప్కు కూడా వర్తిస్తుంది. - ఏజెంట్ వైరింగ్ను పట్టించుకోవడం లేదు. మ్యాప్ ఉపయోగించబడుతోందని నిర్ధారించుకునే ముందు, నిజమైన సెషన్లో టూల్ కాల్స్ను గమనించండి. ఒక ఏజెంట్ ఇంకా
grepరన్ చేస్తోందంటే, అది రూల్స్ ఫైల్ను ఎప్పుడూ చదవలేదని అర్థం.
FAQ
Should I commit the graft/ folder to git?
వద్దు. graft build, graft/ ను మీ .gitignore లోకి ఆటోమేటిక్గా జోడిస్తుంది, ఎందుకంటే ఈ గ్రాఫ్ అనేది node_modules లాంటి పునరుత్పత్తి చేయదగిన కాష్ (regenerable cache). ఇది దాదాపు ప్రతి ఎడిట్లో మారుతుంది, కాబట్టి దీన్ని commit చేయడం వల్ల వందలాది జనరేట్ అయిన ఫైళ్ల మధ్య అసలైన diffs కనిపించకుండా పోతాయి. ఏజెంట్లకు మ్యాప్ ఉందని తెలియజేసే వైరింగ్ను commit చేయండి, అందులో AGENTS.md మరియు .mcp.json ఉన్నాయి, మరియు ప్రతి టీమ్ సభ్యుడిని వారి లోకల్ మెషీన్లో graft build రన్ చేయనివ్వండి. మీ మొదటి commit కి ముందే grep -n graft .gitignore మరియు git status --short తో సరిచూసుకోండి, ఎందుకంటే ఒక ఫైల్ యాడ్ అయిన తర్వాత git దాన్ని ట్రాక్ చేస్తూనే ఉంటుంది, ఆ తర్వాత .gitignore ని ఎడిట్ చేసినా అది ట్రాకింగ్ ఆపదు.
Does Graft cost money to run?
స్ట్రక్చరల్ భాగం ఉచితం. graft build, graft ask, graft check మరియు ఆరు MCP రిట్రీవల్ టూల్స్ అనేవి tree-sitter ఆపరేషన్లు, ఇవి ఏ మోడల్ను కాల్ చేయవు. graft build --deep అనేది పెయిడ్ భాగం: ఇది plain-English సారాంశాలను మరియు ప్రతి సింబల్ యొక్క ముఖ్య అంశాలను LLM ద్వారా రాస్తుంది, ఇది GRAFT_PROVIDER, GRAFT_API_KEY మరియు GRAFT_MODEL తో కాన్ఫిగర్ చేయబడుతుంది, అదనంగా OpenAI-compatible ఎండ్పాయింట్ కోసం GRAFT_BASE_URL ని ఉపయోగిస్తుంది. మీరు Graft ని కేవలం స్ట్రక్చర్తో మాత్రమే రన్ చేయవచ్చు మరియు గ్రాఫ్ కోసం ఒక్క టోకెన్ కూడా ఖర్చు చేయాల్సిన అవసరం లేదు.
How much will a codebase map actually save on my repository?
కొలవకుండా ఎవరూ చెప్పలేరు. ఈ ప్రాజెక్ట్ తన సొంత 162-run స్వీప్లో 42% తక్కువ uncached ఇన్పుట్ టోకెన్లను మరియు SWE-bench Verified పై 23% తక్కువ టోకెన్లను నివేదించింది, ఇవి రెండూ మ్యాప్ లేని బేస్లైన్తో పోల్చబడినవి. ఇవి రెండూ వెండర్ బెంచ్మార్క్లు, వీటిలో ఒకటి Graft సొంత రిపోజిటరీపై పాక్షికంగా రన్ చేయబడింది, మరియు ఏదీ మీ ప్రైవేట్ కోడ్ గురించి వివరించదు. ఒక పునరావృతమయ్యే ప్రశ్నను మ్యాప్తో మూడుసార్లు మరియు మ్యాప్ లేకుండా మూడుసార్లు రన్ చేయండి, CLAUDE_CODE_ENABLE_TELEMETRY=1 మరియు OTEL_METRICS_EXPORTER=console సెట్ చేసి, ఆపై input మరియు cacheRead రకాల కోసం claude_code.token.usage యొక్క మీడియన్ను పోల్చండి.
What happens to the graph when I refactor?
స్ట్రక్చర్ తనను తాను రీ-పార్స్ (re-parse) చేసుకుంటుంది. Graft వర్కింగ్ ట్రీని స్టేట్ (stat) చేసి, మారిన ఫైళ్లను మాత్రమే రీ-పార్స్ చేస్తుంది, కాబట్టి తదుపరి క్వెరీలో పేరు మార్పు (rename) గుర్తించబడుతుంది. ఏమీ మారనప్పుడు, ఆ చెక్ 0.21.1 వెర్షన్లో సుమారు 3 ms మరియు ప్రస్తుత రిలీజ్లో కొన్ని పదుల మిల్లీసెకన్లు తీసుకుంటుంది, మరియు ఇది git హిస్టరీని కాకుండా ఫైళ్లను చదువుతుంది కాబట్టి commit చేయని మార్పులను కూడా చూస్తుంది. మోడల్ రాసిన సారాంశాలు పాతబడిపోతాయి: ప్రతి నోడ్ తన సోర్స్ల కంటెంట్ హ్యాష్ను స్టోర్ చేస్తుంది, మరియు మారిన సోర్స్ నోడ్ను రీరైట్ చేయడానికి బదులుగా పాతబడినదిగా (stale) గుర్తిస్తుంది. డ్రిఫ్ట్ (drift) కోసం చెక్ చేయండి (0.21.1 లో graft check ., 0.22 నుండి graft build --check), ఆపై రాసిన భాగాన్ని రిఫ్రెష్ చేయడానికి graft build --deep ని రన్ చేయండి.
Which coding agents can use Graft today?
పిన్ చేసిన 0.21.1 వెర్షన్లో, graft init అనేది Claude Code, Cursor, Codex, GitHub Copilot, Google Gemini, Kiro, Windsurf, Grok (xAI), AdaL, Hermes Agent మరియు Google Antigravity లను కలుపుతుంది, మొత్తం పదకొండు హోస్ట్లు. చేంజ్లాగ్ 0.13.0 నుండి Hermes Agent ని ఫస్ట్-క్లాస్ హోస్ట్గా పేర్కొంది, మరియు hermes మరియు antigravity లు పిన్ చేసిన రిలీజ్లో సాధారణ --agents ఐడిలు. Claude Code కి అత్యధికంగా అందుతాయి: .mcp.json లో ఒక MCP సర్వర్ ఎంట్రీ, ఒక స్టేటస్లైన్, పోస్ట్-ఎడిట్ హుక్స్ మరియు .claude/ కింద ఒక స్కిల్ ఫైల్. Codex ఒక AGENTS.md సెక్షన్ను మరియు ~/.codex/ కింద మెషీన్-వైడ్ ఎంట్రీలను పొందుతుంది, వీటిని graft init --no-global స్కిప్ చేస్తుంది. Grok ఒక స్కిల్ ఫైల్ను మరియు .grok/config.toml లో ఒక MCP బ్లాక్ను పొందుతుంది. Hermes Agent మరియు Antigravity లు AGENTS.md సెక్షన్ను చదువుతాయి, మరియు మిగిలినవి రూల్స్ లేదా స్టీరింగ్ ఫైల్ను అందుకుంటాయి. మరేదైనా MCP క్లయింట్ npx -y @nanonets/graft@0.21.1 mcp కమాండ్ను రిజిస్టర్ చేయడం ద్వారా సర్వర్ను నేరుగా ఉపయోగించవచ్చు.