Completion is a Substrate, not a UI

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.