CodeGraph

Кросс-языковой интеллект кода для ИИ-агентов и разработчиков.

CodeGraph строит семантический граф вашей кодовой базы — функции, классы, импорты, цепочки вызовов — и предоставляет к нему доступ через 42 инструмента MCP, расширение для VS Code, плагин для JetBrains IDE и слой постоянной памяти. Поддерживает парсинг 38 языков с помощью tree-sitter. ИИ-агенты получают структурированное понимание кода вместо поиска по файлам.

Быстрый старт

MCP-сервер (Claude Code, Cursor, любой MCP-клиент)

Добавьте в ~/.claude.json (или конфигурацию вашего MCP-клиента):

{
  "mcpServers": {
    "codegraph": {
      "command": "/path/to/codegraph-server",
      "args": ["--mcp"]
    }
  }
}

Сервер автоматически индексирует текущую рабочую директорию.

Расширение для VS Code

Установите VSIX:

code --install-extension codegraph-0.20.1.vsix

Один VSIX подходит для всех платформ. Аналитический движок не входит в комплект: при первом запуске расширение предложит загрузить движок, собранный для вашей платформы, проверит его контрольную сумму и установит в ~/.codegraph/bin — то же место, которое использует плагин для JetBrains, так что одна загрузка обслуживает оба инструмента. Загрузка предлагается, а не выполняется автоматически, поскольку это нативный бинарный файл, который запускается с вашими правами. Откажитесь от загрузки и выполните команду CodeGraph: Download Analysis Engine из палитры команд, когда будете готовы.

После установки движка расширение запускает его автоматически и регистрирует все инструменты как Language Model Tools для Copilot.

IDE JetBrains

Плагин для IntelliJ IDEA, PyCharm, GoLand, Android Studio и других продуктов семейства использует тот же движок через LSP: окна Code Vision, Symbols и Memories, панель графа и одноразовую регистрацию MCP для AI Assistant. Он разрешает или загружает движок так же, как расширение для VS Code, используя общую директорию ~/.codegraph/bin.

→ jetbrains/README.md для описания интерфейсов, порядка разрешения движка и сборки из исходников.

Правила для ИИ-агентов

Предварительно настроенные файлы правил, которые обучают ИИ-агентов для кодирования (Claude, Cursor, Windsurf, Codex, Cline) использовать инструменты MCP CodeGraph перед переходом к grep или чтению нескольких файлов. Сопоставляет намерения на естественном языке с подходящим инструментом codegraph_*.

→ codegraph-ai/codegraph-rules-for-agents

Установка: cp <agent>/codegraph.md ~/<agent>/ (одна строка на агента — см. README репозитория с правилами).

GitHub Action — ревью PR в CI

Добавьте workflow в ваш репозиторий, чтобы получать автоматический комментарий с анализом кодового графа для каждого PR — радиус изменений, пробелы в тестах, устаревшая документация, предложенные ревьюеры. Работает только с графом (без эмбеддингов, без модели ONNX), поэтому быстро и не требует API-ключей — достаточно встроенного GITHUB_TOKEN.

Скопируйте .github/workflows/codegraph-pr.yml в ваш репозиторий. Основной вызов — одна команда:

codegraph-server --graph-only \
  --run-tool codegraph_pr_context \
  --tool-args '{"baseBranch":"main","format":"markdown"}'

Она выводит готовый к публикации markdown-комментарий. Флаг --graph-only пропускает генерацию эмбеддингов (индексация в 10-50 раз быстрее); --run-tool запускает один инструмент и завершает работу без рукопожатия MCP stdio — идеально для скриптов.

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

Флаги MCP-сервера

--embedding-model static — быстрая индексация с model2vec

Статические эмбеддинги (model2vec) заменяют ONNX-трансформер на токен→вектор

Таблица поиска: индексация в ~100 раз быстрее (5 873 символа из этого репозитория встраиваются за ~1 с против ~3,4 мин с BGE), и нет зависимости от ONNX runtime или порога в 1,5 ГБ ОЗУ. Поиск остаётся гибридным (BM25 + семантический), поэтому качество сквозного поиска составляет ~90% от BGE. Модель не входит в состав клиента — ей требуется локальный каталог с моделью (config.json + tokenizer.json + model.safetensors) по пути ~/.codegraph/static_models/jina-code-static-256 или в том месте, на которое указывает CODEGRAPH_STATIC_MODEL:

