Graft: Peta Codebase untuk Coding Agent

Peta codebase untuk coding agent

Peta codebase untuk coding agent adalah indeks repositori yang dipertahankan dan digunakan agent untuk mencari informasi, alih-alih menelusuri codebase dari awal dengan grep pada setiap sesi baru. Graft adalah salah satu implementasi pendekatan ini. Graft mengurai kode Anda dengan tree-sitter, menulis folder berisi node markdown yang saling terhubung serta grafik wiring per simbol, lalu menyediakan alat retrieval melalui MCP (model context protocol, antarmuka standar yang digunakan coding agent untuk memanggil alat eksternal).

Graft bukan proxy dan bukan gateway. Tidak ada komponen yang berada di antara agent dan model API. Peta tersebut adalah folder di disk yang dibaca oleh agent. Perbedaan ini menentukan masalah yang sedang Anda selesaikan: token gateway yang di-host sendiri mengukur dan merutekan request yang sudah Anda kirim, sedangkan peta mengubah jumlah request yang perlu Anda kirim sejak awal.

Teknik ini lebih lama daripada tool tersebut dan akan tetap digunakan setelah tool tersebut tidak lagi ada. Pelajari tekniknya terlebih dahulu, kemudian mekanismenya.

Mengapa coding agent menghabiskan context untuk menemukan kembali struktur

Amati agent yang mulai bekerja pada repository yang sudah dilihatnya lima puluh kali. Agent tersebut mencantumkan direktori. Agent mencari sebuah simbol dengan grep. Agent membuka tiga file untuk mencari file yang mendefinisikan fungsi, lalu file keempat untuk mengetahui siapa yang memanggilnya. Tidak satu pun dari langkah tersebut merupakan tugasnya. Semua itu adalah orientasi, dan biayanya dibayar dalam input token pada setiap sesi.

Penyebabnya sederhana. Model tidak memiliki memori antarsesi. Semua hal yang dipelajari agent tentang layout Anda tersimpan di context window yang dibuang ketika sesi berakhir. Karena itu, proses penemuan yang sama berjalan lagi dari awal dengan biaya penuh. Pada repository besar, fase orientasi dapat lebih mahal daripada pengeditan: sepuluh pemanggilan tool untuk menemukan kode, lalu satu pemanggilan untuk mengubahnya. Orientasi hanya merupakan separuh dari biaya tersebut dan pengeditan merupakan separuh lainnya. Karena itu, skill yang membatasi agent agar hanya melakukan perubahan terkecil yang berfungsi layak dipadukan dengan peta, bukan dipilih sebagai pengganti peta.

Peta memutus siklus tersebut dengan memindahkan proses penemuan dari model ke disk. Parser menelusuri repository satu kali, mencatat simbol yang didefinisikan di setiap lokasi serta simbol yang memanggil simbol lain, lalu memperbarui catatan tersebut saat kode berubah. Agent mengajukan satu pertanyaan dan memperoleh jawaban yang mencantumkan file serta barisnya. Eksplorasi berulang berubah menjadi pencarian data yang murah.

Anda sudah menggunakan versi yang lebih sederhana dari pendekatan ini. AGENTS.md yang menyatakan konvensi Anda mencegah agent menyimpulkan kembali konvensi tersebut setiap kali. Peta yang dibuat secara otomatis mencegah agent menyimpulkan kembali struktur repository. Perbedaannya terletak pada pihak yang menulisnya. Anda menulis file instruksi secara manual, sehingga ukurannya tetap kecil. Parser membuat peta secara otomatis, sehingga peta tersebut dapat mencakup sepuluh ribu file. Untuk mengetahui ke mana anggaran context sebenarnya digunakan dalam sebuah sesi, cara Claude Code menggunakan context window menjelaskan perhitungannya.

Hal yang Sebenarnya Dibangun Graft

Dua artefak, keduanya berada di bawah satu folder graft/ di root repositori.

