Ещё один инструмент индексации кодовой базы под AI-агентов — но с интересной реализацией на tree-sitter и SQLite. Чем отличается от SocratiCode и где реальные границы

Если вы работаете с Claude Code на больших проектах, то знаете типичную картину. Задаёшь вопрос «как у нас устроена авторизация» — и агент начинает спавнить Explore-агентов, которые рекурсивно бегают по файлам через grep, glob и Read, читают десятки файлов, заполняют контекстное окно и жгут токены. На монорепе с тысячами файлов один такой запрос может занять полторы-две минуты и сотню вызовов инструментов.

Я уже разбирал на Хабре похожий инструмент — SocratiCode, который решает эту задачу через векторный поиск на Qdrant. Недавно мне попался ещё один проект из той же ниши — CodeGraph от colbymchenry. Подход другой: вместо векторных эмбеддингов он строит граф символов (функции, классы, их связи) через tree-sitter и хранит его в SQLite. Решил разобраться, как это устроено, проверить заявленные бенчмарки и понять, чем оно отличается от альтернатив.

Сразу оговорка про телеграм-маркетинг. Пост, через который я узнал про инструмент, содержит пару неточностей, которые я поправлю по ходу. Например, «для ИИ-агента Hermes построила контекст из 3479 файлов» — никакого «агента Hermes» в проекте нет, это выдумка. Цифры 92%/71% — реальные, из README. Разберём предметно.

Что это и какую проблему решает

CodeGraph — это MCP-сервер (Model Context Protocol) для Claude Code. Он индексирует вашу кодовую базу в граф знаний и предоставляет агенту набор инструментов для запросов к этому графу: найти символ, найти кто вызывает функцию, построить контекст под задачу, проанализировать impact от изменения.

Ключевая идея — дать Explore-агентам Claude Code предварительно проиндексированный граф вместо того, чтобы они сканировали файлы вживую. Агент запрашивает граф мгновенно, вместо того чтобы рекурсивно читать дерево файлов.

Технические характеристики из репозитория:

• Node.js 18+, ставится через npx @colbymchenry/codegraph

• MIT-лицензия, 552 звезды на GitHub на момент обзора

• 100% локально — никаких API-ключей, никакого облака, только SQLite-база

• Поддержка 19+ языков: TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Swift, Kotlin, Dart, Svelte, Liquid, Pascal/Delphi

• File watcher с автосинхронизацией через нативные OS-события Это та же категория, что SocratiCode, Aider repo-map, Continue codebase indexing. Но реализация заметно отличается, и об этом стоит поговорить подробнее.

Архитектура: tree-sitter → SQLite граф

В отличие от SocratiCode, который строит векторный индекс через эмбеддинги Ollama, CodeGraph идёт по пути статического анализа AST. Никаких нейросетевых эмбеддингов в самом индексе нет — это чистый структурный граф.

Процесс делится на четыре стадии.

Стадия 1: Extraction. tree-sitter парсит исходный код в AST. Дальше языко-специфичные запросы извлекают узлы (функции, классы, методы) и связи (вызовы, импорты, наследование). tree-sitter — это та же библиотека, что использует GitHub для подсветки синтаксиса и навигации по коду, проверенный инструмент.

Стадия 2: Storage. Всё складывается в локальную SQLite-базу .codegraph/codegraph.db с полнотекстовым поиском через FTS5. Выбор SQLite тут разумный — это zero-config встроенная БД, которая не требует поднимать отдельный сервис (в отличие от Qdrant у SocratiCode, который тянет Docker).

Стадия 3: Resolution. После извлечения резолвятся ссылки: вызовы функций сопоставляются с определениями, импорты — с исходными файлами, наследование классов, фреймворк-специфичные паттерны. Это превращает разрозненные узлы в связный граф.

Стадия 4: Auto-Sync. MCP-сервер следит за проектом через нативные OS-события (FSEvents на macOS, inotify на Linux, ReadDirectoryChangesW на Windows). Изменения дебаунсятся (окно 2 секунды), фильтруются только до исходных файлов и инкрементально досинхронизируются. Граф остаётся свежим по мере написания кода без ручного переиндексирования.

