The codebase is organized into self-contained modules in src/:
Core Libraries (Lua + C):
std/ - Standard library
filesystem (std.fs)
process (std.ps)
UTF-8 (std.utf)
text (std.txt)
tables (std.tbl)
Git metadata parsing (std.git)
conversions (std.conv)
MIME types (std.mime)
logging (std.logger)
term/ - Terminal I/O with Kitty keyboard & graphic protocols support, widgets, TSS (Terminal Style Sheets)
crypto/ - Cryptography via LITLS
lev/ - Async I/O runtime: epoll event loop, TCP/UDP sockets with TLS 1.3 via LITLS
mneme/ - Embedded key-value DB with FT and vector support
calm/ - CALM models C implementation and Lua bindings
lem/ - LEM text editor
zlib/ - Deflate, zlib-wrapped, and gzip compression, CRC-32/Adler-32 checksums via miniz
zx/ - ZX Spectrum emulator (48K/128K/+2 machines, TAP/TZX/Z80 formats)
Pure Lua Libraries:
shell/ - The Lilush Shell implementation (see Shell Architecture below)
argparser/ - Argument parsing
markdown/ - Markdown parser and renderers (static, streaming, HTML)
redis/ - Async Redis protocol client (requires lev.run() context)
dns/ - DNS client library (caching, CNAME following, failover, UDP/TCP/DoT transports)
testimony/ - Minimal testing framework for Lilush
theme/ - Central TSS-based styling for shell, markdown, and agent
lilpack/ - LILPACK package system (MNEME-backed module loading)
http/ - HTTP client and server, SSE streaming, URL parsing, form-data encoding/parsing
reliw/ - HTTP server/framework (Redis-centric)
recall/ - Caching recursive DNS resolver (Redis-centric)
C-only Libraries:
cjson/ - Fast JSON encoding/decoding
wireguard/ - WireGuard client bindings
inotify/ - File system event monitoring
litls/ - Lilush TLS stack
Consult SHELL.md for the Lilush Shell (src/shell/) detailed overview.
The shell has three built-in modes: shell (F1), lua REPL (F2), and
wiki viewer (F3). The wiki mode opens self-describing MNEME databases
for browsing, searching, and viewing content — see WIKIDB.md.
Lilush embeds all modules in the binary:
Lua modules - Compiled to bytecode, embedded as C char arrays
C modules - Statically linked, registered via luaL_Reg
Preloading - Both registered in package.preload before Lua execution
The c_tmpl template generates:
mod_lua__t lua_preload[] - Array of Lua bytecode modules
luaL_Reg c_preload[] - Array of C module loaders
preload_modules(L) - Populates package.preload
Create files in src/yourmodule/*.lua
Add module to buildgen/modinfo.lua luamods section
Add to whichever app configs need it (e.g. buildgen/apps/lilush.lua, buildgen/apps/lilu.lua) luamods array
Create source in src/yourmodule/*.c with luaopen_* function
Create src/yourmodule/Makefile
Add to buildgen/modinfo.lua c_libs section
Add to whichever app configs need it (e.g. buildgen/apps/lilush.lua, buildgen/apps/lilu.lua) c_libs array
Lilush uses the LILPACK system for package loading. On startup,
lilpack.init() strips all default Lua searchers except the preload
searcher, then installs two custom searchers:
LILPACK searcher - Loads modules from MNEME-backed .lilpack
databases in ~/.local/share/lilush/packages/
Script-local searcher - Tries ./module.lua and ./module/init.lua
relative to CWD
After initialization, package.path is set to an empty string.
See LILPACK.md for the full package system specification.