Pernahkah kamu merasa Claude Code, Cursor, atau Codex terasa lambat saat bekerja di codebase besar? Itu bukan kebetulan. Setiap kali sesi dimulai, coding agent memulai dari nol: ia melakukan grep, membuka file, mengikuti import, mundur, lalu mencoba lagi. Ia membangun ulang peta codebase yang sebenarnya sudah ia petakan satu jam lalu, dan membuangnya begitu sesi selesai. Proses eksplorasi ulang inilah yang memakan sebagian besar tool call, token, dan waktu.

Graft adalah context layer open-source (lisensi MIT) yang menyelesaikan masalah tersebut. Ia membangun pemahaman codebase satu kali, menulisnya sebagai graph berisi file markdown di dalam repo, lalu menyuntikkannya ke coding agent secara otomatis. Hasilnya: agent tidak perlu lagi menjelajah dari nol setiap sesi. Di tutorial ini kita akan memasang Graft, membangun graph, menyambungkannya ke agent favoritmu, dan memakai CLI-nya untuk menavigasi codebase besar dengan cepat.

Apa Itu Graft dan Mengapa Coding Agent Butuh Memori Jangka Panjang?

Manusia cukup sekali onboarding ke sebuah codebase; setelah itu ia mengingat struktur, komponen, dan ketergantungannya. Coding agent justru melakukan onboarding setiap kali. Setiap tugas membayar biaya eksplorasi dari nol, dan apa pun yang ia pahami mati bersama sesi tersebut. Pengetahuan itu juga tidak dibagikan ke rekan tim — agent milik rekanmu mulai dari nol lagi.

Graft bekerja dengan membangun pemahaman itu sekali, lalu menulisnya sebagai folder graft/ berisi node markdown — satu node per subsistem, API, atau konsep. Setiap node menyimpan ringkasan bahasa alami, cuplikan baris kode terpenting (crux), file sumber yang dilacak dengan hash konten, dan link berarah antar-node. Ketika agent memulai tugas, Graft menarik node yang relevan ke dalam prompt, sehingga agent tahu apa yang perlu diketahui sebelum membuka satu file pun.

Angka resmi dari benchmark Graft: dibanding Claude Code “dingin” (tanpa Graft), pemakaian Graft memangkas tool call hingga 46%, token 42%, dan waktu 60% — dengan hasil 4x lebih murah dan 3x lebih cepat. Pada SWE-bench Verified, Graft menyelesaikan 33 dari 50 instance versus 27/50 tanpa Graft (naik 12 poin persentase).

Prasyarat

Sebelum mulai, pastikan hal-hal berikut tersedia di mesinmu:

  • Node.js versi aktif (Graft adalah paket npm).
  • Sebuah project Git — repositori pribadi atau open source, ukuran berapa pun.
  • Salah satu coding agent: Claude Code, Cursor, Codex, Gemini CLI, atau sejenisnya (opsional; CLI Graft tetap berguna tanpa agent).
  • Kunci API model (opsional) — hanya dibutuhkan untuk fitur ringkasan LLM di langkah 5.
bash
node --version
npm --version
git --version

Jika Node.js belum terpasang, unduh installer resminya dari nodejs.org atau gunakan manajer versi seperti nvm sebelum melanjutkan.

Langkah 1: Install Graft

Instalasi Graft hanya satu perintah. Kamu bisa memasangnya secara global, atau memanggilnya lewat npx tanpa instalasi permanen.

bash
# Install global (sekali saja)
npm install -g @nanonets/graft

# Atau, tanpa install global:
npx @nanonets/graft init

Setelah terpasang, verifikasi versinya:

bash
graft version

Perintah ini menampilkan versi terpasang dan versi terbaru yang dipublikasikan di npm. Graft otomatis memberitahumu jika ada versi baru (dicek sekali sehari), dan kamu bisa upgrade kapan saja dengan graft upgrade.

Langkah 2: Bangun Graph Codebase

Masuk ke direktori project-mu, lalu jalankan graft build. Perintah ini memindai seluruh file kode dan membangun graph struktural: setiap fungsi, kelas, dan edge pemanggilan diekstrak dengan tree-sitter — deterministik, tanpa model, tanpa kunci API, dan sepenuhnya offline.