Artefak pertama adalah graf node yang ditulis sebagai markdown tertaut, satu file untuk setiap node. Setiap node berisi ringkasan dalam bahasa yang mudah dipahami, “crux” yang memuat baris logika penting dari source, file source yang tepat beserta content hash, wikilink bertipe ke node lain (depends_on, part_of, uses, implements), serta bagian catatan yang tetap dipertahankan saat regenerasi agar Anda dapat mencatat konteks yang tidak dapat disimpulkan oleh parser.

Artefak kedua adalah graft/.graph/wiring.json, yaitu graf struktural per simbol yang diekstrak oleh tree-sitter: definisi, referensi, dan edge pemanggilan di antaranya.

Pemisahan ini penting karena hanya satu bagian yang memerlukan model. graft build sepenuhnya menggunakan tree-sitter dan tidak pernah memanggil LLM (large language model), sehingga hasilnya deterministik dan tidak memerlukan biaya. graft build --deep menambahkan ringkasan tertulis dan crux per simbol, yang memerlukan pemanggilan model dan dikenai biaya.

Dukungan bahasa dibagi ke dalam beberapa tier, dan tier tersebut menunjukkan sejauh mana Anda dapat mempercayai call graph. TypeScript, JavaScript, Python, Go, dan Java mendapatkan resolusi lintas-file yang mempertimbangkan scope. Rust, C, C++, C#, Ruby, PHP, Kotlin, Scala, Swift, Elixir, Solidity, OCaml, Zig, dan Dart mendapatkan simbol serta edge pemanggilan generik. Artinya, sebuah edge dapat didasarkan pada kecocokan nama, bukan referensi yang telah di-resolve. Edge setara compiler dapat diaktifkan secara opsional dengan --lsp dan language server seperti rust-analyzer atau gopls.

Instal Graft dan kunci versinya

Graft memerlukan Node.js 20 atau yang lebih baru dan menggunakan lisensi MIT. Per Agustus 2026, rilis saat ini adalah 0.10.1, sedangkan versi pertama yang dipublikasikan, 0.1.0, bertanggal Juli 2026. Anggap Graft sebagai software yang masih baru.

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

npm ls -g harus menampilkan @nanonets/graft@0.10.1. Kunci versi tersebut secara sengaja. npm install -g @nanonets/graft tanpa versi akan menggunakan tag latest pada saat perintah dijalankan. Jika sebuah project merilis beberapa versi minor setiap bulan, Anda dapat menggunakan tool yang berbeda pada hari Selasa dari yang diinstal rekan Anda pada hari Senin. Versi yang dikunci memastikan flag CLI dan format graph tetap sama untuk semua orang, sehingga Anda dapat melakukan upgrade sesuai keputusan Anda.

Berikutnya, hubungkan Graft ke repository yang Anda miliki:

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

graft init menanyakan coding agent yang ingin Anda hubungkan, lalu membuat graph. Jalankan --dry-run terlebih dahulu dan baca daftar file yang akan diubah, karena beberapa file tersebut berada di luar repository. graft init bersifat idempotent dan tidak menimpa konfigurasi yang sudah ada, sehingga aman dijalankan untuk kedua kalinya.

Per Agustus 2026, integrasi ini mencakup Claude Code, Cursor, Codex, GitHub Copilot, Google Gemini, Kiro, Windsurf, dan AdaL. Claude Code mendapatkan integrasi paling lengkap: entri server MCP, statusline yang menampilkan ukuran dan tingkat kedaluwarsa graph, hook post-edit yang membangun ulang graph, serta file skill di bawah .claude/. Agent lain mendapatkan file instruksi atau rule yang memberi tahu agent bahwa tool tersebut tersedia. Jadi, "didukung" berarti Graft menulis konfigurasi integrasinya. Jika agent mengabaikan file rule miliknya, agent tersebut juga akan mengabaikan map. Itulah alasan umum agent mengabaikan instruksi yang Anda tulis untuknya, dan hal yang sama berlaku di sini.

