README.md

July 19, 2026 · View on GitHub

███████╗███╗   ███╗ █████╗  ██████╗███████╗      ███████╗██╗     ██╗███████╗██████╗
██╔════╝████╗ ████║██╔══██╗██╔════╝██╔════╝      ██╔════╝██║     ██║██╔════╝██╔══██╗
█████╗  ██╔████╔██║███████║██║     ███████╗█████╗█████╗  ██║     ██║███████╗██████╔╝
██╔══╝  ██║╚██╔╝██║██╔══██║██║     ╚════██║╚════╝██╔══╝  ██║     ██║╚════██║██╔═══╝
███████╗██║ ╚═╝ ██║██║  ██║╚██████╗███████║      ███████╗███████╗██║███████║██║
╚══════╝╚═╝     ╚═╝╚═╝  ╚═╝ ╚═════╝╚══════╝      ╚══════╝╚══════╝╚═╝╚══════╝╚═╝

`[EMACS MAJOR MODE // DERIVED FROM EMACS-LISP-MODE // RUN + LSP + DAP]`

"Open a .el. Emacs' own lisp editing, plus the elisprs runtime's subrs, run, and language server."

Emacs major mode (elisprs-mode) for Emacs Lisp on the elisprs runtime — Emacs Lisp compiled to the fusevm bytecode VM with a Cranelift JIT. elisprs-mode derives from the built-in emacs-lisp-mode, so it inherits Emacs' own lisp syntax table, indentation, paren handling, and font-lock, and layers the elisprs toolchain on top: run a buffer through elisp, elisp --lsp language server, elisp --dap debug adapter, eldoc + completion over the runtime's builtin surface, and an extra font-lock layer for the elisprs subrs. By default it claims *.el (plus .emacs / _emacs), shadowing the stock mode for those files.

`Read the Docs` · `Engineering Report` · `elisprs` · `vim-elisp` · `vscode-elisp`

[0x00] OVERVIEW

emacs-elisp is the Emacs major mode for Emacs Lisp on the elisprs engine. It provides:

Filetype detection — *.el and the .emacs / _emacs init files (auto-mode-alist) plus the elisp interpreter shebang (interpreter-mode-alist).
Syntax highlighting — everything emacs-lisp-mode gives you, plus an extra font-lock layer that styles the 18 elisprs special forms (font-lock-keyword-face) and the 252 subrs the runtime implements (elisprs-subr-face).
Run — elisprs-run-buffer (C-c C-c) runs the buffer through elisp via compile.
eldoc + completion — one-line signatures and completion-at-point over the elisprs builtin surface.
Language server — elisp --lsp via eglot (built in since Emacs 29) and lsp-mode.
Debug adapter — elisp --dap for step / breakpoint / variable inspection with DAP clients.

Because elisprs-mode derives from emacs-lisp-mode, it is a strict superset of the stock editing experience — nothing is lost, the runtime tooling is added. The builtin surface (special forms + subrs, with signatures and docs) lives in elisprs-stdlib.el, generated verbatim from elisprs' own LSP metadata (elisprs/src/lsp.rs → SPECIAL_FORMS + SUBRS), so it never drifts from what the binary evaluates.

elisp --lsp is launched with only --lsp — no --stdio is appended.

Created by MenkeTechnologies.

[0x01] FEATURE MATRIX

Capability	Status
Filetype detection — `*.el`	Implemented — `auto-mode-alist`
Filetype detection — `.emacs` / `_emacs`	Implemented — `auto-mode-alist`
Filetype detection — shebang	Implemented — `interpreter-mode-alist` (`elisp`)
Syntax highlighting	Implemented — inherited `emacs-lisp-mode` + elisprs subr/special-form layer
Comments / strings / chars	Implemented — inherited lisp syntax table
Indentation	Implemented — inherited lisp indentation
Run buffer	Implemented — `elisprs-run-buffer` (`C-c C-c`) via `compile`
eldoc	Implemented — builtin signatures from the corpus
Completion	Implemented — `completion-at-point` over the builtin surface
Language server (eglot)	Implemented — `elisp --lsp`
Language server (lsp-mode)	Implemented — registered client
Debug adapter	Implemented — `elisp --dap`
Config	`elisprs-executable`, `elisprs-claim-dot-el`

The elisp binary must be on $PATH to run buffers and for the servers. Install elisprs (brew install menketechnologies/menketech/elisprs).

[0x02] INSTALL

Manual

;; clone, then:
(add-to-list 'load-path "/path/to/emacs-elisp")
(require 'elisprs-mode)

use-package + built-in VC

(use-package elisprs-mode
  :mode "\\.el\\'"
  :vc (:url "https://github.com/MenkeTechnologies/emacs-elisp"))

Open any .el file — it opens in elisprs-mode. Press C-c C-c to run it through elisp. With eglot, run M-x eglot to start the language server (or (add-hook 'elisprs-mode-hook #'eglot-ensure)).

To keep the stock emacs-lisp-mode association for .el and enable elisprs-mode only on demand, set elisprs-claim-dot-el to nil before loading:

(setq elisprs-claim-dot-el nil)
(require 'elisprs-mode)   ; now M-x elisprs-mode / shebang only

[0x03] SYNTAX // FACES

Token group	Face
Special forms (`defun` `let` `when` `setq` `cond` `lambda`)	`font-lock-keyword-face`
Subrs the runtime implements (`cons` `mapc` `message` `concat` `length`)	`elisprs-subr-face`
Definition names (`(defun NAME …)`)	`font-lock-function-name-face`
Keyword symbols (`:key`)	`font-lock-builtin-face`
Strings / chars / comments	inherited `emacs-lisp-mode` syntax table

[0x04] RUN

elisprs-run-buffer (bound to C-c C-c) runs the current buffer through elisp FILE using Emacs' compile, so output, errors, and next-error navigation land in the *compilation* buffer. The executable is elisprs-executable (default "elisp").

[0x05] LANGUAGE SERVER + DEBUG ADAPTER

elisprs-mode registers elisp --lsp for both clients (lazily, so neither is a hard dependency):

eglot (Emacs 29+): M-x eglot in a .el buffer.
lsp-mode: M-x lsp.

The debug adapter is elisp --dap — point any DAP client at it for stepping, breakpoints, and variable inspection. The executable is elisprs-executable (default "elisp"); the server is launched with --lsp only (no --stdio appended).

[0x06] LAYOUT

emacs-elisp/
├── elisprs-mode.el         # major mode: derives from emacs-lisp-mode; run, LSP, DAP, eldoc, completion, subr font-lock
├── elisprs-stdlib.el       # builtin surface (special forms + subrs) — generated from elisprs' LSP metadata
├── scripts/face-test.el    # fontifies a sample and asserts faces
├── tests/face-test.sh      # byte-compile + face assertions wrapper
└── tests/*.sh              # README / docs / workflow validators

Read the Docs · Engineering Report · elisprs · vim-elisp · vscode-elisp

`Read the Docs` · `Engineering Report` · `elisprs` · `vim-elisp` · `vscode-elisp`