Graphify — навык, который превращает проект в граф знаний

Graphify — это навык для ИИ-ассистентов, который по команде /graphify разбирает ваш проект (код, документацию, PDF, изображения, видео) и складывает всё в один граф знаний. Дальше ассистент отвечает на вопросы о проекте не грепом по файлам, а запросом к графу: можно спросить связь между двумя сущностями, объяснить один концепт или получить подграф по вопросу на естественном языке. Устанавливается он через одну команду и работает в Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot и ещё 20+ ассистентах.

Проект написан на Python, лицензия Apache-2.0, репозиторий публичный.

Что именно делает навык

Главное отличие от привычного семантического поиска — в том, что это не векторный индекс. Эмбеддингов и векторного хранилища нет вообще: строится настоящий граф, который можно обходить. У каждого ребра есть тег уверенности:

• EXTRACTED — связь явно прослеживается в исходниках;
• INFERRED — связь восстановлена самим graphify;
• AMBIGUOUS — гипотеза, которую стоит перепроверить.

Это позволяет ассистенту честно показывать, что он прочитал напрямую, а что додумал. Отдельно извлекаются комментарии # NOTE:, # WHY:, # HACK:, докстринги и ссылки на ADR/RFC — они становятся самостоятельными узлами, связанными с кодом, который объясняют.

Ключевое обещание — локальность. Код разбирается через tree-sitter AST: детерминированно, без вызовов LLM, без единого байта наружу. Только семантический проход по документам, PDF и картинкам обращается к модели вашего ассистента. Корпус из одного лишь кода вообще не требует API-ключа и работает офлайн.

Установка

uv tool install graphifyy      # поставить CLI (или: pipx install graphifyy)
graphify install               # зарегистрировать навык в ассистенте

Дальше в ассистенте:

/graphify .

Обратите внимание на двойную «y» в имени пакета на PyPI: пакет называется graphifyy, а команда — graphify. Нужен Python 3.10+. В Windows PowerShell пишите graphify . без ведущего слэша — там это разделитель пути. На macOS и Windows авторы советуют избегать голого pip install и использовать uv tool install или pipx install, чтобы навык не подхватил чужое окружение.

Что остаётся на диске

graphify-out/
├── graph.html       интерактивный граф в браузере — клики, поиск, фильтр по сообществам
├── GRAPH_REPORT.md  ключевые концепты, неожиданные связи, подсказки вопросов
└── graph.json       полный граф — можно запрашивать спустя недели, не перечитывая файлы

Отчёт содержит узлы-максимумы (самые связанные концепты, через которые проходит всё остальное), неожиданные связи между сущностями из разных файлов и модулей, извлечённые «почему», а также 4–5 вопросов, на которые именно этот граф лучше всего умеет отвечать.

Запросы к графу

Пример реального вывода на кодовой базе FastAPI:

$ graphify explain "APIRouter"
Node: APIRouter
  Source:    routing.py L2210
  Community: 2
  Degree:    47

Connections (47):
  --> RequestValidationError [uses] [INFERRED]
  --> Dependant [uses] [INFERRED]
  --> .get() [method] [EXTRACTED]
  <-- __init__.py [imports] [EXTRACTED]
  ...

$ graphify path "FastAPI" "ModelField"
Shortest path (3 hops):
  FastAPI --uses--> DefaultPlaceholder <--references-- get_request_handler() --references--> ModelField

graphify query отдаёт подграф по вопросу на естественном языке, graphify path строит кратчайший путь между двумя сущностями, graphify explain разбирает один узел со списком связей. Популярные флаги: --mode deep для более агрессивного извлечения, --update для пересборки только изменённых файлов, --cluster-only для повторной кластеризации без повторного извлечения, --no-viz, если HTML слишком большой.

Какие файлы понимает

Исходя из .gitignore поведение тоже продуманное: игнорируются сгенерированное и скомпилированное, а .graphifyignore добавляет свои правила и имеет приоритет.

Бенчмарки

Все системы гонялись на одном стенде с одной моделью и одинаковыми бюджетами; оценки выставлял судья, проверенный вторым судьёй вслепую (согласие 90.6%, Cohen's kappa 0.81). Подробные таблицы и команды воспроизведения — в файле BENCHMARKS.md.

Как заставить ассистент всегда пользоваться графом

Отдельная команда платформенного уровня записывает инструкции, по которым ассистент сначала спрашивает граф, а не файлы:

graphify claude install    # CLAUDE.md + PreToolUse hook (Claude Code)
graphify codex install     # AGENTS.md + hook-запись в .codex/hooks.json
graphify cursor install    # .cursor/rules/graphify.mdc с alwaysApply: true
graphify opencode install  # AGENTS.md + плагин tool.execute.before

Для платформ с хуками (Claude Code, Gemini CLI) хук срабатывает перед поисковыми вызовами инструментов и мягко подталкивает ассистент к graphify query. Для платформ с файлами инструкций (Codex, OpenCode, Cursor) ту же роль играет постоянный файл с инструкциями. Убирается всё разом через graphify uninstall, а --purge дополнительно удаляет graphify-out/.

Отдельный режим --strict для Claude Code идёт дальше мягкой подсказки: он блокирует первое чтение исходника в сессии и перенаправляет к графу, после чего возвращается к обычному режиму.

График живёт в git

graphify-out/ рекомендуют коммитить, чтобы вся команда начинала с готовой карты. Дальше три привычные git-команды держат граф актуальным сами:

Приватность

• Код обрабатывается локально через tree-sitter, ничего не уходит с машины.
• Видео и аудио транскрибируются локально faster-whisper.
• Документация, PDF и картинки уходят в модель ассистента — для headless-запуска нужен один из ключей: Gemini, Kimi, Claude, OpenAI, DeepSeek, Azure, Bedrock (по IAM, без ключа), Ollama или бинарник claude.
• Телеметрии и аналитики нет.
• Локальный лог запросов выключен по умолчанию и включается через GRAPHIFY_QUERY_LOG_ENABLE=1.

Заметный нюанс: Kimi (MOONSHOT_API_KEY) маршрутизирует запросы на серверы Moonshot AI в Китае — при требованиях к резидентности данных используйте --backend ollama или явно указывайте провайдера.

Что ещё есть

Граф можно отдать наружу: экспорт в SVG, GraphML (Gephi, yEd), Obsidian-хранилище, markdown-вики для навигации агентом, выгрузка Cypher для Neo4j и FalkorDB. Есть MCP-сервер с инструментами query_graph, get_node, get_neighbors, shortest_path, list_prs, get_pr_impact, triage_prs — как по stdio, так и общий HTTP-сервер для всей команды за одним адресом. Отдельная линия — работа с pull request: graphify prs показывает дашборд с CI, ревью и влиянием на граф, а graphify prs --conflicts находит PR, затрагивающие одни и те же сообщества графа. Наконец, graphify reflect собирает итоги прошлых вопросов-ответов в LESSONS.md и накладывает «уроки» поверх графа, помечая узлы как предпочтительные, спорные или устаревшие.

Дальше

• Как это работает — пайплайн извлечения, детекция сообществ, подсчёт уверенности
• ARCHITECTURE.md — модули и как добавить свой язык
• Дополнительные интеграции — Docker MCP Toolkit и SQLite
• Формат навыков Agent Skills: anthropics/skills — сюда попадает установка через --platform agents
• Пакет на PyPI: graphifyy

Активная разработка идёт в ветке v8, компания Graphify Labs выпустила продукт на YC (S26).