repo-graph

Структурная графовая память для ИИ-ассистентов программирования. Картографируйте свою кодовую базу. Ориентируйтесь по структуре. Читайте только то, что важно.

repo-graph предоставляет LLM карту вашей кодовой базы — сущности, связи и потоки — чтобы они могли переходить к нужным файлам, не читая всё подряд.

Вместо того чтобы переполнять контекстное окно LLM всей кодовой базой (или надеяться, что она угадает), repo-graph строит легкий граф того, что существует, как вещи связаны и где находятся точки входа. LLM запрашивает граф, находит минимальный набор необходимых файлов и читает только их.

Демо

https://github.com/user-attachments/assets/a1e4171b-b225-40d4-9210-39453e14b76a

https://github.com/user-attachments/assets/fc3191e5-fc35-4bd7-8372-72af55995883

Та же ошибка, та же модель, тот же промпт — единственная разница в том, установлен ли repo-graph.

Задача: исправить обратный оператор сравнения в монорепозитории Go + Angular (566 узлов, 620 ребер).

В 2.5 раза меньше токенов. В ~9 раз быстрее. Тот же правильный результат.

Как проводился тест

В обоих случаях использовались идентичные условия для честного сравнения:

• Та же модель: Claude Opus, 100% (без маршрутизации Haiku)

• Тот же промпт: "Группы, созданные недавно, отображаются как закрытые, а старые группы — как открытые. Это неправильно — новые группы должны быть открыты для вступления участников. Найдите и исправьте ошибку."

• Чистый контекст: каждый запуск начинался с /clear без предыдущего диалога

• Никаких других инструментов: CLAUDE.md, плагины, хуки и все другие MCP-серверы были удалены для обоих запусков — единственной переменной было наличие установленного repo-graph

• Никаких подсказок: промпт описывает симптом, а не местоположение — Claude должен самостоятельно найти group_controller.go:57

Без repo-graph Claude использует grep для поиска ключевых слов, читает файлы, снова использует grep, читает еще файлы и в конечном итоге сужает круг до ошибки. С repo-graph Claude вызывает flow("groups"), получает точную функцию-обработчик и файл, читает его и исправляет.

Просмотрите предварительно сгенерированные примеры для FastAPI, Gin, Hono и NestJS — реальный вывод графа, который можно изучить без установки чего-либо.

Проблема

LLM, работающие с кодом, тратят большую часть своего контекста на ориентацию:

• Чтение файлов, которые оказываются нерелевантными

• Пропуск связей между компонентами на разных языках

• Незнание того, где начинается функция или чего она касается

• Загрузка 50 файлов, когда достаточно 5

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

Как repo-graph решает это

repo-graph сканирует вашу кодовую базу один раз и строит граф:

• Сущности: модули, пакеты, классы, функции, маршруты, сервисы, компоненты

• Связи: импорты, вызовы, обработчики, определения, вхождения

• Потоки: сквозные пути от точки входа до уровня данных

Затем он предоставляет 12 инструментов MCP, которые позволяют LLM:

1. Ориентироваться — "Какие языки есть в этом репозитории? Какие основные функции?"

2. Навигировать — "Отследи поток входа от маршрута до базы данных" / "Какой кратчайший путь между UserService и API платежей?"

3. Определять область — "Сколько строк мне нужно прочитать, чтобы понять эту функцию?" / "Дай мне только файлы, необходимые для исправления этой ошибки"

4. Оценивать — "Каков радиус поражения при изменении этой функции?" / "Какие файлы представляют наибольший риск для поддержки?"

LLM получает структурный контекст в нескольких сотнях токенов вместо чтения тысяч строк.

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

Несколько анализаторов могут соответствовать одному репозиторию (например, бэкенд на Go + фронтенд на Angular + SCSS). Каждый вносит свои узлы и ребра в единый граф.

Установка

pip install mcp-repo-graph

Требуется Python 3.11+. Единственная зависимость среды выполнения: mcp[cli].

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

1. Генерация графа

repo-graph-generate --repo /path/to/your/project

Это сканирует кодовую базу и записывает данные графа в .ai/repo-graph/ внутри целевого репозитория.

2. Подключение к ИИ-ассистенту

Добавьте в конфигурацию MCP:

