Hermes agent

Gitnexus Explorer

Индексирует кодовую базу с помощью GitNexus и запускает интерактивный граф знаний через веб-интерфейс и туннель Cloudflare.

Метаданные навыка

ИсточникОпциональный (устанавливается по запросу) — установить командой hermes skills install official/research/gitnexus-explorer
Путьoptional-skills/research/gitnexus-explorer
Версия1.0.0
АвторHermes Agent + Teknium
ЛицензияMIT
Платформыlinux, macos, windows
Тегиgitnexus, code-intelligence, knowledge-graph, visualization
Связанные навыкиnative-mcp, codebase-inspection

Справочник: полный SKILL.md

инфо

Ниже приведено полное определение навыка, которое Hermes загружает при его активации. Именно эти инструкции видит агент во время работы навыка.

GitNexus Explorer

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

Когда использовать

  • Пользователь хочет визуально изучить архитектуру кодовой базы
  • Пользователь просит построить граф знаний или граф зависимостей репозитория
  • Пользователь хочет поделиться интерактивным обозревателем кодовой базы с кем-то другим

Требования

  • Node.js (v18+) — нужен для GitNexus и прокси
  • git — репозиторий должен содержать директорию .git
  • cloudflared — для туннелирования (устанавливается автоматически в ~/.local/bin, если отсутствует)

Предупреждение о размере

Веб-интерфейс загружает все узлы в браузер. Репозитории до ~5 000 файлов работают без проблем. Крупные репозитории (30k+ узлов) будут тормозить или приведут к краху вкладки браузера. CLI и MCP-инструменты работают с любым масштабом — ограничение касается только веб-визуализации.

Шаги

1. Клонируем и собираем GitNexus (однократная настройка)

GITNEXUS_DIR="${GITNEXUS_DIR:-$HOME/.local/share/gitnexus}"

if [ ! -d "$GITNEXUS_DIR/gitnexus-web/dist" ]; then
  git clone https://github.com/abhigyanpatwari/GitNexus.git "$GITNEXUS_DIR"
  cd "$GITNEXUS_DIR/gitnexus-shared" && npm install && npm run build
  cd "$GITNEXUS_DIR/gitnexus-web" && npm install
fi

2. Патчим веб-интерфейс для удалённого доступа

По умолчанию веб-интерфейс обращается к API на localhost:4747. Нужно переключить его на same-origin — тогда он корректно работает через туннель/прокси:

Файл: $GITNEXUS_DIR/gitnexus-web/src/config/ui-constants.ts Заменить:

export const DEFAULT_BACKEND_URL = 'http://localhost:4747';

На:

export const DEFAULT_BACKEND_URL = typeof window !== 'undefined' && window.location.hostname !== 'localhost' ? window.location.origin : 'http://localhost:4747';

Файл: $GITNEXUS_DIR/gitnexus-web/vite.config.ts Добавить allowedHosts: true внутрь блока server: { } (нужно только при запуске в режиме разработки, не для production-сборки):

server: {
    allowedHosts: true,
    // ... existing config
},

Затем собрать production-бандл:

cd "$GITNEXUS_DIR/gitnexus-web" && npx vite build

3. Индексируем целевой репозиторий

cd /path/to/target-repo
npx gitnexus analyze --skip-agents-md
rm -rf .claude/    # remove Claude Code-specific artifacts

Флаг --embeddings добавляет семантический поиск (медленнее — минуты вместо секунд).

Индекс сохраняется в директории .gitnexus/ внутри репозитория (автоматически добавляется в .gitignore).

4. Создаём прокси-скрипт