bash
cd /path/ke/project-mu
graft build

Graft menghasilkan folder graft/ berisi dua hal: graph wiring per-simbol (graft/.graph/wiring.json) dan kartu per-file yang mencerminkan struktur direktori source-mu. Graft juga otomatis menambahkan graft/ ke .gitignore, karena graph adalah cache lokal yang bisa dibuat ulang — seperti node_modules, tidak perlu di-commit.

Semua pass di-cache berdasarkan hash konten. Build kedua hanya menyentuh file yang berubah — pada repo dengan 124 file, build kedua memakan 0,18 detik. Gunakan graft build --no-reuse untuk memaksa parse ulang dari nol.

Langkah 3: Sambungkan Graft ke Coding Agent-mu

Satu perintah menghubungkan Graft ke coding agent yang terdeteksi di mesinmu:

bash
graft init

Pada terminal interaktif, init menampilkan semua agent yang dikenalnya, menandai yang terdeteksi lewat direktori konfigurasinya, dan hanya menghubungkan agent yang kamu pilih (Claude Code sudah dipilih secara default). Tidak ada file yang ditulis sampai kamu memilih.

Setiap agent mendapat bagian Graft di file instruksinya masing-masing: AGENTS.md untuk Codex dan CLI lain yang membacanya, GEMINI.md, .github/copilot-instructions.md, atau file aturan yang dimiliki penuh seperti .claude/skills/graft/SKILL.md dan .cursor/rules/graft.mdc. Claude Code mendapat integrasi lebih dalam: statusline langsung, auto-sync graph, dan peringatan blast radius saat kamu mengedit file.

bash
# Lihat dulu file apa saja yang akan disentuh (tidak menulis apa pun):
graft init --dry-run

# Hubungkan hanya agent tertentu, tanpa prompt:
graft init --agents claude cursor

# Hubungkan semua agent yang terdeteksi, tanpa prompt:
graft init --yes

graft init bersifat idempoten: menjalankannya lagi hanya memperbarui bagian milik Graft dan tidak pernah menimpa konten milikmu (seperti CLAUDE.md). Namun, memilih host “agents” juga menyentuh konfigurasi level pengguna di ~/.codex/ — gunakan --no-global jika kamu tidak ingin perubahan di luar repo.

Langkah 4: Menjelajah Codebase dengan CLI Graft

Di luar integrasi agent, Graft menyediakan serangkaian perintah CLI yang kuat untuk menavigasi codebase tanpa model dan tanpa kunci API. Berikut yang paling sering dipakai.

4.1 graft ask — Tanya Langsung ke Graph

Perintah ini mengembalikan node yang relevan beserta lokasi file:baris yang tepat, lengkap dengan sumbernya — biasanya sudah menjadi jawaban penuh tanpa perlu membuka file lagi.

bash
graft ask "di mana logika validasi record ditulis dan fungsi apa saja yang memakainya?"
4.2 graft grep — Cari Semua Kemunculan Pola

Pencarian regex yang menyeluruh di seluruh file terindeks, dikelompokkan berdasarkan simbol yang membungkusnya dan diurutkan berdasarkan tingkat keterhubungan.

bash
graft grep "ValidateRecord"

# Case-insensitive, perlakukan pola sebagai string literal:
graft grep "validate_record" -i --fixed

# Sempitkan ke prefix path tertentu:
graft grep "ValidateRecord" --in src/apis/
4.3 graft map — Peta Repo dalam Sekejap

Memberi gambaran pertama sebuah repo yang belum dikenal: klaster direktori, hub lokal, dan hotspot global — diurutkan berdasarkan in-degree, tanpa LLM dan tanpa kunci.

bash
graft map
# Output contoh:
#   repo map — 113 files · 687 symbols · 2186 edges · typescript
#   src/    63 files · 527 symbols   hubs: contextDirFor (node-file.ts, 21), wiringPath (write.ts, 14)
4.4 graft skeleton & callers — API Surface dan Blast Radius

