GitNexus Explorer: Interactive Codebase Knowledge Graph with Hermes Agent

GitNexus Explorer turns any git repository into a browsable knowledge graph. You index the codebase, and it serves a web UI where you can inspect symbols, trace call chains, explore clusters, and follow execution flows. If you need to understand an unfamiliar codebase, audit dependencies, or share an interactive map of a repo with a colleague, this skill gives you a visual entry point without leaving the terminal.

What it does

After setup, GitNexus Explorer runs two processes: a backend API that serves the indexed graph data, and a Node.js proxy that delivers the web UI and forwards API requests on the same port. The result is a single URL you can open in a browser or tunnel through Cloudflare for remote access. The web UI renders the entire graph in the browser, letting you click through nodes, search symbols, and see relationships. The backend also supports semantic search if you opt into embeddings during indexing.

Before you start

• Node.js v18 or later is required for both GitNexus and the proxy script.
• git must be installed, and the repo you want to index must have a .git directory.
• cloudflared is optional but auto-installed to ~/.local/bin if missing when you run the tunnel command.
• The web UI loads all nodes into browser memory. Repos under about 5,000 files work well. Larger repos (30,000+ nodes) will be sluggish or crash the browser tab. The CLI and MCP tools work at any scale, but the web visualization has this limit.

Steps

1. Clone and Build GitNexus (one-time setup)

This clones the GitNexus repository, installs dependencies for the shared library and the web UI, and builds the shared package. You only need to do this once per machine.

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. Patch the Web UI for Remote Access

The web UI defaults to localhost:4747 for API calls. When you access it through a tunnel or proxy, that address won't work. You patch it to use the same origin as the page itself.

File: $GITNEXUS_DIR/gitnexus-web/src/config/ui-constants.ts Change:

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

To:

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

File: $GITNEXUS_DIR/gitnexus-web/vite.config.ts Add allowedHosts: true inside the server: { } block (only needed if running dev mode instead of production build):

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

Then build the production bundle:

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

3. Index the Target Repo

Navigate to the repo you want to explore and run the analyzer. The --skip-agents-md flag prevents creation of Claude Code markdown files that Hermes Agent users don't need. The index is stored in .gitnexus/ inside the repo, which is automatically gitignored.

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

Add --embeddings for semantic search (slower, minutes instead of seconds).

4. Create the Proxy Script

Write this to a file (e.g., $GITNEXUS_DIR/proxy.mjs). It serves the production web UI and proxies /api/* to the GitNexus backend, keeping everything on the same origin to avoid CORS issues. No sudo or nginx needed.

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. Start the Services

Run the GitNexus backend API and the proxy in separate terminals (or background them). The proxy listens on port 8888 by default.

# 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 &

Verify: curl -s http://localhost:8888/api/repos should return the indexed repo(s).

6. Tunnel with Cloudflare (optional, for remote access)

If you want to share the graph with someone else, tunnel the proxy through Cloudflare. The command below installs cloudflared if missing and starts a quick tunnel.

# 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

The tunnel URL (e.g., https://random-words.trycloudflare.com) is printed to stderr. Share it, and anyone with the link can explore the graph.

7. Cleanup

When you are done, stop the services and remove the index from the target repo.

# 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/

When not to use it

If you only need to query a codebase programmatically or through an MCP tool, the web UI adds unnecessary overhead. The GitNexus CLI and MCP integrations work at any scale and don't suffer from browser memory limits. Skip the web UI if you are working with repos larger than 5,000 files or if you don't need visual exploration.

Limits and gotchas

• --config /dev/null is required for cloudflared if the user has an existing named tunnel config at ~/.cloudflared/config.yml. Without it, the catch-all ingress rule in the config returns 404 for all quick tunnel requests.
• Production build is mandatory for tunneling. The Vite dev server blocks non-localhost hosts by default (allowedHosts). The production build + Node proxy avoids this entirely.
• The web UI does NOT create .claude/ or CLAUDE.md. Those are created by npx gitnexus analyze. Use --skip-agents-md to suppress the markdown files, then rm -rf .claude/ for the rest. These are Claude Code integrations that hermes-agent users don't need.
• Browser memory limit. The web UI loads the entire graph into browser memory. Repos with 5k+ files may be sluggish. 30k+ files will likely crash the tab.
• Embeddings are optional. --embeddings enables semantic search but takes minutes on large repos. Skip it for quick exploration; add it if you want natural language queries via the AI chat panel.
• Multiple repos. gitnexus serve serves ALL indexed repos. Index several repos, start serve once, and the web UI lets you switch between them.

What pairs with this

This skill is part of the Hermes Agent optional skills collection. It complements codebase-inspection for deeper static analysis and hermes-agent for autonomous code exploration. If you are already using Hermes Agent, you can invoke GitNexus Explorer as part of a research workflow without leaving the agent runtime.