Claude Code (~/.claude/claude_code_config.json или проектный .mcp.json):

{
  "mcpServers": {
    "repo-graph": {
      "command": "repo-graph",
      "args": ["--repo", "/path/to/your/project"]
    }
  }
}

С переменной окружения:

{
  "mcpServers": {
    "repo-graph": {
      "command": "repo-graph",
      "env": { "REPO_GRAPH_REPO": "/path/to/your/project" }
    }
  }
}

3. Использование

ИИ-ассистент теперь имеет доступ ко всем 12 инструментам. Примеры запросов, на которые он может ответить:

• "Что делает эта кодовая база?" -> инструмент status

• "Отследи поток оформления заказа" -> инструмент flow

• "Что сломается, если я изменю UserService?" -> инструмент impact

• "Какие файлы мне нужны для этой ошибки?" -> инструмент minimal_read

• "Этот файл слишком большой, как мне его разделить?" -> инструмент split_plan

• "Покажи мне поток аутентификации визуально" -> инструмент graph_view

4. Поддержание актуальности с помощью git-хука (рекомендуется)

Добавьте repo-graph-generate в pre-commit хук, чтобы граф обновлялся автоматически — контекст LLM не тратится на перегенерацию:

# .git/hooks/pre-commit (or add to your existing hook)
#!/bin/sh
repo-graph-generate --repo .
git add .ai/repo-graph/

chmod +x .git/hooks/pre-commit

Каждый коммит поддерживает граф в актуальном состоянии. У LLM всегда есть свежая карта без траты ни одного токена на generate.

Совет: Если вы не хотите хранить данные графа в системе контроля версий, добавьте .ai/repo-graph/ в .gitignore и пропустите строку git add — граф будет существовать локально.

Справочник инструментов MCP

Генерация

Навигация

Бюджетирование контекста

Анализ состояния

Как это работает

1. Обнаружение — scan_project_dirs() находит корни проекта (включая макеты монорепозиториев, такие как packages/*, apps/*, services/*, src/*). Каждый анализатор проверяет наличие своих маркерных файлов.

2. Сканирование — соответствующие анализаторы извлекают сущности и связи с помощью эвристик регулярных выражений. Никакого парсинга AST, никаких внешних цепочек инструментов, никаких этапов сборки.

3. Объединение — все результаты анализаторов объединяются в единый граф. Узлы дедуплицируются по ID, ребра — по (откуда, куда, тип).

4. Обслуживание — MCP-сервер загружает граф в память и предоставляет инструменты обхода на основе BFS.

Формат данных графа

Сгенерированные файлы находятся в .ai/repo-graph/ внутри целевого репозитория:

• nodes.json — [{id, type, name, file_path}, ...]

• edges.json — [{from, to, type}, ...]

• flows/*.yaml — именованные потоки функций с упорядоченными последовательностями шагов

• state.md — человекочитаемый снимок для быстрой ориентации

Типы ребер: imports, defines, contains, uses, calls, handles, handled_by, exports, includes.

Добавление нового анализатора

Создайте repo_graph/analyzers/<language>.py:

from .base import AnalysisResult, Edge, LanguageAnalyzer, Node, scan_project_dirs, rel_path, read_safe

class MyLangAnalyzer(LanguageAnalyzer):

    @staticmethod
    def detect(repo_root):
        # Check for language marker files
        return any(
            (d / "my-marker").exists()
            for d in scan_project_dirs(repo_root)
        )

    def scan(self):
        nodes, edges = [], []
        # ... scan files, extract entities, build relationships ...
        return AnalysisResult(
            nodes=nodes,
            edges=edges,
            state_sections={"MyLang": f"{len(nodes)} entities\n"},
        )

    # Optional: file-level analysis for bloat_report / split_plan
    def supported_extensions(self):
        return {".mylang"}

    def analyze_file(self, file_path):
        # Return dict with function/method sizes, class counts, etc.
        pass

    def format_bloat_report(self, analysis):
        # Format the analysis dict into a human-readable string
        pass

Зарегистрируйте его в analyzers/__init__.py, добавив в _analyzer_classes().

Лицензия

MIT

Поддержка

Если repo-graph сэкономил вам время, подумайте о том, чтобы купить мне кофе.