zemacs is an Emacs-like editor built around a live Common Lisp image. Rust owns the substrate — the rope, the window, the parser — and Common Lisp owns the policy: your keybindings, your theme, your dashboard, your commands.
- Common Lisp inside — an embedded ECL image runs on its own thread. Your
init.lispdrives the editor the way elisp drives Emacs. - GPU-accelerated — SDL3 on an
acceleratedcanvas (Metal on macOS, Vulkan or GL elsewhere). Glyphs are rasterized once into a per-character texture cache and thereafter blitted and recolored by the GPU. The dashboard footer and the startup line both print the backend actually in use, so “accelerated” is a fact you can check rather than a claim. - Multithreaded — three threads that never block each other: input+draw, the Lisp image, and syntax highlighting.
- Modal (“Evil”) editing — Normal / Insert / Visual / Visual-Line are first-class, with counts, operators and motions, not an add-on.
- tree-sitter highlighting, themed from Lisp.
- A dashboard on open, with your recent files, also configured from Lisp.
- A completing minibuffer —
M-x, find-file and the buffer switcher, with fuzzy matching, drawn either as aconsult-style panel from the bottom or atelescope-style box in the middle. One setting, one word.
Three threads matter, and none of them waits on another for long:
- Main thread — the SDL3 event loop, the renderer, and
App::dispatch. - Lisp thread — owns the ECL image and its GC. It evaluates one queued form
at a time and reaches the
Editorthrough a mutex it holds for one primitive at a time, never across a redraw; the main thread releases the same mutex before it presents a frame. See docs/threading.org. - Syntax thread — reparses the buffer and returns highlight spans. Its queue coalesces: a burst of keystrokes causes one parse of the newest text, not one parse per key, so a fast typist can’t outrun it. Results carry the revision they were computed from and are dropped if the buffer has moved on.
Language servers, terminals, remote files and project search each get helper threads that hand results back over channels.
Every change to a document — from the keyboard or from Lisp — is an
EditorCommand, and every one goes through Editor::apply. The exceptions are
the effects the pure core cannot perform (calling Lisp, reading and writing
files, git, dired, terminals, closing an OS window); the app layer performs
those in App::dispatch.
Fourteen crates under crates/ (core, render, syntax, lisp, app and
nine smaller ones) and the Lisp runtime under runtime/. The map, the crate
graph and the path of one keystroke are in docs/architecture.org; how to work
on the code is in AGENTS.md.
- Rust (stable, 1.89+)
brew install ecl sdl3 sdl3_ttf pkgconf- Used by features at run time, not by the build:
git,rg(project search),mutool(PDFs),latexanddvipng(org LaTeX previews).
cargo run -p zemacs-app # or: cargo run --bin zemacs
cargo run -p zemacs-app -- FILE # open a file instead of the dashboard
scripts/install.sh # release build to ~/.local/bin and ~/Applications
cargo test -p zemacs-lisp --test pdf_mode # one test file; see docs/testing.orgcargo test --workspace runs everything and takes minutes; docs/testing.org
says how to run one piece.
Environment overrides, useful for trying things without touching your config:
ZEMACS_INIT | path to an init file, instead of the usual lookup |
ZEMACS_RUNTIME | the runtime/ directory to read the shipped Lisp from, instead of the checkout the binary was built from |
ZEMACS_FONT | path to a monospace .ttf / .ttc |
ZEMACS_PROSE_FONT | path to the proportional font scenes set prose in |
ZEMACS_PERF | seconds between frame-timing reports on stderr |
ZEMACS_PERF=1 puts a line a second on stderr saying where the frame went —
time waiting for you, handling input, drawing and presenting, plus draw calls
and, whenever you type, how long a keystroke took to reach the screen:
perf: 60 fps (61 frames in 1.0s) | per frame: wait 12.11 input 0.06 draw 2.30 present 1.80 ms, worst 26.6 ms | 0.1 presents, 1336 draw calls perf: 6 keys, key to screen 11.7 ms average, 18 ms worst
It is measured in the real window because it cannot be measured anywhere else:
present blocks until the display’s next vertical blank, so what a frame costs
depends on the monitor. If the editor ever feels slow again, start here rather
than guessing.
Highlighting covers rust, lisp (.lisp .cl .asd .el .scm), python, json, toml,
c and javascript.
Motions take counts and compose with operators, so d2w, 3j, c$ and dfx
all work as you’d expect.
| Mode | Key | Action |
|---|---|---|
| Normal | h j k l | move |
| Normal | w b e | word motions (- counts as a word char) |
| Normal | 0 ^ $ | line start / first non-blank / line end |
| Normal | gg G {count}G | buffer start / end / line |
| Normal | { } | previous / next blank line |
| Normal | f F t T | find character on the line |
| Normal | i a I A o O | enter Insert |
| Normal | d c y + motion | delete / change / yank (dd, cc, yy) |
| Normal | x D C r J p P | the usual single-key edits |
| Normal | u / C-r | undo / redo |
| Normal | v / V | Visual / Visual-Line |
| Normal | / then n N | search |
| Normal | C-d / C-u | half-page scroll |
| Normal | gh | back to the dashboard |
| Normal | :q :w :wq :e | quit, write, write-quit, edit |
| Normal | :lisp FORM | evaluate Common Lisp |
| Insert | Esc / C-c | back to Normal |
| any | M-x | run any Lisp command, with completion |
| any | C-c | evaluate Lisp (selection / form / buffer) |
| Normal | SPC j j / C-⌘-j | switch buffer |
| Normal | SPC f f | find file |
| any | M-+ / M-- | magnify / shrink (M-0 resets) |
| any | C-<ret> | split side by side |
| any | C-M-<ret> | split stacked |
| Normal | C-w | other window |
The cursor is a block in Normal and a bar in Insert.
Holding a key repeats it. SDL text input is enabled only in Insert mode and in
prompts, which is where the keyboard layout, dead keys and IME matter; in the
modal modes it is off and characters come straight from the keycode. That is
deliberate: macOS press-and-hold (the accent panel) is a text-input feature, so
leaving it on would mean holding j offers you ĵ instead of moving down.
Meta is Command (⌘), the macOS Emacs convention. Option is deliberately not Meta: it is how you type –, ≠ and ü.
The mouse wheel scrolls the view; the cursor is dragged along only as far as keeping it on screen requires, so scrolling is not a motion.
In a completing prompt:
C-j / C-n / ↓ | next candidate |
C-k / C-p / ↑ | previous candidate |
Tab | adopt the highlighted candidate |
RET | accept |
Esc / C-g | cancel |
Matching is a fuzzy subsequence ranked so word starts win: sb finds
switch-buffer, tsi finds text-scale-increase. In find-file, Tab on a
directory rewrites the input to it, so the next listing is that directory —
repeated Tab walks down a tree. When completing leaves several candidates,
Tab cycles instead.
The Emacs vocabulary, because it is the one that distinguishes the three things that actually differ:
- a buffer is text — it belongs to the editor, not to any window;
- a window is a viewport onto a buffer, with its own cursor and scroll, so the same buffer shown twice scrolls independently;
- a frame is an OS window, holding a tree of windows.
*dashboard* and *scratch* are ordinary buffers, so they appear in the buffer
switcher and can be put in any window. M-x new-frame opens another OS window
on the dashboard; each one is titled with the project it is showing, or the
file outside a project.
Layout is a binary tree, and the arithmetic that turns it into rectangles is a
pure function in zemacs-core. That is deliberate: the renderer and the mouse
hit-testing have to agree on where a divider is to the pixel, and the only way
to guarantee that is for both to call the same code.
C-c evaluates the selection if there is one, else the top-level form under
point, else the whole buffer — read from the live buffer, so there is nothing
to save first. M-x eval-buffer, eval-region and eval-last-sexp name the
pieces individually, and :lisp FORM evaluates a form you type.
A form’s value is echoed ((+ 1 2) shows 3). NIL is not, because every
command that calls message returns NIL and echoing it would overwrite the
message the command just printed.
Note C-c no longer leaves Insert mode — Esc and C-g still do.
A buffer has exactly one major mode, taken from its file — notes.org opens
in org-mode — plus any number of minor modes on top. M-x org-mode sets it
by hand. This is a different axis from the modal editing state: a buffer is in
org-mode whether you are in Normal or Insert.
A binding whose mode name is not an editing mode belongs to that major or minor mode and applies only in its buffers:
(define-key "org-mode" "<tab>" "org-cycle") ; only in org buffersMinor modes are consulted first, most recently enabled first — a minor mode is something you switched on for this buffer, so it outranks the major mode.
A function named <mode>-hook runs when the mode is entered. Defining one is
the whole extension mechanism; there is nothing to register.
(defun org-mode-hook ()
(set-line-overflow "wrap"))Org rendering covers headings (coloured by level), *bold*, /italic/,
~code~, [[links][with descriptions]], #+DIRECTIVES, tables and lists.
Emphasis is carried by real weight and slant, not by colour standing in for
them: the renderer opens a bold face and an italic one alongside the body face,
so *bold* is bold. Syntax faces can ask for the same — see set-face below.
runtime/init.lisp (or ~/.zemacs.d/init.lisp if present) is loaded at
startup, into a live ECL image.
(in-package :zemacs)
(set-font-size 18)
(set-background 0.11 0.12 0.18) ; r g b in 0.0 .. 1.0
(set-face "keyword" '(0.78 0.57 0.94) :bold t)
(load-theme "tokyo-night") ; or M-x theme / SPC t t
(set-line-numbers t)
(set-relative-line-numbers t) ; count from the cursor, vim-style
(set-line-overflow "truncate") ; or "wrap"
(set-modeline-relief 2) ; negative sinks the bar instead
;; "center" = telescope-style box, "bottom" = consult-style panel,
;; "minibuffer" = a plain one-line vim prompt.
(set-completion-style "center")
(defun scratch-notes ()
(find-file "~/notes.lisp"))
(dashboard-item #\n "Notes" "scratch-notes")
(define-key "normal" "SPC f f" "find-file")
(define-key "normal" "SPC j j" "switch-buffer")
(define-key "normal" "M-x" "execute-command")
(message (format nil "~a ~a is live"
(lisp-implementation-type)
(lisp-implementation-version)))Keybindings are looked up before the built-in Evil grammar, so Lisp always
wins. A binding and a dashboard item name the same things: either a built-in
verb (find-file, execute-command, switch-buffer, scratch, config,
quit, open:PATH) or the name of a Lisp function, called as (name).
M-x offers every zero-argument function in the ZEMACS package, so a
defun in your config is a command the moment you write it — there is no
registration step.
An error in init.lisp is caught and reported in the status line — a broken
config never stops the editor from starting.
What is done, what is open and why is kept in TODO.org; the Lisp API is documented in docs/.