Add prelude-corfu module as a Company alternative

bbatsov · bbatsov · commit e26e628f48d2 · 2026-05-01T08:26:28.000Z
Corfu is a minimal in-buffer completion UI that uses Emacs' built-in
completion-at-point infrastructure -- so it cooperates with the
orderless completion style already configured by prelude-vertico,
no separate frontend/backend abstraction.

Cape is bundled alongside to add a few useful capf sources
(cape-dabbrev, cape-file).  More can be enabled from personal
config.

The module is mutually exclusive with prelude-company.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,7 @@
 - Add `prelude-ai` module: a thin wrapper around [gptel](https://github.com/karthink/gptel) for LLM-backed chat (Claude, GPT, Gemini, Ollama, etc.). Binds `gptel-menu` to `C-c q`. Backends and API keys are configured in personal config -- see the module documentation for examples.
 - Add `prelude-forge` module: enables [Forge](https://github.com/magit/forge) on top of Magit so you can read and reply to GitHub/GitLab/Gitea pull requests and issues without leaving Emacs.
 - Add `prelude-eglot-booster` module: speeds up Eglot via the [emacs-lsp-booster](https://github.com/blahgeek/emacs-lsp-booster) wrapper. The Emacs side ([eglot-booster](https://github.com/jdtsmith/eglot-booster)) is auto-installed via `package-vc-install` when the booster binary is on `PATH`; otherwise the module no-ops.
+- Add `prelude-corfu` module: a modern, lightweight in-buffer completion stack ([corfu](https://github.com/minad/corfu) + [cape](https://github.com/minad/cape)) -- alternative to `prelude-company`. Pairs naturally with the vertico/orderless setup in `prelude-vertico`.
 
 ### Changes
 
diff --git a/docs/modules/corfu.md b/docs/modules/corfu.md
@@ -0,0 +1,69 @@
+# Prelude Corfu
+
+## Overview
+
+[Corfu](https://github.com/minad/corfu) is a minimal in-buffer
+completion UI for Emacs -- a modern, lightweight alternative to
+Company. It uses Emacs' built-in `completion-at-point` infrastructure
+and the standard completion styles (so it cooperates with
+`orderless` from `prelude-vertico`), instead of providing its own
+backend abstraction the way Company does.
+
+[Cape](https://github.com/minad/cape) extends
+`completion-at-point-functions` with extra sources -- file paths,
+dabbrev, keywords, ispell, abbrevs, etc. -- so they show up in the
+Corfu popup alongside the language-specific completions provided by
+LSP servers, Eglot, etc.
+
+!!! Note
+
+    This module is mutually exclusive with the
+    [Company](company.md) module -- enable one or the other, not
+    both.
+
+## Packages
+
+- [corfu](https://github.com/minad/corfu) - the completion popup
+- [cape](https://github.com/minad/cape) - completion-at-point extensions
+
+## Defaults
+
+Corfu auto-pops after typing 2 characters (with a 200 ms debounce)
+and cycles through candidates with <kbd>TAB</kbd>:
+
+| Variable | Value | Effect |
+| -------- | ----- | ------ |
+| `corfu-auto` | `t` | Open the popup automatically as you type |
+| `corfu-auto-prefix` | `2` | Minimum prefix length to trigger |
+| `corfu-auto-delay` | `0.2` | Delay (seconds) before popup |
+| `corfu-cycle` | `t` | Wrap around at end of list |
+
+`corfu-popupinfo-mode` is enabled by default -- it shows
+documentation for the highlighted candidate in a side popup.
+
+## Default Cape sources
+
+The following completion-at-point sources are added globally:
+
+- `cape-dabbrev` - completes from words in open buffers
+- `cape-file` - completes file paths
+
+Add more from your personal config:
+
+```emacs-lisp
+(with-eval-after-load 'cape
+  (add-hook 'completion-at-point-functions #'cape-keyword)
+  (add-hook 'completion-at-point-functions #'cape-elisp-block))
+```
+
+## Tips
+
+- Press <kbd>M-SPC</kbd> in the popup to insert a space without
+  dismissing it (useful with orderless).
+- <kbd>M-g</kbd> opens the candidate at point (e.g. jumps to the
+  function definition); <kbd>M-h</kbd> shows its documentation in a
+  separate buffer.
+- For language-specific completions to feel snappy, configure your
+  LSP setup (Eglot or `lsp-mode`) to expose richer
+  `completion-at-point-functions` -- both already do this out of
+  the box.
diff --git a/docs/modules/index.md b/docs/modules/index.md
@@ -120,7 +120,8 @@ These modules provide shared functionality used by other modules:
 - [Lisp Base](lisp.md) - common foundation for Lisp-family language modules
 - [LSP](lsp.md) - common foundation for modules using the Language Server Protocol
 - [Eglot Booster](eglot-booster.md) - speeds up Eglot via the `emacs-lsp-booster` wrapper
-- [Company](company.md) - completion framework used across many modes
+- [Company](company.md) - completion framework (legacy)
+- [Corfu](corfu.md) - lightweight modern alternative to Company
 
 ## Programming Language Modules
 
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -15,6 +15,7 @@ nav:
         - LSP: modules/lsp.md
         - Eglot Booster: modules/eglot-booster.md
         - Company: modules/company.md
+        - Corfu: modules/corfu.md
     - Programming Languages:
         - C/C++: modules/c.md
         - Clojure: modules/clojure.md
diff --git a/modules/prelude-corfu.el b/modules/prelude-corfu.el
@@ -0,0 +1,61 @@
+;;; prelude-corfu.el --- Corfu in-buffer completion setup
+;;
+;; Copyright © 2011-2026 Bozhidar Batsov
+;;
+;; Author: Bozhidar Batsov <bozhidar@batsov.com>
+;; URL: https://github.com/bbatsov/prelude
+
+;; This file is not part of GNU Emacs.
+
+;;; Commentary:
+
+;; Corfu is a minimal in-buffer completion UI -- a modern, lightweight
+;; alternative to Company.  It pairs naturally with the
+;; vertico/orderless/marginalia stack in `prelude-vertico'.
+;;
+;; Cape extends `completion-at-point-functions' with useful sources
+;; (file paths, dabbrev, keywords, etc.).  This module enables a few
+;; sensible defaults; add more from your personal config if you want.
+;;
+;; This module is mutually exclusive with `prelude-company' -- enable
+;; one or the other, not both.
+
+;;; License:
+
+;; This program is free software; you can redistribute it and/or
+;; modify it under the terms of the GNU General Public License
+;; as published by the Free Software Foundation; either version 3
+;; of the License, or (at your option) any later version.
+;;
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+;;
+;; You should have received a copy of the GNU General Public License
+;; along with GNU Emacs; see the file COPYING.  If not, write to the
+;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+;; Boston, MA 02110-1301, USA.
+
+;;; Code:
+
+(use-package corfu
+  :ensure t
+  :custom
+  (corfu-cycle t)
+  (corfu-auto t)
+  (corfu-auto-prefix 2)
+  (corfu-auto-delay 0.2)
+  :init
+  (global-corfu-mode)
+  :config
+  (corfu-popupinfo-mode))
+
+(use-package cape
+  :ensure t
+  :init
+  (add-hook 'completion-at-point-functions #'cape-dabbrev)
+  (add-hook 'completion-at-point-functions #'cape-file))
+
+(provide 'prelude-corfu)
+;;; prelude-corfu.el ends here
diff --git a/sample/prelude-modules.el b/sample/prelude-modules.el
@@ -47,6 +47,7 @@
 ;; (require 'prelude-helm) ;; Interface for narrowing and search
 ;; (require 'prelude-helm-everywhere) ;; Enable Helm everywhere
 (require 'prelude-company)
+;; (require 'prelude-corfu) ;; Lightweight modern alternative to Company (mutually exclusive with prelude-company)
 ;; (require 'prelude-key-chord) ;; Binds useful features to key combinations
 ;; (require 'prelude-eglot-booster) ;; Speeds up Eglot via emacs-lsp-booster (requires the binary)
 
diff --git a/test/prelude-load-test.el b/test/prelude-load-test.el
@@ -17,6 +17,7 @@
 (defvar prelude-load-test-modules
   '(prelude-vertico
     prelude-company
+    prelude-corfu
     prelude-ai
     prelude-eglot-booster
     prelude-forge