Yang masuk ke repository Anda, dan yang tetap berada di luar git

Setelah graft init, Anda akan melihat hal berikut:

• graft/: graf node markdown dan graft/.graph/wiring.json. File ini ditambahkan ke .gitignore untuk Anda.
• .mcp.json: mendaftarkan server MCP graft agar Claude Code dapat menjalankannya.
• .claude/settings.json: digabungkan pada bagian yang sesuai, lalu menambahkan statusline dan hook post-edit.
• AGENTS.md, GEMINI.md, .github/copilot-instructions.md, .cursor/rules/graft.mdc, .kiro/steering/graft.md, .windsurf/rules/graft.md, dan .adal/skills/graft/SKILL.md: bagian yang dibatasi marker dan ditambahkan ke file yang sesuai dengan agent yang Anda pilih.
• ~/.codex/config.toml, ~/.codex/hooks.json, dan ~/.codex/hooks/graft/graft-hooks.cjs: berlaku untuk seluruh mesin dan hanya ditulis ketika Anda memilih Codex. graft init --no-global melewati file-file tersebut, sedangkan graft init --no-hooks sendiri melewati shim hook.

Graf tersebut adalah cache, seperti node_modules. Jangan commit file tersebut. Graf dibuat ulang dari kode dalam hitungan detik, berubah hampir pada setiap edit, dan jika di-commit, perbaikan satu baris dapat berubah menjadi diff yang terdiri atas beberapa ratus file yang tidak akan dibaca oleh reviewer. Commit konfigurasi penghubungnya, termasuk AGENTS.md dan .mcp.json. Rekan satu tim dapat melakukan clone repository, menjalankan graft build, lalu mendapatkan graf lokal mereka sendiri.

Pastikan aturan ignore sudah diterapkan sebelum commit pertama:

grep -n graft .gitignore
git status --short

grep seharusnya menampilkan baris yang berisi graft/, sedangkan git status --short seharusnya tidak menampilkan apa pun di bawah graft/. Jika file di bawah graft/ muncul dalam output tersebut, berarti entri ignore tidak ada atau ditimpa di tempat lain. Perbaiki sebelum commit, karena git akan tetap melacak file setelah file tersebut ditambahkan, dan edit .gitignore berikutnya tidak akan berhenti melacaknya.

Jika Anda ingin mendaftarkan server MCP secara manual, atau menetapkan versinya agar sama dengan versi yang Anda instal, entri yang diperlukan singkat:

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

Alat penelusuran yang dipanggil agent Anda sebagai pengganti grep

Graft menyediakan enam alat melalui MCP. graft_find_code mengembalikan node berperingkat untuk deskripsi tugas, beserta file dan barisnya. graft_file_api mengembalikan semua signature dalam sebuah file tanpa body. graft_trace_calls menelusuri caller atau callee hingga beberapa tingkat. graft_find_all mengembalikan hasil regex yang dikelompokkan berdasarkan simbol. graft_repo_map memberikan gambaran awal tentang repository yang belum dikenal. graft_check_freshness melaporkan apakah graph masih sesuai dengan kode.

Masing-masing memiliki padanan CLI. Gunakan padanan ini untuk memeriksa apa yang benar-benar diterima agent Anda:

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 seharusnya mencetak node berperingkat dengan referensi file:line, bukan isi file. Itulah keseluruhan mekanismenya: agent menerima pointer lalu membuka satu file, bukan membaca sepuluh file untuk menemukan file yang tepat. graft viz membuka viewer interaktif di localhost jika Anda ingin melihat graph sendiri. Jika graft ask tidak mengembalikan informasi yang berguna untuk pertanyaan yang dapat Anda jawab dalam tiga puluh detik, graph sudah usang atau bahasa yang Anda gunakan berada pada tier umum, dan peta tersebut juga tidak akan membantu agent Anda.

