# Clangd Graph RAG

> This skill enables deep semantic and structural analysis of C/C++ codebases using a pre-built Neo4j GraphRAG. It provides insights into call chains, class hierarchies, macro causality, and type aliases. Use when this capability is needed.

- Skill: `tomevault-io/clangd-graph-rag` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/clangd-graph-rag`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/clangd-graph-rag/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/clangd-graph-rag

---

# Skill: clangd-graph-rag

This skill enables deep semantic and structural analysis of C/C++ codebases using a pre-built Neo4j GraphRAG. It provides insights into call chains, class hierarchies, macro causality, and type aliases.

## Activation
Activate this skill when the user asks questions about:
- Project architecture, module responsibilities, or high-level workflows.
- Call chains (caller/callee relationships) or method overriding.
- C++ inheritance structures and template specializations.
- "Magic symbols" generated by macros or complex `typedef`/`using` alias chains.
- Semantic code search (e.g., "Find the logic for packet validation").

## Setup Requirements
- A Neo4j database populated by the `clangd-graph-rag` pipeline.
- The `graph_mcp_server.py` must be configured as an MCP server.
- Environment variables: `NEO4J_URI`, `NEO4J_USER`, `NEO4J_PASSWORD`.

## Core Instructions

### 1. Orientation & Discovery
- **Always start** by calling `get_project_info` and `get_graph_schema`. 
- `get_project_info` provides the `path` (absolute project root) and a high-level `summary`.
- `get_graph_schema` explains the node labels (e.g., `FUNCTION`, `CLASS_STRUCTURE`, `MACRO`, `TYPE_ALIAS`) and relationships.
- **Paths**: All `path` properties in the graph are **relative** to the project root.

### 2. Structural Querying (Cypher)
- Use `execute_cypher_query` for precise structural analysis. 
- **Semantic Labels**: Prefer specific labels (`FUNCTION`, `METHOD`, `CLASS_STRUCTURE`, `MACRO`, `TYPE_ALIAS`) over the generic `ENTITY` label for efficiency.
- **Macros**: Follow `(s)-[:EXPANDED_FROM]->(m:MACRO)` to explain symbols generated by the preprocessor. Check the `original_name` property on the symbol for the raw invocation text.
- **Types**: Follow `(ta:TYPE_ALIAS)-[:ALIAS_OF]->(t)` to resolve alias chains (e.g., `MyInt2` -> `MyInt` -> `int`).
- **Calls**: Use `SHORTEST` path selectors (e.g., `MATCH p = SHORTEST 5 (a:FUNCTION)-[:CALLS*]->(b:FUNCTION)`) to prevent result set explosion.
- **Result Management**: Always use `LIMIT` (e.g., `LIMIT 10`) on custom queries.

### 3. Implementation Retrieval
- **Precise Reading**: Use `get_source_code_by_id`. It retrieves the **exact implementation span** (including template headers and bodies) as seen by the compiler.
- **File Context**: Use `get_source_code_by_path` only when you need to see the entire surrounding file (e.g., checking includes or global variables).
- **Labels**: Use `get_semantic_label` if you are unsure which specific label a node has (besides `ENTITY`).

### 4. Semantic Search
- Use `search_nodes_for_semantic_similarity` for concept-based discovery (e.g., "Where is the error handling for disk I/O?").
- Use the returned `summary` property to understand a node's purpose without reading its code.

## Example Workflow: Resolving a "Magic" Symbol
1. **Find**: `MATCH (n:ENTITY {name: 'SomeMagicName'}) RETURN n.id, n.original_name`.
2. **Trace**: `MATCH (n)-[:EXPANDED_FROM]->(m:MACRO) RETURN m.name, m.macro_definition`.
3. **Analyze**: Read `m.macro_definition` or use `get_source_code_by_id` on the `MACRO` node to see the ground-truth definition.
4. **Context**: Look at `n.original_name` to see the exact arguments passed to the macro at the expansion site.

---
> Source: [2015xli/clangd-graph-rag](https://github.com/2015xli/clangd-graph-rag) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-17 -->