CodeGraph: AI Agent'ler İçin Kod Bilgi Grafiği — %94 Daha Az Tool Call

AI coding agent’ler kod tabanını keşfederken klasik yöntemlerle çalışır: dosya dosya okur, grep/search yapar, proje yapısını anlamaya çalışır. Bu süreçte tonlarca token harcanır ve değerli context penceresi boşa gider.

CodeGraph bu sorunu kökünden çözüyor: kodu AST seviyesinde parse edip bir SQLite knowledge graph’e kaydediyor. Agent MCP üzerinden bu grafiğe anlık sorgular yaparak, saniyeler sürecek keşif işlemlerini milisaniyelere indiriyor.

CodeGraph ile kod tabanını sembol seviyesinde anlık sorgula

Sorun: Agent’lar Kod Tabanında Kayboluyor

Bir AI coding agent’in yeni bir projeyi anlaması için yaptığı tipik adımlar:

1. Dosya yapısını keşfet (ls, glob)
2. İlgili dosyaları oku (read)
3. Fonksiyon/sınıf tanımlarını bul (grep pattern’leri)
4. Çağrı graflarını çıkar (birden çok dosyayı okuma)
5. Bağımlılıkları anla (import/export zinciri)

Her adımda tool call + token harcanır. Büyük projelerde bu süreç dakikalar alır ve context penceresinin büyük kısmını gereksiz dosya içerikleri doldurur.

Çözüm: CodeGraph

CodeGraph, @colbymchenry/codegraph, AI coding agent’ler için önceden indexlenmiş bir kod bilgi grafiği. Kurulumu tek satır:

npx @colbymchenry/codegraph
# → Interaktif kurulum: Claude Code, Cursor, Codex, OpenCode entegrasyonu

cd projen
codegraph init -i
# → Tüm kod tabanını AST'den parse edip SQLite'e indexler

Nasıl Çalışır?

Kod tabanı → AST Parser (19+ dil) → Symbol Graph → SQLite (.codegraph/)
                                                       ↓
                                              MCP Server (anlık sorgular)
                                                       ↓
                                         Claude Code / Cursor / Codex / OpenCode

19+ programlama dilini destekler: TypeScript, Python, Rust, Go, Java, C++, Swift, Ruby, PHP ve daha fazlası.

MCP Araçları: Agent’ın Yeni Süper Gücü

CodeGraph, MCP (Model Context Protocol) üzerinden 7 özel araç sunar:

CLI Komutları

Doğrudan terminalden de kullanılabilir:

# Sembol ara
codegraph query "authenticateUser"

# Task context'i oluştur (markdown çıktı)
codegraph context "login sayfasını next.js'e taşı"

# Dosya yapısını göster
codegraph files

# Etki analizi
codegraph affected src/services/auth.ts

# MCP server olarak başlat
codegraph serve

# Görselleştirme (tarayıcıda aç)
codegraph visualize

# Index durumu
codegraph status

Benchmark: Sayılar Konuşuyor

CodeGraph’ın resmi benchmark sonuçları:

Bu rakamlar şu anlama geliyor:

• Agent 10 tool call yapacağına 1 tool call yapıyor
• Dakikalarca süren keşif saniyeler sürüyor
• Context penceresi boş dosyalarla değil, gerçek kod bilgisiyle doluyor

Framework Desteği: 13+ Web Framework Tanıma

CodeGraph sadece sembolleri değil, framework routing yapılarını da anlar:

Bir Express rotasını değiştirirken hangi middleware’lerin, controller’ların ve view’ların etkilendiğini anlık görebilirsiniz.

Gerçek Kullanım Senaryoları

1. Paperclip Kod Tabanında Hızlı Keşif

Paperclip EBA framework’ü üzerinde çalışırken sık sık yeni özellik eklemem gerekiyor. CodeGraph ile:

codegraph context "lead enrichment pipeline'a yeni bir data source ekle"