• Установка @astudioplus/codegraph-mcp из npm загружает её в это расположение по умолчанию (по возможности; установите CODEGRAPH_SKIP_MODEL_FETCH=1, чтобы пропустить загрузку, и установка никогда не завершится с ошибкой из-за этого).
• В противном случае загрузите предварительно собранную модель с помощью scripts/fetch-static-model.sh или дистиллируйте свою собственную из любой sentence-transformer (по умолчанию используется Jina-Code с лицензией Apache-2.0) за ~30 с на CPU: python scripts/distill_static_model.py.
• Модели в расположении по умолчанию не требуется настройка в IDE: оба клиента для IDE оставляют CODEGRAPH_STATIC_MODEL неустановленным, и движок сам разрешает путь. Чтобы использовать модель, хранящуюся в другом месте, установите codegraph.staticModelPath в VS Code или Настройки → Инструменты → CodeGraph → Встраивания → Каталог статической модели в JetBrains; каждый клиент затем передаёт этот путь как CODEGRAPH_STATIC_MODEL.

CODEGRAPH_SKIP_MEMORY_CHECK — принудительная загрузка модели встраивания, несмотря на ограничение ОЗУ

Перед загрузкой ONNX-модели сервер проверяет доступную память и, если её меньше ~1,5 ГБ, пропускает загрузку модели, чтобы избежать завершения процесса из-за нехватки памяти (работает только граф). Установите CODEGRAPH_SKIP_MEMORY_CHECK=1 (также принимает true/yes), чтобы обойти эту проверку и всегда загружать модель.

Используйте это, если встраивания отключены, несмотря на то, что на машине достаточно свободной ОЗУ. Показание 0 МБ доступно считается сбоем обнаружения, и модель всё равно загружается (macOS резервирует восстанавливаемую память в неактивных/спекулятивных страницах, которые некоторые средства чтения памяти не учитывают как свободные), поэтому это переопределение в основном предназначено для других случаев, когда сообщаемая цифра низкая, но неверная. Оно работает как в режиме MCP, так и в режиме одноразового запуска --run-tool.

--profile — сужение поверхности инструментов MCP

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

Настройки VS Code

Настройки codegraph.* задокументированы один раз рядом с расширением, которое их считывает:

→ vscode/README.md — Конфигурация

Встраивания полных тел функций включены по умолчанию. Текст тела функции захватывается во время парсинга без накладных расходов на ввод-вывод.

Встроенные исключения (всегда пропускаются) охватывают ~47 каталогов в трёх категориях:

• Сборка / кэш: node_modules, target, dist, build, out, .git, __pycache__, vendor, .venv, venv, .tox, .pytest_cache, .mypy_cache, .ruff_cache, .next, .nuxt, .svelte-kit, .parcel-cache, .npm, .yarn, .pnpm-store, .cache, .cargo, .bundle, .gradle, DerivedData, Pods, xcuserdata, cmake-build-*
• Состояние IDE / IaC: .idea, .vscode-test, .fleet, .terraform, .terragrunt-cache, .serverless
• Каталоги с конфиденциальными данными: .aws, .ssh, .gnupg, .kube, .docker

Плюс шаблоны для бинарных архивов, нативных библиотек, метаданных ОС и расширений секретных файлов (*.pem, *.key, *.p12, *.pfx, *.crt, *.gpg, *.kdbx, соглашения об именах SSH-ключей, такие как id_rsa и т. д.) — глубокая защита от случайного встраивания учётных данных.

Индексация не создала файлов или что-то ещё выглядит не так? См. docs/troubleshooting.md.

Инструменты

42 инструмента сообщества, плюс ещё 27 (из них 17 — анализаторы безопасности) в CodeGraph Pro.

Анализ кода (11)

code --install-extension codegraph-0.20.1.vsix