Принципиальное отличие от векторного подхода: граф детерминированный. Если функция login() вызывает validateToken() — это факт из AST, а не «семантическая близость с вероятностью 0.87». Для задач трассировки вызовов это надёжнее векторного поиска. Для задач «найди что-то концептуально похожее» — наоборот, граф проигрывает векторам.

Установка

Тут всё просто, что приятно. Интерактивный установщик одной командой:

npx @colbymchenry/codegraph

Установщик сам делает несколько вещей: ставит codegraph глобально (нужно для MCP-сервера), прописывает MCP-сервер в ~/.claude.json, настраивает auto-allow права для инструментов CodeGraph, добавляет глобальные инструкции в ~/.claude/CLAUDE.md.

Дальше в проекте инициализируем граф:

cd your-project
codegraph init -i

После этого Claude Code автоматически использует CodeGraph, когда видит директорию .codegraph/ в проекте.

Если не любите автоматику, можно настроить руками. Установщик прописывает в ~/.claude.json примерно такой блок:

{
  "mcpServers": {
    "codegraph": {
      "type": "stdio",
      "command": "codegraph",
      "args": ["serve", "--mcp"]
    }
  }
}

Обратите внимание — тип stdio, а не url. CodeGraph работает как локальный процесс, общающийся с Claude Code через stdin/stdout, а не как сетевой сервис. Это логично для инструмента, который позиционируется как «100% локально».

Инструменты, которые получает агент

После запуска CodeGraph экспонирует Claude Code набор MCP-инструментов. Вот они с назначением:

• codegraph_search — найти символы по имени across всей кодовой базы

• codegraph_context — построить релевантный контекст под задачу

• codegraph_callers — найти, что вызывает функцию

• codegraph_callees — найти, что вызывает сама функция

• codegraph_impact — проанализировать, что затронет изменение символа

• codegraph_node — детали по конкретному символу (опционально с исходным кодом)

• codegraph_files — структура проиндексированных файлов

• codegraph_status — здоровье индекса и статистика Интересный архитектурный момент: установщик прописывает в CLAUDE.md инструкции, которые запрещают главной сессии вызывать тяжёлые инструменты напрямую. Цитирую суть из README:

NEVER call codegraph_explore or codegraph_context directly in the main session.

Логика в том, что эти инструменты возвращают большие куски исходного кода, которые забивают контекст главной сессии. Вместо этого CodeGraph настаивает, чтобы для исследовательских вопросов всегда спавнился отдельный Explore-агент. А главная сессия может пользоваться только лёгкими инструментами (codegraph_search, codegraph_callers, codegraph_impact, codegraph_node) для точечных запросов перед редактированием.

Это грамотное проектирование. Авторы понимают проблему «context bloat» и архитектурно её обходят: тяжёлый код едет в субагента, чей контекст потом схлопывается, а главная сессия остаётся чистой.

Бенчмарки: что заявлено и как это читать

Авторы протестировали на 6 реальных кодовых базах, сравнивая Explore-агент Claude Code с CodeGraph и без. Все тесты на Claude Opus 4.6 (контекст 1M), Claude Code v2.1.91. Каждый тест — один Explore-агент с одним и тем же вопросом.

Усреднённый результат: 92% меньше вызовов инструментов, на 71% быстрее. На главной странице README указано даже 94%/77% — видимо, по другому набору, в детальной таблице среднее 92%/71%.

Самые показательные кейсы:

• VS Code (TypeScript, 4002 файла): 3 вызова за 17 секунд против 52 вызовов за 1м37с. То есть 94% меньше вызовов, 82% быстрее.

• Swift Compiler (Swift/C++, 25 874 файла, 272 898 узлов): самая большая база. CodeGraph проиндексировал её менее чем за 4 минуты, и агент ответил на сложный кросс-каттинг вопрос за 6 вызовов и ноль чтений файлов за 35 секунд. Как эти цифры читать критически.

Во-первых, это бенчмарк автора, не независимая проверка. Чтобы убедиться, что вопросы репрезентативны, нужно воспроизвести самому. Я бенчмарк целиком не гонял, но по описанию методология честная — указаны точные вопросы, версии, кодовые базы. Это лучше, чем «нам показалось, что стало быстрее».

