Norn

Why Norn

Language servers built on a compiler, such as clangd, need to know exactly how every file is compiled. A great deal of real C cannot tell them: firmware built with a proprietary toolchain, SDKs with a header per chip, vendor trees that only build on one machine, code too large or too old to have a working compilation database. Text indexers such as ctags and cscope work anywhere, but they find names, not calls, and they cannot tell which #if branch is compiled.

Norn reads the sources the way a person would, and the build's own description where there is one:

• No setup. Open a folder. Norn finds the build's configuration in Arm DS-5, Keil, IAR, Visual Studio, CMake, Makefile, PlatformIO, Kconfig or compile_commands.json files and works out which #if branches are compiled.
• Calls, not just names. It follows calls through macros and through function pointers stored in structs, and says how each call comes about.
• Fast enough to forget about. The whole Linux kernel indexes in about a minute on a desktop PC; saving a file updates the index in milliseconds.
• Checked against the compiler. Measured call by call against clang's own view of real builds of public projects (see Benchmarks).
• Private. Everything runs on your machine. No network, no telemetry.

	Norn	clangd	ctags / cscope / GNU Global
Works without a compilation database	✅	⚠️ less accurate	✅
Knows which #if branches the build compiles	✅	✅ with a database	❌
Call graph (callers and callees)	✅	✅	⚠️ cscope, by name
Calls through function pointers	✅	❌	❌
Calls generated by macros	✅	✅ with a database	❌
Index updated as you save	✅	✅	❌ re-run
Source Insight-style views (Relation, Context)	✅	❌	❌

Benchmarks

Measured on public projects against clang's own view of a real build of each. Each tool's cold index of the whole project is timed, and every call it reports is checked against the call clang compiles. clangd is measured twice: given each build's own compilation database (clangd at its best, the reference for an index that is told exactly how every file is compiled) and given none, as a project without a working compile_commands.json leaves it. Norn is given nothing. ctags, cscope and GNU Global index fastest because they record names and places, not a call graph.

Project	Language	Files	Norn	clangd + build database	clangd	codebase-memory-mcp	cscope	GNU Global	Universal Ctags
Redis	C	801	100.0%0.33 s	100.0%2.71 s	95.8%15 s	97.1%15 s	96.9%0.28 s	n/a0.20 s	n/a0.18 s
git	C	919	99.9%0.26 s	99.9%2.42 s	64.2%34 s	85.9%12 s	87.9%0.28 s	n/a0.21 s	n/a0.17 s
binutils	C	1,622	99.6%2.56 s	92.7%9.65 s	32.3%22 s	81.0%38 s	70.6%1.40 s	n/a0.87 s	n/a1.03 s
STM32F4 HAL	C	253	96.5%0.67 s	95.0%2.82 s	0.0%1.86 s	85.8%10 s	75.7%0.46 s	n/a0.72 s	n/a0.63 s
nrfx	C	535	99.4%0.58 s	100.0%1.12 s	14.1%1.59 s	94.2%8.65 s	12.0%0.31 s	n/a0.41 s	n/a0.36 s
curl	C	1,067	89.6%0.34 s	100.0%1.12 s

Each cell: the share of calls found (checked against clang), and below it the time to index.

clangd on binutils, STM32F4 HAL, nrfx, curl, Mbed TLS, FreeRTOS, lwIP, U-Boot, Linux, LevelDB, Bitcoin Core, Ninja, GoogleTest, Abseil, yaml-cpp, spdlog: given no include paths and no -D, as a project without a compilation database would, most of the code that needs the build's include paths or definitions does not parse for it. With a real build's database it does far better; that is not what is measured here.

How the numbers are made, every figure for every project, and the versions of the tools: docs/benchmarks. Every number there is produced by bench/compare.py; none is typed in. To measure it again from nothing, on EC2 or any Ubuntu 24.04: bench/ec2.

Features

Norn is a complete language server: Go to Definition, Find References, Call Hierarchy, signature help, rename, folding, formatting and quick fixes too. Alongside Microsoft's C/C++ extension it becomes IntelliSense's configuration provider instead of competing with it. The full list is on the extension's page.

Getting started

1. Install Norn — Code Navigation & Symbol Index: from the Visual Studio Marketplace, from Open VSX for VSCodium, Cursor and the other editors that use it, or a .vsix from the releases. From the command line: code --install-extension humphrey0925.norn-c.
2. Open a folder with C sources.

That is all. The server is included for Windows, Linux and macOS, on x64 and Arm64. The user guide covers every view and setting.

Without VS Code, the same indexer is a command of its own, norn, for the terminal, scripts, CI, other editors (as a language server) and AI agents such as Claude Code, Codex, OpenCode and Copilot (as an MCP server, norn mcp; norn setup sets the agents up, Norn for AI agents says how): see the command line.

How it works

sources ─► tree-sitter parse ─► facts per file ─► link ─► call graph (CSR) ─► language server
              ▲                                     ▲
   #if worked out from the build's              calls through macros and
   own configuration and the sources            function pointers resolved

Norn is written in Rust. Each file is parsed once with tree-sitter after its preprocessor conditions are worked out, from the build's configuration and from what the sources themselves define. The facts of each file are cached by content hash, and a folder opened inside or around one already indexed takes those facts for every file it reads the same way; linking them into a call graph takes milliseconds, so saving a file updates the index almost at once. The graph is kept in compressed sparse rows, which answer a callers query in well under a microsecond.

Building from source

Requires Rust (stable) and Node.js 20.

cargo build --release

cd vscode && npm ci && npm run compile

Path
crates/si-core	The index: parsing, preprocessor conditions, linking, the stored graph
crates/si-cli	The norn executable: norn lsp (the language server), norn mcp (for AI agents), norn index, norn query
vscode	The VS Code extension
bench	Accuracy and speed measurements against clang and other indexers

Releases are built and tested on Windows, Linux and macOS by GitHub Actions; see docs/releasing.md.

Contributing

Issues and pull requests are welcome; see CONTRIBUTING.md. Contributions are accepted under the Contributor License Agreement, which the CLA check asks you to sign on your first pull request.

License

Copyright 2026 humphrey0925 and the Norn contributors. Licensed under the Apache License, Version 2.0.

Source Insight is a trademark of Source Dynamics, Inc. Norn is not affiliated with, or endorsed by, Source Dynamics; the name is used only to describe the style of navigation. Other names are trademarks of their owners.