CodeGraph — прединдексированный граф знаний для AI-агентов

CodeGraph (версия 1.0) — инструмент от Colby McHenry, который строит прединдексированный knowledge graph кода и отдаёт его AI-агентам через MCP-протокол. 59.6k звёзд на GitHub. Результат: 58% меньше tool calls, 22% быстрее, file reads сокращаются почти до нуля. Всё полностью локально, без API-ключей и внешних сервисов.

Проблема, которую решает CodeGraph: AI-агент при исследовании незнакомой кодовой базы порождает grep, glob и Read — десятки вызовов, каждый сжигает токены. CodeGraph даёт готовый индекс — символы, call edges, зависимости — и агент получает контекст за один вызов вместо файл-за-файлом.

Как работает

tree-sitter парсит исходники в AST, языково-специфичные запросы извлекают узлы (функции, классы, методы, свойства) и рёбра (вызовы, импорты, наследование, переопределения методов). Всё складывается в SQLite с полнотекстовым поиском FTS5 (.codegraph/codegraph.db). Агентское взаимодействие — через единственный MCP-инструмент codegraph_explore, который за один вызов возвращает исходный код релевантных символов, карту отношений и радиус влияния.

Архитектура автосинхронизации трёхслойная: file watcher на нативных событиях ОС (FSEvents/inotify/ReadDirectoryChangesW) с debounce 2с, staleness-баннер при незавершённой синхронизации, и connect-time reconciliation через content-hash при подключении MCP-сервера.

Установка

Node.js не нужен — CodeGraph идёт с bundled runtime:

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

Подключение агентов:

codegraph install

Определяет Claude Code, Cursor, Codex CLI, OpenCode, Hermes Agent, Gemini CLI, Antigravity и Kiro автоматически. Инициализация проекта — одна команда:

cd your-project
codegraph init

После codegraph init автоматическая синхронизация включена по умолчанию — индекс обновляется при каждом изменении файлов.

Бенчмарки

Тестирование на 7 open-source проектах (Opus 4.8, медиана 4 запусков per arm):

Универсальный выигрыш на любом размере проекта — хирургический контекст и скорость. Экономия токенов и стоимости значима на крупных проектах и при массовом использовании командой.

Ключевые возможности

• Хирургический контекст — один вызов возвращает точки входа, связанные символы и код
• Полнотекстовый поиск — FTS5 по всей кодовой базе
• Impact-анализ — callers, callees, радиус влияния любого символа
• Автосинхронизация — индекс всегда актуален, нулевая конфигурация
• Framework-aware routes — 17 веб-фреймворков: Django, Flask, FastAPI, Express, NestJS, Laravel, Drupal, Rails, Spring, Play, Gin/chi/gorilla, Axum/actix/Rocket, ASP.NET, Vapor, React Router/SvelteKit, Vue Router/Nuxt, Astro
• iOS/React Native бриджинг — Swift ↔ ObjC, React Native legacy bridge + TurboModules + Fabric, Expo Modules
• 100% локально — SQLite, данные не покидают машину

Поддерживаемые языки

30+ языков: TypeScript, JavaScript, ArkTS, Python, Go, Rust, Java, C#, VB.NET, PHP, Ruby, C, C++, CUDA, Objective-C, Metal, Swift, Kotlin, Scala, Dart, Lua, Luau, R, Nix, Erlang, CFML, COBOL, Solidity, Terraform/OpenTofu, Svelte, Vue, Astro, Liquid, Pascal/Delphi.

CLI

codegraph init [path]             # Инициализация и индексация
codegraph sync [path]             # Инкрементальное обновление
codegraph status [path]           # Статистика индекса
codegraph query <search>          # Поиск символов
codegraph callers <symbol>        # Кто вызывает
codegraph callees <symbol>        # Что вызывается
codegraph impact <symbol>         # Анализ влияния
codegraph affected [files...]     # Затронутые тесты (для CI)
codegraph explore <query>         # Структурный запрос (CLI-эквивалент MCP)
codegraph node <symbol|file>      # Исходный код символа или файла
codegraph install / uninstall     # Подключение/отключение агентов
codegraph upgrade                 # Обновление

codegraph affected трассирует импорты транзитивно и находит тестовые файлы, затронутые изменениями — полезно для CI:

AFFECTED=$(git diff --name-only HEAD | codegraph affected --stdin --quiet)
if [ -n "$AFFECTED" ]; then npx vitest run $AFFECTED; fi

Программный API

import CodeGraph from '@colbymchenry/codegraph';

const cg = await CodeGraph.init('/path/to/project');
await cg.indexAll({ onProgress: (p) => console.log(`${p.phase}: ${p.current}/${p.total}`) });

const results = cg.searchNodes('UserService');
const callers = cg.getCallers(results[0].node.id);
const impact = cg.getImpactRadius(results[0].node.id, 2);

cg.watch();   // автосинхронизация
cg.close();

Требуется Node 22.5+ (для node:sqlite). CLI и MCP-сервер работают на bundled runtime.

Конфигурация

Zero-config. Пропускаются node_modules, vendor, dist, build, target, .venv, Pods, .next, всё из .gitignore и файлы > 1 МБ. Для нестандартных расширений — опциональный codegraph.json:

{
  "extensions": { ".dota_lua": "lua", ".tpl": "php" },
  "exclude": ["static/"],
  "include": ["Tools/"]
}

Ссылки

• GitHub: https://github.com/colbymchenry/codegraph
• Документация: https://colbymchenry.github.io/codegraph/
• npm: https://www.npmjs.com/package/@colbymchenry/codegraph