Planet Emacslife

This is the third post in a series on Emacs completion. The first post argued that Incremental Completing Read (ICR) is not merely a UI convenience but a structural property of an interface, and that Emacs is one of the few environments where completion is exposed as a programmable substrate rather than a sealed UI. The second post broke the substrate into eight packages (collectively VOMPECCC), each solving one of the six orthogonal concerns of a complete completion system.

In this post, I show, concretely, what it looks like when you build with VOMPECCC, by walking through the code of spot, a Spotify client I implemented as a pure ICR application in Emacs.

A word I'll use throughout this post to refer to the use of VOMPECCC in spot is shim, and it is worth qualifying that. The whole package is about 1,100 non-blank, non-comment lines of Lisp¹. Roughly 635 of those is infrastructure any Spotify client would need regardless of its UI choices: OAuth with refresh, HTTP transport with error surfacing, a cached search layer, a currently-playing mode-line, a config surface, player-control commands, blah blah blah. The shim is the rest: 493 lines across exactly three files (spot-consult.el, spot-marginalia.el, spot-embark.el) whose entire job is to feed candidates into Consult (source), annotate them with Marginalia (source), and attach actions to them through Embark (source). When I say spot is a shim, I mean those three files, and I'm emphasizing the fact that there is relatively little code. The rest of spot is plumbing that has nothing to do with the completion substrate.

spot implements no custom UI. It has no tabulated-list buffer, no custom keymap for navigation, no rendering code. Every interaction surface; the search prompt, the candidate display, the annotations, and the action menu; is rented from the completion substrate by the 493-line shim.

This post is about the code. Instead of cataloging spot's features (I'll do that when I publish the package to Melpa), I want to show how the code actually hangs together on top of VOMPECCC, with verbatim snippets mapped onto the interaction they produce. If the previous two posts were the why and the what, this one is the how, with a working application to ground the pattern.

Before any code, here is the concrete task the video is solving: I am trying to find a J Dilla song whose title I can't remember; all I recall is that the word don't is somewhere in the track name. The entire post revolves around this one video, so it is worth watching before reading on. Everything that follows is a line-by-line breakdown of the code that produces what you are about to see. In the upper right hand side of my emacs (in the tab-bar), you'll see the key-bindings and, more importantly, the commands I am invoking to drive spot. (To make this clip easier to digest, you can play, pause, scrub, view in full screen, or view as "Picture in Picture" use the video controls).

Here is what happens in the clip:

