gitnexus-cgc-combo 0.1.0

Code Intelligence Bootstrap Kit — agent-provisioned GitNexus + CodeGraphContext for AI coding agents

Code Intelligence Bootstrap Kit

One sentence, give your AI coding agent superpowers. Drop this kit into any project, say "/combo-setup", and your agent self-provisions GitNexus + CodeGraphContext — dual knowledge graphs that give it impact analysis, concept search, dead code detection, safe rename, execution tracing, and visual graphs. The agent enforces impact-analysis-before-edit discipline forever after.

What It Does

Gives your AI coding agent a dual knowledge graph of your codebase — two complementary code intelligence engines working together. Instead of grepping blindly through files, your agent can:

• Run impact analysis before every edit ("if I change this function, what breaks?")
• Find code by meaning, not by keyword matching
• Detect dead code automatically
• Safely rename symbols across the entire codebase (understands the call graph, so it never misses a reference)
• Trace full execution flows step-by-step for debugging
• Check change scope before commits (maps git diffs back to affected symbols)
• Query the codebase with Cypher (same graph query language used by Neo4j)
• Visualize module dependencies as an interactive graph

Supports 10 AI coding platforms out of the box: Kilo, Claude Code, Cursor, Cline, Roo Code, Continue.dev, Opencode, GitHub Copilot, Windsurf, and Augment Code.

Quick Start

You never run a command yourself. Just open this project in your AI coding tool and ask:

/combo-setup or "Set up code intelligence"

The agent detects your platform, checks your environment, installs both tools, generates platform-correct MCP configs, indexes your codebase, and writes permanent behavioral rules that make it use these tools forever after.

Option A: GitHub Template

1. Click "Use this template" → "Create a new repository"
2. Open your new repo in your AI coding tool
3. Say: /combo-setup

Option B: Manual Clone

git clone https://github.com/Im-Busy/gitnexus-cgc-combo.git
cd gitnexus-cgc-combo
rm -rf .git && git init && git add -A && git commit -m "Initial: Code Intelligence Bootstrap Kit"

Open in your AI coding tool and say /combo-setup.

What Gets Provisioned

Layer	What	How
GitNexus	Impact analysis, safe rename, execution flows, change detection, semantic search (BM25+vectors), Cypher queries, 7 MCP tools	npx gitnexus@latest (auto-fetched from npm, no install)
CodeGraphContext	Code search (name/content/regex), dead code detection, class hierarchy analysis, import analysis, complexity analysis, visual graph, Cypher queries, 21 MCP tools	uv pip install codegraphcontext
MCP Configs	Both tools registered as MCP servers in the correct format for your platform	Auto-generated, merged into existing configs (never overwrites)
Agent Protocol	AGENTS.md with Always/Never rules — impact-analysis-before-edit, change-check-before-commit, concept-search-instead-of-grep	Injected idempotently into your project
Skills	8 operational skills (6 GitNexus + 1 CGC + 1 combo workflow)	Copied to .kilo/skills/ or .claude/skills/
File Watcher	CGC live watcher auto-updates the graph on file changes	Background process (systemd / launchd / PowerShell)

What Each Tool Can Do — Individual Strengths & Limits

GitNexus — Strengths

Capability	How
Impact analysis	Given a function/class/method, reports every caller, every execution flow it participates in, and a risk level (LOW/MEDIUM/HIGH/CRITICAL). Answers "what will break if I change this?"
Safe rename	Graph-assisted multi-file rename — finds all references through the call graph, not text matching. Dry-run mode shows you what will change before anything happens.
Change detection	Maps git diff output to affected symbols. Before committing, tells you exactly which functions and execution flows your changes touched.
Concept search	Hybrid BM25 + vector embedding search. Ask "how does auth middleware work?" and get ranked results grouped by execution flow, not just file matches.
Symbol context	360-degree view of any symbol — all callers, all callees, all execution flows it participates in.
Execution flows	Maps your entire codebase as business-process flows. Follow a request from entry point through every function call to the response.

GitNexus — Limitations

• Class hierarchy analysis — Not its strength. Use CGC's analyze inheritance instead.
• Import analysis — "Who imports this module?" is better answered by CGC.
• Dead code detection — CGC has a dedicated find_dead_code tool. GitNexus can infer unused code from impact analysis but it's not a first-class feature.
• Fuzzy code search — GitNexus excels at semantic/concept search, but exact name or regex matching is CGC's territory.
• Visual graph — GitNexus has a web UI graph explorer, but CGC's 2D/3D force graph visualization is richer for module-dependency views.

CodeGraphContext (CGC) — Strengths