| get_ai_context | Основной инструмент контекста. Осведомлён о намерениях (объяснение/изменение/отладка/тестирование) с учётом бюджета токенов. Возвращает исходный код, связанные символы, импорты, родственные элементы, подсказки для отладки. | | get_edit_context | Всё необходимое перед редактированием: исходный код + вызывающие функции + тесты + воспоминания + история Git | | get_curated_context | Контекст по всему кодовой базе для запроса на естественном языке («как работает аутентификация?») | | analyze_impact | Прогнозирование радиуса поражения — что сломается при изменении, удалении или переименовании | | analyze_complexity | Цикломатическая сложность с разбивкой (ветвления, циклы, вложенность, исключения, ранние возвраты) | | find_circular_deps | Обнаружение циклических цепочек импорта/зависимостей между файлами | | find_hot_paths | Наиболее вызываемые функции, ранжированные по количеству транзитивных вызывающих функций | | find_dead_imports | Поиск неиспользуемых импортов — модулей, которые импортированы, но никогда не используются | | get_module_summary | Высокоуровневая сводка по каталогу: количество файлов, функций, разбивка по языкам, самые сложные функции | | search_by_pattern | Поиск по регулярным выражениям в телах функций, сигнатурах, именах и строках документации | | search_by_error | Поиск функций, которые выбрасывают, перехватывают или обрабатывают определённые типы ошибок |

Навигация по коду (13)

Индексация (3)

Память (7)

Постоянный контекст ИИ между сессиями — идеи отладки, архитектурные решения, известные проблемы.

Хорошо сочетается с Tempera — системой эпизодической памяти, которая фиксирует переносимые стратегии отладки и решения между проектами. Инструменты памяти CodeGraph хранят заметки в рамках проекта; Tempera фиксирует межпроектные BKM (лучшие известные методы), которые со временем улучшаются.

Анализ PR / изменений (1)

Документация (7)

Постоянная документация проекта — индексация проектных документов, их семантический поиск, проверка соответствия кода дизайну, генерация архитектурной документации из графа кода.

Все названия инструментов начинаются с префикса codegraph_ (например, codegraph_get_ai_context). Инструменты, нацеленные на конкретный символ, принимают uri + line или nodeId из результатов symbol_search.

Примеры использования

Индексация проектной документации и её поиск:

codegraph_index_markdown(path: "/projects/myapp/docs/ARCHITECTURE.md")
codegraph_search_docs(query: "how does the auth module handle JWT refresh?")

Проверка соответствия кода проектной документации:

codegraph_verify_design(source: "/projects/myapp/docs/ARCHITECTURE.md", direction: "forward")
// → "132/132 identifiers verified, 0 gaps"

Поиск описанного в документации, но ещё не реализованного:

codegraph_design_gaps(source: "/projects/myapp/docs/API_DESIGN.md")
// → "4 of 12 identifiers not found in code: PaymentService, RefundHandler, ..."

Генерация документации по архитектуре из графа кода:

codegraph_generate_architecture_doc(scope: "src/", topN: 5)
// → Markdown with modules, complexity hotspots, hot paths, circular deps

Сохранение отладочных инсайтов для будущих сессий:

codegraph_memory_store(kind: "debug_context", title: "Nginx body size limit",
  content: "The /upload endpoint fails on payloads > 1MB...",
  problem: "API returns 500 on large uploads",
  solution: "Increase nginx client_max_body_size to 10M",
  agentSource: "claude")

Получение контекста для ИИ с компрессией графа и дополнением из проектной документации:

codegraph_get_ai_context(uri: "file:///projects/myapp/src/auth.rs", line: 42, intent: "modify")
// → Code context + graphStats: {entitiesInGraph: 13555, entitiesTraversed: 47, entitiesKept: 8}
// → design_context section from indexed docs mentioning "auth"

Ревью PR — радиус изменений, пробелы в тестах, устаревшая документация, ревьюеры в одном вызове:

codegraph_pr_context(baseBranch: "main")
// → "PR changes 4 files (+263/-77, 12 functions). 37 direct callers, 8 tests, 3 untested. Risk: medium."
// → test_gaps: [refresh_token, revoke_session] — functions with 0 test callers
// → stale_docs: ["auth.rs described in ARCHITECTURE.md > Authentication — doc may need updating"]
// → suggested_reviewers: [{author: "anvanster", lines_owned: 3200}]
// → commit_hint: "feat(mcp): <describe the change>"

Сужение поверхности инструментов для многословных сессий:

