gitnexus-explorer

name	gitnexus-explorer
description	Serve an interactive codebase knowledge graph web UI.
version	1.0.0
author	Ouro + Teknium
license	MIT
platforms	["linux","macos","windows"]
metadata	{"hermes":{"tags":["gitnexus","code-intelligence","knowledge-graph","visualization"],"related_skills":["ouro-agent","codebase-inspection"]}}

GitNexus Explorer

Index any codebase into a knowledge graph and serve an interactive web UI for exploring symbols, call chains, clusters, and execution flows. Tunneled via Cloudflare for remote access.

When to Use

• User wants to visually explore a codebase's architecture
• User asks for a knowledge graph / dependency graph of a repo
• User wants to share an interactive codebase explorer with someone

Prerequisites

• Node.js (v18+) — required for GitNexus and the proxy
• git — repo must have a .git directory
• cloudflared — for tunneling (auto-installed to ~/.local/bin if missing)

Size Warning

The web UI renders all nodes in the browser. Repos under ~5,000 files work well. Large repos (30k+ nodes) will be sluggish or crash the browser tab. The CLI/MCP tools work at any scale — only the web visualization has this limit.

Steps

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

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. Patch it to use same-origin so it works through a tunnel/proxy:

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

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).

The index lives in .gitnexus/ inside the repo (auto-gitignored).

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 — same origin, no CORS issues, no sudo, no 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: , : ,
    : req., : req., : req.,
  };
   proxy = http.(opts,  {
    res.(upstream., upstream.);
    upstream.(res, { :  });
  });
  proxy.(,  { res.(); res.(); });
  req.(proxy, { :  });
}

 () {
   filePath = path.(, req. ===  ?  : req..()[]);
   (!fs.(filePath)) filePath = path.(, );
   ext = path.(filePath);
   mime = [ext] || ;
   {
     data = fs.(filePath);
    res.(, { : mime, :  });
    res.(data);
  }  { res.(); res.(); }
}

http.( {
   (req..()) (req, res);
   (req, res);
}).(,  .());

5. Start the Services

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

# 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 — anyone with the link can explore the graph.

7. Cleanup

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

Pitfalls

• --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 ouro-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.