CodeGraph: semantyczny graf repozytorium dla agentów AI

Każdy kto pracował z agentem AI na dużym repozytorium wie, jak to wygląda: agent dostaje zadanie, po czym metodycznie otwiera dziesiątki plików zanim trafi na właściwy kontekst. Tokeny lecą, rachunek rośnie, a większość tego skanowania jest bezproduktywna. CodeGraph rozwiązuje dokładnie ten problem.

Co to jest i jak działa

CodeGraph to lokalne narzędzie, które indeksuje repozytorium i buduje z niego semantyczny graf symboli — baza SQLite z mapą zależności między funkcjami, klasami, modułami i routingiem. Graf powstaje raz, potem jest na bieżąco aktualizowany przez FSEvents/inotify przy każdej zmianie pliku.

Narzędzie dostarcza ten graf agentom przez protokół MCP jako 8 dedykowanych narzędzi: codegraph_search, codegraph_context, codegraph_trace, codegraph_callers, codegraph_callees, codegraph_impact, codegraph_node, codegraph_explore. Zamiast czytać pliki na ślepo, agent pyta graf: „co wywołuje tę funkcję?”, „co zmieni się, jeśli zmodyfikuję ten moduł?”, „gdzie jest punkt wejścia tego routingu?”.

Obsługuje 20+ języków (TypeScript, Python, Go, Rust, Java, Swift, Kotlin, C#, PHP, Ruby, i inne), rozumie routing popularnych frameworków (Django, Flask, Express, NestJS, Laravel, Rails, Spring) i mosty React Native (Swift↔ObjC, TurboModules).

Liczby

Twórcy podają wyniki z benchmarków na 7 prawdziwych projektach:

Metryka	Średnia poprawa
Koszt API	−25%
Zużycie tokenów	−57%
Wywołania narzędzi	−62%
Czas odpowiedzi	−23%

Na bardzo dużych repozytoriach (przykład VS Code, ~10 tys. plików) oszczędności rosną: 33% niższy koszt i 80% mniej wywołań narzędzi. Projekt zebrał 35 tys. gwiazdek na GitHubie — to jeden z szybciej rosnących projektów w tym segmencie w 2025 roku.

Instalacja i konfiguracja

Jedno polecenie — szczegóły w repozytorium projektu:

npx @colbymchenry/codegraph

Instalator auto-wykrywa zainstalowane edytory (Claude Code, Cursor, Codex, opencode, Gemini, Antigravity, Kiro) i sam tworzy konfigurację serwera MCP. Do projektu trafia tylko .codegraph/codegraph.db — żaden plik instrukcji nie jest dodawany do repo, baza powinna trafić do .gitignore. Wszystko działa lokalnie, bez żadnego zewnętrznego API.

Kiedy to ma sens

Przy małych projektach z kilkudziesięcioma plikami różnica będzie mała — agent i tak szybko znajdzie kontekst. Wartość rośnie proporcjonalnie do rozmiaru codebase’u.

Z mojej perspektywy szczególnie użyteczne przy:

• Dużych monorepo — gdzie agenci regularnie „gubią się” między pakietami
• Refactoringu — codegraph_impact pokazuje zakres zmian zanim zaczniesz
• Onboardingu do nieznanego repo — semantyczny graf to szybsza mapa niż czytanie każdego pliku z osobna
• Optymalizacji kosztów — jeśli używasz Claude Code intensywnie na produkcyjnym kliencie, różnica w rachunku za API jest wymierna

Przy projektach opartych na Astro czy małych serwisach analitycznych efekt będzie skromniejszy. Ale narzędzie jest na tyle lekkie w instalacji (jedno polecenie, lokalne, zero zewnętrznych zależności), że próg wejścia jest niski.

Podsumowanie

CodeGraph rozwiązuje realne ograniczenie dzisiejszych agentów: brak strukturalnej wiedzy o repo na starcie. Pre-indeksowany graf daje agentowi mapę zamiast zmuszania go do samodzielnego eksplorowania terytorium. Mniej tokenów, niższy koszt, szybszy wynik — i to bez żadnych zmian w samym kodzie projektu.

Warto dodać do workflow, szczególnie jeśli pracujesz regularnie z dużymi kodebazami i zależy Ci na optymalizacji kosztów API.