Capability	How
Code search	Three modes: search by exact name, by regex pattern, or by fuzzy content. Finds functions, classes, variables across 20+ languages.
Dead code detection	Dedicated tool that finds unreferenced functions, classes, and variables.
Class hierarchy	Analyzes inheritance chains. "What inherits from BaseModel?" — CGC answers directly.
Import analysis	"Who imports this module?" and "What does this module import?" — both directions.
Complexity analysis	Identifies complexity hotspots — functions with high cyclomatic complexity, deep nesting, or large parameter counts.
Visual graph	Built-in viz server with 2D/3D force graphs. See your module dependency structure as an interactive graph.
Cypher queries	Read-only Cypher execution. Write arbitrary graph queries if the built-in tools don't cover your exact need.
Registry bundles	Search and load shared code-intelligence bundles.

CGC — Limitations

• Impact analysis — CGC's analyze_code_relationships can show callers/callees, but it does not report risk levels, execution-flow grouping, or business-process impact. Use GitNexus impact for "what breaks?"
• Safe rename — CGC has no rename tool. You'd need to manually Cypher-query + find. Use GitNexus rename instead.
• Change detection — CGC has no git-diff-to-symbol mapping. Use GitNexus detect_changes before committing.
• Semantic/concept search — CGC's fuzzy search is keyword-based. GitNexus's hybrid BM25+vector search is better for "find me the auth logic" type queries.
• Execution flows — CGC builds a structural graph (files, classes, functions, calls). GitNexus additionally maps business-process execution flows through those structures.

Combined Power — What They Do Together

The two tools are intentionally complementary — one covers the other's gaps. Together they form defense-in-depth code intelligence:

Situation	Use
"What breaks if I change this function?"	GitNexus impact — blast radius + risk level
"What files changed and which symbols are affected?"	GitNexus detect_changes
"Rename foo() to bar() everywhere"	GitNexus rename (with dry_run first)
"Find everywhere authentication logic lives"	GitNexus query — semantic concept search
"Show me everything about handleRequest"	GitNexus context — 360-degree symbol view
"What inherits from BaseController?"	CGC analyze inheritance
"Who imports the utils module?"	CGC analyze imports
"Find all functions named validate*"	CGC find name or find pattern
"Are there any unused functions?"	CGC analyze dead-code
"Show me a visual graph of module dependencies"	CGC visualize
"Write a custom Cypher query"	Either — both support Cypher
"Trace how a login request flows through the system"	GitNexus process resources — step-by-step execution flow
"Show all callers of processPayment"	Either — GitNexus context or CGC analyze_code_relationships

Mindset shift: you stop grepping and start querying. Instead of rg "auth" --include="*.py", you ask gitnexus_query({query: "authentication middleware"}) and get results grouped by execution flow with relevance ranking.

How It Works — Step by Step

When you say /combo-setup, the agent runs 8 phases automatically. Here is what happens under the hood:

Phase 0: Platform Self-Identification

The agent checks its own system prompt, environment variables, and filesystem markers to determine which AI coding platform it is running under. It supports 10 platforms with a declarative detection system — each platform has a set of filesystem markers (e.g., .kilo/ + kilo.json for Kilo, .mcp.json + CLAUDE.md for Claude Code).

Phase 1: Environment Detection

Checks your OS, shell, Node.js version, Python version, uv, and git. Reports any missing prerequisites and guides installation. If Python is missing, uv python install 3.13 auto-handles it.

Phase 2: Install Tools

• GitNexus — No install. npx gitnexus@latest auto-fetches from npm. Run npx gitnexus --version to verify.
• CodeGraphContext — uv sync installs from pyproject.toml dependencies, or uv pip install codegraphcontext for global install.

Phase 3: Generate MCP Configs

Runs config_gen.py which reads platforms/matrix.json — a declarative registry of all 10 supported platforms — and generates the correct MCP server JSON for each detected platform. Three format families are handled automatically: mcpServers (7 platforms like Cursor, Windsurf), mcp (Kilo, Opencode), and servers (GitHub Copilot VS Code). Generated configs are merged into existing config files — your other MCP servers are preserved untouched. Idempotent: re-running returns [SKIP].

Phase 4: Index Your Project

• npx gitnexus analyze --embeddings --skills builds the GitNexus knowledge graph with embeddings for semantic search and skill files for agent guidance.
• uv run cgc index <your_project> builds the CGC structural graph database (files, functions, classes, calls, imports, inheritance).

Phase 5: Start CGC Live Watcher

Starts a background process that monitors src/ for file changes and auto-updates the CGC graph. Platform-specific: systemd user service on Linux, launchd plist on macOS, PowerShell background process on Windows. Survives terminal close and auto-restarts on failure.

