🔧 gitnexus-stable-ops

Production-grade operational toolkit for running GitNexus at scale — purpose-built for autonomous AI agent swarms.

"designed for autonomous agent swarms" — @d3thshot7777, GitNexus maintainer

Built by 合同会社みやび (Miyabi G.K.) — Running 25+ repositories indexed with GitNexus in production, daily.

⚠️ License Notice: This repository is licensed under MIT and covers only the wrapper scripts, tooling, and documentation. GitNexus itself is licensed under PolyForm NonCommercial 1.0.0. This toolkit calls the GitNexus CLI but does not include or redistribute any GitNexus source code.

Why This Exists

GitNexus is one of the most capable open-source code intelligence engines available today. But running it in production — across dozens of repositories, with automated reindexing, inside AI agent workflows — exposes four critical operational problems:

| Problem | Impact | This toolkit's fix | |---------|--------|-------------------| | Version drift | CLI and MCP reference different GitNexus versions, causing data corruption | Pinned binary ($GITNEXUS_BIN) used by all scripts | | Embedding loss | analyze --force without --embeddings silently deletes embeddings | Auto-detect existing embeddings, add flag automatically | | Dirty worktree | Reindexing uncommitted work pollutes the code graph | Skip dirty repos by default (ALLOW_DIRTY_REINDEX=0) | | Impact instability | impact command crashes on arm64 macOS with concurrent queries | Graceful fallback to context-based analysis |

We discovered and solved these problems running GitNexus on 25+ repos for 3+ months.

Production Stats

Running in production at 合同会社みやび (Miyabi G.K.):

| Metric | Value | |--------|-------| | Repositories indexed | 25+ | | Symbols in knowledge graph | 32,000+ | | Edges (relationships) | 73,000+ | | AI agents using the graph | 40 (OpenClaw MAS) | | Embedding loss incidents | 0 since v1.0 | | Upstream PRs merged to GitNexus | 7 of 13 submitted | | Production uptime | 3+ months |

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Your Repositories                         │
│   repo-1/  repo-2/  repo-3/  ...  repo-25+/                    │
└─────────┬───────────────────────────────────────────────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────────────┐
│              gitnexus-stable-ops  (this toolkit)                 │
│                                                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │  gni (CLI)   │  │   doctor.sh  │  │  auto-reindex.sh     │  │
│  │  Readable    │  │  Version     │  │  Stale detection     │  │
│  │  output +    │  │  drift +     │  │  Embedding protect   │  │
│  │  fallbacks   │  │  health      │  │  Dirty skip          │  │
│  └──────┬───────┘  └──────┬───────┘  └──────────┬───────────┘  │
│         │                 │                      │               │
│  ┌──────┴─────────────────┴──────────────────────┴───────────┐  │
│  │                  Pinned GitNexus Binary                    │  │
│  │              (~/.local/bin/gitnexus-stable)                │  │
│  └──────────────────────────┬────────────────────────────────┘  │
└─────────────────────────────┼───────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    ~/.gitnexus/                                   │
│   registry.json  ─  KuzuDB databases  ─  meta.json per repo    │
│   32,000+ symbols  │  73,000+ edges  │  execution flows        │
└─────────────────────────────────────────────────────────────────┘

Integration with AI Agent Systems

This toolkit was designed to work with autonomous AI agent swarms — systems where multiple agents collaborate on code changes across repositories.

How agents use gitnexus-stable-ops

Agent receives task: "Fix auth bug in service-api"
    │
    ├─ 1. gni context AuthService     → Get callers, callees, dependencies
    ├─ 2. gni impact AuthService      → What breaks if we change it?
    ├─ 3. gni cypher "MATCH..."       → Custom graph queries
    ├─ 4. Agent writes code fix
    └─ 5. auto-reindex.sh             → Graph stays current (post-commit hook)

OpenClaw Multi-Agent System example

We run gitnexus-stable-ops with 40 agents coordinating across 25+ repositories:

# Agent workflow: "Fix Issue #123"
steps:
  - agent: dev-architect
    action: gni impact TargetClass --direction upstream
    purpose: Blast radius analysis before code change

  - agent: dev-coder
    action: gni context TargetClass
    purpose: Understand dependencies before writing fix

  - agent: guardian
    action: gitnexus-doctor.sh ~/dev/repo project TargetClass
    purpose: Post-change health verification

  - trigger: post-commit hook
    action: gitnexus-auto-reindex.sh
    purpose: Graph stays current for next agent

Key insight: When agents share a code knowledge graph, they make better decisions. gni impact prevents agents from breaking callers they don't know about.

Production Deployment

Docker (recommended for teams)

FROM node:22-slim

# Install GitNexus
RUN npm install -g gitnexus@1.4.6

# Install stable-ops
RUN git clone https://github.com/ShunsukeHayashi/gitnexus-stable-ops.git /opt/stable-ops \
    && cd /opt/stable-ops && make install

# Pin the binary
RUN ln -sf $(which gitnexus) /usr/local/bin/gitnexus-stable

ENV GITNEXUS_BIN=/usr/local/bin/gitnexus-stable
ENV REPOS_DIR=/repos

COPY crontab /etc/cron.d/gitnexus
CMD ["cron", "-f"]

# docker-compose.yml
services:
  gitnexus:
    build: .
    volumes:
      - ./repos:/repos:ro
      - gitnexus-data:/root/.gitnexus
    restart: unless-stopped

volumes:
  gitnexus-data:

Cron schedule (our production setup)

# Smart reindex: only repos changed in last 24h
0 3 * * *   cd /opt/stable-ops && REPOS_DIR=/repos bin/gitnexus-reindex.sh >> /var/log/gitnexus-reindex.log

# Weekly full reindex (Sunday 4 AM)
0 4 * * 0   cd /opt/stable-ops && bin/gitnexus-reindex-all.sh >> /var/log/gitnexus-full-reindex.log

# Health check (daily)
30 9 * * *  cd /opt/stable-ops && bin/gitnexus-doctor.sh /repos/main-app main-app >> /var/log/gitnexus-doctor.log

Features

| Script | Purpose | |--------|---------| | bin/gni | Production CLI wrapper — readable output, cypher stderr capture, impact fallback | | bin/gitnexus-doctor.sh | Diagnose version drift, index health, MCP config, embedding status | | bin/gitnexus-smoke-test.sh | End-to-end health check (analyze → status → list → context → cypher → impact) | | bin/gitnexus-safe-impact.sh | Impact analysis with automatic context-based fallback on failure | | bin/gitnexus-auto-reindex.sh | Smart single-repo reindex (stale detection + embedding protection + dirty skip) | | bin/gitnexus-reindex.sh | Batch reindex recently changed repos (cron-friendly) | | bin/gitnexus-reindex-all.sh | Reindex all registered repos with safety defaults | | bin/graph-meta-update.sh | Generate cross-community edge JSONL for graph visualization | | bin/gitnexus-install-hooks.sh | Install git hooks for auto-reindex on commit/merge |

Edge Cases & Lessons Learned

After 3 months of production use, here are the edge cases we've encountered and solved:

1. LadybugDB concurrent query lock errors (arm64 macOS)

Problem: Running multiple impact queries simultaneously crashes or returns lock errors from LadybugDB.

Root cause: LadybugDB connections can serialize to a BUSY/lock error under concurrent access from the Node.js async event loop.

Status: ✅ Fixed upstream in PR #425 (merged 2026-03-22) — withLbugDb now retries on BUSY/lock errors with exponential backoff.

Our mitigation (still valuable for older versions): gitnexus-safe-impact.sh catches the error and returns context-based fallback JSON. Upgrade to gitnexus@1.4.7+ to get the upstream fix.

2. Embedding silent deletion

Problem: gitnexus analyze --force rebuilds the index but drops embeddings if --embeddings is not explicitly passed.

Our fix: gitnexus-auto-reindex.sh checks meta.json for existing embedding data. If found, --embeddings is added automatically. Zero embedding loss since deployment.

Gitnexus Stable Ops

Install / Use

README