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

CodeGraph стоит изучить, потому что он решает реальную проблему в AI-программировании: агенты тратят лишние итерации на повторное обнаружение одной и той же структуры кода с помощью grep, glob и чтения файлов.

1. CodeGraph в одном предложении

CodeGraph — это инструмент для анализа кода с лицензией MIT и приоритетом локальной работы, который преобразует репозиторий в граф знаний SQLite, содержащий файлы, символы, вызовы, импорты, маршруты и ссылки, а затем предоставляет этот граф AI-агентам для программирования через MCP.

A граф знаний кода — это база данных сущностей кода и связей между ними. MCP, или Model Context Protocol, — это протокол инструментов, который многие агенты используют для вызова внешних функций.

2. Почему это существует

The repo's README frames the problem around Claude Code exploration agents that repeatedly call grep, glob, Bash, and Read before answering architecture questions. That is expensive because file discovery is repeated per session and per task. CodeGraph moves discovery up front: parse once, store relationships locally, then let the agent query the graph.

The official docs site makes the same point in a smaller form: CodeGraph turns a codebase into a queryable local graph for AI coding agents, using tree-sitter parsing, MCP, and impact analysis. The npm package page repeats the README benchmark table and setup commands, which matters because the npm package is the main installation surface for many developers.

Status quo:
agent question
  -> grep/glob/read loop
  -> partial mental map
  -> answer
  -> next task repeats discovery

CodeGraph model:
codegraph init/index
  -> .codegraph/codegraph.db
  -> agent calls codegraph_context / trace / impact
  -> answer from graph-backed source context

3. Ментальная модель: пять компонентов

CodeGraph проще оценивать как конвейер, а не как единую команду поиска.

+---------------------+      +----------------------+      +----------------------+
| scanner             | ---> | extractor             | ---> | resolver             |
| git + filesystem    |      | tree-sitter + helpers  |      | imports, calls,      |
| ignore rules        |      | language files         |      | frameworks, bridges  |
+---------------------+      +----------------------+      +----------+-----------+
                                                                      |
                                                                      v
                         +----------------------+      +----------------------+
                         | MCP tools            | <--- | SQLite graph         |
                         | context, trace,      |      | nodes, edges, files, |
                         | callers, impact      |      | FTS5 search          |
                         +----------------------+      +----------------------+

4. Кратчайший пример сквозной реализации (End-to-End)

В README проекта в настоящее время приводится краткий путь установки и более подробное руководство по быстрому старту. codegraph init -i создает индекс проекта, но агенту все равно требуется запись MCP server, прежде чем он сможет вызвать CodeGraph.

# 1. Install or run the interactive installer.
npx @colbymchenry/codegraph

# 2. Restart the agent after the installer writes its MCP config.

# 3. Build the project-local graph.
cd your-project
codegraph init -i

# 4. Check the index from the CLI.
codegraph status

# 5. Ask the agent a structural question.
# Example prompt:
"Use CodeGraph first. How does the auth request reach the database?"

Для ручной настройки Claude Code в README приведена JSON-запись MCP в mcpServers.codegraph. ~/.codex/config.toml.

# Codex CLI manual shape, from the installer target.
[mcp_servers.codegraph]
command = "codegraph"
args = ["serve", "--mcp"]

5. Глубокое погружение: как работает каждый слой

5.1 Сканер: что индексируется

Сканер по возможности использует файлы, видимые в git, и переключается на обход файловой системы для проектов без git или при игнорировании родительских структур. node_modules, dist, target, .venv, Pods, и .next.

// Schema-level artifact: each indexed file becomes a row.
files(path, content_hash, language, size, modified_at, indexed_at, node_count, errors)

// Scanner-level artifact: ignored dependency/build directories are excluded
// before the graph becomes agent context.

Субъективный вывод: CodeGraph наиболее эффективен, когда область индексации предсказуема и стандартна.

5.2 Экстрактор: сначала символы, потом текст

Процесс извлечения построен на базе tree-sitter — инкрементального парсера, который создает синтаксические деревья. src/extraction/languages/ преобразуют эти деревья в узлы, такие как функции, методы, классы, интерфейсы, маршруты, компоненты, переменные, константы и модули.

nodes(
  id,
  kind,
  name,
  qualified_name,
  file_path,
  language,
  start_line,
  end_line,
  docstring,
  signature
)

Субъективный вывод: именно поэтому CodeGraph — это не просто обертка для векторного поиска.

5.3 Резолвер: самая сложная часть

Static extraction finds references, but references are not useful until they resolve. CodeGraph's resolver handles import paths, name matching, framework routes, callback synthesis, dynamic-dispatch bridges, Swift to Objective-C bridging, React Native bridges, Expo modules, and framework-specific route shapes. Recent release notes show that much of the project's velocity is in this layer.

edges(
  source,
  target,
  kind,        -- calls, imports, contains, references, extends, implements...
  metadata,
  line,
  col,
  provenance
)

Субъективный вывод: качество работы резолвера определяет, насколько безопасно использовать CodeGraph для рефакторинга. 0 callers результат может быть хуже, чем отсутствие инструмента, так как он сообщает агенту, что «живой» код является неиспользуемым.

5.4 SQLite и FTS5: локальный граф, локальный поиск

Схема хранит узлы, ребра, файлы, неразрешенные ссылки и метаданные проекта в локальной базе данных SQLite в .codegraph/codegraph.db.

CREATE VIRTUAL TABLE nodes_fts USING fts5(
  id,
  name,
  qualified_name,
  docstring,
  signature,
  content='nodes'
);