Phase 6: Write Agent Protocol Sections

Extracts the GitNexus + CGC behavioral protocol template from this repo's AGENTS.md, substitutes actual index stats (symbol count, relationship count, execution flow count), and idempotently injects it into your project's AGENTS.md using <!-- gitnexus:start --> / <!-- gitnexus:end --> markers. Writes short meta-directives into platform-specific instruction files (CLAUDE.md, .cursorrules, .clinerules, etc.) pointing the agent to AGENTS.md.

Phase 7: Copy Operational Skills

Copies 8 skill files to your project. For Kilo: .kilo/skills/; for Claude Code: .claude/skills/. Skills cover: exploring architecture, impact analysis, debugging, refactoring, CLI operations, tool reference (GitNexus), CGC graph queries, and unified combo workflow. Other platforms get behavioral rules embedded in AGENTS.md instead.

Phase 8: Verification

Runs a full health check: GitNexus index freshness, CGC index stats, watcher process status, tool versions, and MCP connectivity. Reports a summary of what passed and what needs attention.

Multi-Platform Support

The bootstrap kit auto-detects your AI coding platform and generates the correct MCP config format. Each platform has a different config schema, file location, and merge strategy — all handled automatically:

Platform	MCP Family	Config File	Skills	Detection Markers
Kilo	mcp	.kilo/kilo.json	Yes	.kilo/, kilo.json
Claude Code	mcpServers	.mcp.json	Yes	.mcp.json, CLAUDE.md
Cursor	mcpServers	.cursor/mcp.json	—	.cursor/, .cursorrules
Cline	mcpServers	.cline/mcp.json	—	.cline/, .clinerules
Roo Code	mcpServers	.roo/mcp.json	—	.roo/, .roorules
Continue.dev	mcpServers	.continue/mcpServers/gitnexus-cgc.json	—	.continue/, config.yaml
Opencode	mcp	opencode.json	—	opencode.json, .opencode/
Copilot (VS Code)	servers	.vscode/mcp.json	—	.vscode/mcp.json
Windsurf	mcpServers	Manual paste (global)	—	.windsurf/, .windsurfrules
Augment Code	mcpServers	Manual paste (global)	—	.augment/

MCP configs use merge-into-existing strategy (7 platforms), create-standalone-file (Continue.dev), or print-for-manual-paste (Windsurf, Augment — both lack project-level MCP support). Existing MCP servers are never touched.

Architecture & Technical Implementation

How the Bootstrap System Works

This project is an agent-native provisioning system — the product is the protocol, not the executables. The AI agent reads AGENTS.md as its instruction manual and executes all 8 phases autonomously. The user never runs a command.

gitnexus_CGC_combo/
├── AGENTS.md                 # The program — 8-phase bootstrap protocol for the agent
├── README.md                 # Human-facing overview (this file)
├── pyproject.toml            # Single entry point: combo-setup
├── platforms/
│   └── matrix.json           # Declarative platform registry (10 platforms, 3 MCP families)
├── src/
│   └── config_gen.py         # MCP config engine + setup orchestrator (~300 LOC)
├── tests/
│   └── test_config_gen.py    # Config generation tests
├── .kilo/
│   ├── kilo.json             # This project's own MCP config
│   ├── global-rules.md       # Agent behavioral standards
│   ├── project-rules.md      # Combo-specific rules
│   ├── agent/                # 3 agent definitions (combo-setup, combo-diagnose, combo-uninstall)
│   ├── command/              # 3 slash command manifests
│   └── skills/               # 8 operational skills (6 GitNexus + 1 CGC + 1 combo workflow)
└── docs/
    ├── DESIGN_RATIONALE.md   # Design decisions and rationale
    ├── SETUP_GUIDE.md        # User-facing setup walkthrough
    ├── TOOL_REFERENCE.md     # Complete tool-by-tool reference
    └── MCP_CONFIGS.md        # MCP config format reference (all 3 families)

Core Design: Platform Matrix

At the heart of the config generation system is platforms/matrix.json — a declarative JSON registry that maps each AI coding platform to its MCP config format, file path, detection markers, and capabilities. Instead of hardcoding platform-specific logic, config_gen.py reads this matrix and generates the correct JSON for any platform. Adding a new platform requires only a new entry in the matrix — no code changes needed.

Three MCP format families are supported:

Family	Top-Level Key	Server Type	Platforms
mcpServers	"mcpServers"	command + args + cwd	7 (Claude Code, Cursor, Cline, Roo Code, Continue.dev, Windsurf, Augment)
mcp	"mcp"	"type": "local", command array + workdir	2 (Kilo, Opencode)
servers	"servers"	"type": "stdio", command + args + cwd	1 (GitHub Copilot VS Code)