Ada satu biaya yang mudah terlewatkan. Enam definisi alat disisipkan ke system prompt pada setiap request selama seluruh sesi. Anda tetap membayar biaya tersebut, baik agent menggunakan peta maupun tidak. Pada repository yang cukup kecil untuk dimuat ke dalam context, biaya tetap ini dapat lebih besar daripada eksplorasi yang dihemat.

Apa yang terjadi pada graph ketika kode berubah

Pembaruan struktural berlangsung cepat dan otomatis. Graft membaca working tree, bukan git, sehingga perubahan yang belum Anda commit dan perubahan yang sudah Anda stage sama-sama terlihat olehnya. Query hanya mengurai ulang file yang nilai stat-nya berubah. Dokumentasi proyek menyebut overhead-nya sekitar 3 ms. Rebuild pada akhir turn hanya menyentuh file yang mengalami perpindahan kode. Atur GRAFT_NO_REFRESH=1 atau teruskan --no-refresh untuk memperoleh jawaban dari graph di disk tanpa mengurai ulang. Teruskan --no-reuse untuk memaksa penguraian ulang penuh, yang diperlukan setelah Anda meng-upgrade Graft.

Bagian yang ditulis model berperilaku berbeda. Bagian inilah yang dapat mengalami kesalahan secara diam-diam. Summary dan crux disimpan dalam cache. Setiap node mencatat content hash dari sumbernya. Jika file sumber berubah, node ditandai sebagai stale, bukan dianggap masih terkini. Penanda tersebut hanya berguna jika ada proses yang menindaklanjutinya. Lakukan refresh dengan graft build --deep. Proses ini akan menggunakan token model lagi.

Tampilkan status stale:

graft check .
echo $?

Exit status 0 berarti graph sesuai dengan kode. Exit status 1 berarti terdapat drift. Jalankan perintah ini dari pre-push hook atau pada branch di CI agar map yang berusia enam bulan tidak memberikan jawaban dengan yakin tentang kode yang ditulis ulang pada bulan Maret.

Baca dengan saksama angka benchmark yang dipublikasikan

Klaim utama Graft adalah "hingga 4x lebih murah dan 3x lebih cepat, dengan kualitas yang sama atau tanpa penurunan kualitas". Angka tersebut berasal dari benchmark Graft sendiri yang dipublikasikan dalam README-nya. Berikut dua pengujian yang dilaporkan secara lengkap.

[
  {
    "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
  }
]

Pengujian terkontrol mencakup 162 pengujian pada dua repositori, salah satunya Graft sendiri, dengan tiga percobaan untuk setiap tugas. Pengujian ini melaporkan pengurangan token sebesar 42% dan pengurangan pemanggilan tool sebesar 46%. Pengujian SWE-bench Verified mencakup 50 instance dengan model yang sama pada kedua kelompok, dan melaporkan penghematan yang lebih kecil: 23% token dan 25% pemanggilan tool. Pengujian ketiga mereproduksi lima pull request PocketBase yang telah digabungkan, dengan biaya 11.02 dolar AS dibandingkan 13.91 dolar AS untuk baseline.

Anggap semua angka tersebut sebagai benchmark vendor. Ada dua hal yang membatasi informasi yang dapat disimpulkan. Pengujian terkontrol mencakup repositori Graft sendiri, yaitu codebase yang menjadi dasar penyetelan oleh pengembangnya. SWE-bench Verified adalah dataset publik yang berisi issue dari proyek Python open source yang terkenal, dan dataset publik merupakan sasaran optimasi tool, disengaja ataupun tidak. Keduanya tidak mencerminkan monorepo privat Anda, yang memiliki kebiasaan penamaan dan dead code sendiri.

Baca kembali bagian correctness dengan saksama. Pada pengujian terkontrol, nilainya tidak berubah: 93% dengan map dibandingkan 93% tanpa map. Kenaikan menjadi 66% dari 54% hanya muncul pada SWE-bench Verified. Tool yang mengurangi tagihan token tanpa menurunkan kualitas tetap merupakan pilihan yang baik. Namun, jangan menerapkan hasil correctness dari SWE-bench ke hasil token pada pengujian terkontrol, lalu mengutip keduanya sebagai satu klaim.

