GitNexus - Moses Yebei

GitNexus

Abstract

GitNexus: The Zero-Server Code Intelligence Engine - GitNexus is a client-side knowledge graph creator that runs entirely in your browser. Drop in a GitHub repo or ZIP file, and get an interactive knowledge graph wit a built in Graph RAG Agent. Perfect for code exploration

The Problem Developers need a way to explore a codebase’s full dependency, call‑graph and type information without spinning up a server or installing heavyweight analysis tools. Current IDE plugins surface only local symbols; they miss cross‑file bindings, generated code and runtime‑only paths, forcing engineers to guess architecture or run ad‑hoc scripts.

What This Does GitNexus builds a client‑side knowledge‑graph of any GitHub repository or ZIP archive and exposes it through a visual Web UI and a CLI‑driven “MCP” (model‑connect‑pipeline). The core ingestion pipeline lives under gitnexus/src/core/ingestion/ and parses source files with Tree‑sitter, extracts types (type‑extractors/shared.ts), builds a graph (graph/graph.ts), and persists it in LadybugDB (WASM in the browser, native in the CLI). The UI (gitnexus-web/src/App.tsx) consumes the same graph via the local MCP server (gitnexus/src/cli/serve.ts). A built‑in Graph‑RAG agent (gitnexus/src/core/llm/) can answer natural‑language queries over the graph.

How It Is Wired

Entry point – gitnexus/src/cli/serve.ts exports serveCommand. Running gitnexus serve starts an Express server that loads the persisted graph and registers LLM endpoints.
Ingestion flow – gitnexus/src/core/ingestion/pipeline.ts (oversized, 2624 lines) orchestrates workers (workers/parse-worker.ts). parseWorker calls extractSimpleTypeName, setLanguage, clearCaches (30 functions, 20 classes) and ultimately invokes mapToGraph. mapToGraph repeatedly calls generateId (81 calls) and addRelationship (24 calls) to populate graph/graph.ts.
Graph persistence – gitnexus/src/core/lbug/lbug-adapter.ts wraps LadybugDB; functions like runWithSessionLock and initLbug read/write the DB (30+ call sites).
LLM bridge – gitnexus/src/core/llm/index.ts receives a user prompt, calls wikiCommand → prompt (13 calls) and ultimately executeQuery which hits the DB.
Hotspots – gitnexus/src/core/ingestion/utils/ast-helpers.ts is a hub (66 inbound imports) and part of a circular import cycle, so changes here have a wide blast radius. gitnexus/src/core/ingestion/type-extractors/shared.ts also sits in the cycle and is called from 26 other files. * Large files (pipeline.ts, tree-sitter-queries.ts, local-backend.ts) exceed 2000 lines and should be split for maintainability.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/GitNexus.git
cd GitNexus

# Install the CLI globally (npm is the package manager)
npm install -g gitnexus

# Index a repository (example: a local copy of a project)
gitnexus ingest /path/to/target-repo

# Start the MCP server (exposes the graph to the UI and LLM agents)
gitnexus serve   # runs serveCommand in gitnexus/src/cli/serve.ts

# Open the browser UI (auto‑detects the local server)
open https://gitnexus.vercel.app   # or navigate to the hosted demo