Запишите следующий код в файл (например, $GITNEXUS_DIR/proxy.mjs). Он раздаёт production-сборку веб-интерфейса и проксирует /api/* к бэкенду GitNexus — один origin, никаких проблем с CORS, без sudo и nginx.

import http from 'node:http';
import fs from 'node:fs';
import path from 'node:path';

const API_PORT = parseInt(process.env.API_PORT || '4747');
const DIST_DIR = process.argv[2] || './dist';
const PORT = parseInt(process.argv[3] || '8888');

const MIME = {
  '.html': 'text/html', '.js': 'application/javascript', '.css': 'text/css',
  '.json': 'application/json', '.png': 'image/png', '.svg': 'image/svg+xml',
  '.ico': 'image/x-icon', '.woff2': 'font/woff2', '.woff': 'font/woff',
  '.wasm': 'application/wasm',
};

function proxyToApi(req, res) {
  const opts = {
    hostname: '127.0.0.1', port: API_PORT,
    path: req.url, method: req.method, headers: req.headers,
  };
  const proxy = http.request(opts, (upstream) => {
    res.writeHead(upstream.statusCode, upstream.headers);
    upstream.pipe(res, { end: true });
  });
  proxy.on('error', () => { res.writeHead(502); res.end('Backend unavailable'); });
  req.pipe(proxy, { end: true });
}

function serveStatic(req, res) {
  let filePath = path.join(DIST_DIR, req.url === '/' ? 'index.html' : req.url.split('?')[0]);
  if (!fs.existsSync(filePath)) filePath = path.join(DIST_DIR, 'index.html');
  const ext = path.extname(filePath);
  const mime = MIME[ext] || 'application/octet-stream';
  try {
    const data = fs.readFileSync(filePath);
    res.writeHead(200, { 'Content-Type': mime, 'Cache-Control': 'public, max-age=3600' });
    res.end(data);
  } catch { res.writeHead(404); res.end('Not found'); }
}

http.createServer((req, res) => {
  if (req.url.startsWith('/api')) proxyToApi(req, res);
  else serveStatic(req, res);
}).listen(PORT, () => console.log(`GitNexus proxy on http://localhost:${PORT}`));

5. Запускаем сервисы

# Terminal 1: GitNexus backend API
npx gitnexus serve &

# Terminal 2: Proxy (web UI + API on one port)
node "$GITNEXUS_DIR/proxy.mjs" "$GITNEXUS_DIR/gitnexus-web/dist" 8888 &

Проверка: curl -s http://localhost:8888/api/repos должен вернуть проиндексированный репозиторий (или несколько).

6. Туннель через Cloudflare (опционально — для удалённого доступа)

# Install cloudflared if needed (no sudo)
if ! command -v cloudflared &>/dev/null; then
  mkdir -p ~/.local/bin
  curl -sL https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 \
    -o ~/.local/bin/cloudflared
  chmod +x ~/.local/bin/cloudflared
  export PATH="$HOME/.local/bin:$PATH"
fi

# Start tunnel (--config /dev/null avoids conflicts with existing named tunnels)
cloudflared tunnel --config /dev/null --url http://localhost:8888 --no-autoupdate --protocol http2

URL туннеля (вида https://random-words.trycloudflare.com) выводится в stderr. Поделитесь им — любой, кто получит ссылку, сможет открыть граф.

7. Очистка

# Stop services
pkill -f "gitnexus serve"
pkill -f "proxy.mjs"
pkill -f cloudflared

# Remove index from the target repo
cd /path/to/target-repo
npx gitnexus clean
rm -rf .claude/

Подводные камни

  • --config /dev/null обязателен для cloudflared, если у пользователя уже есть именованный туннель в ~/.cloudflared/config.yml. Без этого флага catch-all ingress-правило из конфига возвращает 404 на все quick-tunnel запросы.

  • Production-сборка обязательна при туннелировании. Vite dev server по умолчанию блокирует нелокальные хосты (allowedHosts). Production-сборка с Node-прокси обходит это ограничение полностью.

  • Веб-интерфейс сам по себе не создаёт .claude/ и CLAUDE.md. Их создаёт npx gitnexus analyze. Флаг --skip-agents-md подавляет генерацию markdown-файлов, а rm -rf .claude/ убирает остальное. Эти артефакты нужны для интеграции с Claude Code и не требуются пользователям hermes-agent.

  • Ограничение памяти браузера. Весь граф загружается в память браузера. Репозитории от 5k файлов начинают тормозить; при 30k+ вкладка, скорее всего, упадёт.

  • Эмбеддинги — опционально. Флаг --embeddings включает семантический поиск, но на больших репозиториях индексация займёт минуты. Для быстрого ознакомления можно обойтись без него; добавляйте, если нужны запросы на естественном языке через панель AI-чата.

  • Несколько репозиториев. gitnexus serve обслуживает все проиндексированные репозитории сразу. Проиндексируйте несколько, запустите serve один раз — веб-интерфейс позволит переключаться между ними.

⌕ ESC