Integrating GitNexus into Codex: Installation, Indexing, Web UI, and Project Analysis in Practice

AI coding tools have no problem reading files, but when it comes to questions like "how is the project layered," "who calls this interface downstream," or "which processes are affected by changing a class," relying solely on filename and keyword searches falls short. GitNexus's approach is to first index a project into a code knowledge graph, then provide this graph to the CLI, Web UI, and MCP. After integrating with Codex, Codex can directly read GitNexus's project context, functional clusters, and execution flows.

This operation is based on a multi-module Java project bo-camunda-flow. The process includes installation, Codex MCP configuration, a directory error, project indexing, viewing the graph via the Web UI, and finally having Codex perform an architectural analysis based on GitNexus.

Environment and Installation

First, confirm the local Node and npm versions. The actual environment is Node v22.12.0, npm 10.9.0.

GitNexus's CLI loads local parsing and graph database dependencies. If the version is too low, problems can easily arise during installation or runtime. The environment info is kept here not to pad the steps, but so that if an installation failure or native dependency build failure occurs later, you can quickly determine if the runtime environment is the cause.

Install GitNexus globally:

npm install -g gitnexus@latest
gitnexus --version

After installation, the version returned is 1.6.5. Deprecated warnings that appear during the process do not affect usage.

If the installation gets stuck on building optional grammar packages, you can skip some optional grammars:

GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 npm install -g gitnexus@latest

Configuring for Codex

The most valuable use of GitNexus is not running the CLI standalone, but connecting it to tools like Codex that support MCP. Here, the globally installed command is used to register MCP:

codex mcp add gitnexus -- gitnexus mcp

The terminal returns Added global MCP server 'gitnexus'., indicating that Codex can now start the GitNexus MCP service.

You can also use the npx syntax:

codex mcp add gitnexus -- npx -y gitnexus@latest mcp

Both methods work. Using gitnexus mcp after a global installation makes startup more direct.

GitNexus also provides a universal configuration command:

gitnexus setup

It will attempt to automatically detect locally installed editors and write the MCP configuration. The benefit of manually executing codex mcp add is that it's more explicit and only modifies Codex; gitnexus setup is suitable for configuring multiple tools like Claude Code, Cursor, and Codex simultaneously. If the article only covers Codex, keeping the codex mcp add command is clearer.

gitnexus analyze is the Core Command

The entry command for GitNexus is:

gitnexus analyze

This command scans the current Git repository, parses the code, generates a .gitnexus local index, and registers the repository in the global registry. The subsequent Web UI and MCP both depend on this index.

The command used this time is:

gitnexus analyze --embeddings --skills --verbose

The meanings of the three parameters are:

Parameter	Purpose	Required
--embeddings	Generates semantic search vectors, making subsequent query/search more suitable for natural language retrieval, but slower and more resource-intensive.	Optional
--skills	Generates repo-specific skills based on project functional clustering, making it easier for AI tools to obtain more specific module context.	Optional
--verbose	Outputs more detailed analysis logs, suitable for first-time installation or troubleshooting skipped files or parsing issues.	Optional

You can also run it without these parameters:

gitnexus analyze

If you just want to quickly see the graph for the first time, you can run the default command first. When you need better semantic search and AI context, add --embeddings --skills.

You can choose the command based on your goal here. To generate only a basic graph, use gitnexus analyze. To prepare for natural language queries via Codex, use gitnexus analyze --embeddings. To give AI tools finer module context, use --skills. For first-time troubleshooting or to see which files were skipped, add --verbose. These parameters are enhancements, not mandatory.

In practice, you can run it in two rounds. First, execute gitnexus analyze to confirm the project can be parsed normally, gitnexus list can see the repository, and gitnexus status is up-to-date. In the second round, supplement with --embeddings and --skills as needed. This is more stable: if the basic index isn't generated, there's no need to spend time generating vectors first; if you only want the Web UI to draw a relationship diagram, the default analyze is sufficient; if you plan to let Codex do natural language Q&A and module analysis, then adding the enhancement parameters is more appropriate.

--verbose is not recommended to be enabled by default long-term. It's suitable for the first integration or troubleshooting phase, allowing you to see a more detailed parsing process; once the command is stable, just keep the necessary parameters for daily use. Generating embeddings for large projects takes longer, so it's best to run it when the machine is idle.

If the project changes frequently, re-executing gitnexus analyze before committing and then letting Codex query will be more reliable than analyzing with an old index.

In a multi-person collaboration project, also confirm the current branch and local modification status first. This makes results easier to reproduce stably.

A Common Error: Current Directory is Not a Git Repository

When executing analyze directly for the first time, the terminal prompted:

Not inside a git repository.
Tip: pass --skip-git to index any folder without a .git directory.

The reason is simple: the command was run in a non-Git directory. GitNexus needs to be inside a Git repository by default for analysis because it needs to record the project path, commit, and index status.