Субъективный вывод: локальная SQLite — оптимальный выбор хранилища для инструментов такого класса.

5.5 Инструменты MCP: управление агентом

CodeGraph предоставляет компактный набор инструментов MCP: search, context, callers, callees, impact, node, explore, status, files и trace. src/mcp/server-instructions.ts, поэтому он загружается через ответ инициализации MCP, а не дублируется в файле инструкций каждого агента.

Важный вывод: руководство по MCP — это часть продукта.

6. Что мы сделали не так

Сначала я рассматривал CodeGraph как очередной проект по сжатию токенов.

Я также предполагал, что путь настройки будет выглядеть как «установил и проиндексировал».

Bad assumption:
"init -i means my agent has CodeGraph"

Correct model:
"install wires MCP; init/index builds the repo graph"

7. Паттерны рабочих процессов в реальных условиях

8. Распространенные ошибки и сценарии сбоев

Активные GitHub issues — лучший источник информации об ошибках, так как пользователи сообщают о реальных сбоях, а не дают общие советы.

9. Заметки о производительности, масштабировании и стоимости

В README CodeGraph сообщается о преимуществах в тестах производительности на нескольких open-source кодовых базах при использовании Claude в headless-режиме с CodeGraph и без него. codegraph_explore масштабированием.

Объективно говоря, результаты скромнее, чем заявлено в заголовке.

Use this local A/B shape:

Task: "How does request X reach handler Y?"
Run A: agent with CodeGraph MCP enabled
Run B: same agent, same repo, CodeGraph disabled

Measure:
- time to first useful answer
- file reads
- grep/bash/search calls
- accepted edits
- follow-up corrections
- total cost, if your client exposes it

10. Для кого предназначен CodeGraph

11. Реакция сообщества

Публичная реакция оказалась полезной и неоднозначной.

Обсуждение на Reddit в r/ClaudeCode отнесло CodeGraph к другим оптимизаторам токенов и контекста, таким как упаковщики репозиториев, компрессоры вывода команд, инструменты памяти и MCP code explorers.

В отдельной ветке r/ClaudeAI, посвященной крупным TypeScript монорепозиториям, обсуждалось, как люди работают с кодовыми базами, которые не помещаются в контекст.

12. Вердикт: стоит ли использовать CodeGraph?

The best version of CodeGraph is boring: initialize the repo, let the agent call codegraph_context сначала используйте trace для вопросов по потоку, и используйте impact перед внесением правок.

13. Общая картина

CodeGraph является частью более широкого перехода от «набивания» промптов к контексту, подкрепленному инструментами.

Эта середина ценна, потому что AI-агентам для написания кода нужно больше, чем просто фрагменты.

Context stack:
AGENTS.md / CLAUDE.md     -> rules and project intent
docs / package READMEs    -> human-authored architecture notes
CodeGraph                 -> local symbol and relationship graph
compiler / tests / linter -> correctness checks

The graph helps the agent navigate. It does not replace the rest.

14. Часто задаваемые вопросы

15. Глоссарий

16. Все источники и ссылки

Первичные источники

• Репозиторий colbymchenry/codegraph на GitHub
• Официальный сайт документации CodeGraph
• npm package page for @colbymchenry/codegraph
• Страница текущего релиза, проверяемая во время исследования
• CHANGELOG.md

Прочитанные исходные файлы

• src/index.ts - main CodeGraph class.
• src/db/schema.sql - nodes, edges, files, схема FTS5.
• src/extraction/index.ts — сканер, игнорируемые по умолчанию файлы, оркестрация индексации.
• src/mcp/tools.ts — определения инструментов MCP.
• src/mcp/server-instructions.ts — инструкции по управлению агентом.
• src/sync/watcher.ts — файловый вотчер и модель устаревания ожидающих обработки файлов.
• src/installer/targets/codex.ts — структура конфигурации Codex CLI.
• src/installer/targets/claude.ts — структура конфигурации Claude Code.

GitHub Issues и Pull Requests

• Issue #644 — утечка файловых дескрипторов в macOS / отчет об ошибке ENFILE.
• Issue #631 — путаница в порядке настройки в README.
• Issue #629 — неразрешенные barrel-экспорты в Svelte/TypeScript.
• Issue #628 — ограничения ресурсов в watch-mode.
• Проблема #621 - Пропуски в MCP resources/list и prompts/list.
• Проблема #613 - Тайм-аут MCP при работе с большой базой данных.
• Проблема #634 - Имена сервисов в виде строковых литералов TypeScript не индексируются.
• PR #632 - Документация по настройке и исправления обнаружения MCP.
• PR #643 - предложена .codegraphignore поддержка override.
• PR #603 - восстановлен встроенный SDK API.

Источники сообщества

• Обсуждение оптимизатора токенов в r/ClaudeCode
• Обсуждение контекста больших кодовых баз в r/ClaudeAI
• Пост в X с осторожным комментарием о скорости чтения «из первых рук»
• Пост в X, в котором CodeGraph был упомянут среди быстрорастущих AI-репозиториев

Внутренние ссылки

• Руководство по контексту Claude: Semantic Code Search MCP через Milvus
• Руководство по ArcKit: Wardley Mapping + инструментарий для мульти-ИИ архитектуры
• OpenAI Agents Python SDK: подробный разбор в сравнении с LangGraph и CrewAI
• AntiGravity MCP: забудьте о переключении контекста

17. Таблица атрибуции источников