a0-gitnexus-plugin

# GitNexus for Agent Zero Gives Agent Zero code-graph superpowers by installing the [GitNexus](https://www.npmjs.com/package/gitnexus) CLI and registering its MCP server, so the agent can analyze a codebase — dependencies, impact/blast-radius, symbol callers, route/tool maps, and ad-hoc graph (Cypher) queries — before it changes anything. ## Support If this plugin is useful to you, you can support the developer. [](https://buymeacoffee.com/king0james0) [](https://solscan.io/account/HXrzPqgcxBR9LctTVdTF6xCLpah4hQwyYEevsQ98QvTo) [](https://etherscan.io/address/0xfF61681F907fA8DB39C1d23cbdbE89D24A94De17) [](https://mempool.space/address/bc1qyr6x7kmxpy6ke0xutkxg90f30658fnr39h0d7r) ## What it can do - **Code-graph queries** (`gitnexus-code-graph` skill) — once enabled, GitNexus's MCP tools appear in the agent's toolset: list indexed repos, find a symbol's callers, gauge the blast radius of an edit, map routes/tools, and run Cypher queries over the graph. - **Visual code graph in the Canvas** (`gitnexus-canvas-view` skill) — adds a **GitNexus** icon to Agent Zero's right-side Canvas rail. Click it to explore an indexed repository's graph (symbols, dependencies, execution flows) and file tree right inside Agent Zero. Because GitNexus's web UI is local-only (it talks to its server over `localhost`), the plugin renders it in a **headless Chromium inside the container** and streams that view to the Canvas — everything stays on `127.0.0.1`, nothing is exposed externally. (Needs a Chromium in the environment; the plugin installs one via `apt` if none is present. The MCP tools work regardless.) The repo list **auto-refreshes**: when you index or re-index a repo, the surface reloads itself within a couple of seconds (and on open) so the new/updated repo appears — no manual refresh, and the code word-wrap is preserved. The reload only happens when the index actually changed, so it won't disturb your view otherwise. You can also **select text in the surface and `Ctrl/Cmd+C`** to copy it to your own machine's clipboard (the code view and detail panels are made selectable for this), and **`Ctrl/Cmd+V`** to paste your local clipboard into a field on the surface. It's cross-platform; copying uses the async Clipboard API on `https`/`localhost` with a legacy fallback for plain-`http` LAN access. - **Scheduled re-index** — keeps your indexed graphs fresh. Opt-in (off by default) — turn it on and the plugin registers a recurring Agent Zero scheduled task (**"GitNexus re-index"**, Sundays 06:00 by default) that re-runs `gitnexus analyze` on any repo you've **already** indexed whose latest commit has changed since it was last indexed. It does **not** discover or index new repos — that's your call. See [Keeping indexes fresh](#keeping-indexes-fresh). ## Setup 1. **Install** via the Plugin Hub, a GitHub repo URL, or by uploading the plugin ZIP, then enable it in the **Plugins** list. 2. On first run the plugin installs the `gitnexus` CLI (`npm install -g gitnexus`) and registers `gitnexus mcp` as a stdio MCP server in Agent Zero's MCP settings. **Restart / re-enable** so the MCP server connects. 3. That's it — no API key. Ask something like *"what depends on this function?"* or *"map this repo"* and the agent will use the GitNexus tools. > Requires Node.js/npm in the Agent Zero environment (present in the standard Docker image) and outbound network access on first run to install the CLI. > **Note on `onnxruntime-node`:** gitnexus pulls in `onnxruntime-node` for its *optional* local-embeddings (`--embeddings`) feature, and that dependency's native installer downloads a NuGet runtime that fails to unpack in some environments — which would otherwise abort the whole CLI install. The plugin doesn't use embeddings, so it installs gitnexus with `ONNXRUNTIME_NODE_INSTALL=skip`: only that one optional download is skipped, while gitnexus's required native pieces (its graph-DB engine and language grammars) build normally. You get a fully working CLI (MCP, analysis, Canvas, all core languages), just without local embeddings. ## How it works The plugin registers a standard MCP server entry under Agent Zero's `mcp_servers` setting: ```json "gitnexus": { "type": "stdio", "command": "gitnexus", "args": ["mcp"] } ``` Agent Zero spawns `gitnexus mcp` and exposes its tools to the agent. Because A0 reloads MCP automatically when that setting changes, the server connects without manual configuration. ## Keeping indexes fresh A GitNexus index is a snapshot — it reflects a repo at the commit it was analyzed at, so it drifts out of date as you keep committing. To keep it current the plugin can register a scheduled task — **opt-in, off by default.** Turn **Scheduled re-index** on in the plugin's **Config** panel and the task is registered; turn it off and it's removed — the toggle takes effect immediately, no restart: - **Task name:** `GitNexus re-index` (visible in Agent Zero's **Scheduler**; set its cadence in the plugin's **Config** panel). - **Default cadence:** Weekly (Sundays at 06:00), in Agent Zero's configured timezone — change it in the Config panel (**Interval** preset or **Custom cron**). - **What it does each run:** reads the GitNexus registry and, for every repo you've already indexed that is a git work-tree, compares the repo's current `HEAD` against the commit it was last indexed at. If they differ, it runs an incremental `gitnexus analyze` on that repo; if not, it skips it (so an idle week does almost no work). - **What it does *not* do:** it never indexes new repos. You decide what to index (`gitnexus analyze <path>`); the task only keeps current what you already chose. ### How it's wired The work and the schedule are deliberately separated: - **A deterministic helper does all the work.** `helpers/reindex.py` is plain Python — it reads the registry, does the commit comparison, and runs `gitnexus analyze` on the repos that changed. No model/LLM is involved in the indexing logic itself. - **The scheduled task is purely the visible trigger.** The `GitNexus re-index` task carries no logic; its instruction is just *"call the `gitnexus_reindex` tool once and report the summary."* It exists so the schedule is something you can see, run on demand, disable, or delete from the Scheduler UI (the cadence itself is set in the Config panel). - **Triggering goes through the agent loop.** Agent Zero runs every scheduled task by handing its prompt to the agent (that's the only execution path A0 has), so when the task fires the agent's single action is to call the built-in `gitnexus_reindex` tool, which runs the helper **in-process** (no terminal/code-execution session — so a manual **Run** from the Scheduler works the same as a scheduled run). There is **no background thread** — nothing runs the helper except this task, so it never double-fires. - **Cost:** because the trigger passes through the agent, each run spends a small amount of the model's budget on that one "run this command" hop — *not* on the indexing, which is the deterministic helper's job. ### Setting the schedule The cadence lives in the plugin's **Config** panel — the config is the **source of truth** (applied on save and on every boot, so editing the task's schedule directly in the Scheduler gets overwritten; change it here instead): - **Interval** — a preset dropdown: every **6h** / **12h**, **Daily**, **Weekly** (the default), or **Monthly**. Daily/weekly/monthly run at 06:00. - **Custom schedule (cron)** — a 5-field crontab (`minute hour day month weekday`) for anything the presets can't express (e.g. `0 3 * * *` = daily at 03:00). **Overrides the interval when set.** - **Reset context each run** — clear the task's conversation after each run so its context can't grow unbounded (on by default). - **Timezone** — set `reindex.timezone` in the config to differ from Agent Zero's default. The task still appears in Agent Zero's **Scheduler**, where you can see its history, **Run** it on demand, or **disable**/delete it. To turn the whole feature off, switch **Scheduled re-index** off in the Config panel (it removes the task). **Limitations:** repos indexed with `--skip-git` (or non-git folders) have no commit to compare, so they aren't auto-refreshed; re-index those manually. ## Configuration `default_config.yaml` (override per scope in the plugin config UI): | Key | Default | Meaning | |---|---|---| | `gitnexus_version` | `latest` | npm version of the gitnexus CLI to install, or a pinned version. | | `mcp_server_name` | `gitnexus` | Key under `mcp_servers.mcpServers` this plugin registers. | | `serve_port` | `4747` | Local port for the `gitnexus serve` graph web UI (what the in-container Chromium loads; bound to `127.0.0.1`). | | `cdp_port` | `9223` | The headless Chromium's remote-debugging port that the screencast bridge connects to. | | `bridge_port` | `14601` | The screencast bridge port registered with A0's Canvas gateway. | | `reindex.enabled` | `false` | Register the scheduled re-index task. **Opt-in — off by default.** Turn it on in the plugin's **Config** panel (takes effect immediately, no restart). | | `reindex.interval` | `7d` | Cadence preset: `6h` / `12h` / `1d` (daily) / `7d` (weekly) / `30d` (monthly). Daily/weekly/monthly run at 06:00. | | `reindex.cron` | `""` | Advanced: a full 5-field cron (`minute hour day month weekday`). When set it **overrides** `interval`. | | `reindex.reset_context` | `true` | Clear the task's conversation after each run so its context can't grow unbounded. | | `reindex.timezone` | `""` | Timezone for the schedule; empty uses Agent Zero's configured timezone. | ## Uninstalling Uninstall through the **Plugins UI**. The uninstall hook removes the `GitNexus re-index` scheduled task, removes the gitnexus entry from your `mcp_servers` setting (Agent Zero reloads MCP) and, **if this plugin installed the gitnexus CLI, uninstalls it too** — so nothing is left behind. Your indexed repos and their `.gitnexus` data are left untouched. A `gitnexus` you had installed independently beforehand is left untouched. (A manual `rm -rf` of the plugin folder bypasses this hook — always uninstall via the UI for a clean removal.) ## Citing If you use this in your work, please cite it (use the **"Cite this repository"** button on GitHub, or): ```bibtex @misc{a0gitnexusplugin2026, title = {a0-gitnexus-plugin: GitNexus code-graph for Agent Zero}, author = {King0James0}, year = {2026}, howpublished = {\url{https://github.com/King0James0/a0-gitnexus-plugin}}, note = {GitHub repository} } ``` ## License MIT — see [LICENSE](LICENSE).