LoL is an environment you work inside, in the tradition of the Lisp Machines and Smalltalk: one live Common Lisp image holds your code, your tools and the desktop they’re drawn on. Every part of it can show its own source, be inspected, be debugged with its stack standing and be redefined while it runs — the code browser, the debugger, the window system, the terminal, the editor you type in. The tool you look with is made of the same stuff as the thing you look at.
It’s the whole userland of a bare Linux kernel. SBCL is PID 1: no shell, no systemd, no X server, no toolkit. The machine boots straight into the environment, which draws every pixel itself on the framebuffer.
/As it boots, under QEMU: the Workspace tiled across the screen, a Lisp scratch
buffer whose lines are verbs, and the module index (Super-m) torn off into a
window with Super-g. Both are morphs in one world, drawn by the Lisp from TrueType
outlines it rasterises itself. Across the top: tabs, then the systray (network, the
agent and what it has spent, the clock)./
Everything is a subject you can drill into. One protocol, present, turns any
object into a view of drillable rows: a module, a package, a class, a generic
function and its dispatch matrix, a condition and who signals it, a closure and
what it captured, a file, a process, a web page. ↵ opens the next pane on the
selection, so a trail of panes reads as the path you took. Super-Space (the
Spotter) finds anything by name; Super-? lists every key.
/Live definition: C-c C-c on line 10 has compiled greet into the running image
and recorded it in the change set; C-c C-p printed (greet "lisp") under itself.
The status bar names the verbs: Do it, Print, Inspect, Debug, define, Ask./
- Change it while it runs. Any source pane is live: edit a definition,
C-c C-c, and it’s compiled into the image and becomes the source the browser shows. Each change is first tried in a throwaway child process, so a definition that hangs or kills its process is refused before it reaches yours. - A real debugger. An error stops with the stack still standing: restarts, an
sb-dibacktrace, frame locals you can change, a frame you can restart,M-.into any frame’s source. One restart asks the agent to explain the error. - An inspector with the old powers. Every instance of a class (a heap walk), why
an object is still alive (the path from a root), evaluation with
selfbound to the object, a closure’s captured variables as settable fields (inspector-history.org). - A window system in the same image (Morphic). Everything on screen is a CLOS
morph in one world.
Super-gtears a tab off into a window you move and resize; the middle button’s halo acts on whatever is under the pointer; a row, a field or a name drags from one view into another (Super-ppicks it up,Super-ddrops it) (morphic.org). - A session that survives power-off. Every
C-c C-cis journalled and replayed at the next boot; tabs, windows and the Workspace text come back; the journal view’sFfiles the edits back into the source files. It all lives under one~/.lol/tree (session-persistence.org).
/The debugger, from the Workspace’s C-c C-d: the condition, its restarts (the last
one asks the agent), the call stack, and the selected frame’s locals; degrees is
settable./
- A terminal (
Super-↵). A login shell in a user-namespace container over the host’s own Debian, sogit, language runtimes and databases work without growing the image. The pty, the VT parser and the cell grid are Lisp. - A web browser (
Super-b). The host’s Chrome, headless in a container, driven over the DevTools protocol; the Lisp decodes and draws its frames and turns our keys and clicks into its input. A page is a tab like any other, or a window. - A file manager (
Super-f). Previews (PNG, GIF, JPEG, archives, ELF, hex), and the Spotter reads paths. - An agent. An LLM client written in Lisp, living in the image, whose tools are
the image’s own introspection. Every write it wants (an eval, a definition, a
file, a command) is a condition with restarts that you approve on screen;
C-gstops it. - Networking in Lisp (DHCP, DNS, SNTP, HTTP/HTTPS, IPv6, Wi-Fi), a clipboard with history, runtime font scaling, screencasts with sound.
- It explains its own freezes. A session log with a heartbeat, stall reports carrying every thread’s backtrace, the kernel’s log copied to disk (diagnostics.org).
/The module index: every definition in the image, grouped by the file it came from,
beside the selected module’s contents. It’s the only view that shows the whole
system, the toolkit included (it lives in its own lol.* packages)./
The file manager, filtered to =~/Pictures=, with a JPEG previewed beside the listing.
Build the image and boot it in a QEMU window you can type into (prerequisites are under “Rebuilding the environment from scratch” below):
./build.sh --interactiveIt opens on the Workspace. Put the point after a form and use a verb (C-x C-e Do
it, C-c C-p Print, C-c C-i Inspect, C-c C-d Debug). Super-Space then “tour”
walks the system’s own code, stop by stop. To learn the code from outside, start at
tour.org, the index of an offline HTML guide with diagrams and reading paths.
The environment’s design and phase tracker is code-browser.org; the status of
every piece on one page is doc/status.html.
The project started as the smallest Linux a UEFI machine can boot from a USB stick with no bootloader (EFISTUB, micro-distro.org); SBCL then replaced everything above the kernel (sbcl-init.org). The boot chain is still small:
firmware → the kernel (it is the EFI application) → a small C preinit → SBCL.
- Boot source. A USB stick, or an entry in the host’s GRUB.
- =preinit=. Mounts the host’s disk read-only except for
/home, drops to the user with five capabilities, and =execve=s the Lisp, which stays PID 1 for the life of the machine. - The supervisor. Leave the environment (
Super-q) and you land on its console menu, with a REPL of its own.
/The supervisor’s menu and its REPL on the framebuffer console, with the Land of
Lisp alien (the “LoL” is also a nod to Land of Lisp). Screenshots are archived
per date under media/screenshots/; ./refresh-screenshot.sh re-captures them
from a headless QEMU./
Every kernel option and why is in kernel-config.org. This is a learning project:
the .org docs are the deliverable, written to be read, and the code is meant to
be understood as much as run.
Tracked here: the sources and docs — the C preinit, the Lisp modules, the
initramfs description, build.sh, deps.sh, every .org write-up, and a pinned
snapshot of the kernel .config under kernel/.
Not tracked (too big, version-specific): the Linux kernel source tree and the SBCL source tree. The build reaches them through two gitignored symlinks in the project root:
./linux -> a Linux kernel source tree (e.g. linux-7.2.5) ./sbcl -> an SBCL source tree (already built)
build.sh locates itself and uses ./linux and ./sbcl; nothing hardcodes a home
path, so the project folder is relocatable and clone-able by anyone.
You need the two symlinks above (pointing at real trees) and the host toolchain.
deps.sh creates the symlinks.
sudo apt install build-essential bc kmod cpio flex bison \
libncurses-dev libelf-dev libssl-dev dwarves rsync \
qemu-system-x86 ovmf dosfstools mtools gdisk musl-toolsIf you already have a kernel source tree:
./deps.sh link linux /path/to/linux-7.2.5From nothing (downloads into ./sources/, symlinks, applies our pinned config):
./deps.sh kernel 7.2.5 # version defaults to the one we pin in kernel/The pinned config is kernel/config-7.2.5 (kernel-config.org explains every
option). deps.sh kernel copies it to linux/.config and runs make
olddefconfig.
If you already have a built SBCL checkout:
./deps.sh link sbcl /path/to/sbclFrom nothing (clones; you then build it — SBCL needs an existing Lisp to bootstrap):
./deps.sh sbcl
cd sbcl && sh make.sh && cd ..build.sh expects sbcl/src/runtime/sbcl and sbcl/output/sbcl.core to exist.
./deps.sh status # sanity: both symlinks resolve
./build.sh # preinit + lisp-init + initramfs.cpio (seconds)
./build.sh --kernel # ALSO rebuild the kernel + BOOTX64.EFI (minutes)
./build.sh --run # build, boot HEADLESS in QEMU/OVMF, screenshot it
./build.sh --interactive # build, boot in a QEMU WINDOW you can type into- =–interactive= (=-i=) is for driving the environment, the supervisor menu and
the REPL. PID 1’s console is the framebuffer VT (
tty0), so you type in the QEMU window while the launching terminal mirrors the serial/kernel log. - =–run= boots, screenshots and kills QEMU: quick checks and CI.
Then write the USB and boot real hardware: micro-distro.org. Or skip the stick:
./build.sh --install-host puts both files in the host’s /boot/lisp for a
one-time GRUB entry (micro-distro.org → Booting from the host’s GRUB).
The symlink is the whole trick: point ./linux at the new tree and rebuild.
./deps.sh kernel 7.3 # download + extract + symlink + apply config
# if 7.3 has no pinned snapshot yet, configure, then:
# cp linux/.config kernel/config-7.3 (commit it)
./build.sh --kernelNothing in the project needs editing; only the symlink moves.
| File | What it covers |
|---|---|
| tour.org | Start here to learn the code. Index of the HTML guide (doc/guide/: diagrams of the boot, build, module graph, present, pixels and input; reading paths; glossary; exercises) and of the in-image tour. |
| code-browser.org | The environment’s design and phase tracker: the present drill-down protocol, the accordion shell, trails/tabs/Spotter, live editing, the debugger. |
| morphic.org | Morphic: morphs as CLOS objects in one world, damage repair, trail windows (SuperL-g), the halo, overlays and stepping, every pane and its body a morph, drag and drop through the hand. |
| session-persistence.org | How a session is kept: the per-Accept journal replayed at boot, the desk (tabs, windows, Workspace text), file-out into the checkout, the leave menu — all under ~/.lol/. |
| inspector-history.org | What inspectors did on Interlisp-D, the Lisp Machines, Smalltalk, CLIM and SLIME, and the four powers built here: all instances, why an object is alive, eval in its context, settable frame locals. |
| agent.org | An LLM client native to the image: JSON/SSE and the Messages protocol in Lisp, the introspection layer as its tools, gated writes as a condition with restarts, C-c C-a Ask it. |
| terminal.org | The terminal pane (SuperL-↵): pseudo-terminals, sessions and controlling terminals, escape sequences and Williams’ parser, the cell grid, keys as bytes, mouse and bracketed paste. |
| web-browser.org | The web browser (SuperL-b): the host’s Chrome, headless in a container, driven over the DevTools protocol; screencast frames drawn by the Lisp, our input sent back. Why Chrome over WPE. |
| file-manager.org | The file manager (Super-f): folders and files as subjects, the operations, safe save, the Spotter’s path grammar. Previews: previews.org. |
| containers.org | Running a full distro’s projects (a web app with a database) without growing the image: a user-namespace container over the host’s Debian, per-directory overlays, you inside as yourself. |
| processes.org | Concurrent components sharing the screen: one writer of /dev/fb0, sending a view vs sending pixels, workers in a second process, the sandboxed Accept, the sb-posix audit. |
| clipboard.org | The clipboard as plain data: history, the Emacs kill ring, PRIMARY vs CLIPBOARD, rectangles, undo. |
| org.org | Org files in the environment: colouring, folding, heading motion, subtree edits, links, the outline as a subject. |
| screencast.org | Screencasts with sound: the HDA kernel options, a pure-Lisp ALSA mixer, the recorder (live or a damage log), playback through the host’s MPlayer. |
| fonts.org | How a character becomes pixels: a TrueType outline rasterised in pure Lisp, or the Cozette bitmap fallback, and how the size changes at run time (SuperL- / - / 0=). |
| diagnostics.org | Why a frozen screen happens and what the machine writes down about it: the session log, stall reports, the kernel log, crash-then-reboot. How to read it from the host. |
| File | What it covers |
|---|---|
| micro-distro.org | The EFISTUB boot chain, USB creation, real-hardware boot, the host’s GRUB entry. |
| sbcl-init.org | SBCL as PID 1: the preinit shim, the supervisor, the build, updating from inside. |
| kernel-config.org | Every kernel option we enable and why (single source of truth). |
| framebuffer.org | Framebuffer → efifb → fbcon, /dev/fb0, drawing images. Why there is no GPU driver. |
| input.org | Input devices: evdev, finding devices without udev, poll(2), the wheel, every keyboard and pointer at once, hotplug, keyboard layouts. |
| storage.org | The host’s disk: NVMe + ext4, found by reading superblocks, mounted read-only but for /home; PID 1 drops to the user with five capabilities, lol-rootd keeps root for a few jobs. |
| networking.org | The network layer in Lisp: DHCP, routes, DNS, SNTP, HTTP/1.1 and HTTPS (the host’s OpenSSL, loaded at run time), IPv6, Wi-Fi through the host’s wpa_supplicant, the TCP REPL. |
| systray.org | The systray’s data: battery from sysfs, time from the RTC, the network item. |
| line-editing.org | Readline-class REPL editing in pure Lisp. |
| x11.org | The pure-Lisp X11 client (no Xlib): why “supporting X” is just a socket protocol, and how the browser gets a window on the dev host. |
| File | What it covers |
|---|---|
| steps.org | Inspiration. VPRI’s STEPS and Piumarta & Warth’s Open, Extensible Object Models (2008): the paper summarised, what LoL shares and doesn’t, and the loc.sh split of our code into ours vs conformance. |
| learn-clos.org | From-scratch tutorial: CLOS (multiple dispatch, method combination) and the MOP — the Lisp the code browser is built out of. |
| learn-networking.org | From-scratch networking tutorial (progress tracker + code links). |
| background.org | Background theory: UEFI handoff, x86 modes, USB-HID, multicore, entropy. |
| AGENTS.md | Working notes and conventions for AI agents in this repo. |
build.sh one-step build (userland, --kernel, --run, --interactive, --install-host)
deps.sh fetch/link/update the ./linux and ./sbcl trees
check-links.sh verify every [[file:...]] link in the .org docs resolves
check-*.lisp boot the image under QEMU and assert behaviour over QMP + the net REPL
refresh-screenshot.sh re-capture the screenshots (headless QEMU, driven over QMP)
loc.sh lines of code/prose, by language and by origin (ours vs conformance)
kernel/ pinned .config snapshots (config-<version>)
initramfs/ preinit.c, lol-ct.c, the Lisp modules (*.lisp), the cpio list, alien assets
poc/ the pixel toolkit and the shell — canvas, text view, morphs, X11
client, the Cozette font blob — plus host tests. Host-runnable
from a plain sbcl, AND baked into the image (build.sh loads it in place)
media/ screenshots (archived per date) + the HTML design mock-ups
host-client/ HOST-side tools (NOT in the image): the net-REPL client, QMP, PNG, mocks
iso_root/ build output: BOOTX64.EFI + initramfs.cpio (gitignored)
README.org this file (the only .org in the root)
doc/ all other documentation (*.org); doc/background/ = theory + tutorials
linux -> … sbcl -> … gitignored symlinks to the external source trees
sources/ (optional) where deps.sh downloads trees (gitignored)
This project’s own code — preinit.c, the Lisp modules, build.sh, deps.sh,
the .org docs, and the kernel/config-* snapshots — is released under the MIT
License (see LICENSE).
Why MIT and not GPL. This repository does not redistribute the Linux kernel
(its source and the compiled bzImage are gitignored; deps.sh fetches the tree),
and our userland talks to the kernel only through system calls, which the
kernel’s own licence explicitly excludes from being a derivative work. So our code
is ours to license.
Third-party components you obtain or build separately keep their own licences:
| Component | License | How it reaches you |
|---|---|---|
| Linux kernel | GPLv2 | fetched by deps.sh from kernel.org; never redistributed here |
| musl libc | MIT | statically linked into preinit (you build it) |
| SBCL | public domain + BSD-style | the runtime your image embeds (you build it) |
| GNU C Library (glibc) | LGPL-2.1-or-later | copied verbatim into the initramfs — the SBCL binary is dynamically linked, so ld-linux-x86-64.so.2, libc.so.6 and libm.so.6 are taken from your host and shipped (see initramfs/initramfs.sbcl.list) |
Intel Wi-Fi firmware (iwlwifi-*.ucode) | Intel’s binary-redistribution licence (LICENCE.iwlwifi_firmware in linux-firmware; Debian’s copyright file calls it binary-redist-Intel) | copied by build.sh from your host’s /lib/firmware (Debian’s firmware-iwlwifi) into the initramfs only; never committed here; card-keyed, LOL_WIFI_FIRMWARE=0 leaves it out (networking.org, Wi-Fi) |
regulatory.db (+ .p7s) | ISC (wireless-regdb) | likewise copied from your host’s /lib/firmware (the upstream-signed regulatory.db-upstream), never committed |
OpenSSL 3, wpa_supplicant | Apache-2.0; BSD-3-Clause | not shipped at all: the image loads/runs the host’s own copies from /mnt/host at runtime (networking.org, Userland half — reaching the network from SBCL, Wi-Fi) |
| stb_image | MIT or public domain (Unlicense), your choice | committed here, vendored as poc/vendor/stb_image.h; compiled into libstbi.so, which ships in the image for JPEG/PSD/HDR previews (previews.org) |
| Cozette (font) | MIT | committed here as poc/cozette.lolf (our 6×15 blob, regenerated from the upstream BDF) with the upstream license beside it in poc/cozette-LICENSE.txt; it also ships inside the image, as the fallback font |
| DejaVu Sans Mono (font) | Bitstream Vera licence (DejaVu’s own changes: public domain) | never committed: build.sh copies it from the build host (Debian’s fonts-dejavu-core, /usr/share/fonts/truetype/dejavu/) into the image at /usr/share/lol/mono.ttf. The licence permits redistribution with its notice (/usr/share/doc/fonts-dejavu-core/copyright on the host). LOL_FONT ships another file instead — then that file’s licence applies |
If you distribute a bootable image or USB, three obligations come along; none affects your own MIT code:
- The kernel (GPLv2). The image contains the compiled
bzImage. Make the corresponding kernel source available (unmodified upstream linux-7.2.5 from kernel.org) together with the exact.config, whichkernel/already keeps. - glibc (LGPL-2.1+). The image carries the glibc loader and libc/libm as
unmodified binaries. Say which version you shipped, pass its licence text along
and make its source obtainable. The relinking requirement is met because SBCL is
dynamically linked and the
.sofiles are ordinary replaceable files in the initramfs. - Wi-Fi firmware. If the image carries the Intel firmware (the default when the
build host has it), Intel’s licence permits binary redistribution on its own
terms: read
LICENCE.iwlwifi_firmware(Debian:/usr/share/doc/firmware-iwlwifi/copyright) and pass it along, or build withLOL_WIFI_FIRMWARE=0.
Everything else is aggregation: your MIT userland sits alongside these on the medium, unaffected. (A plain-English summary of what the licences cover, not legal advice — read them if you intend to ship.)
The alien sprite (initramfs/alien256.png and the derived initramfs/alien.rgba)
is the Lisp alien logo by Conrad Barski, M.D. — https://www.lisperati.com/logo.html
— released into the public domain (“anyone may use these freely for any purpose
and in any way”). Attribution isn’t required but is appreciated, so: thanks,
Conrad. The logo is also the namesake nod behind “LoL” / Land of Lisp.





