codegen is a production-grade C++ code generation engine. You annotate C++ declarations directly in source — structs, classes, enums, free functions, aliases — and each rule declares in its YAML which AST node kinds it consumes. You write a LuaU script that receives a structured AST node as JSON and emits whatever you want — C++, TypeScript, Markdown, SQL. The engine handles the rest: parsing, scheduling, deduplication, inline injection, and file routing.
It ships as a single binary. It calls nothing home. It runs the same on every machine.
How codegen is built
Section titled “How codegen is built”codegen separates the problem into two clean layers:
- Analysis — handled by the engine. The full C++ AST is resolved and serialised to JSON (namespaces, template arguments, member variables, enumerators, annotations), and on top of it the engine builds a real semantic model: a symbol database, class hierarchy, dependency graphs, and resolved types.
- Transformation — handled by you, in LuaU. Your rule receives one AST node as JSON and returns output text — and can query the semantic model on demand (resolve a field’s type to its declaring symbol, look up references, walk base classes). The rule has no compiler coupling, no filesystem access, and no network access.
This split is what makes everything below possible.
Core capabilities
Section titled “Core capabilities”Same source ⇒ same output. Always. The engine is a pure function over your AST. Generated files are stable across machines and CI runs, making diffs meaningful and code review tractable.
Most generators emit one output file per input file. codegen does not require this.
A grouping.luau script routes each matched entity to any output path — fan-in
dozens of structs into a single api-reference.md, a registry.cpp, or a sorted
bindings.ts. The topology is yours to define.
Rules emit text. The engine does not care whether that text is C++, TypeScript, Markdown, SQL, or a JSON manifest. One annotated C++ type can drive a serialiser, an FFI binding, a documentation page, and a database migration — all from the same source of truth.
The C++ AST is fully serialised as JSON before any rule sees it. Rules are testable
without a compiler, inspectable with jq, and the full docs are also published as
a single plain-text bundle at /llms-full.txt — drop it into any
LLM agent for codegen-aware code intelligence.
Rules see more than syntax. A semantic query API resolves a field’s type to its declaring symbol, pivots into that type’s own AST, and looks up references, base classes, and members — the same analysis that powers the LSP and MCP servers. Generate against what your types mean, not just how they’re spelled.
codegen connects to the workspace daemon on every run — there’s no
flag to opt in or out. AST subtrees and semantic queries are served from the shared
workspace intelligence cache, and types resolve against a whole-workspace snapshot for
accurate cross-header resolution. The daemon must already be serving --workspace-dir
(defaults to the current directory).
Feed a JSON blob to a rule, assert on the output. No compiler, no project, no fixtures. The same property that makes rules LLM-friendly makes them unit-testable in seconds.
LuaU runs in a sandboxed VM. Rules have no filesystem access and no process spawning — neither is grantable. Network access is the one escape hatch, and only for hosts you allowlist in the config. A malicious rule in a third-party library cannot exfiltrate your source code.
Rules can emit a source (to a .g.cpp file) and an inline list — declarations
injected back into the original header at a designated anchor comment. Bare anchors
are rewritten into idempotent :begin]] / :end]] blocks on first run.
codegen generates parts of its own infrastructure. We use it ourselves to build it, so every feature you rely on has already been exercised against a 100k+ LoC real-world codebase.
Licensing
Section titled “Licensing”codegen is free. There are no tiers and no feature gates — the TUI diff viewer,
the VS Code DAP debugger, and shared .codegen/shared/ libraries are all available
to everyone, on every install.