The correct approach is to enter the project root directory:

cd /Users/xiaobo/huawei-code/bo-camunda-flow
gitnexus analyze --embeddings --skills --verbose

If you really need to analyze a regular folder, you can add:

gitnexus analyze --skip-git

Indexing the Project and Verifying Status

After re-executing in the bo-camunda-flow directory, GitNexus completed indexing:

105 files
863 symbols
1844 edges
28 clusters
32 processes

These statistics correspond to files, code symbols, relationship edges, functional clusters, and execution flows, respectively. For subsequent analysis, edges, clusters, and processes are more critical than the file count, as they are the source of call relationships and module boundaries.

After indexing is complete, it's recommended to check:

gitnexus list
gitnexus status

gitnexus list shows the registered repositories, and gitnexus status is used to confirm whether the current commit matches the indexed commit. The image shows Status: up-to-date, indicating the current index is not stale.

Starting the Web UI

Start the local service:

gitnexus serve

The output shows:

MCP HTTP endpoints mounted at /api/mcp
GitNexus server running on http://localhost:4747

Open in a browser:

http://localhost:4747

The page will list the indexed camunda-flow and display 105 files, 863 symbols, 32 flows.

After gitnexus serve starts, the terminal must remain running. The web page is just the frontend entry point; what actually provides the repository list, graph data, and MCP HTTP endpoint is this local service. The file count, symbol count, and flow count displayed on the page come from the previously generated .gitnexus index; there's no need to re-upload the code.

After entering the project, the left side shows the file tree, and the right side shows the knowledge graph. Modules like flow-common, flow-config, flow-service, flow-web can be seen directly on the left; the right-side graph displays 863 nodes and 1844 edges.

The role of the graph is not to replace the IDE, but to first provide a relational perspective. For example, the relationship density near flow-service is higher, with nodes like Controller, CommonFlowServiceImpl, SysWorkFlowServiceImpl concentrated in the main area, indicating that business logic primarily revolves around these classes.

For business projects, the file tree only answers "where is the code," while the graph answers "how is the code connected." These two perspectives work well together: the left side shows the Maven module split, and the right side shows which classes are at the center of relationships. When first taking over a project, you can start from highly connected nodes and then return to the source code to confirm responsibilities.

After clicking a node, the left side opens the Code Inspector and navigates to the source code. Here, ProcessDetailInfoRespVO is selected, and you can directly see the Java file content, annotations, and fields.

This step is quite practical: first find the node on the graph, then return to the source code for confirmation. The graph tells you "who it's related to," and the source code confirms "what it actually does."

Letting Codex Use GitNexus to Analyze the Project

After configuring MCP, Codex can directly call GitNexus tools. During the actual analysis, Codex was first asked to analyze the project architecture, and it called:

gitnexus.query
gitnexus.read_mcp_resource

The resources read included:

gitnexus://repo/camunda-flow/context
gitnexus://repo/camunda-flow/clusters
gitnexus://repo/camunda-flow/processes

context provides a project overview, clusters provides functional clustering, and processes provides execution flows. Compared to directly having Codex scan directories, this method builds a project map much faster.

This step is equivalent to having Codex read an "index summary" first, rather than starting a search from scratch. query is suitable for finding execution flows by concept, and read_mcp_resource is suitable for reading fixed resources like project overviews, functional areas, process lists, and graph schemas. For an unfamiliar project, getting this information first before expanding into source code analysis makes the direction more accurate.

Continuing the analysis, Codex combined local files and GitNexus context to confirm the project structure. It first looked at pom.xml and Java files, then called gitnexus.context around key classes like CommonFlowServiceImpl, CommonFlowController, SysWorkFlowServiceImpl.

Here, the difference between GitNexus and ordinary grep can be seen. grep can find files containing keywords, but it won't proactively tell you what processes these classes are part of. context returns callers, callees, process participation, and related relationships around a symbol, suitable for tracing the path from Controller to Service, and Service to Camunda Runtime.

The final conclusion drawn was: this is a multi-module Maven Spring Boot + Camunda 7 workflow backend. The module relationship is roughly:

flow-web
  -> flow-service
      -> flow-common
      -> flow-config

flow-web is responsible for the application entry point, REST Controllers, and web configuration; flow-service handles business implementation; flow-common contains models, VOs, enums, exceptions, and BPMN generation tools; flow-config holds MyBatis, Camunda, Sa-Token, logging, and application configurations.

This kind of conclusion is not guessed solely from directory names. GitNexus provided functional clusters and execution flows, and Codex combined them with local source code to confirm the critical paths. For example, the process deployment chain was organized as:

POST /sys/flow/deploy
-> SysWorkFlowController.definition
-> SysWorkFlowServiceImpl.processDeploy
-> Bpmn.createEmptyModel
-> BpmnElementFactory / BpmnModelUtil
-> CamundaProcessUtil
-> repositoryService.createDeployment().deploy()