graft skeleton menampilkan seluruh signature dalam satu file tanpa isi fungsinya — permukaan API dengan sekitar sepersepuluh token. graft callers menunjukkan siapa yang memanggil sebuah simbol (dan sebaliknya), berguna untuk menaksir dampak perubahan.

bash
graft skeleton src/apis/file.go

graft callers ValidateRecord          # siapa yang memanggil/referensi simbol ini
graft callers ValidateRecord --direction out   # apa yang dipanggil simbol ini
graft callers ValidateRecord -d 2     # telusuri transitif 2 level (blast radius penuh)
Langkah 5: Aktifkan Ringkasan LLM dengan graft build --deep (Opsional)

Secara default, graph struktural dibangun tanpa model. Untuk menambahkan lapisan pemahaman bahasa alami — ringkasan per-file dan node konsep — jalankan build dengan flag --deep sambil mengonfigurasi penyedia model. Graft bersifat netral vendor: atur GRAFT_PROVIDER ke openai (untuk endpoint yang kompatibel dengan OpenAI, termasuk OpenRouter, Groq, atau server lokal) atau anthropic untuk API native.

bash
export GRAFT_PROVIDER=openai
export GRAFT_API_KEY=sk-...
export GRAFT_MODEL=gpt-4o-mini
# Opsional: arahkan ke endpoint lain (OpenRouter, LiteLLM, server lokal):
export GRAFT_BASE_URL=https://api.openrouter.ai/v1

graft build --deep

Bagian --deep memanggil LLM, jadi ia butuh kunci API dan menimbulkan biaya. Bagian ini sepenuhnya opsional — graph struktural dan semua perintah CLI tetap berfungsi tanpa kunci. Ringkasan di-cache per hash konten, sehingga biaya hanya muncul saat file berubah.

Langkah 6: Visualisasi dengan graft viz

Graft menyertakan viewer interaktif bawaan untuk melihat kedua graph — tanpa instalasi tambahan atau dev server. Viewer dikirim ter-bundle di dalam paket.

bash
graft viz
# Buka browser secara manual dengan port tertentu:
graft viz --port 5000 --no-open

# Ekspor satu file index.html mandiri (untuk CI atau GitHub Pages):
graft viz --export site/ --title "PR #12"

Viewer menyediakan tiga tab: Context (graph arsitektur dari graft/*.md), Code (graph per-simbol dari wiring.json), dan Outline (hierarki file → kelas → method). Saat kamu memilih node, edge-nya menyala dengan arah: amber untuk yang bergantung padanya, teal untuk yang bergantung ke node itu.

Langkah 7: Integrasi MCP Server (Opsional)

Untuk agent yang mendukung MCP, kamu bisa mendaftarkan server MCP Graft agar enam tool (find_code, file_api, trace_calls, find_all, repo_map, check_freshness) muncul secara native. Claude Code otomatis mendapatkan ini lewat graft init (ditulis ke .mcp.json proyek). Untuk mendaftarkannya manual:

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

Graft mengirim statistik penggunaan anonim (bukan kode, path file, atau query kamu). Jika ingin mematikannya, jalankan graft telemetry disable atau set variabel DO_NOT_TRACK=1. Telemetri otomatis nonaktif di lingkungan CI.

Kesimpulan

Graft menambal lubang terbesar dalam workflow coding agent modern: hilangnya konteks antar-sesi. Dengan membangun graph codebase sekali dan menyuntikkannya ke setiap sesi, agent-mu berhenti membuang token untuk eksplorasi ulang dan mulai fokus pada pekerjaan yang sebenarnya. Yang paling menarik, inti Graft bersifat deterministik dan tanpa biaya — graph struktural, perintah ask, grep, map, skeleton, dan callers semuanya berjalan lokal tanpa kunci API.

Mulailah dengan dua perintah: npm install -g @nanonets/graft lalu graft init di repo-mu. Dari sana, bereksperimenlah dengan graft ask dan graft map untuk merasakan perbedaannya, lalu tambahkan lapisan --deep saat kamu ingin ringkasan bahasa alami. Selamat mencoba — dan semoga agent-mu tidak pernah “tersesat” di codebase lagi.