Во-вторых, «92% меньше вызовов» — это про tool calls агента, не про «вызовы кода», как переврал телеграм-пост. Это число обращений Explore-агента к инструментам (grep, read, glob против codegraph-запросов).

В-третьих — и это главное — выигрыш проявляется на больших кодовых базах и архитектурных вопросах. Вопросы в бенчмарке вида «как extension host общается с main process» или «как работает collaborative editing». Это вопросы про структуру, где надо обойти много файлов. На точечной задаче «покажи определение функции parseConfig» grep отработает так же быстро, и выигрыша от графа не будет.

Это, кстати, ровно тот же вывод, к которому я пришёл, разбирая SocratiCode. Инструменты индексации кода выигрывают на «понимании структуры», а не на точечном поиске.

Откуда взялась цифра «3479 файлов за 3 минуты» и про «агента Hermes»

Отдельно разберу телеграм-формулировку «для ИИ-агента Hermes тулза построила контекст из 3479 файлов за три минуты», потому что это смесь правды и выдумки.

Никакого «агента Hermes» в проекте CodeGraph нет. Я прочитал весь README, CLI reference, список MCP-инструментов — слова Hermes там не встречается. Откуда автор поста его взял — загадка, возможно перепутал с другим инструментом.

Цифра «3479 файлов за 3 минуты» близка к реальным данным, но неточна. В бенчмарке самые большие индексации: VS Code — 4002 файла, Swift Compiler — 25 874 файла за «менее 4 минут». Похоже, автор поста взял ballpark «несколько тысяч файлов за несколько минут» и округлил до конкретных, но неверных чисел.

Это типичная история с телеграм-пересказами: основной факт (быстрая индексация больших проектов) — правда, конкретные детали — выдуманы. Поэтому я всегда проверяю первоисточник, прежде чем писать.

Чем отличается от SocratiCode и других

Раз уж я разбирал SocratiCode, проведу прямое сравнение — это самый близкий конкурент.

SocratiCode строит векторный индекс через Qdrant + Ollama, делает гибридный поиск (семантика + BM25 через RRF). Сильная сторона — концептуальный поиск: «найди код про авторизацию», даже если слова auth там нет. Слабая — требует Docker для Qdrant и Ollama, тяжелее по ресурсам.

CodeGraph строит структурный граф через tree-sitter + SQLite. Сильная сторона — детерминированная трассировка вызовов (кто кого вызывает, что на что влияет) и легковесность (только SQLite, без Docker). Слабая — не умеет в семантическую близость, ищет по именам и связям, а не по смыслу.

Грубо говоря: если вам нужно «проследить, как запрос проходит от Session.request() до URLSession» — это к CodeGraph, граф пройдёт цепочку вызовов. Если нужно «найди все места, где мы делаем что-то похожее на rate limiting, как бы оно ни называлось» — это к SocratiCode, вектора поймают синонимы.

Другие альтернативы:

• Aider repo-map — встроенная карта репозитория, но без полноценного графа связей и без MCP

• Continue — локальная индексация через свой формат, привязана к Continue-расширению

• Cody от Sourcegraph — мощный, но в основном через свой клиент, не универсальный MCP CodeGraph выигрывает в нише «легковесный детерминированный граф через стандартный MCP». Поставил npx-командой, работает в любом MCP-совместимом хосте, не тянет Docker.

Где это реально полезно

После изучения проекта и бенчмарков сформулирую, когда инструмент оправдан.

Стоит ставить, если:

• У вас большая кодовая база (от нескольких сотен файлов), и вы регулярно работаете с ней через Claude Code

• Часто решаете архитектурные задачи — рефакторинг, трассировка вызовов, impact-анализ перед изменением

• Хотите легковесное решение без Docker и внешних сервисов

• Важна приватность — всё локально, код никуда не уходит Особенно ценный сценарий — impact-анализ перед рефакторингом. Инструмент codegraph_impact показывает, что затронет изменение символа, до того как вы его меняете. Это то, на что вручную через grep уходит куча времени, а тут один запрос к графу.

Не стоит заморачиваться, если:

• Проект маленький (десятки файлов) — grep отработает мгновенно, граф не нужен