The CLI reads optional configuration from eval/.env.example. No additional secrets are required; the project ships a license file and CI definitions (.github/workflows/*.yml).

Real‑World Use A development team can run gitnexus ingest nightly on their monorepo. The resulting graph is served locally; developers query the UI (“Which modules import UserService?”) or let an LLM (Claude, Cursor, etc.) augment PR reviews via the MCP endpoint. Because all data stays on the developer’s machine, privacy is preserved and no network latency is introduced.

Code Health & Issues

HIGH – Steps in .github/workflows/ci-e2e.yml discard exit codes, potentially masking build failures.
MEDIUM – GITHUB_TOKEN permissions are not scoped (ci-e2e.yml).
MEDIUM – No Dependabot/Renovate configuration for 6 manifests.
MEDIUM – Dockerfile.test uses an unpinned base image (node:20‑bookworm).
MEDIUM – CI lacks a dependency‑vulnerability scan.
MEDIUM – Checkout action keeps credentials persisted; persist-credentials: false is missing.
MEDIUM – Dockerfile runs as root; no non‑root USER defined.

Static analysis also reports 24 import‑cycle members, high branching density in several ingestion helpers, and three oversized files (>2500 LOC). These are the primary maintainability concerns.

The Bottom Line GitNexus delivers a fully client‑side code‑graph engine with a usable UI and a CLI that can feed AI agents, making deep code insight accessible without server infrastructure. The architecture is solid, but the ingestion layer suffers from circular imports, large monolithic files, and a handful of CI hygiene issues that should be addressed before production use. Teams comfortable with TypeScript and willing to invest in refactoring the ingestion core will find it a valuable addition to their tooling stack.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

1,983 files

TypeScript620
Python169
Java124
C#114
PHP113
Rust113

ReactVueFlaskExpressLaravelDocker

Module dependencies

The 10 most depended-upon modules of 462, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0__ingestion_utils_ast_helpers["ast-helpers"] n1_stion_type_extractors_shared["shared"] n2_ion_field_extractors_generic["generic"] n3_ntegration_resolvers_helpers["helpers"] n4_itnexus_src_core_graph_types["types"] n5_xus_src_storage_repo_manager["repo-manager"] n6__ingestion_language_provider["language-provider"] n7__src_mcp_local_local_backend["local-backend"] n8_itnexus_src_core_group_types["types"] n9__core_ingestion_method_types["method-types"] n2_ion_field_extractors_generic --> n0__ingestion_utils_ast_helpers n6__ingestion_language_provider --> n9__core_ingestion_method_types n6__ingestion_language_provider --> n0__ingestion_utils_ast_helpers n9__core_ingestion_method_types --> n0__ingestion_utils_ast_helpers n1_stion_type_extractors_shared --> n0__ingestion_utils_ast_helpers n0__ingestion_utils_ast_helpers --> n6__ingestion_language_provider n7__src_mcp_local_local_backend --> n5_xus_src_storage_repo_manager n3_ntegration_resolvers_helpers --> n4_itnexus_src_core_graph_types classDef cyc stroke:#ef4444,stroke-width:2px; class n0__ingestion_utils_ast_helpers,n1_stion_type_extractors_shared,n2_ion_field_extractors_generic,n6__ingestion_language_provider,n9__core_ingestion_method_types cyc;

Dependencies

28 of 91 declared dependencies are a major version behind. Resolved 90 of 91 against the registry.

Package	Declared	Latest	Behind
`vite`	^5.2.0	8.2.1	3 major
`commander`	^12.0.0	15.0.0	3 major
`datasets`	>=3.0.0	5.0.1	2 major
`rich`	>=13.0.0	15.0.0	2 major
`@types/node`	^24.10.1	26.2.0	2 major
`typescript`	^5.4.5	7.0.2	2 major
`glob`	^11.0.0	13.0.6	2 major
`pandas`	>=2.0.0	3.0.5	1 major

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high1

medium6

Stop discarding the exit code of steps whose failure mattershigh

.github/workflows/ci-e2e.yml

lines 47 discard failure

The job reports green while the artifact it was supposed to produce was never produced, so a crash becomes a successful run built on stale data.

Fix: Let the step fail, or test the specific expected condition instead of discarding all exit codes.

Declare least-privilege permissions for GITHUB_TOKENmedium2 occurrences

.github/workflows/ci-e2e.yml

2 workflow(s) declare no permissions

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

6 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium

gitnexus/Dockerfile.test

node:20-bookworm

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/ci-e2e.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Add a non-root USER to the imagemedium

gitnexus/Dockerfile.test

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.