Ukur selisih token Anda sendiri sebelum mempercayainya

Satu-satunya angka yang penting adalah angka dari repositori Anda. Metode ini memerlukan waktu satu sore.

Pilih tugas yang dapat Anda ulangi secara persis. Pertanyaan lebih baik daripada pengeditan karena pengeditan mengubah repositori, sehingga proses kedua bukan lagi eksperimen yang sama. Pertanyaan seperti "Modul mana yang menerapkan pembatasan laju pada rute login" memiliki bentuk yang tepat.

Aktifkan telemetri dan kirim hasilnya ke terminal Anda sendiri:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
claude

Eksportir konsol mencetak catatan metrik saat catatan tersebut dikumpulkan. Metrik yang Anda perlukan adalah claude_code.token.usage, yang memiliki atribut type dengan nilai input, output, cacheRead, atau cacheCreation. Informasi orientasi terdapat dalam input dan cacheRead karena isi file disimpan di sana. Jumlahkan keduanya.

Jalankan tugas tersebut tiga kali, masing-masing dalam sesi baru, dengan map yang sudah terhubung. Kemudian hapus entri graft dari .mcp.json dan jalankan tugas tersebut tiga kali lagi. Bandingkan median, bukan hasil tunggal, karena hasil eksekusi agent sangat bervariasi dan satu eksekusi yang tidak menguntungkan dapat memberikan kesimpulan yang berlawanan dari kenyataan. Catat juga jumlah pemanggilan tool: pemanggilan tool adalah mekanismenya, sedangkan token adalah dampaknya. Jadi, penghematan token tanpa pengurangan pemanggilan tool berarti ada hal lain yang berubah.

Kemudian kurangi biaya yang tidak ditampilkan benchmark. graft build --deep menggunakan token model pada setiap refresh penuh. Keenam skema tool disertakan dalam setiap request. Jika agent Anda berjalan pada server yang disewa, menetapkan batas pengeluaran agent mengubah situasi ini dari kejutan menjadi anggaran, sedangkan hal yang sebenarnya dilaporkan telemetri agent coding menjelaskan data yang keluar dari mesin setelah Anda mengaktifkan eksportir.

Kapan codebase map tidak lagi membantu?

• Repository sudah cukup kecil untuk dimuat ke dalam konteks. Satu service kecil tidak memerlukan map, dan Anda tetap membayar enam skema tool pada setiap request. Jika saat ini agent dapat menemukan file apa pun hanya dalam satu atau dua tool call, lewati map.
• Bahasa Anda berada pada tier umum. Edge pemanggilan generik berarti graft callers dapat melewatkan caller atau menghasilkan caller yang keliru akibat benturan nama. Konfirmasikan dengan graft grep sebelum mempercayai blast radius.
• Graph sudah kedaluwarsa dan tidak ada yang menyadarinya. graft check keluar dengan status 1 saat terjadi drift. Ini hanya berguna jika ada sesuatu yang menjalankannya. Gunakan hook atau langkah CI, bukan kebiasaan manual.
• Monorepo memerlukan scoping. Satu monorepo berbasis git secara otomatis dipecah berdasarkan file workspace, go.mod, pyproject.toml, atau Cargo.toml, dan graft ask "..." --in services/billing/ mempersempit query ke satu sub-proyek. Prinsip yang sama yang mendorong penggunaan file AGENTS.md bertingkat untuk setiap package juga berlaku pada map.
• Agent mengabaikan wiring. Amati tool call dalam sesi nyata sebelum menyimpulkan bahwa map digunakan. Jika agent masih menjalankan grep, berarti agent tidak pernah membaca file aturan.

FAQ

Haruskah saya memasukkan folder graft/ ke git?