• Вам нужен в основном семантический поиск по смыслу — тогда SocratiCode или векторное решение лучше

• Вы не используете Claude Code или другой MCP-совместимый хост — инструмент заточен под MCP

Ограничения, о которых стоит знать

Чтобы не выглядело рекламно, отмечу слабые места.

Только структурный поиск. Граф знает про вызовы и импорты, но не понимает семантику. «Найди код, концептуально похожий на X» — не его задача.

Качество зависит от языка. tree-sitter-парсеры разного качества для разных языков. Для TypeScript, Python, Go — зрелые. Для Pascal/Delphi, Liquid, Svelte (которые в списке 19+) — наверняка менее точные. На экзотических языках граф может быть неполным.

Resolution не идеальна. Сопоставление вызовов с определениями для динамических языков (Python, Ruby, JS) — принципиально сложная задача. Динамическая диспетчеризация, monkey-patching, рефлексия — всё это статический анализ ловит плохо. Граф будет иметь пропуски.

Свежесть индекса с задержкой. File watcher дебаунсит на 2 секунды. Если только что добавил функцию и сразу спрашиваешь про неё — может не успеть попасть в граф. Мелочь, но бывает.

Молодой проект. 552 звезды, 237 коммитов, 10 открытых issue. Это не зрелый продукт уровня Sourcegraph, а активно развивающийся pet-проект одного автора. Для критичных рабочих процессов стоит это учитывать.

Бенчмарки не независимые. Повторю — цифры 92%/71% от автора. Они выглядят честно по методологии, но это не сторонняя проверка.

Что я вынес для себя

Несколько уроков, которые выходят за рамки самого инструмента.

Граф vs вектора — это выбор под задачу, не «что лучше». Структурный граф детерминирован и точен для трассировки. Вектора гибки и ловят смысл. Идеальный инструмент будущего, наверное, совместит оба подхода — граф для структуры, вектора для семантики.

Прогрессивная подача контекста — снова ключ. Как и в SocratiCode, и в DeerFlow, и в book-to-skill — паттерн «не вали всё в контекст, дай инструмент запросить нужное» повторяется. CodeGraph идёт дальше и архитектурно запрещает главной сессии тянуть тяжёлый код, форсируя субагентов. Это становится стандартом проектирования агентных систем.

MCP закрепляется как стандарт интеграции. Ещё год назад каждый инструмент изобретал свой способ интеграции с агентом. Сейчас всё больше проектов — это просто MCP-серверы, работающие с любым совместимым хостом. CodeGraph, SocratiCode, LazyWeb — все на MCP. Это хороший тренд для экосистемы.

SQLite — недооценённый выбор для локальных инструментов. Не нужен Qdrant, не нужен Docker, не нужен отдельный сервис. SQLite + FTS5 закрывает поиск и хранение графа на проектах до десятков тысяч файлов. Для локального инструмента это правильный минимализм.

Резюме

CodeGraph — рабочий легковесный инструмент для тех, кто использует Claude Code на больших кодовых базах и хочет, чтобы агент не жёг токены на рекурсивный grep. Архитектура грамотная: tree-sitter для парсинга, SQLite для хранения, MCP для интеграции, продуманная защита от context bloat через субагентов.

Заявленные 92%/71% — реальные цифры из README, но это бенчмарк автора и выигрыш в основном на больших проектах с архитектурными вопросами. «Агент Hermes» из телеграма — выдумка, такого в проекте нет. «Без ограничений» правда только в смысле «локально и без API-ключей».

Если у вас большой проект и Claude Code — попробуйте, установка занимает минуту, риск нулевой (всё локально, MIT). Если проект маленький или нужен семантический поиск — посмотрите в сторону альтернатив. А вообще полезно поставить и CodeGraph, и что-то векторное вроде SocratiCode, и использовать под разные типы задач: граф для трассировки, вектора для концептуального поиска.

Полезные ссылки:

• Репозиторий: github.com/colbymchenry/codegraph

• npm-пакет: npmjs.com/package/@colbymchenry/codegraph

• tree-sitter: tree-sitter.github.io

• Спецификация MCP: modelcontextprotocol.io

• Мой прошлый разбор похожего инструмента SocratiCode — для сравнения подходов