1. I invoke spot-consult-search and type j dilla. Each keystroke fires an async query against the Spotify Web API, and the result set is streamed into the minibuffer. That is Consult. In my emacs config, Vertico² renders the candidate set vertically so the per-row metadata is legible.
2. I use Spotify's query parameters to widen the result set per type. Spotify's search endpoint caps results per content type, so I append parameter flags (--type=track --limit=50, etc.) to ask for a fatter haul across tracks, albums, and artists. The candidates are streamed back through Consult exactly as before, just more of them.
3. I type ,, the consult-async-split-style character, to switch from remote search to local ICR. Everything before the comma continues to be the API query; everything after is a local narrowing pattern that matches against the candidate set already in hand. No further Spotify requests are issued, and each incremental keystroke only filters the rows Consult is already holding.
4. I type dont (no apostrophe) looking for the song. The default matching is literal, so "dont" doesn't match "Don't". Zero candidates. The corpus contains the song; my pattern just doesn't. (You thought I did this by mistake didn't you 😜? It actually highlights why fuzzy matching is so important.)
5. I backspace and prefix the query with ~, the Orderless³ dispatcher for fuzzy matching. ~dont now matches "Don't Cry" (and others) because fuzzy matching tolerates the missing apostrophe. The search set is unchanged; I swapped matching styles without re-querying Spotify. This may sound like a small feature, but consider how much a little fuzz widens the match space of your input strings. This is espacially important in an application like Spotify where entity names can be long and difficult to remember.
6. I append @donuts, the Orderless dispatcher for matching against the Marginalia annotation column rather than the candidate name. That narrows the surviving candidates to tracks whose annotation mentions "donuts" (i.e., tracks on Dilla's Donuts album, my personal favourite), even though the word "donuts" never appears in any track title. The song I was looking for is right there. (note my orderless-component-separator is also ",")
7. With the track selected, I invoke Embark (embark-act) and press P to play. The P binding dispatches to spot-action--generic-play-uri, which pulls the track's URI off the candidate's multi-data property and sends a PUT to the Spotify player. The song starts playing; no further navigation required.

Three VOMPECCC packages are doing the work: Consult (the async streaming + the split-character handoff to local ICR), Marginalia (the metadata column the @ dispatcher just narrowed against), and Embark (the action menu that allows you to play the track, list the album's other tracks, or add it to a playlist). The whole rest of this post is an argument that the code required to make this happen is pleasantly concise, because none of those capabilities (asynchronous search with narrowing, metadata annotation, annotation-aware fuzzy filtering, or contextual actions) needed to be built. They already exist in the VOMPECCC framework, and spot's only job is to feed them data.

spot is organized so that each file corresponds to one concern. This is deliberate: the architecture mirrors the modularity of VOMPECCC itself, not because I was trying to be cute (I'm cute enough 👺), but because when your substrate is modular, consuming it modularly is the lowest-friction path.

The breakdown is the whole point of the shim framing. The three substrate-facing files (194 + 159 + 140 = 493 lines) are the part that actually integrates with VOMPECCC. None of that is UI code; there is no UI code in spot. Every pixel the user sees comes from Consult, Marginalia, Embark, or whatever the user has slotted in below them.

One caveat on the 194-line figure for spot-consult.el: roughly 105 of those lines are a 7-way parallel triplet (one source definition, one history variable, and one completion function per Spotify content type), varying only in the narrow key and the :category symbol. A small macro (spot-define-consult-source) would collapse the 105 lines into 7 invocations plus a ~25-line definition, for 30-35 lines total. The honest Consult-facing line count, with redundancy factored out, is closer to 115 than 194, and the whole shim closer to 420 than 493.

The reason I didn't write this macro is because it would muddy the concrete depiction of the VOMPECCC APIs here, and honestly, I tend to avoid over-macroizing as it creates new and confusing APIs over well-established and intuitive APIs.

Before looking at any of the three VOMPECCC layers individually, there is one piece of code that makes the entire integration possible. It is a short function, and if you understand it, you understand how Consult, Marginalia, and Embark cooperate without knowing anything about each other.

(defun spot--propertize-items (tables)
  "Propertize a list of hash TABLES for display in completion.
Each table is expected to have `name' and `type' keys.  Names are
truncated for display per `spot-candidate-max-width'; the full
name remains accessible via `multi-data'."
  (-map
   (lambda (table)
     (propertize
      (spot--truncate-name (ht-get table 'name))
      'category (intern (ht-get table 'type))
      'multi-data table))
   tables))

Every candidate that spot hands to Consult is a string (the Spotify item's name) carrying two text properties:

• category is one of album, artist, track, playlist, show, episode, or audiobook. Emacs's completion metadata protocol uses this property to route candidates to the right annotator and the right action keymap. Marginalia reads it to pick an annotator; Embark reads it to pick a keymap. The two packages never talk to each other, and yet they agree on every candidate's type, because both are reading the same Emacs-standard property.
• multi-data is the raw hash table the Spotify API returned for this item: the full JSON response with every field the API exposes. Marginalia's annotator reads from it to format the margin; Embark's actions read from it to execute playback, to navigate to an album's tracks, to add to a playlist. The candidate is the full record; the name is just the visible handle. The name multi-data is spot's own designation, not a Consult or Marginalia convention (the multi- prefix is unrelated to consult--multi); any symbol would have worked. What is conventional is attaching the domain record to the candidate via propertize in the first place.

Marginalia and Embark never talk to each other. They both read the same text property on the same candidate, and that is enough.

That is the entire integration surface: One string (display name) and two props (category and metadata). Everything else (the async fetching, the narrowing, the annotation columns, the action menu) is handled by VOMPECCC, keyed on those two properties. This is a key take away for those looking to build with VOMPECCC: build your candidates like this and you will have a good time on the mountain.

This is what I meant in the first post when I called completion a substrate rather than a UI. A UI would be "here is a widget, bind data to it." A substrate is "here is a common currency (candidates with standard properties); tools that speak the currency can be mixed freely."

Consult is spot's frontdoor. It gives me three things I would otherwise have had to build from scratch: async candidate streaming, multi-source unification with narrowing keys, history, and probably other things I'm forgetting. Here is one of the seven source definitions spot uses:

(defvar spot--consult-source-track
  `(:async ,(consult--dynamic-collection
             #'spot--consult-completion-function-consult-track
             :min-input 1)
    :name "Track"
    :narrow ?t
    :category track
    :history spot--history-source-track)
  "Consult source for Spotify tracks.")

A Consult source is just a plist. The interesting keys are:

• :async is the candidate stream. consult--dynamic-collection is the de-facto extension point third-party packages have settled on for async sources, despite the double-dash that conventionally marks it internal⁴. It wraps a function that takes the current minibuffer input and returns a list of candidates. Consult handles the debouncing and the "only recompute when the input changes" logic on its side; my code just has to produce candidates for a given query. :min-input 1 prevents a search on an empty query. This is the two-level async filtering that Consult is designed around: the external tool (Spotify's API, in this case) handles the expensive filtering against its own corpus, and my completion style (Orderless, if I have it) narrows the returned set locally.
• :narrow ?t binds the narrowing key. In the video, I could have pressed t SPC when running spot-consult-search, and the session would have been scoped to tracks only, and would have avoided querying the other sources. I didn't implement narrowing; Consult did. I just declared which character maps to which source!
• :category track is the property that will propagate onto every candidate from this source. This is the same category property that spot--propertize-items stamps on individual candidates, and it is the hinge that Marginalia and Embark both key off.
• :history gives me free persistent search history for this source, isolated from the other sources.

The completion function itself is trivial because all the work happens in spot-search.el:

(defun spot--consult-completion-function-consult-track (query)
  "Return track candidates for QUERY."
  (spot--search-cached-and-locked query spot--mutex spot--cache)
  spot--candidates-track)

Seven of these functions exist, one per content type, all identical except for which global they return. The heavy lifting (the HTTP call, the cache, the propertization) is shared. Each source is effectively a view onto a single search result split by type.

Putting all seven sources together into one interface is also trivial:

(defvar spot--search-sources
  '(spot--consult-source-album spot--consult-source-artist
    spot--consult-source-playlist spot--consult-source-track
    spot--consult-source-show spot--consult-source-episode
    spot--consult-source-audiobook)
  "List of consult sources for Spotify search.")

;;;###autoload
(defun spot-consult-search (&optional initial)
  "Search Spotify with consult multi-source completion.
Optional INITIAL provides initial input."
  (interactive)
  (consult--multi
   spot--search-sources
   :history '(:input spot--consult-search-search-history)
   :initial initial))

This is the command you saw in the video. consult--multi takes the list of sources, unifies their candidates into a single list, and wires the narrowing keys. Seven heterogeneous content types, one prompt, one keystroke to filter to any subset, async throughout, with per-source history.

Without Consult I would need: a separate candidate display, an async debouncer, a narrowing mechanism, per-source history buffers, and some way to visually distinguish content types in a single list.

Compare this to the counterfactual. Without Consult I would need: a separate candidate display, an async debouncer, a narrowing mechanism, per-source history buffers, and some way to visually distinguish content types in a single list. And because Consult uses the standard completing-read contract, every minibuffer feature my Emacs already has (Vertico's display, Orderless's matching, Prescient's sorting) applies to spot with zero integration code.

I have been brushing past a detail of spot-consult.el that deserves its own section, because it is the honest cost of building on an async-on-every-keystroke substrate. consult--dynamic-collection wires the completion function to the minibuffer such that it is invoked on (a debounced version of) every keystroke the user types. For spot, each invocation issues an HTTP request to Spotify's Web API, receives a mixed-type result set, splits it across the seven global candidate lists, and returns the slice relevant to the calling source. That is the hot path. And the hot path is a rate-limited network call.

Spotify's Web API is rate-limited 🙃. Exact limits are dynamic and not publicly documented in detail, but the envelope is small enough that a rapid-typing ICR session can hit it quickly. Consider the baseline: typing radiohead fires a completion call for each prefix the user's typing pauses on (Consult's consult-async-input-debounce and consult-async-input-throttle collapse runs of keystrokes into a smaller set of actually-issued calls, but realistically that still leaves several distinct prefixes per word). Now add the common real-world pattern of typing too far, backspacing a few characters, and retyping: the same query string is re-issued within the same search session. Without a cache, each repetition burns a request, but with a cache keyed on the raw query string, repeats are actually free (or at least as cheap as a cache hit):

(defun spot--search-cached (query cache)
  "Search for QUERY, using CACHE to avoid duplicate requests."
  (when (not (ht-get cache query))
    (let ((results (spot--propertize-items
                    (spot--union-search-items
                     (spot--search-items query)))))
      (ht-set cache query results)))
  (let ((results (ht-get cache query)))
    (spot--set-search-candidates results)))

The cache is a hash table from query strings to propertized candidate lists. It lives for the life of the Emacs session, so not only backspace-and-retype within one search but also the next search session that hits the same prefix is instant. The memory cost is negligible (a few hundred candidates per query, small hash tables for each) and the request-budget win is real. And if you find yourself listening to the same music over and over, then you'll have snappier results when you go down familiar paths.

Async-on-every-keystroke against a remote corpus is the feature. A query-string cache is the bill.

This is the honest consumer tax of the substrate. The first post sold you on ICR by promising that the interaction scales constantly regardless of how big the underlying corpus gets. That claim depends on async sources that fire on every keystroke against a remote corpus, and that in turn means you as package author inherit rate-limit pressure your users never see. Consult gives you the debouncer, the display, the narrowing keys, and the stale-response discarding on its side of the protocol. The cache is what you owe back on your side when your candidate source is a rate-limited network API rather than a local list, and it is exactly the kind of infrastructure that does not belong in Consult itself (because Consult has no way to know your backend is rate-limited, or which queries are equivalent enough to cache together).

If you watch the video carefully, each track in the candidate list is followed by a horizontally aligned column of fields: #<track-number>, artist, a M:SS duration, album name, album type, release date. Each field is rendered to a fixed width in its own face, so numbers and dates and names land as visually distinct columns rather than getting mashed together with a delimiter. Small glyph prefixes (# for counts, ★ for popularity, ♥ for followers) disambiguate otherwise bare numbers. That column is provided by Marginalia, and it comes from one function:

(defun spot--annotate-track (cand)
  "Annotate track CAND with number, artist, duration, album, type, and date.
The track number is prefixed with `#' and duration rendered as M:SS."
  (let ((data (get-text-property 0 'multi-data cand)))
    (marginalia--fields
     ((spot--format-count (ht-get data 'track_number))
      :format "#%s" :truncate 5 :face 'spot-marginalia-number)
     ((spot--annotation-field (spot--first-name (ht-get data 'artists)))
      :truncate 25 :face 'spot-marginalia-artist)
     ((spot--format-duration (ht-get data 'duration_ms))
      :truncate 7 :face 'spot-marginalia-number)
     ((spot--annotation-field (ht-get* data 'album 'name))
      :truncate 30 :face 'spot-marginalia-album)
     ((spot--annotation-field (ht-get* data 'album 'album_type))
      :truncate 8 :face 'spot-marginalia-type)
     ((spot--annotation-field (ht-get* data 'album 'release_date))
      :truncate 10 :face 'spot-marginalia-date))))

The first line is the only plumbing: (get-text-property 0 'multi-data cand) pulls the full Spotify API response off the candidate (exactly the hash table spot--propertize-items stashed earlier), and everything after it is Marginalia's own marginalia--fields macro doing the formatting. marginalia--fields handles the alignment, the per-field truncation, and the face application. The only thing my code does is declare which fields of the Spotify payload go in which columns with which faces. This is another substrate borrow hiding in plain sight: Marginalia registers the annotator and formats its output. I never wrote a single character of alignment, padding, or colourisation logic. The annotator reached into multi-data for its fields, Marginalia's macro did the cosmetic work, and Marginalia never had to know about Spotify's data model.

spot ships seven annotators. Each one is a domain-specific projection of a single Spotify response type onto a display string. Albums surface artist, release date, and track count, artists surface popularity and follower count, shows surface publisher, media type, and episode count; and all this context is really important, especially if you are 'browsing'. The annotators are independent of the search code, independent of the actions code, and independent of each other.

Registering them with Marginalia is three lines of bookkeeping:

(defvar spot--marginalia-annotator-entries
  '((album spot--annotate-album none)
    (artist spot--annotate-artist none)
    (playlist spot--annotate-playlist none)
    (track spot--annotate-track none)
    (show spot--annotate-show none)
    (episode spot--annotate-episode none)
    (audiobook spot--annotate-audiobook none))
  "List of marginalia annotator entries registered by spot.")

(defun spot--setup-marginalia ()
  "Register spot annotators with marginalia."
  (dolist (entry spot--marginalia-annotator-entries)
    (add-to-list 'marginalia-annotators entry)))

The spot--marginalia-annotator-entries list keys on the category symbol (album, artist, and so on), the very same symbols the Consult sources stamp onto their candidates. Marginalia looks up the category of the current candidate in marginalia-annotators, finds the entry, and runs the annotator. No spot code is in that path. I only had to declare the mapping.

This is where one of the most interesting benefits of the second post shows up concretely. That post mentioned that because Marginalia annotations are themselves searchable, Orderless's @ dispatcher lets you match against annotation text. spot did not ship this feature. Orderless and Marginalia did, for free, because I stamped the annotation onto the candidate in the right way.

The third leg of spot's tripod is Embark. In the video, pressing the Embark action key on any candidate surfaces a menu of single-letter actions appropriate to that kind of candidate: P plays it, s shows its raw data, t lists its tracks (on albums and artists), + adds it to a playlist (on tracks). Each of those actions is a one-function definition in spot-embark.el, and their binding to candidates is declarative.

The simplest action is play:

(defun spot-action--generic-play-uri (item)
  "Play the Spotify item represented by ITEM."
  (let* ((table (get-text-property 0 'multi-data item))
         (type (ht-get table 'type))
         (offset (cond
                  ((string= type "track") `(("uri" . ,(ht-get* table 'uri))))
                  ((string= type "playlist") '(("position" . 0)))
                  ((string= type "album") '(("position" . 0)))
                  ((string= type "artist") nil)))
         (context_uri (cond
                       ((string= type "track") (ht-get* table 'album 'uri))
                       ((string= type "playlist") (ht-get* table 'uri))
                       ((string= type "album") (ht-get* table 'uri))
                       ((string= type "artist") (ht-get* table 'uri))))
         ...
         (spot-request-async
          :method "PUT"
          :url spot-player-play-url ...))))

Same pattern as the annotators: (get-text-property 0 'multi-data item) pulls the full hash table off the candidate, and the rest is Spotify domain logic. Embark invokes my action with the candidate that was highlighted; my action handles the HTTP.

The keymap wiring is also just bookkeeping:

(defvar-keymap spot-embark-track-keymap
  :parent embark-general-map
  :doc "Keymap for Spotify track actions.")

;; ... one keymap per content type ...

(defvar spot--embark-keymap-entries
  '((album . spot-embark-album-keymap)
    (artist . spot-embark-artist-keymap)
    (playlist . spot-embark-playlist-keymap)
    (track . spot-embark-track-keymap)
    (show . spot-embark-show-keymap)
    (episode . spot-embark-episode-keymap)
    (audiobook . spot-embark-audiobook-keymap)
    ...))

(dolist (map (list spot-embark-artist-keymap spot-embark-album-keymap
                   spot-embark-playlist-keymap spot-embark-track-keymap
                   ...))
  (define-key map "s" #'spot-action--generic-show-data)
  (define-key map "P" #'spot-action--generic-play-uri))

(define-key spot-embark-track-keymap "+" #'spot-action--add-track-to-playlist)
(define-key spot-embark-album-keymap  "t" #'spot-action--list-album-tracks)
(define-key spot-embark-artist-keymap "t" #'spot-action--list-artist-tracks)
(define-key spot-embark-playlist-keymap "t" #'spot-action--list-playlist-tracks)

Again, the key keys off category. Embark looks up the current candidate's category in embark-keymap-alist, finds the matching keymap, opens it. Every layer of this integration is the same trick: a candidate carries a category property, and the substrate routes based on it. All three VOMPECCC packages, working on the same candidates, sharing the same category convention, never importing each other.

Both registries (Marginalia's annotator alist and Embark's keymap alist) plus the two background timers (mode-line updates and access-token refresh) get installed and uninstalled in one place:

;;;###autoload
(define-minor-mode spot-mode
  "Global minor mode for the spot Spotify client.
Registers embark keymaps, marginalia annotators, starts the
mode-line update timer, and starts a periodic access-token
refresh timer when enabled.  Cleanly removes all integrations
when disabled."
  :global t
  :group 'spot
  (if spot-mode
      (progn
        (spot--setup-embark)
        (spot--setup-marginalia)
        (spot--start-update-timer)
        (spot--start-refresh-timer))
    (spot--teardown-embark)
    (spot--teardown-marginalia)
    (spot--stop-update-timer)
    (spot--stop-refresh-timer)))

This is the entire integration layer. Toggle the mode, spot's categories appear in Marginalia and Embark and the two timers begin ticking. Toggle it off, they all disappear. No global state mutation escapes the teardown path.

And by the way, a user who never installs Marginalia or Embark still gets a working spot; the setup functions no-op gracefully (all they do is add-to-list against someone else's variable), that user just doesn't get annotations or actions. The "stack what you want, subset what you don't need" property of VOMPECCC propagates through to spot as a consumer: the package is graceful under any subset of VOMPECCC.

To see what spot isn't building, look at the negative space.

A pre-VOMPECCC Spotify client (see smudge for an example that predates the modern completion ecosystem) has to build the UI itself: a tabulated-list-mode buffer with its own keymap, its own rendering code, its own pagination, its own selection logic. That approach works and can work well. But the cost is structural: a bespoke UI is a parallel universe of interaction that does not benefit from any completion infrastructure the user has already invested in. You have to learn its bindings, and frustratingly, these don't carry over to any other Emacs tool.

The architecture was entirely reasonable when there was nothing else to build on. The point here is purely structural: once the substrate exists, reinventing the UI on top of it is a strictly larger codebase that delivers a strictly less interoperable experience. spot is about 1,100 lines of Lisp, and its interface, as we've shown, is closer to 420 lines of Lisp. A pre-substrate equivalent is many times that, and much of the delta is code implementing things (display, filtering, selection, action menus) that Consult, Marginalia, and Embark implement once, centrally, for every completion-driven command in the user's Emacs.

This is the gap the first post was pointing at when it distinguished using completion from building on completion. A package that uses completion is a consumer of completing-read. A package that builds on completion assumes the existence of a richer substrate (async sources, categorized candidates, annotator hooks, action keymaps) and contributes into that substrate rather than rebuilding around it.

Three things follow.

First, the cost of building an ICR-driven app collapses once the substrate exists. spot is about 1,100 lines including OAuth, token refresh, HTTP, caching, the mode-line, and the integration glue. The three VOMPECCC files (spot-consult.el, spot-marginalia.el, spot-embark.el) are together under 500 lines, much of it boilerplate per content type. A feature-competitive pre-VOMPECCC Spotify client would easily have been several thousand lines larger.

Second, composition is the feature, not the packages. The list-album-tracks action is the most important ten lines in the repository, not because of what it does (a Spotify query), but because of what it demonstrates: an Embark action on a Consult candidate launching a new Consult session in the same substrate. Every ICR-driven package in your Emacs configuration that shares this substrate composes with every other one. embark-export on a spot result set could, in principle, produce a native mode for Spotify results, the same way it produces Dired from file candidates or wgrep from ripgrep hits. The composability is a property of the substrate, not of any individual package.

Third, the category property is doing an enormous amount of load-bearing work. Three different packages, each knowing nothing about the others, all agree on the right behavior for every candidate because they are keying off the same standardized property 'category. The "text" in the protocol is (candidate . (category . metadata)), and every tool that speaks the protocol interoperates for free.

spot is specifically a Spotify client, but nothing about the recipe it follows is Spotify-specific. Strip the domain out and what remains is a six-step shape that applies to an enormous fraction of the services and data sources you interact with daily:

1. An API or backend that returns typed items: each item has a type discriminator and a bag of metadata.
2. A candidate-constructor (the spot--propertize-items analogue) that turns those items into completion candidates with a category text property and a multi-data payload.
3. A Consult source per type, async, with a narrow key, all unified under a consult--multi entry point.
4. A Marginalia annotator per type, keyed on category, reading the multi-data payload for its domain metadata.
5. An Embark keymap per type, keyed on category, binding single-letter actions that operate on the multi-data payload.
6. A minor mode that installs and uninstalls the three registries together. This one can even be optional, but I recommend doing it.

Any domain that fits that shape can be built the same way. The thought exercise from the first post (which of your daily tools reduces to "pick a thing, act on it" over a typed corpus?) has a lot of concrete answers: issue trackers, cloud consoles, email, chat, package managers, news feeds, knowledge bases, code hosting. Two worked examples are enough to sketch the altitude:

• Issue trackers. Types are issue / epic / comment / user, metadata is status / assignee / priority / labels, actions are transition / assign / comment / close.
• Code hosting. consult-gh already does the GitHub version. Types are repo / PR / issue / branch / release / user, metadata is state / author / date / counts, actions are clone / checkout / review / merge / close.

Several domains already ship as working packages: consult-gh, consult-notes, consult-omni, consult-tramp, consult-dir, and many others. None of these packages ships a UI; they all (roughly) follow the same six-step recipe spot follows, and each one composes with every other one automatically.

The more interesting exercise is the shape of domains that don't cleanly fit. The pattern starts to strain when items aren't naturally enumerable, or when the right interaction is a canvas rather than a list (a map, a timeline, a dependency graph). Those cases need something more than ICR. What I find remarkable is how often even those interfaces still have an ICR-shaped core (pick a location on the map, pick a node on the graph, pick a frame on the timeline), which could be delegated to the substrate while the custom-UI parts focus on what genuinely needs rendering.

The concrete-enough test I apply to any new Emacs workflow I'm considering building: can I express it as a Consult source, a Marginalia annotator, and an Embark keymap? If yes, the package will be mostly a client of the VOMPECCC API. If no, the package needs custom UI, and I should be deliberate about which parts genuinely do and which parts could still be delegated. spot is the case where the answer is a clean "yes across the board", but I've found that more often than not, the answer is yes for the first draft.

This post took a working application and showed what the argument looks like when you cash it in.

If there is one thing I want a reader to take away from the series, it is the reframe. Completion is not a convenience feature you turn on and forget about. It is the primitive on which a surprising fraction of your Emacs interaction either already runs or could run, if you let it. Packages that treat it that way end up smaller, more interoperable, and more amenable to composition than packages that treat it as one feature among many. spot is one example.

The broader claim, which I will leave you with, is that "packages that do one thing" is the lazy reading of the Unix philosophy. The sharper reading is "packages that contribute into a shared substrate." Unix pipes were never interesting because each command was small; they were interesting because every command produced and consumed plain text. VOMPECCC is interesting for the same reason, with candidates-with-properties instead of plain text. spot was easy to write because the substrate is good. Many things in your Emacs configuration could be rewritten today as "ICR applications on the substrate" and would be smaller, cleaner, and more composable as a result.

When you next find yourself thinking "I wish there were a better way to browse X", ask whether it could just be a Consult source, a Marginalia annotator, and an Embark keymap. Surprisingly often, that is the entire package, and all you have to do is feed it data.

spot is a Spotify client for Emacs that implements no custom UI. About 493 of its ~1,100 lines are the "shim" that feeds candidates into Consult, Marginalia, and Embark via a single text-property pattern (category plus multi-data); the remaining ~635 are plumbing any Spotify client would need regardless of UI. The six-step recipe (typed items → propertize → Consult source per type → Marginalia annotator per type → Embark keymap per type → minor mode) generalizes to issue trackers, cloud consoles, email, chat, knowledge bases, and more, many of which already ship as working packages (consult-gh, consult-notes, consult-omni). The claim the series has been building toward: when the substrate is good, ICR applications collapse to their domain logic, and "packages that contribute into a shared substrate" is the sharper reading of the Unix philosophy.

Completion is not a feature or UI, but instead it is a system composed of at least half a dozen orthogonal concerns that most users never think about separately. The previous post in this series argued that Emacs uniquely exposes completion as a programmable substrate rather than a sealed UI, and that this substrate is what makes Incremental Completing Read (ICR) viable as a primary interaction pattern in Emacs. This post is about the packages that build on that substrate in practice.

VOMPECCC is a loose acronym for eight of them that, together, form a complete, modular, Unix-philosophy-aligned completion framework for Emacs: V​ertico, O​rderless, M​arginalia, P​rescient, E​mbark, C​onsult, C​orfu, and C​ape. Each package does one thing, and the key attribute of all eight is that they compose through Emacs's standard completion APIs, meaning any subset works without the others.

I'm writing this post because these packages have recently taken the Emacs community by storm, but I rarely see discussions on how they relate or how they compose together to provide a feature complete ICR system in emacs. These packages implement concretely what the antecedent post argues in the abstract: completion is a substrate, or set of primitives, on top of which users can build rich interfaces for effortlessly interacting with your machine to do almost anything.

Even if you've only used Emacs once, you've likely seen its completion features in action. When you press M-x and start typing, a list appears, you pick something, and it runs. But beneath that interaction lies a system of surprising depth. Consider what a fully featured completion experience actually requires:

Candidate display. Where do completion candidates appear? In the minibuffer, vertically? Horizontally? In a separate buffer? In a popup at point? The display layer determines how you scan and navigate candidates, and of course the optimal display is context dependent. Switching buffers might want a vertical list; completing a symbol in code might want a popup near the cursor.

Filtering. You can also think of this as 'matching': how does your input match against candidates? Literal prefix matching is the simplest: find-f matches find-file. But if we want to add some flexibilty (or 'fuzzy matching'), where for examplke ff matches find-file? What about splitting your input into multiple components and matching all of them in any order? What about mixing strategies, for example, where one component matches as a regexp, and another matches as an initialism? Candidate lists can be huge, so we need this set of features as a sort of query language for filtering the candidate list to find what we're looking for.

Sorting. Once you have your filtered candidates, in what order do you see them? Alphabetically? By string length? By how recently you selected them? By frequency of use? A good sorting strategy means the candidate you want is almost always within the first few results. A bad one means scrolling every time.

Annotation. A bare list of candidate names is often insufficient or unhelpful. Often, candidates are of a certain 'type' or 'category' and have rich metadata associated with them. In the M-x example, when selecting a command, you likely want to see its keybinding and docstring. When selecting a file, you likely want to see its size and modification date. When selecting a buffer, you want to see its major mode and file path. Annotations transform a list of strings into a list of informed choices.

Actions. Selecting a candidate (and running some default action) is the most common interaction, but not the only one. In the find-file example, what if you want to delete the file instead of opening it? In the M-x example, what if you want to describe the function instead of running it? A completion system without contextual actions forces you out of the flow: complete, exit, invoke a separate command, etc….

In-buffer completion. Everything above applies to the minibuffer (the prompt at the bottom of the screen). But completion also happens inside buffers: symbol completion while writing code, dictionary words while writing prose, file paths while editing configuration. In-buffer completion has its own display requirements (a popup near the cursor, not the minibuffer) and its own backend requirements (language servers, dynamic abbreviations, file system paths). A truly complete completion system must handle both contexts well.

Completion is not one problem. It is at least six, and most frameworks pretend otherwise.

These six concerns are orthogonal. The way you display candidates has nothing to do with how you filter them; the way you sort them has nothing to do with what actions you can take, etc…. It's actually a useful thought exercise to go through each of the six concerns and appreciate how each is independent from the others. A single-package system can deliver an excellent out-of-the-box experience across all of these, and many have (see Ivy and Helm below). The trade-off is usually that the boundaries between concerns become harder to see, and harder to swap one concern's implementation without disturbing the others.

For the better part of a decade, two incredible frameworks dominated Emacs completion: Helm and Ivy. Both were genuinely transformative, because in my opinion, they proved that Emacs's built-in completion experience was inadequate, and they inspired everything that followed. But both, in retrospect, made the same architectural trade-off: they bundled every concern into a single package with a single API. I have used both packages extensively, as both a package author and a consumer. The benefits were immediate for me, but the costs emerged over time.

VOMPECCC is not a framework in the traditional sense. There is no single repository, no shared dependency, and no coordinating package. It is eight independent packages, maintained by three different developers, that compose through Emacs's standard APIs to cover every concern of a complete completion system.

The architecture maps cleanly onto the six concerns identified earlier:

                Minibuffer                     Buffer
                ----------                     ------
Display:        Vertico                        Corfu
Filtering:      Orderless          (shared across both)
Sorting:        Prescient          (shared across both)
Annotations:    Marginalia         (shared across both)
Actions:        Embark             (shared across both)
Backends:       Consult                        Cape

Each package targets a single layer, and they all communicate through standard Emacs APIs: completing-read, completion-styles, completion-at-point-functions, annotation functions, and keymaps. No package knows about the others' internals ‼️, and because of this all of them can be replaced without affecting the rest.

Vertico (VERTical Interactive COmpletion) provides a vertical candidate list in the minibuffer. It is roughly 600 lines of code, excluding its extensions.

Vertico's defining characteristic is strict adherence to the completing-read contract. It doesn't filter candidates (that's your completion style's job). It doesn't sort them (that's your sorting function's job). It doesn't annotate them (that's your annotation function's job). It just displays them. Any command that calls completing-read, whether built-in or third-party, automatically gets Vertico's UI with zero configuration.

If you think 1 package for display is overkill, like I originally did before migrating to VOMPECCC, keep reading.

Vertico ships with 13 built-in extensions that modify the display behavior:

The vertico-multiform extension is particularly worth configuring: it lets you set per-command display modes, so consult-line can open in a full buffer while M-x stays in the minibuffer.

Created: April 2021. Stars: ~1,800. Available on: GNU ELPA.

Orderless is a completion style — it plugs into Emacs's completion-styles variable, the standard mechanism for controlling how user input is matched against candidates. Where built-in styles like basic require prefix matching and flex does single-pattern fuzzy matching, Orderless splits your input into space-separated components and matches candidates that contain all components in any order (Orderless reveals its namesake 😜).

Each component can independently use a different matching method:

Style dispatchers let you select a matching method per component using affix characters: =​= for literal, ~ for flex, , for initialism, ! for negation, & to match annotations. The system is fully extensible.

The typical configuration sets completion-styles to '(orderless basic), with partial-completion for the file category so that ~/d/s expands path components like ~/Documents/src. The fallback to basic is deliberate: some Emacs features (TRAMP hostname completion, dynamic completion tables) require a prefix-matching style.

Let's keep beating the dead horse of this post's theme: because Orderless is a standard completion style, it works with any completion UI that uses Emacs's completing-read API: Vertico, Icomplete, the default *Completions* buffer, and even the minibuffer in Emacs's stock configuration.

Quick timeout: for readers getting to this point thinking "Wow Vertico plus Orderless is a power stack, let's keep stacking", you certainly can see things this way, but instead, I encourage you to consider what it would be like to use each package without the others. That will give you a better understanding of how the consituent stars in the VOMPECCC constellation behave independently. And that's the long term ROI you'll get from VOMPECCC. The independence is what makes stacking safe and fortuitous, but it doesn't make it necessary.

Created: April 2020. Stars: ~979. Available on: GNU ELPA.

Marginalia adds contextual annotations to minibuffer completion candidates. The name refers to notes written in the margins of books, and here it means metadata displayed alongside each candidate.

Marginalia detects the category of the current completion (files, commands, variables, faces, buffers, bookmarks, packages, etc.) and selects an appropriate annotator function. The detection works through two mechanisms: marginalia-classify-by-command-name (lookup table keyed by calling command) and marginalia-classify-by-prompt (regex matching against the minibuffer prompt text).

marginalia-cycle (typically bound to M-A) lets you cycle between annotation levels: detailed, abbreviated, or disabled entirely. This is useful when annotations are consuming screen space during narrow completions.

Marginalia hooks into Emacs's annotation-function and affixation-function properties in completion metadata. Sorry again to the dead horse I've been wailing on, but yes, this means Marginalia works with any completion UI that respects these properties. It is the framework-agnostic successor to ivy-rich⁸, which provided similar annotations but was Ivy-specific. It's cool to see Oleh and Thierry's visions carry on in these packages!

This was a mind blower to me when I discovered it - one subtle but consequential effect of using Marginalia is that the annotations themselves become searchable. Combined with Orderless's & style dispatcher, your input can match against annotation text as well as candidate names: running M-x and typing window &frame narrows to commands whose name contains "window" and whose docstring contains "frame". The search/matching space extends beyond candidate identifiers into candidate metadata, which is an unusually large leverage gain for what feels like a cosmetic layer. You are no longer constrained to remembering exact names (🤯); you can reach for commands, files, or buffers by properties that were previously invisible to your completion input. This helps to solve for cases where you have a ICR UI, but you don't know exactly what you're looking for. It can also be used to help you 'browse' candidates based on their characteristics as opposed to their names. Honestly my favorite feature of any of the VOMPECCC packages.

Created: December 2020. Stars: ~919. Available on: GNU ELPA.

Prescient provides intelligent sorting and filtering of completion candidates based on recency and frequency of use. The portmanteau frecency captures the combined metric that drives the ranking.

Orderless and Prescient are often confused with one another: the difference is that while Orderless answers "which candidates match?", Prescient answers "in what order should they appear?"

The sorting is hierarchical:

1. Recency — most recently selected candidates appear first
2. Frequency — frequently selected candidates next, with scores that decay over time
3. Length — remaining candidates sorted by string length (shorter first)

Usage statistics persist across Emacs sessions via prescient-persist-mode, which writes to a save file. This means Prescient learns your habits: if you frequently run magit-status from M-x, it surfaces near the top after a few uses, regardless of where it falls alphabetically.

Prescient ships as a core library plus framework-specific adapters — vertico-prescient and corfu-prescient being the relevant ones for VOMPECCC. A key architectural insight is that both Vertico and Corfu work seamlessly with Prescient.

A common and powerful configuration combines Orderless for filtering with Prescient for sorting. Among the candidates filtered by Orderless, the most recent and frequent ones get promoted to the top.

Prescient also provides its own filtering methods (literal, regexp, initialism, fuzzy, prefix, anchored) with on-the-fly toggling via M-s prefix commands. However, I personally prefer Orderless for filtering and use Prescient purely for its sorting intelligence. I sort of act as if Prescient was cohesive in this way, rather than giving it responsibility for 2 orthogonal features.

Created: August 2017. Stars: ~695. Available on: MELPA.

Embark provides a framework for performing context-aware actions on "targets" — the thing at point or the current completion candidate. Think of it as a keyboard-driven right-click context menu that works everywhere in Emacs: in the minibuffer and in normal buffers.

The core command is embark-act. When invoked, Embark determines the type of the target (file, buffer, URL, symbol, command, etc.) and opens a keymap of single-letter actions appropriate to that type:

There are over 100 preconfigured actions across all target types.

Beyond embark-act, Embark provides several other capabilities:

• embark-dwim runs the default action without showing the menu
• embark-act-all applies the same action to every current candidate (e.g., kill all matching buffers)
• embark-collect snapshots current candidates into a persistent buffer
• embark-live creates a live-updating collection that refreshes as you type
• embark-export exports candidates into the appropriate Emacs major mode: file candidates become a Dired buffer, grep results become a grep-mode buffer (editable with wgrep), buffer candidates become an Ibuffer buffer
• embark-become switches to a different command mid-stream, transferring your input

Two of these deserve special attention, because they change what a completion session is.

embark-collect freezes the current candidate set into a standalone buffer that persists after the minibuffer exits. This converts an ephemeral interaction (browse, pick, leave) into something durable (collect, hand off, revisit later). The collected buffer remains an Embark target, so the same keymap of actions applies to each entry. It is the right tool when the candidate list itself is the useful artifact: a shortlist of files to process, a set of buffers you want to act on later, a reference you want to keep open on the side.

embark-export goes one step further: instead of a generic candidate buffer, it materializes a buffer in the native major mode appropriate to the candidate type. File candidates become a Dired buffer, with Dired's decades of filesystem operations available. Grep-style candidates become a grep-mode buffer that wgrep can turn into a multi-file editing session, buffer candidates become Ibuffer, package candidates become the package menu, etc…. Each export targets a major mode purpose-built for the candidate type, so you end up inside the tool that was already the best one for the job, arrived at on demand, from a completion prompt, with no navigation overhead. Few interaction patterns in computing convert generic into specialized this cleanly.

Embark is a difference of kind, not quantity, compared to Helm and Ivy's action systems — because it works everywhere, across all types of objects⁹.

Using embark and consult together we can see a canonical example of this pattern: exporting consult-ripgrep results gives you a wgrep-editable grep buffer, so the workflow — search with Consult, export with Embark, edit with wgrep — compounds three independent packages into a multi-file refactor tool without any of them knowing about the others.

Created: May 2020. Stars: ~1,200. Available on: GNU ELPA.

Consult provides 50+ enhanced commands built on completing-read. It is the spiritual successor to Counsel (from the Ivy ecosystem) but designed to work with any completion UI. Where Counsel called ivy-read directly, Consult uses the native contract, which means its commands work with Vertico, Icomplete, fido-mode, or even Emacs's default completion buffer.

Consult's commands span several categories:

Search:

Navigation:

Editing and miscellaneous:

Three features make Consult particularly powerful:

Live preview: Most commands show a real-time preview as you navigate candidates. consult-line highlights the matching line in the buffer. consult-theme applies the theme before you select it. consult-goto-line scrolls to the line as you type the number.

Narrowing and grouping: consult-buffer combines buffers, recent files, bookmarks, and project items into a single unified list. Narrowing keys filter to a single source: b SPC for buffers, f SPC for files, m SPC for bookmarks. Custom sources can be added via consult-buffer-sources.

Two-level async filtering: Commands like consult-ripgrep split input at #: everything before it goes to the external tool as the search pattern, everything after it filters the results locally with your completion style. error#handler searches for "error" with ripgrep, then narrows to results containing "handler" using Orderless. Async support is an enormously important feature, because it makes the cognitive cost of search roughly constant with respect to the size of the search space.

Created: November 2020. Stars: ~1,600. Available on: GNU ELPA.

Corfu (COmpletion in Region FUnction) is simply the in-buffer counterpart to Vertico. Where Vertico handles minibuffer completion display, Corfu handles the popup that appears at point when you complete a symbol while writing code or text. It is roughly 1,220 lines of code.

Corfu's defining architectural choice mirrors Vertico's: it hooks into Emacs's built-in completion-in-region mechanism rather than inventing its own backend system. Any mode that provides a completion-at-point-function (Eglot, Tree-sitter, elisp-mode, etc.) works with Corfu automatically. Any completion-style (basic, partial-completion, orderless) can be used for filtering.

This is the fundamental difference from Company, the incumbent in-buffer completion framework¹⁰. Company uses its own proprietary company-backends API. Company backends don't work with completion-at-point, and Capfs don't work with Company (without an adapter). Anecdotally, I've had many wrestling matches with Company and always found it incredibly difficult to set up properly. Corfu eliminates this split. Doom Emacs recognized this: Company is now deprecated in Doom in favor of Corfu, with plans to remove it post-v3¹¹.

Corfu ships with seven built-in extensions:

Created: April 2021. Stars: ~1,400. Available on: GNU ELPA.

Cape (Completion At Point Extensions) provides a collection of modular completion backends (Capfs) and a powerful set of Capf transformers for composing and adapting them. If Corfu is the frontend (how completions are displayed), Cape is the backend toolkit (what completions are available).

Cape provides 13 completion backends, here are some highlights:

The remaining backends cover dictionary words, emoji, abbreviations, line completion, and Unicode input via TeX, SGML, and RFC 1345 mnemonics.

Cape's Capf transformers are higher-order functions that wrap and modify backends:

• cape-capf-super merges multiple Capfs into a single unified source
• cape-capf-case-fold adds case-insensitive matching
• cape-capf-inside-code / cape-capf-inside-string / cape-capf-inside-comment restrict activation to specific syntactic regions
• cape-capf-prefix-length requires a minimum prefix before activating
• cape-capf-predicate filters candidates with a custom predicate
• cape-capf-sort applies custom sorting

The cape-company-to-capf adapter converts any Company backend into a standard Capf, without requiring Company to be installed. This bridges the two ecosystems: you can use Company-era backends (like company-yasnippet) with Corfu. I don't personally do this, but you can if you want!

Created: November 2021. Stars: ~760. Available on: GNU ELPA.

The most important property of VOMPECCC is that you don't need to buy into all eight packages. You can start with one, add another when you feel a gap, and swap any component for an alternative without breaking anything else.

If you're into inverting dependencies, VOMPECCC is your bag, man.

This works because every package communicates through the native Emacs APIs rather than depending on each other's internals. There are no hard dependencies between any of the eight packages. Here is a map of what each package can be replaced with — or simply omitted:

Some practical subset configurations:

Minimal (2 packages): Vertico + Orderless. You get a vertical candidate list with multi-component matching. No annotations, no actions, no enhanced commands — but a dramatically better M-x and find-file experience than stock Emacs.

Comfortable (4 packages): Vertico + Orderless + Marginalia + Consult. Now you have annotations on every candidate and enhanced commands with live preview. This is probably the sweet spot for most users.

Full stack (8 packages): All of VOMPECCC. Complete coverage of both minibuffer and in-buffer completion, with intelligent sorting, contextual actions, and modular backends.

For concrete configuration, the most reliable starting point is each package's own repository — every package linked in the opener ships a comprehensive README with example use-package snippets, and most also provide wikis or info manuals covering more specialized use cases (Vertico's per-command vertico-multiform patterns, Cape's Capf transformer recipes, Embark's keymap customization examples, Consult's custom sources, and so on). Reading those directly is faster than copying a consolidated configuration and then reverse-engineering what each line does, and it scales better as the packages themselves evolve.

The history of Emacs completion frameworks is a progression from monolithic solutions toward composable ones.

Helm and Ivy accumulated stars over a longer period; the newer packages are growing faster relative to their age (counts as of early 2026):

The community momentum is clear. Doom Emacs, one of the most popular Emacs distributions, has moved to Vertico + Corfu as its defaults¹². Modern configuration guides almost universally recommend the modular stack¹³. And the upstream Emacs project itself has been integrating ideas from this ecosystem: Emacs 30 added completion-preview-mode, and Emacs 31 is incorporating Mct-inspired features (they love Prot, and for good reason, lol).

Engineering is about trade-offs. The modular approach has real advantages, but it does have costs, so I want to be honest about them:

I came to this stack the way most people probably do: one package at a time, over the course of a year or so. I started with Vertico and Orderless because my Ivy config had started fighting with Emacs 28 upgrades and I was tired of debugging someone else's ivy-read edge cases. Two packages, ten minutes of configuration, and M-x already felt better. Marginalia came next for me. Once you've seen keybindings and docstrings next to every command, you can't unsee their absence. Consult replaced Counsel, Embark replaced the "type search string, exit completion, run a different command" waltz, and Corfu replaced Company when I realized the same Orderless filtering I'd grown to depend on in the minibuffer wasn't available in my code buffers.

The whole migration happened very incrementally, which was incidental for me, but is the point of this post. I never sat down to "install VOMPECCC." I solved one friction at a time, and each solution composed with the ones I already had. That's the experience the architecture is designed to produce.

Nobody really calls it VOMPECCC in Emacs circles, it is a mnemonic used here for the sake of an article rather than an established term. But the packages it describes have quietly become the default recommendation for modern Emacs completion, adopted by Doom Emacs, recommended by Protesilaos Stavrou¹⁴, documented by System Crafters¹⁵, and built on by a growing ecosystem of third-party packages.

The shift from Helm to Ivy to the modular stack follows a familiar pattern in software: monoliths are convenient until they aren't. Composable tools with clear interfaces outlast the frameworks that try to be everything¹⁶. Emacs figured this out forty years ago, and the modular stack described here is what completion looks like once you treat it as a substrate, the raw material on top of which you build Incremental Completing Read interactions, rather than as a finished product the vendor hands you. Its completion ecosystem just needed a few years to catch up.

Emacs completion is not one problem but at least six orthogonal concerns: display, filtering, sorting, annotation, actions, and in-buffer completion. For a decade, Helm and Ivy delivered excellent experiences but bundled everything behind proprietary APIs, creating vendor lock-in and maintenance fragility. VOMPECCC names eight independent packages — Vertico, Orderless, Marginalia, Prescient, Embark, Consult, Corfu, and Cape — that each address a single concern and compose through Emacs's native completing-read contract rather than custom APIs. Because no package depends on another's internals, any subset works on its own and any component can be replaced without breaking the rest. The community has moved decisively toward this modular stack, with Doom Emacs switching its defaults to Vertico and Corfu. There are real trade-offs — higher discovery cost and distributed configuration — but the architecture pays off in durability, auditability, and incremental adoption.

• r/softwarearchitecture VOMPECCC: A Modular Completion Framework for Emacs
• r/programming VOMPECCC: A Modular Completion Framework for Emacs
• r/emacs VOMPECCC: A Modular Completion Framework for Emacs
• VOMPECCC: A Modular Completion Framework for Emacs
• VOMPECCC: A Modular Completion Framework for Emacs

My terminal emulator of choice is WezTerm which already supports bidirectional kill & yank out of the box.

But I can't bring my muscle memory to remember to use Ctrl+Shift+V to yank text in Emacs. I want Ctrl+y​/​C-y, like I'm used to.

Luckily .wezterm.lua lets us catch Ctrl+y and yank the clipboard contents into the terminal and with that into Emacs.

local wezterm = require 'wezterm'

local config = wezterm.config_builder()

config.keys = {
    -- Paste in Emacs using regular key bindings
    {
      key = "y",
      mods = "CTRL",
      action = wezterm.action.PasteFrom "Clipboard",
    },
}

return config

For those wanting to run Emacs in a local terminal WezTerm provides yank out of the box but not kill. To kill text from Emacs into the local clipboard we need to use xclip.

The xclip package has an auto-detect function but it has some issues.

• if it finds xclip or xsel it will use them even if we are on Wayland
• it can't detect MacOS (darwin)

So I decided to set the xclip-method manually. In addition I use the :if option of use-package to limit loading the package only when we are in the terminal, an xclip-method was found and we aren't using ssh.

(defun tjkl/xclip-method ()
  (cond
   ((eq system-type 'darwin) 'pbpaste)
   ((getenv "WAYLAND_DISPLAY") 'wl-copy)
   ((getenv "DISPLAY") 'xsel)
   ((getenv "WSLENV") 'powershell)
   (t nil)))

(use-package xclip
  :if (and (not (display-graphic-p))
           (not (getenv "SSH_CONNECTION"))
           (tjkl/xclip-method))
  :custom
  (xclip-method (tjkl/xclip-method))
  :config
  (xclip-mode 1))

It is possible to use OSC-52 (Output/Escape Sequences) in a local WezTerm terminal without the xclip package and cli tool.
The problem with this approach is that we can't work with terminal and GUI Emacs using the same session. Since interprogram-cut-function is global it will also try to use OSC52 in the GUI Emacs and fail with the message progn: Device 1 is not a termcap terminal device.

I have not yet found a good way to restore GUI yank functionality once interprogram-cut-function is set. So the following should only be used if the GUI instance doesn't use the same session or if the GUI is never opened after terminal Emacs.

(unless (display-graphic-p)
  (defun tjkl/osc52-kill (text)
    (when (and text (stringp text))
      (send-string-to-terminal
       (format "\e]52;c;%s\a"
               (base64-encode-string text t)))))
  (setq interprogram-cut-function #'tjkl/osc52-kill))

ICR is not a convenience feature. It is a structural change in how the cost of an interaction scales with the size of the underlying data.

The argument I want to make is sharper than it sounds. Incremental completing read (ICR) is not a convenience feature. It is a structural change in how the cost of an interaction scales with the size of the underlying data; it is one of the few interface patterns that genuinely respects how human memory works; and it can fortuitously change how you organize your data, not just how you retrieve it.

A brief thought exercise reveals how a surprisingly large fraction of all software — email, calendars, file browsers, music players, issue trackers, package managers — is, at its core, just two primitives: 1) pick a thing, 2) act on it. That is the exact shape ICR was built for, and most of the visual chrome we drape around those primitives is decoration.

This matters concretely because very few environments expose completion as a programmable substrate¹ you can build ICR experiences with, rather than as a sealed UI you can only consume. In everything else you use, the candidate sources, the matcher, the sorter, the annotator, and the available actions are largely fixed by the vendor or aren't even available. On the other hand, in Emacs and the shell, every layer is independently replaceable. Taking your completion stack seriously is among the highest-leverage things an Emacs user can do, on the same scale as customizing your shell, and for the same reasons. Done right, ICR can dramatically reduce the cognitive overhead of using your computer to do almost anything.

This post opens a short series on ICR. The remaining two posts get concrete: a breakdown of the modular completion framework I use day to day, and a case study of an entire Spotify client that is just an ICR application. The goal of this opening piece is to convince you that ICR is worth your rigor, and to give you the conceptual vocabulary to recognize how much of your own software experience already runs on it.

"Incremental Completing Read" has three load-bearing words:

Read, in the elisp sense: a function that prompts the user and returns a value. The system asks a question, you answer, and then the answer is something other code can do something with.

Completing: the system maintains a candidate set and shows you which candidates currently match your input. You don't type the full answer. You type enough to disambiguate, and the system fills in the rest.

Incremental: the candidate set is recomputed on every keystroke². You don't submit a query and wait for results. Filtering happens between characters, fast enough that the result list feels like an extension of what you're typing.

Combine the three words and you get an interaction that is qualitatively different from either browsing or searching. Browsing scales poorly to large sets — you can scan a list of ten things, not a list of ten thousand. Search-and-submit scales fine in the back end but introduces a feedback gap that breaks flow. ICR fuses the two.

A clarification before going further. In Emacs, the standard-library function named completing-read is not, on its own, incremental. It TAB-completes at the minibuffer and shows a *Completions* buffer on demand. The incremental UX described above is layered on top by a separate generation of frontends like Icomplete, Ido, Ivy, Helm, and the modern Vertico. Throughout this series, "ICR" refers to the pattern (the API plus an incremental frontend), not to any single function. This separation matters because it makes the Emacs completion stack pluggable, and this separation is the subject of the next post in the series.

Think about all the places you already use ICR. Here's a partial inventory:

• The browser URL bar narrows history and bookmarks as you type.
• Search engines suggest queries character by character.
• Spotify, Apple Music, and YouTube surface tracks, artists, and videos as you fill in the search box.
• Amazon's product search shows partial matches and category filters live.
• IDEs offer symbol completion, file navigation, and command palettes. Think VS Code's Cmd-Shift-P, JetBrains' "Search Everywhere," GitHub's file finder, Sublime Text's "Goto Anything."
• Shell users reach for fzf to fuzzy-find files, branches, processes, and command history.
• Slack jumps to channels by typing fragments of the name.
• Even mobile keyboards suggest the next word as you tap³!

These look like different tools, but when you think about it they are the same interface. Each one accepts a stream of keystrokes, runs an incremental query against a sometimes enormous candidate set, and surfaces the best matches in real time, as you type. Across all these apps, your interaction pattern is the same: you type fragments, watch a candidate list list narrow, and then pick from what survives the narrowing.

ICR has become the lingua franca of navigation.

The pattern is so ubiquitous that its absence now feels strange to me. File pickers that only show a tree, settings panels with no search box, and configuration UIs where you have to remember the menu hierarchy all force me to slow down and then manually browse through candidate sets to find what I'm looking for. These feel like artifacts of an earlier era — the era before incremental completing read became a common default for how humans navigate sets of named things. Today, it feels like ICR has become the lingua franca of navigation.

If you take anything away from this post, let it be what follows in this section. This realization is what makes Emacs legible to its power users:

We've seen where ICR shows up in the previous section, but where else can we use it? Run an inventory of the interfaces you use daily, and for each one, ask: at its core, is this just pick a thing from a set, then do something to it?

• Email: pick a message; reply, archive, forward, delete.
• Calendar: pick an event; accept, reschedule, open.
• File browser: pick a file; open, rename, delete, move.
• Issue tracker: pick an issue; assign, comment, close.
• Music player: pick a track; play, queue, save.
• Package manager: pick a package; install, remove, inspect.
• Git client: pick a branch; checkout, merge, rebase, delete.
• Cloud console: pick a resource; start, stop, configure, destroy.

The list grows uncomfortably long. It turns out that a surprising fraction of all interactions with your sofware uses the same two primitives: a source of candidates and a set of actions you can perform on a set of selected candidate. Most of the visual chrome we drape around these primitives is decoration.

It turns out that a surprising fraction of all interactions with your sofware uses the same two primitives: a source of candidates and a set of actions you can perform on a set of selected candidate. Most of the visual chrome we drape around these primitives is decoration.

Now that you've seen the light, your next move is to ask whether you can chain these. Consider navigating files in a project: ICR to pick a project, which scopes the candidate set to its files; ICR to pick a file, which scopes the actions to its file type; ICR to pick an action, which produces a new candidate set, and so on…. An interaction model built from selecting and acting can be composed into arbitrarily complex workflows, the same way any other small set of orthogonal primitives can.

Shell users already know this composition story well. For most shell users, fzf drives ICR and produces selections. Pipes feed those selections into commands. Commands produce new selections which can be piped back into fzf for more ICR, and so on…. git branch | fzf | xargs git checkout is the pattern in miniature: a candidate source, a selector, an action, all chained. fd | fzf | xargs $EDITOR is the same shape with a different source. Build a few dozen of these one-liners and you have a personal interface to your filesystem, your version control history, your processes, your network, without anyone shipping you that interface. That's powerful!

The interesting, and frustrating, observation is how rare this is composability and feature-richness is where ICR interfaces exist. Spotify will never let you redefine what "select a track" can do. Gmail's search cannot pipe its selected results into your own actions. Some environments come closer than others — Neovim's Telescope, Raycast's extension API, VS Code's QuickPick — but in each of them at least one of the layers (the matcher, the sorter, the annotator, the action set) is fixed by the vendor. Few environments expose every layer, and only Emacs and the shell expose them independently, so that you can swap one without disturbing the others.

This is the difference between using ICR and building ICR, and it is what makes Emacs and the shell uniquely powerful for anyone who works inside them all day. Personally, this is the main reason why I live in Emacs and the shell.

Software engineers have a precise vocabulary for talking about how algorithms scale: time complexity, space complexity, big-O notation. The corresponding field for how interfaces scale is human-computer interaction (HCI), which has its own established vocabulary — Hick-Hyman's Law, Fitts's Law, working-memory load, recognition vs. recall — but engineers rarely reach for it. The argument that follows borrows from both sides, because ICR is best understood through both angles: an algorithmic property (constant-time filtering against an arbitrary corpus) producing an HCI property (constant-cost selection regardless of corpus size).

Consider the simple act of finding a file. In a tree-based file browser, the cognitive effort grows with the size of the file system. Five files in a folder is trivial, but five hundred files spread across a hierarchy is much more cognitively taxing. You have to remember where the file lives, click through directories, scan lists, scroll, and move your cursor to the selection. Add another order of magnitude — half a million files in a project — and the file browser has effectively ceased to function as a tool for finding things. Cognitively, this approach scales worse than linearly.

Now do the same task with ICR. You hit your file-finder binding, type a fragment of the name you remember, watch the list narrow to a handful of plausible matches, and pick one. The experience is the same whether your project contains fifty files or fifty thousand. The interface does not get harder to use as the candidate set grows.

ICR breaks the linkage between the size of the world and the difficulty of finding something in it.

It is tempting to call this O(1) cognitive complexity, by analogy to algorithmic complexity⁴. The point is straightforward: the cost of finding something via ICR is independent of the size of the candidate set, and that independence is what the big-O analogy is reaching for. ICR breaks the linkage between the size of the world and the difficulty of finding something in it.

There is also a literature analogue worth naming. Hick-Hyman's Law⁵ models the time required for a forced choice as roughly proportional to log₂(n+1), where n is the number of equally likely alternatives. A flat menu of ten thousand commands is a Hick-Hyman nightmare; the user pays a logarithmic-in-n decision cost on every selection. ICR sidesteps the law by collapsing n before the choice step happens. By the time the user is selecting from the visible candidate panel, n is already small, typically less than half a dozen in my experience, and the per-selection decision cost is bounded by panel size rather than corpus size. We can calmly let the corpus grow without bound and we can trust that the time-to-pick stays roughly constant.

This is why ICR is not just an ergonomic nicety. It bends the curve. Most interface improvements buy you a constant factor, like a faster animation, a clearer label, or a better-organized menu. ICR changes the curve itself, and anything that changes the curve dominates the things that only change the constant, given enough data.

The corollary is that ICR's value is asymmetric across users. If your projects are tiny and your address book is short, you may never feel the difference. However, if like me you are an Emacs user with a sprawling notes directory, two decades of email, half a dozen languages installed, and a thousand interactive commands, ICR is the difference between a usable system and an unusable one. The bigger your world, the more you'll want to bend the curve.

A really key thing for me personally is the alleviation of any anxiety about the aforementioned search spaces growing. Regardless of the underlying magnitude of my emails, news articles, code repositories, music libraries, etc…, the ease of finding what I'm looking for in any given workflow is roughly constant.

Human-computer interaction research has long distinguished recognition (picking the right item from a presented list) from recall (producing the right item from memory)⁶. Recognition is famously easier, and this is why menus exist, why icon-based interfaces won, why "tip of my tongue" is a complaint about recall failure rather than recognition failure.

ICR sits in a strange and useful place between easy recognotion and hard recall. You don't have to recall the full item, but instead you only have to recall a fragment of it. And you don't have to recognize it from a large fixed presented list because the list narrows (often to a single candidate) in response to whatever fragment you produced. The interface meets you halfway.

This matters because the cognitive load of pure recall and the visual load of pure recognition both grow with set size. Recalling one item out of ten thousand is harder than recalling one out of ten. Recognizing one item in a list of ten thousand is harder than recognizing one in a list of ten. The hybrid form ICR offers — partial recall, then narrowing recognition — degrades much more gracefully. It is one of the few interaction primitives that gets its leverage from how human memory actually works rather than fighting it.

Cognitive psychology has a name for this hybrid: cued recall⁷. The user-typed fragment is a retrieval cue: the system uses it to materialize a small candidate set and the remainder of the task is recognition over that set. ICR is the UI instantiation of cued recall, with the screen serving as an externalized cue-to-candidate index. This is a well establish cognitive primitive, but it is rare to see an interface deploy it as deliberately as a well-tuned completion stack does.

The hybrid form ICR offers — partial recall, then narrowing recognition — degrades much more gracefully.

The best completion frameworks lean into this further. They learn your patterns. Recently selected items rise. Frequently selected items rise. The fragment you produce maps to the candidate you usually pick, not the candidate that happens to alphabetize first. The interface adapts to you. Over months, this turns into something close to muscle memory: you type a few characters and the right answer is already at the top, because that's where it has been for the last hundred selections.

The downstream effect is not just on retrieval. ICR changes the math on how you should structure your data in the first place.

In a world without ICR, hierarchy is a pretty good coping strategy. Tree-structured folders, deeply nested categories, "taxonomies" — these exist because flat lists become unscannable past a certain size. If finding things requires browsing, then organizing into a navigable tree is necessary work, but that work has real and compounding costs. You have to invent the taxonomy up front, before you know what you'll eventually want to file. Then you have to remember it later. The biggest nightmare for me personally is that with hierachies and taxonomies, I have to live with the fact that many items legitimately belong in two categories at once, yet the file system or knowledge management system forces you to pick one. I know people who are good at breaking out of this choice paralysis, but I know from experience that I am not one of them. And you incur an operational cost on every save, because every new item is a small classification problem.

The argument for nesting was always "I cannot scan a flat list of ten thousand items." ICR replies: "you do not need to scan it."

With ICR, hierarchy becomes optional. The argument for nesting was always "I cannot scan a flat list of ten thousand items." ICR replies: "you do not need to scan it." A flat directory plus tags plus links is sufficient, because ICR makes any individual item findable in a few keystrokes regardless of how many neighbors it has.

It is worth being precise about what ICR replaces and what it doesn't. Hierarchy does at least two distinct jobs. One is retrieval: helping you find a thing. The other is explanation: encoding kind-of and part-of relationships, conferring landmark structure on a space, making the shape of a domain legible at a glance. Cognitive psychology has long identified the latter as load-bearing. Eleanor Rosch's work on basic-level categories⁸ showed that hierarchical taxonomies map onto how humans actually carve up the world, and Thomas Malone's classic study of how people organize their physical desks⁹ found that "filing" (hierarchical, classified) and "piling" (flat, recency-ordered) coexist for good reasons: piles support fast access to active material and files support reasoning about the shape of what you have. ICR substitutes cleanly for hierarchy's retrieval function. It does not substitute for the explanatory function. When the relationships between things are themselves the point — a code architecture, a course curriculum, a legal taxonomy — a tree is still doing real work that no completion stack will replace¹⁰.

The sleight of hand to avoid is treating "ICR makes hierarchy optional" as "hierarchy is bad." The honest, narrower claim is this: in domains where hierarchy was load-bearing only as a search affordance, ICR lets you drop it and reclaim its costs.

This is the architectural premise of denote, Protesilaos Stavrou's Emacs note-taking package. denote stores notes in a single mostly-flat directory, and although the package supports subdirectory "silos", Stavrou explicitly argues against using them as a primary organizing principle. Notes relate to each other through filename-encoded tags and explicit hyperlinks. The package leans entirely on completion to find things, and that works because finding things in a flat namespace via ICR is instantaneous. The same idea shows up in tools like Obsidian and in older personal-knowledge systems. These systems abandon of hierarchy because they trust that search interfaces to scale to larger search spaces.

Emacs itself works this way at a much larger scale. One of my all-time favorite quirks is that every interactive command lives in a single flat namespace. A mature configuration easily exposes ten thousand of them (a quick smash of M-x on my Emacs produces over 13,000 interactive commands). Nothing about this is overwhelming to me though, because I never see the full list. I just type M-x and a fragment of what I want, and the relevant commands surface. A hierarchical menu system covering ten thousand commands would be unusable; a flat namespace plus M-x is unremarkable.

In Emacs you can get this flat-list style ICR even where there are rigid hierarchies. This is critical when physical hierarchies or taxonomies are necessary (like in code repositories), but the user still wants to navigate the content without engaging with the hierarchy or taxonomy. For example, when I'm trying to find a file via ICR, I find myself reaching for something like project-find-file (show me all files in a project in a flat list) over something like find-file (let me traverse the directories one level at a time until I find my leaf).

As we've already seen, the ICR pattern generalizes really well. Any structure you build to make scanning easier is a structure ICR makes redundant. Even where these structures need to exist, ICR can still help you get around the rigidity and opacity of that structure. Once you trust your completion stack, you can shed the hierarchies you built and maintain, and you can triumphantly reclaim the cognitive and operational overhead that those hierarchies were costing you.

The thought exercise above hands us the answer to a question this post has been circling: of the environments where ICR is genuinely programmable, why focus a series on Emacs rather than on the shell?

The shell case is well-trodden territory; Unix users have been chaining fzf and pipes for years, the design space is mostly explored, and shell users are typically introduced to the notion of ICR the second they start learning how to configure their prompt. The Emacs case is younger, deeper, and less well documented — and it is the focus of this series, so it is worth zooming in on the specific ways Emacs exposes completion as a substrate. Emacs is also less popular, so there is an air of proselytism to this post 😜.

In Emacs, every layer of the ICR interaction is pluggable. completing-read is a function in the standard library. The display is pluggable. The matching strategy is pluggable. The sorting is pluggable. The annotations are pluggable. The actions you can take on a selected candidate? Pluggable! This is all discussed in my subsequent post on the VOMPECCC composite framework.

In Emacs, every layer of the interaction is a place where you can substitute behavior, and every layer has a small ecosystem of competing implementations to choose from.

Most editors give you a completion UI. Emacs gives you a completion substrate. The difference is what you can build on top.

This is what separates Emacs from the editors that come closest. Most give you a completion UI; Emacs gives you a completion substrate. From an HCI standpoint, what is unusual about Emacs is not the completion interaction itself — the visible behavior is broadly similar to Telescope, QuickPick, or Raycast — but that the layers HCI usually treats as monolithic (matcher, sorter, annotator, action set, display surface) are exposed as independent surfaces. Those other tools let you produce candidates and bind actions, but the matcher, the sorter, the annotator, and the display they hand you are largely fixed. Recently, the Emacs community has done a lot of work towards making all of these pieces independently swappable, and the resulting compositional space is qualitatively bigger. This is the reason the Emacs completion ecosystem is one of the most interesting parts of the software. Every well-designed Emacs package eventually becomes, in part, a completing-read application: a thoughtful choice of candidate source, plus annotations, plus actions, plus a UI that is already familiar because it is the same UI you use for everything else. The cost of adding a new "thing the user can pick from a list" is close to zero, and the resulting interaction inherits all of the user's existing muscle memory.

Don't treat completion as a built-in convenience you don't have to think about. Emacs ships with a working completing-read out of the box, and many users never look further. This is a tragic error on the same scale as never customizing your shell. A serious Emacs user should treat the completion stack the way a serious shell user treats prompt and history setup: as a thing worth investing in, arguably the driving HCI paradigm in the Emacs paltform. Every other piece of the system gets better when this one is good:

ICR is a simple concept, but it has really profound effects on I use Emacs. Better completion makes file finding faster. Faster file-finding changes how I organize my data. Better symbol completion changes how aggressively I refactor. Better command completion changes which commands I remember exist¹¹. Better candidate annotations change which choices I can make confidently. In addition to saving me cognition, keystrokes, and time, ICR raises the upper bound on how much of Emacs I can fluently use.

This was all very woo-woo and hand wavy, but the next two posts get concrete.

The middle post is on VOMPECCC, a name for a loose constellation of eight Emacs packages — Vertico, Orderless, Marginalia, Prescient, Embark, Consult, Corfu, and Cape — that together compose a complete, modular completion framework along Unix-philosophy lines. Each package does one thing, and, boy, does it do it well. Most importantly, Each communicates through Emacs's standard completion APIs, making it possible for any subset of these packages to work with or without the others. That post is a technical breakdown for developers who want to either adopt the whole stack or pick the pieces that solve their specific problems.

The final post is on spot, a Spotify client built as a pure ICR application: search Spotify's catalog through consult, view catalogue metadata inline with with marginalia, and act on them with embark. It builds nothing of its own at the UI layer because it doesn't need to. Every UI primitive it requires is already there, courtesy of the framework the previous post describes. spot is a useful case study in what becomes possible when you stop treating completion as a default and start treating it as a programmable substrate.

Three posts, one argument: incremental completing read is one of the highest-leverage interaction patterns in computing, Emacs gives you uniquely deep control over it, and that control is worth using. The rest of the series is about the practical 'how'.

This post argues that Incremental Completing Read (ICR) — the pattern where a candidate list narrows in real time as you type — is not a convenience feature but a structural change in how interface cost scales with data size. ICR is composed of three ideas: read (prompt the user and return a value), completing (maintain and display a candidate set), and incremental (recompute matches on every keystroke). Together they produce an interaction qualitatively different from both browsing and searching.

The pattern is already ubiquitous across software you use daily — browser URL bars, search engines, music players, IDE command palettes, and shell tools like fzf all implement it. A surprising fraction of all computing boils down to two primitives: pick a thing from a set, then act on it, and these primitives compose into arbitrarily complex workflows through chaining, the way shell pipes do.

From a cognitive-science perspective, ICR breaks the linkage between corpus size and the difficulty of finding something in it. While tree-based browsing degrades with scale and Hick-Hyman's Law penalizes large choice sets, ICR collapses the visible candidate count before the choice step, keeping per-selection cost roughly constant regardless of how large the underlying data grows. ICR also occupies a unique position between recognition and recall — you supply a partial cue, the system materializes a small candidate set, and the rest is easy recognition. Cognitive psychology calls this cued recall, and well-tuned completion stacks lean into it further by learning your selection history.

Beyond retrieval, ICR reshapes how you organize data in the first place. Hierarchy was always a coping strategy for unscannable flat lists; ICR makes flat lists scannable, so hierarchies built purely as search affordances become redundant. This is the design premise behind tools like denote and Emacs's own flat M-x command namespace.

Finally, the post explains why Emacs is the focus of this series: unlike every other environment, Emacs exposes the matcher, sorter, annotator, display, and action set as independently replaceable layers, making completion a programmable substrate rather than a sealed UI. The next two posts get concrete — one on the modular VOMPECCC completion framework, and one on a Spotify client built as a pure ICR application.