Tek sorguda tüm ilgili dosyaları, fonksiyonları ve bağımlılıkları gösteriyor. Normalde dakikalar sürecek keşif saniyeler alıyor.

2. Hermes War Room’da Etki Analizi

Hermes Orchestration War Room’da bir değişiklik yaparken:

codegraph impact "KanbanBoard"

Hangi bileşenlerin, API route’larının ve veritabanı sorgularının etkilendiğini anlık gösteriyor. kanban_create skill’ini değiştirdiğinizde tüm profillerdeki yansımalarını görüyorsunuz.

3. Neo4j Projelerinde Bağımlılık Yönetimi

MomYachting veya Hermes Memory gibi projelerde bir fonksiyon değiştiğinde:

codegraph callers "text_to_cypher.convert"
codegraph search "CypherQueryBuilder"

Fonksiyonu kimlerin çağırdığını, hangi testlerin etkilendiğini, hangi route’ların bu fonksiyonu kullandığını tek seferde görüyorsunuz.

Neden Diğer Çözümlerden Farklı?

Öne Çıkan Teknik Detaylar

AST-Level Parsing

CodeGraph kodu string olarak değil, AST (Abstract Syntax Tree) seviyesinde parse eder. Bu sayede:

// CodeGraph bunu bir "function declaration" olarak değil,
// bir "async arrow function with two params, exported" olarak anlar
export const authenticateUser = async (email: string, password: string) => {
  const user = await db.users.findByEmail(email);
  return user && compare(password, user.hash);
};

FTS5 Full-Text Search

SQLite’in FTS5 (Full-Text Search) motoru sayesinde sembol aramaları anlık:

codegraph_search "auth" → authenticateUser, isAuthenticated, authMiddleware, AuthGuard, authRoutes...

Native OS File Watcher

Debounced file watching ile dosya değişiklikleri otomatik index’lenir. Elle codegraph sync çağırmanız gerekmez.

100% Local, Sıfır Dış Bağımlılık

API key, cloud servisi veya üçüncü parti bağımlılık yok. Her şey .codegraph/ dizininde SQLite olarak saklanır.

Kurulum Rehberi

# 1. CodeGraph'ı yükle
npx @colbymchenry/codegraph
# → Interaktif kurulum başlar
# → Claude Code, Cursor, Codex, OpenCode entegrasyonları
# → MCP server ayarları otomatik yapılandırılır

# 2. Projeni index'le
cd /path/to/project
codegraph init -i

# 3. Test et
codegraph status
codegraph files
codegraph query "yourFunction"

# 4. (Opsiyonel) MCP server'ı başlat
codegraph serve

Not: Projede codegraph init çalıştırdıktan sonra .codegraph/ dizini oluşur. .gitignore’a eklemeyi unutmayın.

Sonuç

CodeGraph, AI coding agent’lerin kod tabanını anlama şeklini kökünden değiştiriyor. Artık agent’ların dosya dosya okumasına, grep yapmasına, proje yapısını çözmeye çalışmasına gerek yok.

Özetle:

• %94 daha az tool call ile agent daha hızlı
• %77 daha hızlı keşif ile bekleme süresi neredeyse sıfır
• 100% local ile veri güvenliği garantisi
• 19+ dil, 13+ framework ile neredeyse her projede çalışır
• MCP native ile Claude Code, Cursor, Codex, OpenCode ile sorunsuz entegrasyon

Kendi projelerimde — Paperclip kod tabanında hızlı keşif, Hermes War Room’da etki analizi ve Neo4j pipeline’larında bağımlılık takibi için kullanıyorum. Şimdiden vazgeçilmez araçlar listesine girdi.

Kaynaklar

• CodeGraph GitHub
• CodeGraph NPM
• Model Context Protocol (MCP)
• SQLite FTS5
• Claude Code
• Hermes Agent

Bu yazıdaki hero görseli fal.ai + FLUX.1 Dev ile üretilmiştir.