codegraph-server --mcp --profile=core  # Only 8 tools: search + symbol info + AI context

CodeGraph Pro

Дополнительные инструменты доступны в CodeGraph Pro:

Сквозные возможности (все инструменты security_check_*): - include_tests / treat_as_production — полноценное игнорирование тестов/примеров/внешних зависимостей - check_compile_gates — обнаружение уязвимостей в C/C++ внутри #ifdef X помечается как DEFENSIVE_GATED_OFF, если X не определён в CMake/Cargo/Makefile - Поддержка 25 маркеров подавления (# nosec, // NOLINT, // codeql[ignore], # rubocop:disable и др.) на уровне строк и функций - Телеметрия по каждому скану: path_filter (проверено/совпадений/пропущено) + compile_gate (количество отключённых через защитные условия)

Языки

38 языков, разбираемых с помощью tree-sitter — функции, классы, импорты, граф вызовов, метрики сложности, графы зависимостей, поиск символов и анализ влияния:

Сборки для сообщества и полные сборки: COBOL, Fortran, Perl, Dart, Zig и R компилируются только с флагом --features extra-languages. В стандартной бинарной сборке для сообщества они отсутствуют — их использование в телеметрии было нулевым, а грамматики tree-sitter добавляют ~25 МБ (только таблицы парсинга COBOL занимают 30 МБ). Остальные 32 языка доступны всегда.

Архитектура

MCP Client (Claude, Cursor, ...)   VS Code Extension   JetBrains Plugin

        |                                  |                  |
    MCP (stdio)                       LSP Protocol       LSP Protocol

        |                                  |                  |
        └───────────┐               ┌──────┴──────────────────┘
                    ▼               ▼
            ┌─────────────────────────────┐
            │       codegraph-server      │
            ├─────────────────────────────┤
            │  38 tree-sitter parsers     │
            │  Semantic graph engine      │
            │  AI query engine (BM25)     │
            │  Memory layer (RocksDB)     │
            │  Docs store (RocksDB+HNSW)  │
            │  Full-body embeddings (BGE) │
            │  HNSW vector index          │
            └─────────────────────────────┘

Один бинарный файл на Rust обслуживает оба протокола: MCP и LSP.

• Индексация: ~60 файлов/сек. Инкрементальная переиндексация при изменении файлов с помощью хеширования содержимого FNV-1a.
• Персистентность: Граф и эмбеддинги сохраняются в ~/.codegraph/graph.db (RocksDB). Мгновенный запуск при перезапуске — без повторного парсинга, без повторного создания эмбеддингов.
• Запросы: Менее 100 мс. Разрешение импортов и вызовов между файлами на этапе индексации.
• Эмбеддинги: Полнотекстовые (тела функций захватываются при парсинге, без дисковых операций ввода-вывода). Векторы хранятся в RocksDB вместе с графом. Автоматическая загрузка модели при первом запуске.

Поддерживаемые платформы

Движок представляет собой нативный бинарный файл, который загружается для вашей платформы при первом запуске.

Для Linux требуется glibc 2.30 или новее и libstdc++ из GCC 11 или новее (GLIBCXX_3.4.29). Второе требование является обязательным и не вытекает из первого — движок включает ONNX Runtime, который собран с GCC 11.

Требования для обеих архитектур Linux идентичны. Если движок завершает работу сразу с сообщением вида

version `GLIBCXX_3.4.29' not found (required by codegraph-server)

значит, C++-рантайм дистрибутива старше, чем требуется движку; установка более новой версии libstdc++ (например, gcc-toolset-11 для RHEL 8) решает проблему без необходимости обновления дистрибутива.

Сборка из исходников

git clone https://github.com/codegraph-ai/codegraph
cd codegraph
cargo build --release -p codegraph-server    # Rust server
cd vscode && npm install && npm run esbuild  # VS Code extension
npx @vscode/vsce package                     # VSIX

Требуется Rust стабильной версии, Node.js 18+ и VS Code 1.90+.

Поддержите проект

CodeGraph — бесплатный проект с открытым исходным кодом, который поддерживается одним разработчиком. Если он экономит ваше время, подумайте о спонсировании на GitHub — это помогает проекту оставаться на плаву и развиваться.

Лицензия

Apache-2.0