{"id":"2fdfb220-1ee4-4442-b51c-5f39c896f8d9","slug":"gitnexus-stable-ops","kind":"mcp","name":"gitnexus-stable-ops","summary":"Production toolkit for running GitNexus at scale — 26 repos, 43K symbols, 100K edges, zero data loss. Docker, cron, AI agent integration. Featured in GitNexus Community Integrations.","owner":"ShunsukeHayashi","repoUrl":"https://github.com/ShunsukeHayashi/gitnexus-stable-ops","license":"MIT","licenseTier":"permissive","trust":"community","stars":8,"match":null,"fewStars":false,"format":"mcp","createdAt":"2026-03-17T23:35:17.000Z","addedAt":"2026-10-21T04:19:53.582Z","logoUrl":"https://avatars.githubusercontent.com/u/11504206?u=bfa0a3e95a7594c1d2359bb8cd29e58ed05d53c2&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra","developer-tools","memory-knowledge"],"tags":["code-intelligence","developer-tools","knowledge-graph","gitnexus","claude-code","codebase-understanding","context-engineering","dependency-graph"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-25T22:53:16.976Z","sample":false,"url":"https://conduits.dev/tools/gitnexus-stable-ops","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# gitnexus-stable-ops\n\n**Give AI Agents a 360° View of Your Codebase.**\n\nStop Copilot and Claude Code from breaking callers they don't know about.\n`gitnexus-stable-ops` is a production ops toolkit that keeps [GitNexus](https://github.com/abhigyanpatwari/GitNexus) running reliably across 25+ repositories — zero embedding loss, zero version drift, zero dirty-graph surprises.\n\n[![CI](https://github.com/ShunsukeHayashi/gitnexus-stable-ops/actions/workflows/ci.yml/badge.svg)](https://github.com/ShunsukeHayashi/gitnexus-stable-ops/actions/workflows/ci.yml)\n[![Stars](https://img.shields.io/github/stars/ShunsukeHayashi/gitnexus-stable-ops?style=social)](https://github.com/ShunsukeHayashi/gitnexus-stable-ops)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Featured in GitNexus](https://img.shields.io/badge/GitNexus-Community%20Integration-blue?logo=github)](https://github.com/abhigyanpatwari/GitNexus#community-integrations)\n\n> *\"designed for autonomous agent swarms\"*\n> — [@d3thshot7777](https://github.com/abhigyanpatwari/GitNexus), GitNexus maintainer\n\n**Powering 39+ OpenClaw Agents · 14 upstream PRs → 7 merged · 3+ months production**\n\n[English](./README.md) | [中文](./README_zh.md) | [日本語](./README_ja.md)\n\n---\n\n## Quick Start\n\n```bash\ngit clone https://github.com/ShunsukeHayashi/gitnexus-stable-ops.git\ncd gitnexus-stable-ops && make install\n\n# Diagnose a repo\nbin/gitnexus-doctor.sh ~/dev/my-repo my-repo MyClassName\n\n# Smart reindex (skips if up-to-date, protects embeddings)\nREPO_PATH=~/dev/my-repo bin/gitnexus-auto-reindex.sh\n\n# See what breaks if you change a class\ngni impact AuthService\n```\n\n```\n✅ Direct callers (d=1):  UserController.login, SessionManager.refresh\n⚠️  Transitive deps (d=2): 14 files affected\n🔴 Risk: HIGH — update callers before merging\n```\n\n---\n\n## Why This Exists\n\nGitNexus 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:\n\n| Problem | Impact | This toolkit's fix |\n|---------|--------|--------------------|\n| **Version drift** | CLI and MCP reference different versions, causing data corruption | Pinned binary (`$GITNEXUS_BIN`) used by all scripts |\n| **Embedding loss** | `analyze --force` silently deletes embeddings | Auto-detect existing embeddings, add `--embeddings` flag automatically |\n| **Dirty worktree** | Reindexing uncommitted work pollutes the code graph | Skip dirty repos by default (`ALLOW_DIRTY_REINDEX=0`) |\n| **Impact instability** | `impact` crashes on arm64 macOS with concurrent queries | Graceful fallback to context-based analysis |\n\n**We discovered and solved these problems running GitNexus on 25+ repos for 3+ months.**\n\n---\n\n## Production Stats\n\n| Metric | Value |\n|--------|-------|\n| Repositories indexed | **25+** |\n| Symbols in knowledge graph | **32,000+** |\n| Edges (relationships) | **73,000+** |\n| AI agents using the graph | **40** (OpenClaw MAS) |\n| Embedding loss incidents | **0** since v1.0 |\n| Upstream PRs merged to GitNexus | **7 of 14** submitted |\n| Production uptime | **3+ months** |\n\n---\n\n## How AI Agents Use This\n\n```\nAgent receives task: \"Fix auth bug in service-api\"\n    |\n    +-- 1. gni impact AuthService   --> What breaks if we change it?\n    +-- 2. gni context AuthService  --> Get callers, callees, dependencies\n    +-- 3. Agent writes code fix\n    +-- 4. auto-reindex.sh          --> Graph stays current (post-commit hook)\n```\n\n**Key insight**: When AI agents share a code knowledge graph, they avoid breaking callers they don't know about. `gni impact` is the difference between a safe refactor and a 2 AM incident.\n\n```yaml\n# Example: OpenClaw 39-agent system\nsteps:\n  - agent: dev-architect\n    action: gni impact TargetClass --direction upstream\n    purpose: Blast radius before code change\n\n  - agent: dev-coder\n    action: gni context TargetClass\n    purpose: Understand dependencies before writing fix\n\n  - trigger: post-commit hook\n    action: gitnexus-auto-reindex.sh\n    purpose: Graph stays current for the next agent\n```\n\n---\n\n## Features\n\n| Script | Purpose |\n|--------|---------|\n| `bin/gni` | Production CLI wrapper — readable output, cypher stderr capture, impact fallback |\n| `bin/gitnexus-doctor.sh` | Diagnose version drift, index health, MCP config, embedding status |\n| `bin/gitnexus-smoke-test.sh` | End-to-end health check (analyze → status → list → context → cypher → impact) |\n| `bin/gitnexus-safe-impact.sh` | Impact analysis with automatic context-based fallback on failure |\n| `bin/gitnexus-auto-reindex.sh` | Smart single-repo reindex (stale detection + embedding protection + dirty skip) |\n| `bin/gitnexus-reindex.sh` | Batch reindex recently changed repos (cron-friendly) |\n| `bin/gitnexus-reindex-all.sh` | Reindex all registered repos with safety defaults |\n| `bin/gitnexus-install-hooks.sh` | Install git hooks for auto-reindex on commit/merge |\n\n---\n\n## Safety Defaults\n\n| Feature | Default | Override |\n|---------|---------|----------|\n| Embedding protection | Auto-detect and preserve | Always on |\n| Dirty worktree skip | Skip dirty repos | `ALLOW_DIRTY_REINDEX=1` |\n| Impact fallback | Context-based JSON on failure | Always on |\n| Version pinning | `$GITNEXUS_BIN` | Set env var |\n\n## Environment Variables\n\n| Variable | Default | Purpose |\n|----------|---------|---------|\n| `GITNEXUS_BIN` | `~/.local/bin/gitnexus-stable` | Pinned GitNexus CLI path |\n| `REGISTRY_PATH` | `~/.gitnexus/registry.json` | Indexed repo registry |\n| `ALLOW_DIRTY_REINDEX` | `0` | Allow reindexing dirty worktrees |\n| `REPOS_DIR` | `~/dev` | Root directory for batch reindex |\n| `LOOKBACK_HOURS` | `24` | How far back to check for changes |\n\n---\n\n## Edge Cases & Lessons Learned\n\nAfter 3 months of production use:\n\n| Edge case | Status | Notes |\n|-----------|--------|-------|\n| LadybugDB concurrent query lock errors | ✅ Fixed upstream [PR #425](https://github.com/abhigyanpatwari/GitNexus/pull/425) + local fallback | Use `gitnexus-safe-impact.sh` for older versions |\n| Embedding silent deletion on `--force` | ✅ Zero incidents since v1.0 | Auto-detects `meta.json`, adds `--embeddings` |\n| Version drift between CLI and MCP | ✅ Pinned binary | All scripts use `$GITNEXUS_BIN` |\n| Dirty worktree graph pollution | ✅ Skipped by default | Override: `ALLOW_DIRTY_REINDEX=1` |\n| Large monorepo heap exhaustion | ✅ Detected and logged clearly | Set `NODE_OPTIONS=--max-old-space-size=8192` |\n\n---\n\n<details>\n<summary>&#9654; Agent Context Graph (v1.3.0) — Index agents, skills, and cluster topology</summary>\n\nBeyond code symbols, gitnexus-stable-ops indexes **agent-level entities** from your workspace — giving LLMs a live map of *who can do what and where*.\n\n### What it indexes\n\n| Entity | Source | Description |\n|--------|--------|-------------|\n| `Agent` | `KNOWLEDGE/AGENTS_*.md` frontmatter | Named agents with roles, pane IDs, society membership |\n| `Skill` | `SKILL/**/*.md` | Skills with priority, keywords, script paths |\n| `KnowledgeDoc` | `KNOWLEDGE/**/*.md` | Reference docs and context files |\n| `MemoryDoc` | `MEMORY/**/*.md` | Session memories and daily logs |\n| `ComputeNode` | `workspace.json nodes[]` | Physical/virtual machines in your cluster |\n| `WorkspaceService` | `workspace.json services[]` | Deployed agents/services with model info |\n\n### Progressive Disclosure\n\n| Level | Tokens | Use case |\n|-------|--------|----------|\n| `--level 1` | ~100 | LLM system prompt overview |\n| `--level 2` | ~400 | Default context injection |\n| `--level 3` | ~2000 | Deep dive with full edges |\n\n```bash\n# Build the agent graph\ngni agent-index ~/dev/MY_WORKSPACE --force\n\n# Query at different detail levels\ngni aq \"deploy agent\"   --level 1\ngni aq \"cc-hayashi\"     --level 2\ngni aq \"announce skill\" --level 3\n\n# Auto-generate CLAUDE.md / AGENTS.md\ngni cg . --update\n```\n\nFor the full guide, see [docs/agent-context-graph.md](./docs/agent-context-graph.md).\n\n</details>\n\n---\n\n<details>\n<summary>&#9654; Production Deployment — Docker and cron setup</summary>\n\n### Docker\n\n```dockerfile\nFROM node:22-slim\nRUN npm install -g gitnexus@1.4.6\nRUN git clone https://github.com/ShunsukeHayashi/gitnexus-stable-ops.git /opt/stable-ops \\\n    && cd /opt/stable-ops && make install\nRUN ln -sf $(which gitnexus) /usr/local/bin/gitnexus-stable\nENV GITNEXUS_BIN=/usr/local/bin/gitnexus-stable\nENV REPOS_DIR=/repos\nCOPY crontab /etc/cron.d/gitnexus\nCMD [\"cron\", \"-f\"]\n```\n\n### Cron schedule\n\n```cron\n# Smart reindex: only repos changed in last 24h\n0 3 * * *  REPOS_DIR=/repos bin/gitnexus-reindex.sh >> /var/log/gitnexus-reindex.log\n# Weekly full reindex (Sunday 4 AM)\n0 4 * * 0  bin/gitnexus-reindex-all.sh >> /var/log/gitnexus-full-reindex.log\n# Health check (daily)\n30 9 * * * bin/gitnexus-doctor.sh /repos/main-app main-app >> /var/log/gitnexus-doctor.log\n```\n\nFor the full CI/CD guide, see [docs/ci-cd-integration.md](./docs/ci-cd-integration.md).\n\n</details>\n\n---\n\n## Upstream Contributions\n\n| PR | Title | Status |\n|----|-------|--------|\n| [#441](https://github.com/abhigyanpatwari/GitNexus/pull/441) | Add `confidence` constant for similarity threshold | ✅ Merged |\n| [#451](https://github.com/abhigyanpatwari/GitNexus/pull/451) | Persist chat history across sessions | ✅ Merged |\n| [#453](https://github.com/abhigyanpatwari/GitNexus/pull/453) | Add structured debug logger | ✅ Merged |\n| [#454](https://github.com/abhigyanpatwari/GitNexus/pull/454) | `detect_changes` — classify by change type | ✅ Merged |\n| [#425](https://github.com/abhigyanpatwari/GitNexus/pull/425) | Fix LadybugDB concurrent lock errors with exponential backoff | ✅ Merged |\n| [#455](https://github.com/abhigyanpatwari/GitNexus/pull/455) | Align `QueryResult` types with LadybugDB WASM API | 🔄 Review |\n| [#458](https://github.com/abhigyanpatwari/GitNexus/pull/458) | Expose per-repo resources in `resources/list` (fix MCP discovery) | 🔄 Review |\n| [#443](https://github.com/abhigyanpatwari/GitNexus/pull/443) | Add `maxIterations` to prevent runaway agent loops | 🔄 Review |\n| _(+6 more)_ | Error handling, performance, CI stability | 🔄 Review |\n\n---\n\n## Compatibility\n\n| Platform | Status |\n|----------|--------|\n| macOS (Apple Silicon) | ✅ Primary development platform |\n| Linux (Ubuntu, Debian, Fedora) | ✅ Tested |\n| Docker | ✅ See deployment section above |\n| Windows | ⚠️ Use WSL or Git Bash |\n\nRequires: Bash 4.0+ · Git 2.0+ · jq 1.6+ · Python 3.6+ · Node.js 20+\n\n---\n\n## Documentation\n\n- [Agent Context Graph Guide](docs/agent-context-graph_en.md) — Setup, commands, LLM injection, FAQ\n- [Runbook](docs/runbook.md) — Step-by-step operational procedures\n- [Architecture](docs/architecture.md) — Design principles and data flow\n- [MCP Integration](docs/mcp-integration.md) — MCP server configuration\n- [CI/CD Integration](docs/ci-cd-integration.md) — GitHub Actions, GitLab, impact analysis in PRs\n- [Enterprise FAQ](docs/enterprise-faq.md) — Docker, K8s, security, SLA\n\n## Contributing\n\nContributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).\n\nAll contributions must include tests, follow [Conventional Commits](https://www.conventionalcommits.org/), and pass `make test`.\n\n---\n\n## Enterprise\n\nRunning GitNexus at scale in a regulated environment? Miyabi G.K. offers architecture review, custom CI/CD integration, and priority issue resolution.\n\n📧 [shunsuke.hayashi@miyabi-ai.jp](mailto:shunsuke.hayashi@miyabi-ai.jp)\n🐦 [@The_AGI_WAY](https://x.com/The_AGI_WAY)\n\n---\n\n## License\n\n**This toolkit: MIT** — covers wrapper scripts, tooling, and documentation only.\n\n[GitNexus](https://github.com/abhigyanpatwari/GitNexus) itself is licensed under [PolyForm NonCommercial 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0/). This toolkit calls the GitNexus CLI but does not include or redistribute any GitNexus source code. For commercial use, verify GitNexus licensing independently.\n\n---\n\n**Built by [Miyabi G.K.](https://miyabi-ai.jp)**\n\n🐦 [@The_AGI_WAY](https://x.com/The_AGI_WAY) · 📧 shunsuke.hayashi@miyabi-ai.jp\n\n<sub>Active contributor to [GitNexus](https://github.com/abhigyanpatwari/GitNexus) — 14 PRs submitted, 7 merged.</sub>\n"}