clangd-indexer

name	clangd-indexer
description	Use when clangd code navigation is not working, compile_commands.json is missing or incomplete, or setting up IDE support for any C/C++ embedded SDK project. Triggers include "clangd not working", "can't jump to definition", "code navigation broken", "generate compile_commands.json", or when a user is setting up a new embedded project in VSCode.

Clangd Indexer

Overview

Generate a comprehensive compile_commands.json + .clangd for any C/C++ codebase using CodeGraph's prebuilt index. Zero SDK-specific configuration — works for HPM SDK, STM32 projects, Keil projects, or any directory full of C code.

When to Use

User says clangd isn't working?
├── No compile_commands.json exists → Use this skill
├── compile_commands.json exists but incomplete → Use this skill
├── User is setting up a new project in VSCode → Offer this skill
└── User just wants better code navigation → Offer this skill

Core Pattern

# Step 1 — ensure CodeGraph index exists
codegraph init -i          # one-time, creates .codegraph/codegraph.db

# Step 2 — generate clangd config
python3 gen_compile_commands.py [--compiler <path>] [--defines FOO BAR]

This produces two files at the project root:

• compile_commands.json — one entry per .c file (minimal, clangd-compatible)
• .clangd — all shared -I and -D flags in CompileFlags.Add

Bundled Tool

The skill includes gen_compile_commands.py. If the project doesn't have its own copy, use the bundled one:

python3 ~/.claude/skills/clangd-indexer/gen_compile_commands.py

Quick Reference

Task	Command
First-time setup	codegraph init -i
Generate index	python3 gen_compile_commands.py
With ARM GCC	python3 gen_compile_commands.py --compiler arm-none-eabi-gcc
With defines	python3 gen_compile_commands.py --defines USE_HAL_DRIVER STM32F407xx
Refresh after adding files	python3 gen_compile_commands.py
Check CodeGraph health	codegraph status

How It Works

1. Reads .codegraph/codegraph.db → gets all .c files + all directories containing .h files
2. Writes .clangd at project root with every include path in CompileFlags.Add
3. Writes compile_commands.json with minimal entries (file + directory only — flags come from .clangd)
4. clangd merges the two at runtime

This keeps compile_commands.json small (~3 MB for 7000 files) while giving clangd full visibility of every source file.

Troubleshooting

"codegraph.db not found"

Run codegraph init -i in the project root. If codegraph CLI is missing:

npm install -g @colbymchenry/codegraph

System headers (<stdio.h>) not resolving

Pass the cross-compiler path so clangd can query it for built-in include paths:

python3 gen_compile_commands.py --compiler arm-none-eabi-gcc

Non-GCC compilers (Keil v5 armcc, IAR iccarm): clangd cannot query them. Project-internal headers still resolve fine.

VSCode not picking up the files

Make sure the compile_commands.json is at the project root (where you open VSCode). If VSCode opens a subdirectory, use:

python3 gen_compile_commands.py -o /path/to/project-root/compile_commands.json

After git pull, new files aren't indexed

Re-run the script. It only takes 1-2 seconds.

The Script Is Portable

gen_compile_commands.py has zero hardcoded SDK paths. It discovers everything from CodeGraph's database. Copy it to any project or use the bundled copy — same result.