Tidak. graft build secara otomatis menambahkan graft/ ke .gitignore, karena graf tersebut merupakan cache yang dapat dibuat ulang seperti node_modules. Isinya berubah hampir setiap kali dilakukan pengeditan, sehingga memasukkannya ke commit akan menutupi diff yang sebenarnya di antara ratusan file yang dibuat otomatis. Masukkan wiring yang memberi tahu agent bahwa peta tersebut tersedia, termasuk AGENTS.md dan .mcp.json, lalu biarkan setiap anggota tim menjalankan graft build secara lokal. Verifikasi dengan grep -n graft .gitignore dan git status --short sebelum commit pertama, karena git terus melacak file setelah file tersebut ditambahkan, dan mengedit .gitignore setelahnya tidak akan menghapus pelacakan tersebut.

Apakah menjalankan Graft memerlukan biaya?

Bagian struktural tidak memerlukan biaya. graft build, graft ask, graft check, dan enam alat pengambilan data MCP merupakan operasi tree-sitter yang tidak pernah memanggil model. graft build --deep adalah bagian berbayar: fitur ini menulis ringkasan dalam bahasa Inggris biasa dan inti per simbol melalui LLM, yang dikonfigurasi dengan GRAFT_PROVIDER, GRAFT_API_KEY, dan GRAFT_MODEL, serta GRAFT_BASE_URL untuk endpoint yang kompatibel dengan OpenAI. Anda dapat menjalankan Graft hanya dengan struktur dan tidak menghabiskan token untuk graf itu sendiri.

Seberapa besar peta codebase dapat menghemat penggunaan token pada repositori saya?

Tidak ada yang dapat menjawabnya tanpa pengukuran. Proyek tersebut melaporkan pengurangan token sebesar 42% pada pengujian 162 kali miliknya dan 23% pada SWE-bench Verified. Keduanya dibandingkan dengan baseline tanpa peta. Keduanya merupakan benchmark vendor; salah satunya sebagian dijalankan pada repositori milik Graft sendiri, dan tidak ada yang menggambarkan kode privat Anda. Jalankan satu pertanyaan yang dapat diulang sebanyak tiga kali dengan peta dan tiga kali tanpa peta, dengan CLAUDE_CODE_ENABLE_TELEMETRY=1 dan OTEL_METRICS_EXPORTER=console ditetapkan, lalu bandingkan median claude_code.token.usage untuk jenis input dan cacheRead.

Apa yang terjadi pada graf ketika saya melakukan refactoring?

Struktur akan diuraikan ulang secara otomatis. Graft memeriksa working tree dan hanya menguraikan ulang file yang berubah, sehingga perubahan nama akan terdeteksi pada kueri berikutnya dengan overhead sekitar 3 ms. Graft juga melihat pekerjaan yang belum di-commit karena membaca file, bukan riwayat git. Ringkasan yang ditulis model adalah bagian yang menjadi usang. Setiap node menyimpan hash konten dari sumbernya, dan perubahan pada sumber menandai node sebagai usang tanpa menulis ulang node tersebut. Jalankan graft check . untuk melihat perbedaannya, lalu graft build --deep untuk memperbarui bagian yang ditulis.

Agent coding apa saja yang saat ini dapat menggunakan Graft?

Per Agustus 2026, graft init menghubungkan Claude Code, Cursor, Codex, GitHub Copilot, Google Gemini, Kiro, Windsurf, dan AdaL. Claude Code mendapatkan integrasi paling lengkap: entri server MCP di .mcp.json, statusline, hook setelah pengeditan, dan file skill di bawah .claude/. Codex mendapatkan bagian AGENTS.md serta entri yang berlaku untuk seluruh mesin di bawah ~/.codex/, yang dilewati oleh graft init --no-global. Agent lainnya menerima file rules atau steering. Klien MCP lain dapat menggunakan server secara langsung dengan mendaftarkan perintah npx -y @nanonets/graft@0.10.1 mcp.