The process start chain was organized as:

POST /flow/start
-> CommonFlowController.start
-> CommonFlowServiceImpl.processStart
-> runtimeService.startProcessInstanceById

The approval chain was organized as:

POST /flow/approve
-> CommonFlowServiceImpl.processApproval
-> taskService.complete / delegateTask
-> runtimeService.createProcessInstanceModification

This is the most direct benefit of integrating GitNexus into Codex: it doesn't just answer "where is a certain class," but can string together classes, modules, interfaces, and business processes.

Common Command Summary

Installation and Configuration:

npm install -g gitnexus@latest
gitnexus --version
codex mcp add gitnexus -- gitnexus mcp

Indexing the Project:

gitnexus analyze
gitnexus analyze --embeddings
gitnexus analyze --skills
gitnexus analyze --embeddings --skills --verbose
gitnexus analyze --force
gitnexus analyze --skip-git

Index Status:

gitnexus list
gitnexus status

Starting Services and MCP:

gitnexus serve
gitnexus mcp

Direct Graph Queries:

gitnexus query "authentication flow"
gitnexus context CommonFlowServiceImpl
gitnexus impact CommonFlowServiceImpl --direction upstream
gitnexus detect-changes
gitnexus cypher "MATCH (n) RETURN count(n) AS count"

These commands correspond to different scenarios:

Command	Suitable Scenario
query	Find related execution flows by natural language or keywords.
context	View the upstream and downstream relationships of a class, method, or function.
impact	Check the impact scope before making changes, especially for public Services, utility classes, and interface DTOs.
detect-changes	When local changes exist, analyze which symbols and processes the current diff affects.
cypher	Directly query the underlying graph database, suitable for more precise structural queries.

How to Use for Debugging and Change Analysis

GitNexus's own positioning is not just "drawing diagrams." After analyzing its project implementation, you can see it exposes a set of tools for AI Agents around MCP: query for finding processes by concept, context for viewing the upstream and downstream of a single symbol, impact for analyzing change impact, detect_changes for mapping the current Git diff to affected symbols and processes, and cypher retaining the underlying graph query capability. These tools combined are quite suitable for debugging and pre-refactoring checks.

For example, if a process start interface is abnormal online, the usual troubleshooting involves first searching for the interface path, then entering the Controller, then the Service, and then manually tracing calls to RuntimeService, RepositoryService, TaskService, etc. After integrating GitNexus, you can first ask:

gitnexus query "start workflow process"

After finding the relevant process, look at the core class:

gitnexus context CommonFlowServiceImpl

If you plan to modify CommonFlowServiceImpl, then run:

gitnexus impact CommonFlowServiceImpl --direction upstream

This way, you can first know which Controllers, process nodes, or other services depend on it. When the code has been changed but not yet committed, use:

gitnexus detect-changes

It will reverse-lookup the affected symbols and processes based on the current Git diff. This capability is closer to real-world development scenarios than just looking at git diff, because many problems are not "which line was changed," but "which entry points and processes use this line."

In Codex, this entire workflow can be completed directly via MCP. First, have Codex use query to find processes related to the problem, then use context to dig deeper into key classes, and finally use impact or detect_changes to make risk judgments before and after changes. GitNexus's benefit is not replacing the debugger, but narrowing down the troubleshooting entry point in advance, so you don't have to blindly search through the entire project directory.

Maintenance Commands:

gitnexus clean
gitnexus clean --all --force
gitnexus wiki

For multi-repository or multi-service scenarios, you can also use group commands:

gitnexus group create <name>
gitnexus group add <group> <groupPath> <registryName>
gitnexus group sync <name>
gitnexus group query <name> "<query>"
gitnexus group status <name>

What GitNexus is Good For

From this usage, GitNexus's benefits are mainly in four areas.

First, onboarding to a project is faster. query, context, clusters, processes can first provide a module and process perspective, without having to blindly start from the directory.

Second, debugging is more directional. When encountering a bug, you can first use query to find the related process, then use context to see the callers and callees of a class, and finally return to the source code to confirm the logic. GitNexus itself also lists debugging as a typical use case, because it excels at tracing problems along the call chain.

Third, you can see the impact scope before changing code. impact <symbol> --direction upstream can show which callers, modules, or processes might be affected, which is closer to "will the business process break" than relying solely on an IDE's reference search.

Fourth, Codex's project analysis no longer relies solely on grep. MCP allows Codex to directly read GitNexus's graph resources, making it easier to ground answers about architecture, processes, and module responsibilities in real files and real call relationships.

It is not runtime monitoring, nor can it guarantee coverage of reflection, dynamic calls, and all framework magic. A more reasonable usage is: use GitNexus to quickly establish a structural judgment, then return to the source code to verify the critical path. For a multi-module Spring Boot + Camunda project like bo-camunda-flow, this combination is already sufficient to make architecture sorting, process tracing, and change impact analysis faster.