Each family has subtly different JSON structure, key names, and semantics. The matrix handles all three.

Merge Strategy

Config generation never overwrites. When a config file already exists:

1. Parses existing JSON
2. Adds only gitnexus and codegraphcontext entries
3. Preserves all user's other MCP servers untouched
4. Re-running returns [SKIP] — fully idempotent

If the existing JSON is corrupted, --force backs it up as .bak and writes fresh.

Two-Path Architecture

The single engine (config_gen.py + platforms/matrix.json) serves two paths:

• Agent Path: The AI agent reads AGENTS.md and executes phases directly — runs bash for commands, uses read/edit for file operations, uses glob for file copying. No scripts needed.
• Manual Path: Users who don't use AI coding tools run uvx gitnexus-cgc-combo setup ./ — a single command that generates MCP configs, indexes both tools, and prints a summary.

Agent-Executed Operations

All non-config phases are performed by the agent directly — no scripts:

• Environment detection — node --version, python --version, etc. via bash
• Template injection — Agent reads AGENTS.md template, substitutes variables, uses edit to inject into target project
• Skill copying — Agent enumerates .kilo/skills/ directories and copies to target
• Verification — Agent runs npx gitnexus status, uv run cgc stats, and pgrep/Get-Process for watcher checks
• Uninstall — Agent performs inverse of setup operations (delete JSON keys, delete file sections, stop processes)
• Watcher management — Agent starts uv run cgc watch as background process (systemd/launchd/PowerShell documented in AGENTS.md Phase 5)

Design Principles

Principle	Implementation
Agent-native	The protocol IS the product. The agent reads AGENTS.md and provisions everything autonomously. Scripts exist only where agents are weak (structured JSON generation).
Merge, don't replace	MCP configs are merged into existing files. User's other servers are preserved. AGENTS.md sections use marker fences for safe injection.
Detect, don't assume	Platform auto-detection via filesystem markers. Environment auto-detection via command probing. No guessing.
Idempotent everywhere	<!-- gitnexus:start --> markers prevent duplicate injection. config_gen.py returns [SKIP] on re-run. All phases are safe to re-run.
Least intrusive	Only writes configs for detected platforms. Meta-directives in platform files are 1-3 lines. Skill files go in dedicated directories.
Cross-platform from the ground up	Python pathlib handles Windows/Unix paths. Matrix handles 3 MCP format families. Watcher instructions cover systemd, launchd, and PowerShell.
Two paths, one engine	Agent reads AGENTS.md (the protocol). Manual users run uvx combo-setup setup . (the CLI). Both use config_gen.py for MCP config generation.

Prerequisites

Prerequisite	Required	Auto-Installed
Node.js >= 18	Yes	No (agent guides you)
Python >= 3.10	Yes	Yes — uv python install 3.13
uv	Yes	Yes — pip install uv or curl installer
Git	Yes	No (agent guides you)
Internet (first run)	Yes	—

The setup agent auto-detects missing prerequisites and guides installation step-by-step. uv-managed Python is fully supported — no system Python needed.

After Setup — What Your Agent Does Forever

Once provisioned, your AI agent follows these rules permanently (enforced by the protocol injected into AGENTS.md):

When	What Happens
Before editing any function/class/method	Runs gitnexus_impact() — shows blast radius (direct callers, affected processes) and risk level. Warns you if HIGH or CRITICAL risk.
Before committing	Runs gitnexus_detect_changes() — maps git diff to affected symbols and execution flows. Verifies changes only affect expected scope.
Exploring unfamiliar code	Uses gitnexus_query() or cgc find instead of grep. Concept-based search returns results grouped by execution flow, ranked by relevance.
Renaming a symbol	Uses gitnexus_rename() instead of find-and-replace. Graph-assisted — finds all references through the call graph, not text matching.
Tracing a bug	Uses gitnexus process resources to follow execution flows step-by-step.
Finding dead code	Uses cgc analyze dead-code to find unreferenced symbols.
Understanding class hierarchy	Uses cgc analyze inheritance to map inheritance chains.
Custom graph queries	Uses cypher (either tool) for arbitrary graph pattern matching.

Slash Commands

Command	Purpose
/combo-setup	Full provisioning: platform detection → environment check → install → MCP config → index → watcher → AGENTS.md injection → verification
/combo-diagnose	Health check: index freshness, watcher process status, MCP tool connectivity, tool versions
/combo-uninstall	Remove everything: MCP entries, AGENTS.md sections, skill files, indexes, platform directives, stop watcher. Dry-run supported.

License

MIT