I thought it would be helpful to modify the title of the Emacs frame to display the Org task I'm clocked in to. It turns out to be a lot easier than it sounds -- just change one Org variable in Customize.

The variable is org-clock-clocked-in-display. Its default value is mode-line. This means that the active clock displays only in the mode line. But it can have one of three other values: nil, frame title, both.

I've set it to both. Now the clocked task displays in both the mode line and the frame title. It shows the clock duration in square brackets followed by the task heading in parentheses, as shown below.

This simple update has improved my productivity significantly. The prominent display of the clocked task reminds me of what I started to do before I went down yet another rabbit. Not that rabbit holes are all bad -- I was in a rabbit hole yesterday when I found org-clock-clocked-in-display.

Try it out!

My actual configs start with pretty usual stuff you’d see across many other Emacs configs. As I was going through these however, I started to wonder how things work and why they ended up the way we have them today. In turn, that led to reading about the intention behind those, which led to more options I didn’t think about. Also, it’s kind of fun. I’ve made two more passes for this part alone in the last couple of weeks, and I could probably go for a third. When reading this post, if you want the good stuff (in my opinion), get lost in the footnotes as I did. There’s a lot to explore. I just scratched the surface.

Load Melpa

Melpa is where many Emacs packages live. The story behind it (from what I can tell) revolves around one of Emacs’ maintainers, Bozhidar Batsov, who pointed to Melpa at some point in 2012, when Emacs’s then go-to third-party package repository went offline. He is not its creator — Melpa has been around before this post — but this seems to be the turning point where Emacs package maintainers started to really use it. I don’t have good coder/repository maintainer knowledge, but from what I read, it’s built on the same idea as Homebrew (for Mac), which was familiar to many of the Emacs folks at the time.

So let’s get Melpa:

(require 'package)
(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t)

UI and Fundamental Emacs tweaks:

Most Emacs folks with a config file like this like to kill the toolbar, scrollbar, and menu bar. I find that the menu bar makes Emacs look more like the other programs, especially in macOS¹. Besides, it’s nice to look every now and then and be reminded of good Emacs kung-fu I forgot exists (org-sort, I’m sorry my friend, I’ll keep saying hi more often).

This is why the menu-bar is commented out in my config; I want it, but I also want to remember I could turn it off if I wanted:

(tool-bar-mode -1)
(scroll-bar-mode -1)
;; (menu-bar-mode -1) 

By default, help commands² display the help buffer in a new window without selecting it. I find this annoying: if I bring up the help window, it’s usually because I want to scroll down to find something or copy (yank) something. On the other hand, if I just want to skim quickly in the help buffer, it’s helpful that the marker is on it for a quick q for quit.

In addition, we want to be able to navigate help menus as Emacs intended if we follow the links in a help buffer. help-window-keep-selected allows us to keep help in its own dedicated window, so it won’t open in a separate window once we follow a link. Going back to the original is the same as we do in other browser-like buffers in Emacs, with l (like in Eww, for example). Likewise, we can go forward with r. I should also expand here on various help options; they definitely deserve a mention, but this is another huge topic (you can get an idea from the footer) that will take a couple of weeks. I will come back to this someday.

(setq help-window-select t)
(setq help-window-keep-selected t)

Lisp is full of parentheses, and it’s easy to lose track. Turning show-paren-mode on means that standing on an open or closed parentheses highlights its matching counterpart, which is handy.

In addition, while we’re here: when we stand on an expression that is only showing a portion of an expression (meaning, we need to scroll down to see the rest) Emacs can highlight the expression for us to make sure we don’t get confused — this is the mixed option below for show-paren-style. If you want to see the whole expression highlighted every time you’re on it, there’s the option expression, which I’m leaving here for reference for myself. For now, I think it’s too much visual noise, especially since we’re using org-edit-special, which also highlights what we’re working on.

  (show-paren-mode t)
  (setq show-paren-style 'mixed)
;; (setq show-paren-style 'expression)

And now, a true Emacs classic. I don’t think I’ve seen a config without it: shortening “yes” or “no,” answer to “y” or “n” like any other program known to mankind. use-short-answers was introduced in Emacs 28.1, which is a more graceful way to do this, intended exactly for this purpose. Before that, back when I started to use Emacs, it was done with (fset 'yes-or-no-p 'y-or-n-p). If you have an older Emacs version, you’d need it.

;;  (fset 'yes-or-no-p 'y-or-n-p)
(setq use-short-answers t)

This one was annoying until I learned this option exists from someone else’s config years ago: “Emacs, please stop asking me if I want to kill process when exiting Emacs (Shell, etc.), just do it!” Yep.

(setq confirm-kill-processes nil)

Emacs has two annoying keyboard shortcuts that I should have disabled as soon as I started using it: C-x C-c (exit Emacs) and C-z (minimize Emacs). Both of them are too easy to press by mistake, especially C-z, which is undo in many other programs. If I had a penny for each time I minimized Emacs by mistake… When we want to minimize Emacs (and why would you want to do that? Emacs deserves a prominent space on your screen), we can just do it by clicking the minimize window itself, shamefully using our mouse, as we do with other apps. And Exiting Emacs? With a shortcut that seems like it fits somewhere in org-mode? No thanks. Let’s disable those:

(global-unset-key (kbd "C-x C-c"))
(global-unset-key (kbd "C-z"))

Turn off the annoying error beep, which I first discovered in SUSE Linux by turning on a visual warning (a flash) instead. This will flash the top and bottom lines of our window instead of going “beep!”

(setq visible-bell t)

Turn on visual line mode so text lines “wrap” inside the frame and don’t continue beyond the window’s edge. This is essential; I can’t read in Emacs without it. And a newcomer I discovered recently: since Emacs 30, we also have global-visual-wrap-prefix-mode, which preserves indentation on wrapped lines. For example, in a list in org-mode (made of dashes one under the other), a long line of text that wraps will align under its starting point (dash) in the list instead of jumping back to column 0 (the start of the window, to the most left). This has been a huge pet peeve. Finally!

(global-visual-line-mode t)
(global-visual-wrap-prefix-mode t)

Winner mode (included in Emacs) is sort of “undo” for changes in windows’ layout in Emacs. C-c ← goes back to our previous setting, and C-c → will “redo” the layout we just left. I use it all the time as in “oops, I closed the wrong window”³.

(winner-mode t)

Saw this over at https://emacsredux.com/blog/2026/04/07/stealing-from-the-best-emacs-configs/. This is a nice little trick, and it requires a bit of reading to understand what exactly it does: preventing Emacs from deleting whatever we have in the system’s clipboard when we kill a line, so it’s still in the kill ring. Here’s an example to help you grasp the idea and why it’s useful:

1. We’re visiting a website with our default browser and copy its URL because we want to write about it in Emacs
2. We go to Emacs, and we kill the line we’re on because we need some space
3. Crap! Now we lost our paste in the clipboard, and we have to go back to the browser and grab that URL again!
4. Wait, which tab was it? Did we close it? Should we look in our browsing history? Ugh!

Not anymore! With this little guy, when we kill the line (step 2 above), Emacs “injects” it into the kill ring. Now, when we yank with C-y, we will still get the last line we killed, yes, butlook up the kill ring with M-y and voilà! Your URL is there. No need to go find that URL again:

(setq save-interprogram-paste-before-kill t)

You know how for years Emacs “jumped” when you scrolled down large embedded images in your org buffers? Let’s turn on pixel-scroll-precision-mode for pixel scrolling instead of the default line scrolling to fix this. It’s pretty much what it reads: the default old way would “scroll” (it’s actually not scrolling at all) by a line of text at a time. Since our image of, say, 600px in height is treated as a single line of text, it will jump to the end of it. With this option turned on, Emacs would read the pixels from your mouse wheels as you scroll, and we get the smooth scrolling we’re used to.

Interesting to know: moving up and down the line without a mouse (arrows, or C-p and C-n) is moving by text lines, utilizing auto-windows-vscroll and line-move, which basically does in Emacs what arrow movement seems to be doing in modern applications: these apply this principle from the other direction — they natively work with pixels, so they treat these arrow movements as a fixed number of pixel movements, which is approximately a line of text. So, when you move up and down a large image (or say a PDF) in a browser, the browser thinks “ok, the user is moving up one line of text, which is.. hm.. let’s see… ah, it says it’s exactly 40 pixels, so let me show that”.

(pixel-scroll-precision-mode t)

Footnotes

In fact, if you’re curious about help and Emacs help, I suggest you head over there now and read that post. It expands on how to approach Emacs help by how to think Emacs, which is something that experienced Emacs users struggle to explain to newcomers. I know, because I was there, and I’m sure many of you who are new to Emacs just shake your head.

As for the history of help in Emacs, I think it’s pretty safe to say it’s been there since the start, or at least since Emacs became intended for public use, sometime around the 1980s. By that point, most of the core help parts we know today (the tutorial, C-h t; the Emacs Manual, C-h R; as well as the framework itself) were already in place. The help system was there before GNU Emacs, back in the days of TECO Emacs that RMS worked on at MIT in the 1970s. You could browse the original code from then (preserved by MIT) and see Stallman writing what certain commands do in emacs.doc inside that repository. Another interesting find about Emacs itself (and the help system that comes with it) is the EMACS paper written by RMS back in 1981. For the help system, take a look at page 17: “6. Self-Documentation and Extensibility” and the following chapter in page 18: “7. History”. Fascinating stuff.

Emacs is the editor of tinkerers and artisans; those who are eternally dissatisfied with all other tools because of their adamantine rigidity. Crafting, or shaping, your tools to meet your exacting needs is what Emacs excels at. Because of that, Emacs is – much to the chagrin of everyone who picks it up for the first time – squarely aimed at people who already know Emacs.

In fact, if you’re curious about help and Emacs help, I suggest you head over there now and read that post. It expands on how to approach Emacs help by how to think Emacs, which is something that experienced Emacs users struggle to explain to new comers. I know, because I was there, and I’m sure many of you who are new to Emacs just shake your head.

As for the history of help in Emacs, I think it’s pretty safe to say it’s been there since the start, or at least since Emacs become intended for public use, sometime around the 1980s. By that point, most of the core help parts we know today (the tutorial, C-h t; the Emacs Manual, C-h R; as well as the framework itself) were already in place. The help system was there before GNU Emacs, back in the days of TECO Emacs that RMS worked on at MIT in the 1970s. You could browse the original code from then (preserved by MIT) and see Stallman writing what certain commands do in emacs.doc inside that repository. Another interesting find about Emacs itself (and the help system that comes with it) is the EMACS paper written by RMS back in 1981. For the help system, take a look at page 17: “6. Self-Documentation and Extensibility” and the following chapter in page 18: “7. History”. Fascinating stuff.

Raw link: https://www.youtube.com/watch?v=Crn6x3RmmyQ

In this video I demonstrate the built-in ‘speedbar’ command. This is the file explorer that Emacs ships with. Starting with Emacs 31, the ‘speedbar’ can be configured to appear on the side of the frame. Whereas the default is to show up in a separate frame. To me, the default is impractical, whereas the new option turns ‘speedbar’ into a very useful piece of functionality.

The first time I opened a web page inside Emacs I thought it was a trick, a hack, a toy... studying it in depth I saw I was wrong. EWW is a browser written 100% in Emacs Lisp, with no external engine behind it (no WebKit, Blink or Gecko). It is absurdly lightweight, intelligently designed and, almost without meaning to, it hands you a platform to do scraping or automate web tasks in a few lines. A tool with enormous potential that many people don't know about, even within the Emacs community itself.

And the best part is that you already have it installed. It ships with Emacs by default. To launch it just run M-x eww and type a URL or a search term (it will open DuckDuckGo).

Is it a replacement for Chrome or Firefox? No, and it doesn't try to be. It plays in a different league.

Two pieces: EWW and SHR

What we call "the Emacs browser" is really two pieces working together.

• EWW (eww.el) is the browser layer: URLs, history, bookmarks, forms, cookies, downloads and sessions.
• SHR, or Simple HTML Renderer (shr.el), is the engine that turns HTML into text inside a buffer. And EWW is not the only one using it: Gnus for mail, elfeed for feeds, and quite a few other packages share it too.

Here's the key: SHR doesn't draw a page, it translates it. It takes the HTML and paints it as Emacs text, with its faces and its properties. What does it understand along the way? Quite a bit more than you'd imagine:

• Rich text: b, i, em, strong, u, s, code, tt, mark, ins, del, sup, sub, abbr, bdo/bdi.
• Structure: h1..h6, p, div, blockquote, pre, hr, ul/ol/li, dl/dt/dd.
• Links and tables.
• Images: it understands data: URIs (base64), srcset (it picks the resolution), cid: (mail), scaling with shr-max-image-proportion, animation and zoom. And if a src is broken, it falls back to its alt text, as it should.
• MathML: it keeps the TeX annotation, it does not render the formula.

Forms are a curious case: SHR doesn't add them, EWW layers them on top via shr-external-rendering-functions. Thanks to that you can submit GET and POST forms, and even multipart/form-data to upload files.

Two things are missing from the list: JavaScript and CSS.

What EWW doesn't do (and why that's fine)

EWW is not meant to run modern web applications. Its limitations aren't an oversight, they are the reason it's so fast and so lightweight. But you'd better be clear about them before you get frustrated.

No JavaScript. This rules out, in one stroke, any SPA (React, Vue, Angular), infinite scroll, content that arrives via fetch or XHR, and most of today's web. If a page needs JS to paint itself, in EWW you'll see little or nothing.

No CSS. The code itself confesses it in its header: "It does not do CSS, JavaScript or anything advanced". In practice:

• <style> sheets and <link rel=stylesheet> are ignored completely. Only the inline style attribute is read, and only if it contains color, display (specifically none) or border-collapse. Everything else (font-size, margin, padding, float, flex, grid, text-align...) is thrown in the bin.
• Colors require (display-color-cells) >= 88. And the contrast system is surprisingly serious: it converts to CIE Lab and uses CIE DE2000 distance to make sure the text is readable.
• There are no class or id selectors, no cascade, no specificity. Nothing.

The parser is not HTML5-conformant. It uses libxml2, which is tolerant but does not follow the HTML5 parsing algorithm to the letter. Manual patches are applied to plug the holes.

EWW is not for SPAs, online banking, JS dashboards, dynamic forms, anything that throws a "enable JavaScript to continue" at you, embedded video or audio, or layouts that are only legible thanks to CSS. It's not its turf, and forcing it is a waste of time.

Scraping out of the box

EWW leans on libxml-parse-html-region, which gives you back the DOM as an S-expression. And Emacs includes dom.el to walk it. That makes scraping trivial, and you don't even need to open EWW.

Look at this script. It extracts the headlines from the Hacker News front page:

(require 'dom)
(require 'url)
(require 'cl-lib)

(defun demo-scrape (url)
  "Download URL and return the Hacker News headlines as a list of conses.
Each element is (TITLE . HREF)."
  (with-current-buffer (url-retrieve-synchronously url t t 30)
    (goto-char (point-min))
    ;; Skip HTTP headers until the first blank line.
    (re-search-forward "\r?\n\r?\n" nil t)
    (let* ((dom (libxml-parse-html-region (point) (point-max)))
           ;; On HN each headline is <span class="titleline"><a>...</a>.
           (titles (dom-by-class dom "titleline")))
      (mapcar (lambda (node)
                (let ((a (dom-child-by-tag node 'a)))
                  (cons (string-trim (dom-texts a))   ; link text
                        (dom-attr a 'href))))          ; destination
              titles))))

(defun demo-scrape-hn ()
  "Download the Hacker News front page and show the headlines in a buffer."
  (interactive)
  (let ((items (demo-scrape "https://news.ycombinator.com/")))
    (with-output-to-temp-buffer "*HN headlines*"
      (princ (format "Headlines found: %d\n\n" (length items)))
      (cl-loop for (title . href) in items
               for i from 1
               do (princ (format "%2d. %s\n    %s\n\n" i title href))))))

;; Evaluating the buffer (M-x eval-buffer) runs it directly:
(demo-scrape-hn)

Evaluate it with M-x eval-buffer and a temporary buffer will pop up with the list of headlines and their links. No external libraries, nothing to install.

This is possible because dom.el gives you a handful of functions that do the heavy lifting: dom-by-tag, dom-by-class, dom-by-id, dom-child-by-tag, dom-attr, dom-text and dom-texts. And if instead of the raw HTML you want the already-rendered text (for example, to index the "readable" version of a page), you can run the DOM through shr-insert-document in a temporary buffer and keep buffer-string. This is, literally, the foundation on which elfeed or mu4e are built.

Designing "for EWW" is designing well

Let me switch perspective. So far we've talked about EWW as a reader. But what if you're the one publishing? What if you want your site to look flawless in there?

The good news is that designing for EWW isn't learning some weird dialect. It's going back to the principles of semantic HTML, the ones that should never have been abandoned. EWW renders HTML as a structured document, not as a canvas painted with CSS. Follow these ideas and, as a bonus, your site will be more accessible everywhere.

DOM order is on-screen order

SHR walks the tree in document order and inserts the text just as it finds it. There is no CSS reordering: float, flex, grid, order and position don't exist. Whatever you put first in the HTML appears first.

So place the main content as early as possible in the DOM, or at least right after opening the <body>. Long <nav> blocks and footers go at the end.

Mark up structure with tags, not with styles

SHR gives its own faces to h1..h6, b/strong, i/em, u, code, pre, blockquote, lists, mark and del/ins. Use them for what they mean, not for how they look:

• Real headings <h1>..<h6> for hierarchy. Never a <div class="big">.
• <ul>/<ol>/<li> for lists and <dl>/<dt>/<dd> for definitions.
• <blockquote> for quotes (it indents) and <pre> for preformatted blocks or ASCII art (it disables reflow).
• <code> for inline code (fixed-width face).

Watch out for the HTML5 semantic elements (article, section, nav, header, footer, main, aside, figure): they have no render of their own. They're treated as transparent containers and only contribute their textual content. They're fine for giving meaning to the document, but don't expect them to "show".

Don't rely on CSS for anything essential

You already know: only the inline style attribute is read, and only color, background-color, display and border-collapse. The rest is ignored. From that come three rules worth tattooing on yourself:

• Your page must be legible with CSS completely disabled. If it isn't, that's not an EWW problem, it's an HTML problem.
• Don't hide content with a display:none class. SHR won't apply it and that content will show up anyway. If you really need to hide something it would have to be style="display:none" inline, but that's bad practice. Better not to put that content in at all.
• Don't convey information with color alone. Even though inline color works, it demands enough contrast (that strict CIE DE2000 filter) and on poor terminals it isn't applied at all. A "required field in red" or a "green = correct" vanishes. Always back it up with text or symbols.

And a consequence that sneaks in: spacing (margin, padding, line-height) doesn't exist. Separation comes from paragraph breaks. Structure with real <p> tags, not with stray <br> or empty divs.

Tables: for data only, never for layout

SHR draws <table> as a surprisingly good ASCII grid: it measures columns, distributes widths and even emulates colspan and rowspan. But it has its rules:

• Use them only for real data. A layout table produces an absurd, illegible grid.
• Watch the width. If the sum of the columns exceeds the frame, EWW just turns on truncate-lines and the experience degrades. Fewer columns and short cells fare much better.
• Images inside cells aren't embedded in the cell (a buffer limitation): they're inserted after the table. If order matters, avoid images in there.

Images with alt and srcset

Yes, Emacs shows images in graphical buffers. But don't get cocky:

• Always give a descriptive alt. It's what shows if the image is blocked, broken or if the user browses without images. In many EWW flows, the alt is the content.
• srcset is supported: EWW picks the right resolution for the frame width, so offer it several.
• Images load asynchronously over a placeholder, they don't block the text render. Don't rely on an image to communicate anything critical.
• data: URIs (base64 included) work, handy for small embedded icons.

Forms that actually work

Forms are fine if they're pure HTML with action and method (GET or POST, including multipart/form-data for files):

• No JavaScript submissions (onclick, fetch). Use a real <form> with its <input type="submit"> or <button>.
• Put name on every field and value for the defaults. EWW collects by name.
• The recognized text types (text, password, email, number, date, color and textarea itself...) are painted as editable fields. The rest degrade to text. checkbox, radio and select work.
• Associate a <label> with each field: keyboard navigation will thank you.

Help the readable mode

If you want your article to look perfect with eww-readable, know your enemy. Its heuristic scores each node by word count, penalizes links (it subtracts their words), rewards images, and keeps the node with more than 100 words and the highest score.

The practical takeaway? Wrap the body of the article in a single container with lots of continuous text and don't chop it up into a thousand tiny divs full of links. An <article> or a <main> with long paragraphs wins. A tangle of <div> with navigation loses.

Headers and metadata that do count

Four small details that make a difference:

• <title>: shown in EWW's header line. Always set it and make it descriptive.
• <meta charset>: EWW uses it as an encoding fallback. Declare UTF-8.
• <base>: respected, useful for resolving relative links.
• HTTPS with a valid certificate: EWW colors the header-line title according to the TLS status. Serve your site over HTTPS.

So, what is it good for?

EWW is an excellent HTML document reader and a deliberately incomplete web browser. And once you accept that duality, it fits like a glove in a handful of scenarios:

• Reading without leaving Emacs: documentation, blogs, articles, wikis, HTML man pages... with all your usual keys and with isearch.
• Focused reading: the readable mode, with its word-density scoring, leaves the text and nothing else. No noise.
• Low bandwidth and zero distractions: no ads, no JS, no pop-ups, no telemetry. Accessibility out of the box.
• Feeds and mail with HTML: remember that SHR is what Gnus, elfeed and mu4e use underneath.
• A single flow: search and open links from Emacs itself, with bookmarks, history, multiple buffers or tabs and sessions.
• Scriptable: you parse the DOM from libxml-parse-html-region directly and automate whatever you want.

Its philosophy is the opposite of a modern browser. Instead of emulating a graphical rendering engine, it translates semantic HTML into Emacs text. Anything that is a "document" works very well and very fast. Anything that is a "web application" doesn't work at all. And that's the beauty of it: it won't pass the Acid3 test, but not out of deficiency, out of design.

Will you buy me a coffee? This is how I keep writing without ads or paywalls. Sure, it's on me!

Send an email to comment+article-e0e00b4b@andros.dev to leave a comment. The subject will be ignored.

Introduction

In my years of using Emacs, I’ve noticed a common pattern: developers who are highly proficient at editing source code in Emacs switch to a “normal IDE” (as they call it)—such as CLion or Visual Studio—when they need to debug their code. They usually explain this by saying that Emacs feels a bit weird for the task.

However, I’d much rather not leave Emacs if something can be done inside it.

In this post, I’ll try to show that debugging in Emacs is both simple and effective, especially after a few small adjustments to the default settings.

Debugging in Emacs revolves around two key components:

1. GDB (GNU Debugger), the most popular and powerful debugger for C, C++, and other languages.
2. GUD (Grand Unified Debugger), Emacs’ built-in interface since at least v19 that turns GDB into a well-integrated debugging environment inside Emacs, allowing you to debug your code without leaving the editor.

A Sample Debug Session

Below is an example of a typical debug session of mine.

In Emacs, I open a source code file (timepoint.c in this example) and run M-x gdb. GDB then prompts in the minibuffer for the path to the corresponding executable, as shown below.

After you enter the path to the executable—assuming it was built with the -g flag (i.e., compiled with debug information)—and press Enter, GDB prints some initial output and may ask whether it should automatically download missing debugging information from trusted online servers.

Because I don’t intend to debug system or third-party libraries, I simply press n to skip this step, which can occasionally freeze Emacs for a while.

The GUD dashboard appears. It usually consists of nine windows.

• Debugger, the GUD interaction buffer (or GDB shell);
• C/*, the source code buffer;
• Frames, the stack buffer, a list of stack frames of the program being debugged;
• Locals, the local variables/registers buffer;
• Inferior I/O, the input/output buffer (usually associated with stdin/stdout);
• Breakpoints, the breakpoints/threads list.

In my usual workflow, I type break main (or simply b main) in the GUD interaction buffer (Debugger) to set a breakpoint at the start of my program.

The new breakpoint shows up right away: as a red fringe marker next to the line in the source buffer (color varies by theme) and as an entry in the breakpoints list.

Now you can type run in the GUD interaction buffer. Execution will then stop at the first breakpoint (line 20 in this example).

GUD Keybindings

Frankly, I find the default GUD keybindings somewhat complex. For example, C-x C-a C-n is the globally defined key chord for gud-next — one of the most frequently used debugging commands. Having to type three keys while holding the Ctrl key feels excessive to me, so I prefer a single keystroke for this operation.

So, in my ~/.emacs, I’ve rebound the most frequently used GUD commands to F6 and its derivatives.

(global-set-key [(f6)] #'gud-next) ;; Execute the next single line.
(global-set-key [(control f6)] #'gud-step) ;; Enter the called function.
(global-set-key [(shift f6)] #'gud-cont) ;; Continue execution until hitting a breakpoint.
(global-set-key [(control shift f6)] #'gud-print) ;; Evaluate the expression at point.

I’ve kept the default keybindings for the less frequently used commands, such as setting a breakpoint (gud-break, C-x C-a C-b), continuing execution to the current line (gud-until, C-x C-a C-u), and so on.

Additionally, I’ve added a new keybinding for gud-watch (C-x C-a C-w), which watches the expression at point. This command has no default keybinding in GUD, at least in Emacs 29.3.

(global-set-key (kbd "C-x C-a C-w") #'gud-watch) ;; Watch the expression at point.

Debugging

Let’s continue with our sample debugging session.

We stopped at line 20, the first breakpoint in my program. Now I want to step through the function print_timepoint line by line. In the source code buffer, I move the cursor to line 9 and set a new breakpoint with C-x C-a C-b (gud-break). Then I continue execution with Shift+F6 (gud-cont) until the new breakpoint is hit.

After stepping through the function line by line with F6 (gud-next) until the end (line 16), I get the following output:

In the Locals buffer, you can see all local variables and their current values. The Inferior I/O buffer shows the program output. Everything looks correct: the tpoint variable has the value 0, which corresponds to the beginning of the Unix epoch (January 1, 1970).

Indeed, we could have inspected the print_timepoint function by simply stepping into it (gud-step, Ctrl+F6) directly from the first line of main, where the initial breakpoint was set. I used this example to demonstrate more GUD commands in action.

Now we can quit the debugging session by typing quit (or simply q) in the GUD interaction buffer (Debugger).

Of course, there’s no way to cover all the functions and commands available in GDB/Emacs GUD in one short post but I hope it provides a helpful introduction to using Emacs GUD for debugging your code.

You can find more information in the Running Debuggers Under Emacs manual; the GDB Cheat Sheet (PDF) is also worth having on hand.

Happy debugging in Emacs!

— The Emacs Cat.

For me, listening to music whenever I’m working on a computer is a commonplace, daresay essential activity. Much of my work is done using Emacs, so the idea of having it control music playback to mitigate an app switch seemed reasonable. Such was the motivation for my latest project, now-playing.el, a Transient interface for the macOS Music (nee iTunes) app.

now-playing.el takes inspiration from the many mini-client interfaces provided by Apple to control the Music app. The idea was to have a compact and simple interface:

• Show what is currently playing (song, artist, album)
• Offer basic controls (play/pause, next/previous track, volume control)
• Optionally log what was played.

now-playing.el takes advantage of AppleScript support in the Music app, providing the needed controllability and observability of it from Emacs. The sequence diagram below illustrates how these programs relate to each other by showing a request/response transaction between Emacs and the Music app using the osascript command line tool.

If Emacs is built with NextStep (NS) support, then Emacs can send a direct AppleScript message to the Music app via ns-do-applescript to avoid making a shell call to osascript.

State synchronization for now-playing.el is fairly simple, with client updates done in a pull fashion. More details about what now-playing.el can do can be found in the now-playing.el User Guide.

Closing Thoughts

It is not coincidental that writing this mini-client for the Music app works into my recent explorations and musings on malleable computing with Emacs. As of this writing, now-playing.el weighs in at 326 lines of code (cloc measured), taking full advantage of Elisp libraries to construct the following client subsystems:

• UI: Transient for menu, cus-edit.el for customization UI
• Client Edge: shell-command-to-string to osascript, ns-do-applescript
• Local Database: Elisp variables

now-playing.el explores integration with AppleScript, itself a mechanism to allow for orchestration between Cocoa applications. Expect some future posts documenting my explorations in this area, particularly with the more contemporary Apple Shortcuts and Intents.

now-playing.el v1.0 is now available on MELPA.

Irreal, as you all know, is an em-dash friendly site. Irreal has always liked them and now we like them even more because it puts a thumb in the eye of those mentally challenged folks who claim, erroneously, that “real people” don’t use em-dashes and their presence in a document is a sure sign of AI generated text.

It turns out that JTR over at The Art Of Not Asking Why is also an em-dash aficionado and has been struggling with how to enter them, especially when using Emacs. His final solution involves expand-abbrev but seems to me overly complicated. He types --- then immediately calls expand-abbrev by typing Ctrl+x `.

We here at Irreal have the same problem, of course, but solved it in what seems to me a much simpler way:

(defun jcs-insert-em-dash ()
  "Insert an em-dash at point"
  (interactive)
  (insert 8212))

and

(global-set-key (kbd "H--") #'jcs-insert-em-dash)

I have Hyper bound to the right ⌘ Cmd key so it’s really easy to invoke it: thumb on Hyper and index finger on - and it inserts an em-dash directly into the source exactly as JTR wanted.

I don’t claim my solution is better than JTR’s, only that it suits me better. It’s just another example of Emacs letting you have it your way.

Still working on Emacs Config Gems part 3. Fell into a deep rabbit hole and got lost for a couple of days, then climbed out just to discover another one I have to explore next. I wanted to crunch the first few tweaks of my Emacs config in one post, but there’s too much to explore. I’m getting there!

I particularly enjoyed the tweaks for EWW (Emacs Web Wowser) in this edition. Could be fun to take whatever page you're looking at in a different application and open it within Emacs, with syntax highlighting and maybe even the ability to copy or execute bits of code more easily. Could be handy during your search for knowledge, which is incidentally the Emacs Carnival theme for August. Enjoy!

• Help wanted:
  • pkal is looking for feedback from package maintainers on how to annotate changelog entries with release info (@pkal@social.sdfeu.org)
  • Ihor Radchenko's looking for insights from maintainers on reviewing large feature branches (@yantar92@fosstodon.org)
  • Testing patches for input methods:
    • [patch] GNU emacs bug#68339 (w32 ime font size)
    • [Patch] Implement preedit text rendering for Windows
• Upcoming events (iCal file, Org):
  • Emacs.si (in person): Emacs.si meetup #8 2026 (v #živo) https://dogodki.kompot.si/events/3944ee8f-6da1-4720-b086-b9217e4f5c7b Mon Aug 3 1900 CET
  • EmacsATX: Emacs Social https://www.meetup.com/emacsatx/events/315091679/ Thu Aug 6 1600 America/Vancouver - 1800 America/Chicago - 1900 America/Toronto - 2300 Etc/UTC – Fri Aug 7 0100 Europe/Berlin - 0430 Asia/Kolkata - 0700 Asia/Singapore
  • M-x Research: TBA https://m-x-research.github.io/ Fri Aug 7 0800 America/Vancouver - 1000 America/Chicago - 1100 America/Toronto - 1500 Etc/UTC - 1700 Europe/Berlin - 2030 Asia/Kolkata - 2300 Asia/Singapore
  • London Emacs (in person): Emacs London meetup https://www.meetup.com/london-emacs-hacking/events/315859503/ Tue Aug 11 1800 Europe/London
  • Emacs Berlin: In-Person-Only Emacs-Berlin Stammtisch https://emacs-berlin.org/ Tue Aug 11 1900 Europe/Berlin
  • OrgMeetup (virtual) https://orgmode.org/worg/orgmeetup.html Wed Aug 12 0900 America/Vancouver - 1100 America/Chicago - 1200 America/Toronto - 1600 Etc/UTC - 1800 Europe/Berlin - 2130 Asia/Kolkata – Thu Aug 13 0000 Asia/Singapore
  • Atelier Emacs Montpellier (in person) https://lebib.org/date/atelier-emacs Fri Aug 14 1800 Europe/Paris
  • OrgDevMeetup https://bbb.emacsverse.org/rooms/orgdevmeetup Sat Aug 15 0100 America/Vancouver - 0300 America/Chicago - 0400 America/Toronto - 0800 Etc/UTC - 1000 Europe/Berlin - 1330 Asia/Kolkata - 1600 Asia/Singapore
• Beginner:
  • How to Cancel a Command in Emacs (01:28)
• Emacs configuration:
  • Customize: hook to focus search field after entering customize mode (@SpaceCadet@chaos.social)
  • Handling environment variables in Emacs on OSX and Linux • Ben Mezger
  • Kakoune recipe using hel-mode https://github.com/helheim-emacs/hel/ (Reddit)
  • My Dotfiles Are an Org File | Dotfile Management with Emacs (02:38)
  • Rewriting my Emacs config (03:39:31)
• Appearance:
  • Marcin Borkowski: A fancier splash screen in terminal Emacs
  • Nice GTK tooltips for Flycheck. Works on GTK builds (Linux: Wayland/X11). (Reddit)
  • tjammer/modukai-sun-theme: Monokai Pro Light Sun based on modus-themes - Codeberg.org (@tjammer@mastodon.gamedev.place)
• Navigation:
  • Marcin Borkowski: Outlining in programs (Irreal)
  • Tip about using helm-multi-swoop-projectile for large-scale renaming in localization files (@ArneBab@rollenspiel.social)
  • Project-x now on Melpa! (+ window layouts and tabs) (Reddit)
  • I decided to customize imenu-list a bit more (Reddit)
  • Flash.nvim For Emacs (16:07) - jump to locations with search labels
• Hyperbole:
  • Hyperbole Question: What do you need to better capture and navigate your knowledge base?
  • Hyperbole Implicit Buttons: Build your Hyperverse (YouTube 34:21, (Reddit)
• Dired:
  • dired configuration similar to yazi keymaps. This is my dired config, share yours please:D (Reddit)
• Writing:
  • How to Turn on Word Wrap in Emacs (01:28)
  • Bicycle for Your Mind: Much Ado About Emacs 015 (Irreal) tabs, newlines, two-space shortcut
  • Raymond Zeitler: One Space or Two?
  • md-mode 0.2 — Add LaTeX, Mermaid, PlantUML and Graphviz rendering support (Reddit)
• Org Mode:
  • Org Mode requests: [FR] Simpler file ID links in HTML export
  • Emacs with Prot: Org Mode Basics Before Projects and Capture (21:16, Protesilaos)
  • I made an Org Mode Advanced Concepts Tutorial, please check it out (Reddit)
  • TAONAW - Emacs and Org Mode: Style & Emacs Config: A Semantic HTML Reckoning
  • grid-table 0.3.0: editable tables with horizontal and vertical merged cells for Emacs and Org (Reddit, Reddit)
  • Notes from [EVENT] #31 bbb:OrgMeetup on Wed, June 10, 19:00 UTC+3 (@yantar92@fosstodon.org)
  • Org development:
    • org-agenda-todo: Add more visual feedback on repeating tasks
    • LaTeX export: New option org-latex-fontspec-config
• Completion:
  • The Completions Buffer Is Now Enough (Reddit)
  • Protesilaos: Emacs: default minibuffer completions overview (Emacs 31) (YouTube, 30:56)
  • TAONAW - Emacs and Org Mode: Em Dashes in org-mode and the Nuances of Abbrev
• Coding:
  • Tip about using magit-commit-extend or magit-commit-instant-fixup (@kickingvegas@sfba.social)
  • Emacs Redux: Flycheck 38: Might & Magic (GitHub, Reddit, lobste.rs)
  • 4coder like scope hint implementation (Reddit)
  • Repeat-mode config for easier indent/dedent in Python (@jap@mastodon.nl)
  • Meta Redux: Leveling Up CIDER’s ClojureScript Support
  • tusharhero: Guix shell now inside Emacs! (HN, lobste.rs)
• Shells:
  • Using nix-shell in eshell (Reddit)
• Web:
  • Irreal: A Quick EWW Hack - retrieve URL from Safari, open in EWW
  • Is there a way to highlight code blocks in eww mode? - shr-tag-pre-highlight package
• Fun:
  • Raymond Zeitler: Emacs Smiley Functions
• LLMs:
  • Ram Krishnan / elisp-agent · GitLab (@kriyative@functional.cafe) - uses eval as its sole tool
  • New package: agent-shell-hq (Reddit)
  • Vibe-coded a simple vterm wrapper to make pairing AI agent sessions to projects easier (Reddit)
• Community:
  • Fortnightly Tips, Tricks, and Questions — 2026-07-28 / week 30
  • The Prot Effect (Reddit)
  • 0015 | New Keyboards, Emacs, Neovim, Catching up (02:11:56)
• Other:
  • Protesilaos: Emacs: tmr version 1.4.0
  • andros/lirve.el: Learn irregular verbs in English with Emacs - lirve.el - Andros's repositories (@andros@activity.andros.dev)
  • chmouel/komga-sync.el: Emacs mode to sync nov-mode reading progress with a Komga server · GitHub (@chmouel@fosstodon.org)
  • tnalpgge/org-hamlog: Log amateur radio contacts with Org tables - Codeberg.org (@nasunasu@bsd.network)
  • adif-mode: Major mode for viewing and editing amateur radio ADIF log files
  • linkarzu's videos:
    • Cashmere’s Emacs Workflow: Denote, Org, and Terminal Emacs (19:17)
    • [03] Emacs Projects, Org Capture, and My Workflow with Prot (02:00:05)
    • What I Need From Emacs: A Video for Prot (16:48)
      • Protesilaos: Reply to @linkarzu about ‘What I Need From Emacs’
• Emacs development:
  • emacs-devel:
    • Looking for reasons to keep letf considering symbol-function
    • Re: eglot-tests fail for emacs-31 branch - Stefan Monnier note about needing to ensure different package managers (ex: apt, npm, package.el) interoperate correctly
  • Canvas patch resubmitted to bug tracker after lots of polishing (@divyaranjan@mathstodon.xyz)
  • Don't immediately show *​Completions* for icomplete-in-buffer
  • * lisp/cus-start.el (completion-ignore-case): Make customizable.
  • ; * etc/NEWS: Announce support of Kmscon. (Bug#81428)
  • Merge remote-tracking branch 'origin/scratch/intern-without-shorthands'
  • New variable comment-start-line-regexp (bug#80837)
• New packages:
  • now-playing: Interface for the macOS Music app (MELPA)
  • nu-ts-mode: Major mode for Nushell scripts, powered by treesitter (MELPA)
  • ob-agent-shell: Org-babel backend for agent-shell (MELPA)
  • promptu: Compose LLM prompts from building blocks (MELPA)
  • r-ts-mode: R treesitter mode (MELPA)

Links from reddit.com/r/emacs, r/orgmode, r/spacemacs, Mastodon #emacs, Bluesky #emacs, Hacker News, lobste.rs, programming.dev, lemmy.world, lemmy.ml, planet.emacslife.com, YouTube, the Emacs NEWS file, Emacs Calendar, and emacs-devel. Thanks to Andrés Ramírez for emacs-devel links. Do you have an Emacs-related link or announcement? Please e-mail me at sacha@sachachua.com. Thank you!

You can e-mail me at sacha@sachachua.com.

Since I confessed my enjoyment of em dash in my writing last week, I started using them more freely. On a Mac, it’s Option Shift Hyphen, as Sasha would tell you. In Linux, it’s a bit more involved: Ctrl Shift U to bring up a search for Unicode number reference, and then the number for em dash: 2014.

This is all good and well, but what about Emacs, where I write most of my text?

Emacs comes with abbrev-mode, a powerful text-expanding option that automatically converts something like “om” to “org-mode”, or even “fox” to “The quick brown fox jumps over the lazy dog” if I wanted to. But the em dash is a bit more tricky. I could, if I wanted, create an abbreviation like “em” to simply expand to “—”. But this doesn’t make much sense.

When converting org-mode to markdown (as I do when I post something), the built-in solution for Emacs’ markdown exporter is to convert --- (three dashes) to —, em dash — but this presents two annoyances. First, the built-in exporter would convert those to their character reference, as we just saw: ߞ. I explained this more in-depth previously. Second, even after I fixed this issue by using pandoc, I still see --- in org-mode, not —. This looks like the kind of thing abbrev-mode was made for, right?

But it’s a bit more complicated. abbrev-mode triggers only when you type a space after a letter. So, “em” to — would work, but - to — would not, because a dash is not part of a word¹.

The solution was simpler than I thought: expand-abbrev, which “Expands the abbrev before point, if there is an abbrev there. Effective when explicitly called even when ‘abbrev-mode’ is nil.” In other words, it calls expand-abbrev without needing to trigger it the usual way. We simply call the abbrev replacement directly.

Now whenever I want an em dash, I type --- first, and then I make sure the marker is right after the last dash, and call expand-abbrev, which in my config is tied to C-x ‘. I then get an em dash in Emacs, and the exporter in Emacs (or pandoc, in my case) leaves it alone.

HTML enforces the use of a single space to separate sentences. If you want to add another space, you need to use  . I still remember how annoyed I was about that. Back in the century in which I took my technical writing course, two spaces were required. Of course, we weren't using computers very often; hand-written sentences needed to appear more separated than the words within.

I'm definitely not here to convince anyone to switch. Instead, I just want to share that I paid close attention to this detail when I was formulating my style guide for this blog. Should I continue with my out-of-date two-space habit? Or should I adopt the current convention?

I turned to Emacs itself for guidance. It turns out that the individuals who wrote Emacs comments, docstrings and help text used two spaces. Although many times they started each sentence on a new line.

It turns out that the content here mostly is one-space. I start out using two spaces in Org where most of this originates. But when I export to HTML, that second space vaporizes. That would seem like a bug to me.

The only place where you'll see evidence of my two-space style is in the comments and docstrings of my source code.

Am I the only person who nit picks about such details?

Thanks to Irreal for highlighting a customization from macosguru

Emacs Smiley Functions

Here's what my Emacs Tip of the Day dug up: smiley-buffer

Raw link: https://www.youtube.com/watch?v=WQbXKvBT8HY

In about 40 minutes from now I will do a live stream with Christian Arzu from the @linkarzu channel on YouTube. The video will be recorded.

The topic of our meeting revolves around how Christian uses NeoVim and Kitty to handle sessions and write fleeting thoughts. Then we will try to do something along those lines using built-in Emacs functionality.

Christian did a video a couple of days ago about this topic and here is my extensive commentary on it, with points that are useful in general: https://protesilaos.com/codelog/2026-07-31-re-linkarzu-what-i-need-from-emacs/.

Having to deal with Microsoft's outlook has been a growing pain with my computing needs. Of course, this is pertinent only for work email. For personal email, I use Migadu which has good standards for email unlike Microsoft's.

At work, I can only use either the official Outlook webmail or Thunderbird since those are the only clients that are whitelisted by the IT department at my university. Thunderbird is slightly better (it has a few problems of its own but I digress) but I would like to have an offline copy of all my emails, fully searchable with an indexed database provided by notmuch, which uses the excellent Xapian library for indexing. Notmuch is shipped as an emacs package in the form of notmuch.el, which is exactly what I like given that I'm moving most of my computing needs into emacs¹.

I've taken inspiration from Fergus' excellent blogpost which implements the same in neomutt. The initial setup process is identical to Fergus' blogpost.

It should be noted that notmuch is only a mail indexer. It does not fetch mail, nor does it send mail. Those are handled by isync and msmtp, which are commandline programs.

Access authentication with O365

Since Thunderbird is still allowed to access O365's authentication, we will use the client ID provided from it (this is publicly available from Thunderbird's source code)². For authentication for IMAP and SMTP, we will use XOAUTH, which is a simple authentication and security layer (SASL) more suited for email clients.

Tools like isync rely on SASL for authentication, for which we'll require an XOAUTH SASL plugin: https://github.com/moriyoshi/cyrus-sasl-xoauth2.

If you're on Arch, then this plugin is installable from the AUR:

paru -S cyrus-sasl-xoauth2-git

If not, then we can build it from source:

git clone https://github.com/moriyoshi/cyrus-sasl-xoauth2
cd cyrus-sasl-xoauth2/
./autogen.sh   # checks for requirements
./configure    # configure (here we use the defaults)
make           # compile
sudo make install     # install for root user

Token generation for OAuth

Microsoft has conditionally allowed API access to clients and the only way to get access for any client is to register the application in the Microsot Application portal, which is something only my org's IT department can do³. Fortunately, we can use Thunderbird's credentials to generate an access token for our purposes.

Another issue that comes up is the finite lifetime of these access tokens (typically an hour or two), which is cumbersome to generate each time one needs to download email. Fortunately, mutt comes with mutt_oauth2.py, a script to help in the automatic renewal of this token. This script helps in decrypting the token file and renewing it everytime it is invoked.

Fetching the initial token is fairly simple but before we do it, there are certain changes that we need to do to mutt_oauth2.py.

Look into the ENCRYPTION_PIPE variable (line 48) and make sure to specify your gpg key. If you don't have one, then generate one:

gpg --full-generate-key

Select the default options (ed25519 cypher if it allows) and make sure that the expiration of the key is set to 0 (no expiration). This makes your life easier but of course for security reasons, this is not a good practice.

Bring up your public key:

gpg --list-keys

Copy the second line (after the pub line) and paste it into mutt_oauth2.py

ENCRYPTION_PIPE = ['gpg', '--encrypt', '--recipient', 'YOUR-GPG-KEY']

After this, look at line 79. This includes a client_id for microsoft. For Thunderbird, the client id is 9e5f94bc-e8a4-4e73-b8be-63364c29d753. Leave the client_secret value as is. It should look like so:

'client_id': '9e5f94bc-e8a4-4e73-b8be-63364c29d753',
'client_secret': '',

Now we are ready to generate the access token. Simply run:

./mutt_oauth2.py OUTPUT_TOKEN_FILE --verbose --authorize

A series of prompts should appear. Select microsoft, localhostauthcode (or authcode), followed by your email address, after which you should automatically be redirected to a browser for adding your credentials for authentication. Doing so, should reveal the access token in your terminal. No need to copy it, it is present in your OUTPUT_TOKEN_FILE which is encrypted. To obtain the decrypted token, we run the script again with just the file name as an argument

./mutt_oauth2.py OUTPUT_TOKEN_FILE

A nice thing is that running this script with the token file also checks for expiry and renews it if necessary. This can be done multiple times without worry.

UPDATE (2026-06-19): About 20 days after I set this up, for whatever reason the token file expired on my personal laptop. I'm not entirely sure what happened but the fix for now was to regenerate the token again. I'll need to debug the exact cause to prevent it from happening again.

UPDATE (2026-07-29): It looks like this problem only appears on my personal laptop as it's not an authorized device and as such, 14 days is the maximum duration before which the token needs to be reauthorized. My office PC is within this "authorized" devices whitelist and thus doesn't need reauthentication after the initial setup.

Offline email setup

Now that we are done with the difficult part, we move onto setting up isync (the binary is called mbsync) which is available in most distributions. This program basically downloads your emails offline and synchronizes it with your email's remote IMAP servers. It supports multiple accounts too. The program is configurable with a ~/.mbsyncrc file⁴. I highly recommend reading the manual for it via man mbsync. Here's a starting template:

# -- Global defaults
# These will be applied to all accounts

# Create new mail in either location, so if the remote or local has mail
# and the other does not, then create it
Create Both
# never remote mail from either side
Remove None
# Remove messages marked for deletion from the local side on the
# remote. Do not ever delete local if marked for deletion in the
# remote. Prevents admins from deleting one's local mail
Expunge Far
Sync All
SyncState *
CopyArrivalDate yes
# No maximum number of messages
MaxMessages 0

# -- First email account
IMAPAccount university
Host outlook.office365.com
Port 993
User my-username@university.edu
AuthMechs XOAUTH2
PassCmd "~/.local/bin/mutt_oauth2.py ~/.local/bin/TOKEN"
# Use TLS
TLSType IMAPS
SystemCertificates yes
Timeout 10

# A store defines a collection of mailboxes, so we associate the
# remote IMAP mailbox with the account we just configured
IMAPStore university-remote
# Associate the store with our account
Account university

# Where are we going to keep the mail associated with this account
MaildirStore university-local
SubFolders Verbatim
Path ~/.local/share/mail/university/
Inbox ~/.local/share/mail/university/INBOX

# Channel to synchronize everything except "Sent" email
Channel uni-main
Far :university-remote:
Near :university-local:
# Which directories to synchronize
Patterns INBOX "Deleted Items" "Drafts"

# Channel to synchronize "Sent" email
Channel uni-sent
Far :university-remote:"Sent Items"
Near :university-local:Sent

# Group the two channels and sync everything with `mbsync NAME`
Group university
Channel uni-main
Channel uni-sent

# -- Second email account
IMAPAccount personal
...

Once you have everything configured, we can start downloading all our email by running:

mbsync university

The first time mbsync is run, it will take a fair amount of time, since you'll be downloading a lot of email (assuming you've been using your account for a long time). The subsequent runs would be just incremental downloads, so it's much faster.

After navigating to your local Maildir directory (~/.local/share/mail/university in my case), you should see all your emails downloaded and categorized into inbox, drafts, sent, and deleted-items folders.

A way to automate this to run a script periodically. I use systemd-timers where I have a script which is periodically run every 15 mins and notifies me if there's new email (I'll cover this later in the blogpost).

Sending mail via SMTP

Sending email is done via msmtp. It is configured by editing ~/.msmtprc⁵.

defaults
auth on
tls on
tls_trust_file system
logfile ~/.cache/msmtp.log
timeout 10

# -- First account
account university
tls_starttls on
host smtp.office365.com
port 587
auth xoauth2
user my-username@university.edu
passwordeval "~/.local/bin/mutt_oauth2.py ~/.local/bin/TOKEN"
from my-username@university.edu

# -- Second account
account personal

This is fairly self-explanatory. One thing to note is that tls_starttls should be on for this to work. I'm not very familiar with email security protocols like TLS and STARTTLS but from my understanding, STARTTLS is an automatic upgrade (if supported) from the more insecure TLS protocol. TLS however needs to be enabled for any email service, otherwise it won't work.

Now, we can test our configuration by sending email directly from the commandline. Save the contents of a file called example-mail as follows:

From: my-username@university.edu
To: user@example.com
Subject: Hello World

This is a test for msmtp.

And send the email by running:

cat example-mail | msmtp -t -a university

Indexing email offline with notmuch

We have receiving and sending email configured. How about reading and "using" email via an email client. In more technical terms, an email client is called a mail user agent (MUA), which is typically seen in email headers. This includes clients like Thunderbird, Apple mail, neomutt, etc. We will configure notmuch which indexes email and provides an interface for emacs natively with notmuch.el.

Notmuch is entirely tag based. Basic tags exist like unread, inbox, draft, sent but you can customize it with more tags to filter out emails from a particular email address, from a particular range of date, etc. Tags are heavily used and it's a different paradigm of handling email compared to your typical webmail interface. I won't go over the details of tagging in notmuch here for the sake of brevity (to be covered in another blogpost).

When first setting up notmuch, simply run:

notmuch setup

This will prompt you for basic information like your name, email address, Maildir directory, etc. Once this is done, notmuch needs to index your Maildir. Run the following:

notmuch new

This should be fairly fast, even if your Maildir is big. Notmuch is quick like that.

Now you can search an email entry via notmuch search. For example, I can search emails from a particular sender like so:

notmuch search 'from:friend@university.edu'

I would again advise you to go through the man pages (man notmuch-search) for more details.

Emacs setup for notmuch

Simply running M-x notmuch should give you a hello screen, where you can then select tags like inbox, unread to view their respective email. I have a fairly customized config for notmuch.el but below I provide a fairly good starting point for a more minimal notmuch interface⁶:

;; Notmuch for email
(use-package notmuch
  :load-path "/usr/share/emacs/site-lisp/"
  :ensure nil
  :defer t
  :commands (notmuch notmuch-mua-new-mail)
  :init
  ;; Search
  (setq notmuch-search-oldest-first nil)
  :config
  ; General UI
  (setq notmuch-show-logo nil
	notmuch-column-control 1.0
	notmuch-hello-auto-refresh t
	notmuch-hello-recent-searches-max 20
	notmuch-hello-thousands-separator ""
	notmuch-hello-sections '(notmuch-hello-insert-saved-searches)
	notmuch-show-all-tags-list t)

  ; Search
  (setq notmuch-search-result-format
        '(("date" . "%12s  ")
          ("count" . "%-7s  ")
          ("authors" . "%-20s  ")
          ("subject" . "%-80s  ")
          ("tags" . "(%s)")))
  (setq notmuch-tree-result-format
        '(("date" . "%12s  ")
          ("authors" . "%-20s  ")
          ((("tree" . "%s")
            ("subject" . "%s"))
           . " %-80s  ")
          ("tags" . "(%s)")))
  (setq notmuch-show-empty-saved-searches t)

  ; Tags
  (setq notmuch-archive-tags nil ; I don't archive email
	notmuch-message-replied-tags '("+replied")
	notmuch-message-forwarded-tags '("+forwarded")
	notmuch-show-mark-read-tags '("-unread")
	notmuch-draft-tags '("+draft")
	notmuch-draft-folder "university/Drafts"
	notmuch-draft-save-plaintext 'ask)

  ; Email composition
  (setq notmuch-mua-compose-in 'new-window)
  (setq notmuch-mua-hidden-headers nil)
  (setq notmuch-address-command 'internal)
  (setq notmuch-address-use-company nil)
  (setq notmuch-always-prompt-for-sender t)
  (setq notmuch-mua-cite-function
	'message-cite-original-without-signature)
  (setq notmuch-mua-user-agent-function nil)

  (setq notmuch-show-relative-dates t)
  (setq notmuch-show-all-multipart/alternative-parts nil)
  (setq notmuch-show-indent-messages-width 0)
  (setq notmuch-show-indent-multipart nil)
  (setq notmuch-show-part-button-default-action 'notmuch-show-view-part)
  (setq notmuch-wash-wrap-lines-length 120)
  (setq notmuch-unthreaded-show-out nil)
  (setq notmuch-message-headers '("To" "Cc" "Subject" "Date"))
  (setq notmuch-message-headers-visible t)

  :bind
  ( :map global-map
    ("C-c m m" . notmuch)
    ("C-x m" . notmuch-mua-new-mail) ; override `compose-mail'
    :map notmuch-search-mode-map
    ("/" . notmuch-search-filter) ; alias for l
    ("r" . notmuch-search-reply-to-thread) ; easier to reply to all by default
    ("R" . notmuch-search-reply-to-thread-sender)
    :map notmuch-show-mode-map
    ("r" . notmuch-show-reply) ; easier to reply to all by default
    ("R" . notmuch-show-reply-sender)
    :map notmuch-hello-mode-map
    ("J" . notmuch-jump-search)))

You're free to look at my init.el for my own customization for notmuch.el.

Automating email synchronization with systemd timers

Let's automate the email sync to happen every 15 mins (or whatever frequency you prefer). First we create a shell-script to download email via mbsync and also index the email with notmuch. Let's name it it syncmail.sh and place it in $HOME/.local/bin/.

#!/bin/sh
set -eu

# Set environment variable for notmuch config file
export NOTMUCH_CONFIG="$HOME/.config/notmuch/notmuch-config"

mbsync university

before=$(notmuch count --lastmod '*' | cut -f3)
notmuch new > /dev/null

query="lastmod:$((before + 1)).. and path:university/**"
count=$(notmuch count "$query")

if [ "$count" -gt 0 ]; then
    body=$(notmuch search --format=json --limit=5 "$query" \
	       | jq -r '.[] | "\(.authors): \(.subject)"')
    notify-send "New mail: $count" "$body"
fi

In addition to downloading email and indexing, the script also notifies through notify-send if there's new email along with a sender and subject in the notification. Make sure to make the script executable with

chmod +x ./syncmail.sh

Then we write the systemd script to run this script periodically. First we create a syncmail.service file in $HOME/.config/systemd/user/:

[Unit]
Description=Sync mail with mbsync and index with notmuch

[Service]
Type=oneshot
ExecStart=%h/.local/bin/syncmail.sh

Then we create a timer file (make sure it is named syncmail.timer) for actually running the script every n minutes.

[Unit]
Description=Run syncmail every 15 minutes

[Timer]
OnBootSec=2m
OnUnitActiveSec=15m
Persistent=true

[Install]
WantedBy=timers.target

The advantage over cronjobs is that if your system is asleep or shutdown, then booting up accomodates accordingly and runs the script after m minutes (2 minutes in my case).

Finally we enable the script with systemctl:

systemctl --user daemon-reload
systemctl --user enable --now syncmail.timer

Concluding remarks

Now you should have a working setup for using offline email for Microsoft's O365. This is fairly minimal but if you'd like to have encrypted emails, addressbooks, etc., please take a look at the original blogpost from Fergus.

A basic emailing etiquette I like to follow is to use plaintext as opposed to html. Read more on why this is better.

Christian Arzu from the @linkarzu channel on YouTube has just published a ~16-minute video with the title What I Need From Emacs: A Video for Prot.

I am happy he has done this and am eager to discuss those concepts in further depth. In this article I will comment on the specific points Christian raises as well as on the overarching theme of his experiment with Emacs.

Emacs has “sessions” out-of-the-box

Christian has experienced friction with using Emacs. Much of it revolves around the notion of “sessions” that Kitty provides. At least for the way Christian uses sessions, Emacs has the equivalent concept of “projects”. Each project is a version controlled directory (Git in this case, though Emacs supports many others as well).

To tell Emacs where your Git repositories are, so that it can record all of them as known projects, do M-x project-remember-projects-under and select the directory at the follow-up prompt.

To switch between projects, use M-x project-switch-project. At this prompt, you use search to narrow the results and pick one among your existing projects. There is also an option to open a specific directory that is not yet a known project, which will thenceforth be remembered as a project if it is under version control (there are other options on how projects are identified, but the presence of version control system is the default check).

Projects also become known if you invoke one of the project-specific commands from inside the given Git repository. For example, if you call the command project-find-file, it will do what it is supposed to do (more below) in the current repository and store that repository as one your projects for future use.

Quickly find a file anywhere in the project

The find-file command (C-x C-f by default) is about manually navigating to a path. Christian finds this cumbersome and indeed it is if you are thinking in terms of selecting a file related to the current project.

The command project-find-file consolidates all the files into a flat list from where you can type a few characters to narrow the results and pick the file you need.

Similarly, project-find-dir lets you pick any directory in the current project, which is especially useful if you need to do something with many files (e.g. rename a bunch of files or change their permissions).

This principle extends to all other relevant commands. For example, project-shell opens a shell buffer at the root of the current project. If you are using something like the ghostel package (https://github.com/dakra/ghostel), it provides the ghostel-project command to open a fully fledged terminal emulator (i.e. not just a “shell”) in this project’s root directory.

There are many other nice things that can be done on a per-project basis, such as to run the relevant compile command, switch to the project’s buffers, perform a project-wide grep, and more.

And, generally, many packages will build on top of projects, such as the popular consult package (https://github.com/minad/consult) with some of its commands like consult-find and consult-grep (or consult-ripgrep).

The built-in projects can be combined with other features

These Emacs project capabilities can easily be combined with other features that Emacs also supports out-of-the-box.

For example, you can set things up so that when you switch to a new project it appears on another tab (displayed at the top of the Emacs frame) or, indeed, to switch to another frame, within which there can be tabs.

To augment projects, you can combine them with mechanisms that restore buffers and/or window/tab/frame arrangements after you restart Emacs. For example, the bufferlo package (https://github.com/florommel/bufferlo) covers this space.

Piecing together the system

Depending on one’s needs, there is a lot that can be done to not only recreate those sessions that Christian mentions but to do arbitrary things on top, with the help of packages as well as custom Elisp (and writing your own Elisp is very much in the spirit of extending Emacs to do exactly what makes sense to you).

Though here we get into the area of workflow and the overall approach. I think it is safer to try things one at a time from the ground up, so that you can understand how the emergent system is pieced together. This allows you to better reason about what you have and what you need. Plus, it empowers you to troubleshoot things because you already have a sense of what is there.

For example, you start with the projects as they are done in the generic Emacs. When you find something that does not quite work, you read the documentation to see if there is some user option to configure things to your liking. Then you can search for packages that augment the experience, based on your specific requirements and expectations.

Remember that Kitty sessions build on top of existing experience

Taking a step back, consider that what Kitty provides is not something you get up-and-running with as a new user of terminal emulators.

When you are a beginner with terminal emulators, you barely understand how things work and how you are supposed to interact with the tool. Over time you learn all the nice things about the shell and eventually you incorporate custom scripts and extensions that augment your experience (like fuzzy finding, multiplexing, storing/restoring configurations).

To remind yourself how austere the default experience is, launch an unmodified instance of XTerm. It will bring to the foreground the fact that what Christian is doing with his Kitty setup is many levels above what a standard terminal-based workflow looks like.

And the key here is that each level corresponds to a corpus of knowledge that took form through experience. In other words, it was done over time.

The same is true for Emacs and everything else: you cannot speedrun experience.

Capturing thoughts very quickly

Christian demonstrates how he quickly creates a daily note to record a reminder or fleeting thought. The equivalent built-in facility in Emacs is org-capture: it can do a lot of things, but to cover specifically what Christian wants, there is an org-capture-templates configuration that records an entry under a specific tree of date headings. Because there can be many such templates, the user can define any variations they need to match their specific requirements.

If the user prefers that those fleeting thoughts are always captured in standalone files, one per day, then the popular org-roam package can do that through what it calls “dailies” (one note per day). There are other ways to do the same thing, including with core Org, but org-roam streamlines this method.

org-roam also covers another need Christian has, which is about linking files together and finding the backlinks to them (again, there are many ways to achieve this, but covering all the options is not the topic here).

You do not necessarily need Emacs

What I say to others and will write for Christian as well is always have a good idea “why” you want something before committing to it. This is how you find the motivation to stick to a project despite the eventual setbacks. Without the “why” it is practically guaranteed that you will quit early.

NeoVim, Kitty, and friends can combine to provide practically all the features that Emacs has. Users may then argue over the relative pros and cons of each approach, which I personally consider a distraction because what matters is to have a computing environment that gets the job done. The gist, however, is that if NeoVim+extras works for you, then you do not really gain anything from switching to Emacs: it is a lateral step at best.

More importantly, if your current setup covers all your needs, you do not have a compelling reason and thus the drive to persistently try Emacs. It is the same for me: Emacs covers my needs, so I do not feel any enthusiasm—or, indeed, curiosity—to spend time with other options. Maybe those other options are excellent and maybe they can be configured to be superior to my Emacs setup. But what I have fits my workflow, so I do not have the emotional push to look elsewhere.

Without the “why”, it will be practically impossible to stick with any experiment: it will always make sense to revert to the state you are familiar with.

Careful with shortcuts in life

Allow me to elaborate on my claim that you cannot speedrun experience. I will use an example from football (soccer), as I played it at a high level and it may be a more relatable story anyway.

You watch the game and are excited to walk on the pitch right away to score some goals. It looks cool and feels amazing! However, you have not practised the fundamentals, like controlling the ball while running and having situational awareness. You believe you can figure those out while playing the actual match. As such, you overestimate your abilities and set yourself up for failure.

Then, things get real all of a sudden. Within the first minute of the match, you come up against someone like me, who makes no discounts and takes no nonsense. I will not let you ever get near that ball: I will be first on the challenge because I know how to position myself and, even if I am not first, I will regain possession of the ball with ease because I have done it a zillion times.

You will never get anywhere near scoring a goal and you will likely not get the chance to be involved in the flow of even smaller patterns of play like an exchange of passes. Whenever you are close to touching the ball, I will be there breathing down your neck, hounding you everywhere you go. Such is the gulf in experience that I will make your life miserable on that pitch.

In short, your initial enthusiasm will quickly turn into frustration because there will be no gameplay whatsoever for you. And the worst part is that it will only get harder from there, as I will also be competitive on top of being annoyingly better, with tough challenges, crunching tackles, constant shittalking to add insult to injury, and the overall aggression that shows a clear willingness to escalate further.

This is not about me: I am using myself as a proxy for the experienced player who grants you the honour of a true challenge. I am doing it to make it feel real and thus to emphasise the frustrating parts because this is exactly how life works when you are not prepared.

The morale of this story is that working on the fundamentals guarantees a better long-term experience and, above all, is a process you should not skip.

TMR provides facilities for setting timers using a convenient notation. Lots of commands are available to operate on timers, while there also exists a tabulated view to display all timers in a nice grid.

• Package name (GNU ELPA): tmr
• Official manual: https://protesilaos.com/emacs/tmr
• Change log: https://protesilaos.com/emacs/tmr-changelog
• Git repositories:
  • GitHub: https://github.com/protesilaos/tmr
  • GitLab: https://gitlab.com/protesilaos/tmr
• Video demonstration: https://protesilaos.com/codelog/2026-01-19-emacs-timers-tmr-demo/
• Backronym: TMR May Ring; Timer Must Run.

Below are the release notes.

Version 1.4.0 on 2026-07-31

TMR is an efficient package that has been stable for years. This new version introduces some nice new features as well as several smaller internal refinements.

Create a timer that repeats

The command tmr-repeat prompts for a duration, like the standard tmr command but also asks for a number of times to repeat the given timer. When called with a prefix argument (C-u with default keybindings), tmr-repeat will also ask for a description for the new timer and whether it should be acknowledged or not after all repetitions have elapsed.

Thanks to Óscar Fuentes for contributing the original implementation of tmr-repeat (with many extra changes/features by me). This was done in pull request 16: https://github.com/protesilaos/tmr/pull/16. Óscar has assigned copyright to the Free Software Foundation.

Modify the repeat count of an existing timer

The command tmr-edit-repeat-count prompts for an existing timer and updates its repeat count. If the repeat count is set to 0, then the timer is no longer considered repeatable.

As with all commands that operate on existing timers, tmr-edit-repeat-count automatically applies to the timer at point when called from inside the tabulated list of timers (per tmr-tabulated-view).

Modifying a timer’s repeat count does not start a new timer. It simply updates the relevant data. Use the command tmr-clone to start a new timer using the data of an existing timer.

The tabulated view has more columns and all of them can be adjusted

The tabulated list of timers, which is typically produced by the command tmr-tabulated-view, now has extra columns for the data that pertains to repeatable timers.

Users who want to control which columns are displayed, and in what order, can modify the user option tmr-tabulated-columns. Its documentation covers the technicalities. The default value is to display all columns.

Completion metadata for the prompt that selects a timer

Advanced users can now modify all the completion-metadata associated with the prompt that reads/selects one among the existing timer objects (the function is tmr-read-timer). The relevant variable is tmr-completion-metadata. I am not providing this as a user option, because regular users will anyway not be able to do much with it as it involves custom functions.

Timers in the completion prompt are sorted by end time

The prompt for selecting a timer now sorts candidates by their end time. The closest end time appears at the top.

This affects all commands that operate on a timer, such as tmr-edit-repeat-count, tmr-cancel, and more.

In the past, there was no sorting whatsoever. Users who prefer that style can add the following to their configuration:

(setq tmr-completion-metadata
      (list
       (cons 'category 'tmr-timer)
       (cons 'display-sort-function #'identity) ; THIS IS THE RELEVANT PART
       (cons 'annotation-function #'tmr-completion-annotate)))

Miscellaneous

• The manual is easier to read. I have rewritten it to group commands and user options under appropriate headings.

• Lots of internal refinements to the code. I tweaks things to make the code easier to maintain and contribute to.

• Thanks to Pavlo Lysov for adding a small example to the manual about using TMR hooks to send a custom notification on the macOS. This was done in pull request 25: https://github.com/protesilaos/tmr/pull/25. Pavlo does not need to assign copyright to the Free Software Foundation.

• Thanks to Carlos Pajuelo Rojo for refining an earlier version of the function that produces a message about the repeat count of a given timer (I have since made lots of changes on this and other fronts). Carlos’ contribution is in pull request 20: https://github.com/protesilaos/tmr/pull/20. The change is small, meaning that Carlos does not need to assign copyright to the Free Software Foundation.

• Thanks to f6p for use the appropriate face for the paused indicator in the tabulated view. This was done in pull request 17: https://github.com/protesilaos/tmr/pull/17. The change is small, meaning that the author does not need to assign copyright to the Free Software Foundation.

My last post was a tour of Emacs 31, which has since moved into pretest. Sean Whitton announced 31.0.91, the second pretest, on July 23rd, and that's what I'm writing this on. One of the sections in that post was a short list of new completion knobs, three lines of config I mentioned and moved on from. Those three lines turned into a month-long experiment, so they get their own post.

I know how that title reads, so let me put it in context before you close the tab. It comes from someone who ran company, moved to Corfu, and then left Corfu behind for icomplete, which has been my weapon of choice for years now, for both the minibuffer and in-buffer completion.

And I didn't just use icomplete. I sent patches to it. bug#75784, which brought vertical in-buffer behavior and prefix indicators to icomplete, is mine, and I wrote about the road to it here and here. So when I say I turned icomplete off for a month, understand that I was arguing with my own past self, and that the title isn't me saying the last few years were wasted. It's me saying the floor moved.

What made me try was Emacs 31 itself. The *Completions* buffer improved nicely while I wasn't looking, and I wanted to know whether the UI I'd been layering on top of it was still earning its place.

While I was drafting this, Protesilaos published a video on the same territory. I haven't watched it all the way through yet, and I'm publishing anyway, because what follows is my month with this setup rather than a summary of his. His videos have shaped a lot of how I think about Emacs, so go watch it too. I'll probably end up fixing some of my own setup after I do.

Everything below runs on stock Emacs 31. Save the snippets into a test.el and launch with:

emacs -Q --load test.el

The full playground file (search for test.el) is at the bottom of the post if you'd rather skip ahead.

Two completions, one buffer

Emacs completes in two places, and it's worth keeping them apart in your head:

✔️ Minibuffer completion. M-x, C-x C-f, C-x b, every completing-read prompt in every package you have. You type in the minibuffer, candidates come from a completion table.

✔️ In-buffer completion. completion-at-point, the thing bound to M-TAB, and to TAB if you set tab-always-indent to complete. You type in a normal buffer and the candidates come from completion-at-point-functions: elisp symbols, file names, whatever your LSP server offers through Eglot.

Corfu and company handle the second case. Vertico, ivy and friends handle the first. You probably run one of each. Emacs covers both with the same *Completions* buffer, which surprised me, and it means one block of config does the whole job.

The base config

This is what I run:

(defun my/minibuffer-truncate-lines ()
  "Keep minibuffer lines unwrapped."
  (setq truncate-lines t))

(use-package minibuffer
  :ensure nil
  :bind ( :map minibuffer-visible-completions-up-down-map
		  ("C-n" . minibuffer-next-completion)
		  ("C-p" . minibuffer-previous-completion))
  :hook ((minibuffer-setup . cursor-intangible-mode)
		 (minibuffer-setup . my/minibuffer-truncate-lines))
  :custom
  (tab-always-indent 'complete)
  (completion-auto-help t)
  (completion-auto-select t)
  (completion-eager-update t)
  (completion-eager-display t)
  (minibuffer-visible-completions 'up-down)
  (completion-ignore-case t)
  (completion-show-help nil)
  (completion-styles '(partial-completion flex initials))
  (completions-format 'one-column)
  (completions-max-height 10)
  (completions-sort 'historical)
  (enable-recursive-minibuffers t)
  (read-buffer-completion-ignore-case t)
  (read-file-name-completion-ignore-case t)
  (minibuffer-prompt-properties
   '(read-only t intangible t cursor-intangible t face minibuffer-prompt))
  (minibuffer-depth-indicate-mode t)
  (minibuffer-electric-default-mode t))

Two of those carry the post, and both are new in Emacs 31:

:custom
;; ...
(completion-eager-update t)
(completion-eager-display t)
;; ...

completion-eager-display decides whether *Completions* shows up on its own. completion-eager-update decides whether it refreshes as you type. Both default to 'auto in Emacs 31, which means "only if the completion table asks for it," and almost nothing asks. Set both to t and you stop summoning the buffer with TAB. It's already open.

Run emacs -Q, hit M-x, type wind, and you get nothing but your own text in the minibuffer. Load the config above, do the same, and 34 candidates appear the moment you stop typing. Keep typing move-del and the list narrows to 5 without you touching a key that isn't a letter.

completions-format 'one-column and completions-max-height 10 are what turn that list into a vertical one. The default is 'horizontal, which packs candidates across the window like ls output. One column, capped at ten lines, reads as a dropdown.

completions-sort 'historical sorts alphabetically and then floats whatever you picked recently to the top. It's the smallest of these settings and the one I'd miss first.

That exact moment, below: four letters typed into M-x, no TAB pressed, 34 candidates already sitting there in one column.

completion-auto-select t moves point into the *Completions* window when TAB pops it up, so you can navigate the list without a second key to get there. completion-show-help nil drops the two-line "Click or type RET on a completion to select it" banner from the top of the buffer, which I've read enough times for one lifetime.

enable-recursive-minibuffers plus minibuffer-depth-indicate-mode belong together: the first lets you start a minibuffer command from inside another one, the second puts a [2] in the prompt so you know how deep you are. minibuffer-electric-default-mode hides the (default foo) part of a prompt as soon as you type, and brings it back if you erase.

The minibuffer-prompt-properties line keeps point out of the read-only prompt text, and cursor-intangible-mode on minibuffer-setup-hook is what enforces it. truncate-lines in the minibuffer keeps long candidates on one line instead of ballooning the minibuffer to N rows.

One of those settings needs a keybinding to go with it. With minibuffer-visible-completions set to 'up-down, the arrow keys move point inside *Completions* while you're still typing in the minibuffer, and RET takes the highlighted candidate instead of your literal input. Left and right still move in the minibuffer, which is why I use 'up-down rather than t.

By the way, I tend to avoid arrow keys, M-<some-arrow-direction> doesn't feel natural in a completion list for me. That's why I set C-n and C-p like this:

:bind (:map minibuffer-visible-completions-up-down-map
	   ("C-n" . minibuffer-next-completion)
	   ("C-p" . minibuffer-previous-completion))

Below, the same list after a couple of C-n. The highlight has walked down to windmove-delete-default-keybindings while the cursor is still in the minibuffer, where I'm still typing.

The same buffer, in your code

This setting is the one that made the experiment worth running:

:custom
;; ...
(tab-always-indent 'complete)
;; ...

TAB in a code buffer now indents the line if it needs indenting, then completes if it doesn't. Open *scratch*, type (window-lay, hit TAB. Emacs fills in the common prefix, window-layout-. Hit TAB again and *Completions* opens with the five commands that match, with point already inside it thanks to completion-auto-select. C-n to the one you want, RET, done.

The same keys and config as the minibuffer half, in a code buffer now.

After the second TAB, below: the buffer holds (window-layout-, the five commands sit underneath, and the first is already selected.

*Completions* is a real window, so it takes room in your frame instead of floating over it. After a month I've stopped noticing, and I got something back for it: the candidate list is an ordinary buffer, so I can search it, scroll it, and yank out of it.

Where LSP completion goes wrong

One place did annoy me enough to write code.

My completion styles are:

:custom
;; ...
(completion-styles '(partial-completion flex initials))
;; ...

flex is the fuzzy one: it matches an in-order subset of what you typed, so faL finds faLinkedin and faList without you spelling out the middle. Exactly what I want from an LSP buffer, where I half-remember a name and want to see the family.

But flex does two jobs, and only one of them is filtering. Its try-completion also merges the surviving candidates and inserts the result. With tab-always-indent set to complete, that merge happens on TAB, before you ever see the list.

The case that cost me an afternoon comes from this blog's own source. components/footer.tsx imports a handful of FontAwesome icons. I wanted faLinkedin, so I typed faL and pressed TAB once:

;; I typed:            faL
;; TAB left me with:   faEnvelopeSquare

And no list is shown, faEnvelopeSquare matches faL under flex because the l sits inside "Envelope", and that's where the merge landed. TAB typed sixteen characters I didn't ask for, hid the candidates I did want, and left me deleting.

The frame below shows the whole thing. The echo area tells me Complete, but not unique, which is Emacs admitting it guessed and still showing me none of the alternatives:

That's the gap I kept hitting between the default UI and what icomplete had trained me to expect. icomplete shows me candidates on TAB. Here it types at me.

Eglot ran into this too and works around it with its own eglot--dumb-flex style, which skips the merge. That fixes the typing and loses the scoring, so candidates come back in whatever order the server sent them.

I wanted both: flex's filtering and relevance sorting, and no insertion until I pick something. So I wrapped it.

flex-noinsert

(defun my/flex-noinsert-try-completion (string table pred point)
  "Flex `try-completion' that never auto-extends the input on TAB.

The stock `flex' completion style does two jobs: it filters
candidates by fuzzy (subsequence) match, and its `try-completion'
merges the surviving candidates, inserting their common expansion
into the buffer.  With `tab-always-indent' set to `complete' that
merge means TAB silently types a candidate (often a far, wrong one)
*before* the *Completions* list is shown.  Eglot's own
`eglot--dumb-flex' avoids the merge but gives no relevance sorting.

This wrapper keeps flex's filtering and scoring (so prefix matches
sort first, fuzzy ones last) but suppresses the merge:

  - no candidates           -> nil   (no match)
  - exactly one candidate   -> complete it fully (TAB still finishes
							   a unique completion)
  - two or more candidates  -> return STRING unchanged, so TAB only
							   pops the *Completions* list and lets
							   you pick, inserting nothing.

STRING, TABLE, PRED and POINT are the usual `try-completion' args."
  (let ((all (completion-flex-all-completions string table pred point)))
	(cond
	 ((null all) nil)
	 ((= (safe-length all) 1)
	  (let ((sole (car all)))
		(if (string= sole string) t (cons sole (length sole)))))
	 (t (cons string point)))))

;; Register the `flex-noinsert' style: same filtering/sorting as
;; `flex', but with the wrapper above as its try function.
(add-to-list 'completion-styles-alist
			 '(flex-noinsert
			   my/flex-noinsert-try-completion
			   completion-flex-all-completions
			   "Flex matching that never extends input on TAB."))

;; Reuse flex's metadata tweak so *Completions* sorts by flex score.
(put 'flex-noinsert 'completion--adjust-metadata
	 'completion--flex-adjust-metadata)

A completion style in Emacs is four things in a list: a name, a try-completion function, an all-completions function, and a doc string. I reuse completion-flex-all-completions unchanged, so filtering and scoring are stock flex, and I swap in a try-completion that refuses to merge. The completion--adjust-metadata property is what keeps *Completions* sorted by flex score rather than alphabetically.

Then aim it at Eglot only:

:custom
;; ...
(completion-category-overrides '((eglot-capf (styles flex-noinsert))))
;; ...

Minibuffer completion keeps stock flex, where the merge behavior is fine because you can see what it did. Eglot's eglot-capf category gets the no-insert variant.

Now in the same situation as before, trying to complete faL with TAB. The buffer keeps saying faL, and *Completions* opens instead.

It opens with 2664 candidates, which sounds absurd until you look at what's on top: faL itself, then faLeaf, faLess, faLine. Flex matches loosely and scores tightly, so I get a huge tail under a head that's already correct. The trade only works if nothing gets typed into my buffer first.

One more letter sharpens it. faLi cuts the list to 859, and the visible window holds the family I was after:

;; faLi + TAB
;;
;; *Completions*
;;   faLine    @fortawesome/free-brands-svg-icons
;;   faLink    @fortawesome/free-solid-svg-icons
;;   faList    @fortawesome/free-solid-svg-icons
;;   faLinux   @fortawesome/free-brands-svg-icons

Each one appears twice, once for the package and once for the deep import path, and Eglot shows me which module it would pull from. C-n and RET, or keep typing. Unique completions still finish on the first TAB, because that's the one case where the merge can't be wrong.

Here is faL with the fix in place. Emacs wrote nothing into the buffer, and the long tail sits under a head that starts where I was aiming:

And faLi, where the whole visible window is the answer:

Living with it

A month in and:

✔️ The minibuffer half is a straight swap. Take the drawing away and the functionality is exactly what I already had with icomplete-vertical-mode. M-x, C-x b, C-x C-f: same filtering, same narrowing as I type, same keys under the same fingers. My hands and eyes resynced in a day or two, which is the part nobody can argue you into. I'm not tolerating this until I go back to icomplete. It's an alternative with a different UI and the same behavior, and I'm running it. The list being a real buffer is a bonus on top.

✔️ The in-buffer half surprised me. I assumed I'd miss a floating popup within a week. It took a couple of days to stop thinking about it, and splits are what sold me. Complete inside the left window of a C-x 3 and *Completions* opens in that window, under the code I'm completing. The right split never moves. The list arrives where I'm already looking, and the rest of the frame stays where I left it.

A two-window frame below, avatar.tsx on the left and footer.tsx on the right. I completed on the left, and that's the only half that changed:

✔️ flex-noinsert is doing real work. Without it I'd have given up on the default and gone back inside a week.

✔️ The scoring is where the defaults still trail. A dedicated fuzzy matcher does better when I type three letters from the middle of a name. flex gets close without getting there.

IMPORTANT: I haven't deleted icomplete from my config, and I'm not telling you to delete yours. And if you enjoy Vertico, Corfu, company or anything else in that family, please keep using it. Those are excellent projects, with real care put into how they look and feel, and which one you run is a personal preference, not a correctness contest. Nothing here is an argument against them.

I wanted to show how good, and how complete, the default completion has become. That's all. It's really cool now, and it's sitting in the editor you already have.

What changed for me is that I now know what the default does. When I go back to icomplete I'll be choosing it rather than inheriting it.

If you run Emacs Solo, you don't have to take my word for any of it, because the switch is already wired up:

(setq emacs-solo-enable-icomplete nil)  ; plain *Completions*
(setq emacs-solo-enable-icomplete t)    ; icomplete, the default

It's a defcustom, so M-x customize-variable RET emacs-solo-enable-icomplete works too. Flip it, restart, and live with the other side for a week. Emacs Solo adjusts the related settings for you: with icomplete off it sets completion-eager-display to t rather than 'auto, which is the setting that makes *Completions* show up on its own.

Give each side long enough that you stop noticing it. After one day you'll only know which one feels unfamiliar, and that's a different question from which one you want.

The full test.el

Save this, run emacs -Q --load test.el, and poke at it. Emacs 31 or newer, since completion-eager-update, completion-eager-display and minibuffer-visible-completions-up-down-map are all new here.

;;; test.el --- default completions playground -*- lexical-binding: t -*-

(defun my/minibuffer-truncate-lines ()
  "Keep minibuffer lines unwrapped."
  (setq truncate-lines t))

(defun my/flex-noinsert-try-completion (string table pred point)
  "Flex `try-completion' that never auto-extends the input on TAB.

Keeps flex's filtering and scoring but suppresses the merge:

  - no candidates           -> nil   (no match)
  - exactly one candidate   -> complete it fully
  - two or more candidates  -> return STRING unchanged, so TAB only
							   pops the *Completions* list.

STRING, TABLE, PRED and POINT are the usual `try-completion' args."
  (let ((all (completion-flex-all-completions string table pred point)))
	(cond
	 ((null all) nil)
	 ((= (safe-length all) 1)
	  (let ((sole (car all)))
		(if (string= sole string) t (cons sole (length sole)))))
	 (t (cons string point)))))

(use-package minibuffer
  :ensure nil
  :bind ( :map minibuffer-visible-completions-up-down-map
		  ("C-n" . minibuffer-next-completion)
		  ("C-p" . minibuffer-previous-completion))
  :hook ((minibuffer-setup . cursor-intangible-mode)
		 (minibuffer-setup . my/minibuffer-truncate-lines))
  :custom
  (tab-always-indent 'complete)
  (completion-auto-help t)
  (completion-auto-select t)
  (completion-eager-update t)
  (completion-eager-display t)
  (minibuffer-visible-completions 'up-down)
  (completion-ignore-case t)
  (completion-show-help nil)
  (completion-styles '(partial-completion flex initials))
  (completion-category-overrides '((eglot-capf (styles flex-noinsert))))
  (completions-format 'one-column)
  (completions-max-height 10)
  (completions-sort 'historical)
  (enable-recursive-minibuffers t)
  (read-buffer-completion-ignore-case t)
  (read-file-name-completion-ignore-case t)
  (minibuffer-prompt-properties
   '(read-only t intangible t cursor-intangible t face minibuffer-prompt))
  (minibuffer-depth-indicate-mode t)
  (minibuffer-electric-default-mode t)
  :config
  (add-to-list 'completion-styles-alist
			   '(flex-noinsert
				 my/flex-noinsert-try-completion
				 completion-flex-all-completions
				 "Flex matching that never extends input on TAB."))
  (put 'flex-noinsert 'completion--adjust-metadata
	   'completion--flex-adjust-metadata))

;;; test.el ends here

Things to try once it's loaded:

✔️ M-x and type a few letters, then C-n and C-p through the list.

✔️ C-x C-f and walk a directory tree with the same keys.

✔️ In *scratch*, type (window-lay and hit TAB twice.

✔️ C-x C-f into a project with an LSP server, M-x eglot, and type a partial method name followed by TAB to watch flex-noinsert behave.

And C-x C-f doing the same job on a directory, below:

All of it lives in Emacs Solo too, my no-external-packages config, if you'd rather read it in context.

Now, go watch Prot's take after this one.

Happy hacking!

In the Apple ecosphere—especially in iOS—a convenient short cut is to type two spaces to end the current sentence and start a new one. Specifically, two spaces will delete the spaces, insert a period and a space, and capitalize the next letter. There’s probably something similar in the Android world; it seems like a natural thing to do.

Over at Bicycle For Your Mind, macosxguru has a post that describes three of the recent changes he’s made to his Emacs environment. Two of them—showing tabs and newlines explicitly, and fiddling with his mode line probably won’t interest most Irreal readers. The third is importing the two space shortcut into Emacs.

Emacs, of course, doesn’t have that capability but macosxguru added it with a bit of Elisp which he binds to the Space key with the text-mode hook. It looks for two consecutive spaces and repaces them with a period and space. The tricky part is capitalizing the next letter. He does that by reading the next character explicitly and capitalizing it if it’s a letter. He also checks for some special keys (like an arrow key) and “unreads” them so that Emacs can treat them normally. All the code is in the post so see it for the details if you’re interested.

I’m ambivalent about this change. On the one hand, I use it all the time on my iPhone and iPad but that’s because typing is such a pain on virtual keyboards. On a regular keyboard, I’m pretty sure that I could type the period, space, and next letter just as fast. The shift for the next letter might slow things down a bit but not by much. I haven’t decided yet whether I will adopt it but inertia will probably cause me not to.

Marcin Borkowski (mbork) really likes being able to cycle folding in Org buffers. Of course, then he wanted to be able to do the same thing in any buffer. In particular, he wanted to be able to fold and unfold groups of functions as a set. He experimented with all sorts of solutions including the builtin outline minor mode.

None of them were quite what he wanted. Then he found outli. It was perfect for his needs. It’s a third party package but appears to be well maintained and is less than 400 lines of code. What he really likes, though, is the keybindings. Most important to him is that Tab cycles the folding just like in Org mode.

Although I like and use headline folding in Org mode, I’ve never been able warm up to code folding. On those rare occasions when I want to narrow focus to a single function—usually to delimit searches—I simply narrow to the function or region in question. Of course, others, like mbork, disagree and those folks may want to check out mbork’s post to get the details of his solution.

Continuing the series on the notable changes in CIDER 2.0, let’s talk about ClojureScript - forever the trickier sibling in the CIDER family.

I’ll start with a confession I’ve made before: I rarely use ClojureScript myself, which is a big part of why its support in CIDER has historically lagged behind Clojure’s. Every “State of CIDER” survey reminds me of this, usually in the comments section, occasionally in all caps. So in the 2.0 cycle I decided to stop feeling vaguely guilty about it and actually do something - across every layer of the stack: CIDER itself, cider-nrepl, and Piggieback.

First, a strategic decision

The most important ClojureScript change in CIDER 2.0 isn’t a feature - it’s a decision about what not to build. Some of CIDER’s most powerful tools (the debugger, enlighten, tracing, profiling) are deeply tied to JVM runtime introspection, and porting them to ClojureScript would be a massive effort with a poor cost/benefit ratio. Rather than keeping them in eternal “maybe someday” limbo, we’ve explicitly scoped them as Clojure-only and focused the actual work on the things cljs users hit every day: evaluation, testing, error reporting, and clear behavior everywhere else.

That last part matters more than it sounds. Historically, invoking a JVM-only command in a ClojureScript REPL would fail in some confusing way - a cryptic error, a JVM-flavored result, or silence. Now the ops themselves report a clojure-only status, and CIDER tells you plainly that the command isn’t supported for ClojureScript. Knowing what a tool won’t do is half of trusting it.

What actually got better

• The regular test commands (cider-test-run-ns-tests and friends) now work in ClojureScript REPLs, asynchronous cljs.test/async tests included. Previously CIDER just refused, and you were stuck evaluating (run-tests) by hand like an animal.
• Expanding your own macros (e.g. ones brought in via :refer-macros) used to silently echo the form back unexpanded - a bug filed all the way back in 2017. The compiler environment is now threaded to the analyzer properly, and it just works.
• cider-nrepl now resolves the ClojureScript compiler environment through a provider chain, with a dedicated shadow-cljs provider - so the static-analysis ops keep working in a shadow REPL that never loads Piggieback.
• The new cider-tap viewer works with ClojureScript too: a runtime helper buffers tapped values and the JVM side streams them to Emacs. (Tapped cljs values aren’t inspectable - they live in the JS runtime - but you see them as they happen.)
• ClojureScript stack frames now render their ns/fn properly instead of degrading to nil/nil, and unqualified core vars resolve against cljs.core rather than falling back to clojure.core (which quietly broke things like indentation metadata).
• A recent ClojureScript on the classpath (whose Closure compiler wants JDK 21+) no longer crashes cider-nrepl at startup on an older JDK - you get a Clojure-only session instead of no session.
• Piggieback itself got a round of bug fixes in the 0.6.x/0.7.0 releases - it’s easy to forget it exists (which is rather the point of it), but it powers most cljs REPLs CIDER talks to.

The documentation kept pace too: the new full-stack Clojure + ClojureScript guide covers the two-REPLs-one-project setup that trips up nearly everyone, and the ClojureScript docs got a general refresh.

An unexpected assist

Fun aside: this is the area where AI coding agents helped me the most during the 2.0 cycle. My ClojureScript experience is limited, but between the excellent bug reports from the community and the ability to quickly prototype and test fixes against real shadow-cljs and figwheel setups, problems that had been “someone who knows cljs should look at this someday” for years finally got fixed. Make of that what you will.

What’s next

I keep pondering some form of “native” shadow-cljs support, given that shadow-cljs is what most ClojureScript users actually run these days. That’s still very much in the hammock phase, so don’t hold me to it - but the direction is clear: fewer moving parts, clearer errors, and honesty about what’s supported.

If you’re a ClojureScript user, I’d genuinely love to hear how 2.0 feels in your daily work - the feedback loop is what keeps this improving. Keep hacking!

Articles in the Series

• CIDER 2.0: Sky is the Limit
• Simplifying Session Management in CIDER
• Stepping Through Macros in CIDER
• Making CIDER More Discoverable
• Modernizing CIDER's Completion
• Closing the Find-Usages Gap in CIDER
• Sharpening CIDER's Debugging Tools
• Leveling Up CIDER's ClojureScript Support

Not all those who wander are lost.

– J.R.R. Tolkien

Today I’m happy to announce Flycheck 38 - easily the biggest and most ambitious Flycheck release since I took over the stewardship of the project. It’s the release where Flycheck grows a proper story for language servers, gets the kind of inline diagnostics you’d expect from a modern editor, and learns to apply fixes - all without giving up the checker model that made it popular in the first place.

The version number, I’ll admit, doesn’t do this one justice - it’s just the next integer after 37, and nothing about “38” whispers “special”. But that’s how it goes with version numbers: some releases are more special than others, and you’d rarely guess which from the number alone.

There and back again

A little history, because it’s what makes me this excited. Flycheck was born to give Emacs a genuinely modern linting experience, back when the built-in options were, let’s charitably say, uninspiring. For years it was the way to get on-the-fly checking in Emacs. But then development slowed to a crawl, Flymake got a ground-up rewrite and quietly caught up in a lot of areas - it even grew end-of-line diagnostics recently - and I started seeing people wonder aloud whether Flycheck still brought anything to the table.

I get the question - a stagnant project invites it. But I never believed Flycheck was done; it was just resting. This release is my answer: proof that it can still innovate and still delight. And I’m genuinely grateful for the competition. Flymake pushing hard is exactly what nudged me to think bigger and bolder than another round of bugfixes. Competition in this space is a good thing, full stop - it makes both projects better and Emacs users the winners. If you’re curious how the two stack up now, the manual keeps an honest side-by-side.

So, in the spirit of boldly going where many editors have gone before, here’s what’s new.

Eglot support, finally built in

For years the story around Flycheck and LSP was awkward. Eglot renders its diagnostics through Flymake and offers no Flycheck backend of its own, so if you wanted your LSP errors in Flycheck’s error list you had to reach for the third-party flycheck-eglot package. It worked, but “install another package to bridge two things that ship with Emacs” never sat right with me.

Flycheck now bridges that gap itself. Enable global-flycheck-eglot-mode and an Eglot-managed buffer reports the server’s diagnostics through Flycheck - the error list, the navigation, the fringe, all of it - while Eglot keeps doing the LSP heavy lifting. This obsoletes the flycheck-eglot package.¹

And because Flycheck reads the raw LSP diagnostic rather than the flattened Flymake one, the bridge surfaces things Flymake-over-Eglot drops on the floor: an LSP quickfix code action becomes a Flycheck fix you can apply with C-c ! f, and a diagnostic’s related locations become navigable.

Beautiful inline diagnostics

The other thing I really wanted was inline messages - errors shown right next to the code they refer to, the way VS Code’s Error Lens, Neovim, Helix and Zed all do it. Flycheck 38 ships this out of the box.

Turn on flycheck-annotate-mode and you get it. There are two layouts - a compact eol message after the line, and a roomy below layout that lays the full messages out on their own lines underneath, with connectors pointing at the offending column. By default the line at point gets the roomy treatment while the rest stay compact, so the error you’re working on is spelled out in full without every other line shouting for attention. There’s also an Error Lens-style whole-line background tint and a right-aligned sideline style if that’s your thing - the manual has a shot of each.

Turn it on everywhere with the global mode:

(global-flycheck-annotate-mode 1)
;; optional: the Error Lens-style whole-line tint
(setq flycheck-annotate-background t)

A word on the name, since it’s a funny little story. I’d have loved to call this flycheck-inline-mode, but that name was taken by the (now deprecated) flycheck-inline package. “Diagnostics” was the other obvious choice, except Flycheck has always called them errors, not diagnostics - flycheck-error, the error list, flycheck-checkers - and I didn’t want to introduce a second vocabulary for the same thing. So flycheck-annotate-mode it is. Naming things is (still) hard.

Native LSP support, no client required

And to top things off: Flycheck can now talk to a language server directly - no Eglot, no lsp-mode, no full LSP client at all.

Here’s the itch this scratches. A growing number of linters ship their own LSP server - RuboCop, Ruff, Biome, Harper and friends - and a traditional command checker spawns the linter afresh on every check, paying its startup cost over and over (anyone who’s waited on rubocop loading a big project knows the feeling). The linter’s own LSP server stays resident and lints incrementally instead, so checks are much snappier - and you get that without running a full language server and client just to see some diagnostics.

Enable global-flycheck-lsp-mode and it works out of the box for RuboCop (Ruby), Ruff (Python), Biome (JavaScript, TypeScript, JSON, CSS) and Harper (Markdown prose). Each server is only started if its program is installed, so turning the mode on globally is safe. Want a different one? It’s a one-liner:

;; Standard instead of RuboCop for Ruby
(setf (alist-get 'ruby-mode flycheck-lsp-servers) '("standardrb" "--lsp"))

The whole thing is built on Emacs’ own jsonrpc library, so there’s no new dependency. And where the server offers them - RuboCop’s autocorrects, Ruff’s and Biome’s quickfixes - those show up as Flycheck fixes too. It’s meant for the diagnostics-only case; when you want a full language server with completion and hover, run it through Eglot and use flycheck-eglot-mode. The manual has a table to help you pick.

Project-wide diagnostics

Flycheck has always been a resolutely buffer-local affair: it checks the file you’re looking at and shows you those errors. That’s great right up until you want the bigger picture - every problem across the files you have open, plus the cross-file errors that checkers like tsc, cargo check and mypy genuinely know about but the per-buffer view quietly throws away.

Press P in the error list and it flips to a project-wide scope: errors aggregated across every open Flycheck buffer, with those cross-file diagnostics finally given somewhere to live. It’s the closest Flycheck has come to a “problems” panel, and it’s quickly become one of my favourite things to actually use day to day.

Notice the models.py type error in there: it was reported while checking api.py, and the old per-buffer view would have dropped it on the floor. The [project] tag in the mode line tells you you’re looking at the whole project rather than a single file.

Checking remote files over TRAMP

This one is simple to describe and was honestly overdue: Flycheck now runs checkers over TRAMP. Open a file on a remote host and the checker runs there, on the remote machine, against the real environment - where before it simply refused to run at all. If you edit code on servers or inside containers over TRAMP, this alone might be worth the upgrade.

And plenty more

The three headliners above lean on a lot of supporting work that landed in the same release. The highlights:

• Flycheck can apply fixes now. C-c ! f (flycheck-fix-error-at-point) applies the machine-applicable fix a checker suggested, C-c ! F applies every fix in the buffer at once as a single undoable change, and fixable errors get a distinct fringe indicator - a little “fix available” lightbulb. eslint --fix, cargo clippy’s suggestions, ruff, shellcheck and any SARIF-based checker carry these fixes, which Flycheck used to parse and throw away.
• The error list got a serious overhaul: group errors by file, checker or level (and combine those dimensions), collapse the groups, and drive it all with the mouse via a strip at the top.
• Errors can carry secondary locations - the earlier definition behind a redefinition, the borrow behind a Rust lifetime error. Jump to them with C-c ! j, and they show up after the message inline and in the error list.
• A running check is interrupted when a newer one starts (unless it’s already made real progress), so a slow checker no longer makes Flycheck feel sluggish, and the error list no longer rescans all its rows on every cursor move.

There’s more in the changelog, but that’s the shape of it.

Putting it all together

If you want the full modern setup - on-the-fly checking everywhere, inline diagnostics, and your LSP server’s diagnostics flowing through Flycheck - here’s a use-package block that turns it all on:

(use-package flycheck
  :ensure t
  :hook ((after-init . global-flycheck-mode)
         ;; Show diagnostics inline, next to the code (Error Lens style)
         (after-init . global-flycheck-annotate-mode))
  :config
  ;; Report Eglot's LSP diagnostics through Flycheck
  (global-flycheck-eglot-mode 1))

Prefer to skip Eglot and read diagnostics straight from a linter’s own LSP server (RuboCop, Ruff, Biome, Harper)? Swap that last line for (global-flycheck-lsp-mode 1) instead. Reach for the native checker when all you want is diagnostics, and the Eglot bridge when you also want a full language server’s completion and hover.

Upgrading

Most setups will just keep working. The one thing to watch: the built-in flycheck-eglot-mode reuses the names of the old third-party flycheck-eglot package, so if you have that installed, uninstall it before relying on the built-in mode - otherwise the two define the same commands and clash.

A word on funding

Let me get a little uncomfortably candid here. In the couple of years I’ve been maintaining Flycheck, its OpenCollective has taken in less than $300 - total. Individual donations haven’t exactly moved the needle either. I’m not saying this to guilt anyone; it’s just the everyday reality of open source. Popular projects are a lot of work, and the usual reward is the quiet satisfaction of using something you helped make a bit better.

Still, if Flycheck saves you time - especially if it does so at work - please consider chipping in through OpenCollective, GitHub Sponsors, or any of the other options linked from the README. Even a small recurring amount, multiplied across the people who lean on this thing every day, would make a real difference to how much time I can put into it.

Closing thoughts

Even the smallest person can change the course of the future.

– Galadriel

When I took over Flycheck, my motivation was simple: keep the project alive, and keep the competition in this corner of Emacs going. For a long stretch that meant little more than keeping the lights on. This release is the first time in a while it’s genuinely moved forward in a big way, and I’m proud of where it landed - modern diagnostics UX, first-class LSP support in two flavours, project-wide diagnostics, and fixes, all while staying true to the checker model people love it for. Call it the return of the Jedi. I hope you’ll agree I’ve been at least modestly successful at what I set out to do.

Huge thanks to everyone who tested, reported and nudged this along. Give flycheck-annotate-mode and flycheck-lsp-mode a spin and let me know what you think.

Keep hacking!

Raw link: https://www.youtube.com/watch?v=yH0Gan6xMTo

In this video I provide an overview of the default interface for minibuffer completions in Emacs. This is an interface that has been improved considerably over the years. In Emacs version 31, this interface gets some nice new features which make it even more appealing to use.

Below is the article I prepared for this video, with all the code samples.

Table of Contents

1. The default settings are usable but inconvenient
2. Tweaks for a more refined default completion interface
3. The completion-category-overrides for maximum control
   1. How to find the completion category
   2. Completion categories and all the other completion-metadata
4. The default completions and related packages

The core Emacs infrastructure for completions is quite capable. In a previous entry I covered the technicalities of in-buffer completion, the completion-at-point-functions, and related packages/modes like corfu, company, completion-preview-mode: https://protesilaos.com/codelog/2026-07-19-emacs-completion-at-point-functions/.

For this article I will focus on the default user interface of completions as it is done through the minibuffer. Minibuffer completion is performed whenever we type, with default keybindings, M-x (execute-extended-command), C-x b (switch-to-buffer), C-x C-f (find-file), among many others.

The default settings are usable but inconvenient

They are designed to work like TAB-completion in a standard Bash shell. Insert some text, press TAB, and Emacs will interpret your input as a prefix to be completed against available candidates.

The *Completions* buffer pops up. At the top, it informs you about the keybindings you can press to select a candidate. The candidates themselves are presented in rows and columns.

If you type some extra characters or otherwise modify your initial input, the *Completions* buffer will not reflect the new list of candidates. To calculate that anew you have to press TAB again. As such, the *Completions* are static by default.

Tweaks for a more refined default completion interface

Lots of small refinements have been made over the years to expand what we can do with the *Completions* buffer (at least some are inspired by an old package of mine called mct). Here is the essence of my preferred configuration, with comments:

(use-package minibuffer
  :ensure nil
  :config
  ;; Do not inform me about the default keybindings to select a
  ;; candidate.
  (setq completion-show-help nil)

  ;; Do not print messages in the echo area that pertain to
  ;; completion---those are distracting.
  (setq completion-show-inline-help nil)

  ;; Show useful annotations in various minibuffer prompts (though the
  ;; `marginalia' package greatly improves this).
  (setq completions-detailed t)

  ;; Do not use rows and columns for completions: a single vertical
  ;; list is easier to follow.
  (setq completions-format 'one-column)

  ;; Put an upper limit to the Completions window, so that it does not
  ;; disorient me.
  (setq completions-max-height 12)

  ;; Rely on previous inputs to surface candidates towards the top of
  ;; the list (enable the built-in `savehist-mode' to persist
  ;; history).
  (setq completions-sort 'historical)

  ;; Show the Completions buffer if I hit TAB but there is no unique match yet.
  (setq completion-auto-help t)

  ;; Never switch to the Completions buffer when I type TAB, because I
  ;; want to select candidates while the minibuffer is still in focus,
  ;; per `minibuffer-visible-completions'.  This has the advantage of
  ;; auto-updating the completions as I type.
  (setq completion-auto-select nil
        minibuffer-visible-completions t)

  ;; Those two are also relevant for the `completion-category-overrides', which I
  ;; cover elsewhere in this article.
  (setq completion-eager-display t)
  (setq completion-eager-update t))

The completion-category-overrides for maximum control

The user option completion-category-overrides is for those power users who demand complete control of how the completions behave. Concretely, we target the metadata key of the completion-category to tell Emacs which completion-styles and other settings to use specifically for it. For example, we might want to have something like this:

;; Pattern-matching styles to interpret our input in every context.
(setq completion-styles '(basic substring initials flex))

;; An exception to the above for the `file' category, where we
;; specifically want to use the `partial-completion' style:
(setq completion-category-overrides
      '((file . ((styles partial-completion)))))

How to find the completion category

I am not aware of a built-in way to do this, so I have my own function:

(defun prot-common-completion-category ()
  "Return completion category."
  (when-let* ((window (active-minibuffer-window)))
    (with-current-buffer (window-buffer window)
      (completion-metadata-get
       (completion-metadata (buffer-substring-no-properties
                             (minibuffer-prompt-end)
                             (max (minibuffer-prompt-end) (point)))
                            minibuffer-completion-table
                            minibuffer-completion-predicate)
       'category))))

To use this, you need to enable recursive minibuffers, which means that you want to be able to bring up a new minibuffer prompt that will affect the one that was already open. Here are the settings I use for that:

(use-package minibuffer
  :ensure nil
  :config
  (setq read-minibuffer-restore-windows nil)
  (setq enable-recursive-minibuffers t)
  (minibuffer-depth-indicate-mode 1))

With that in place, whenever you want to know the completion category of a prompt, focus the minibuffer and type M-: (eval-expression). In the new prompt input (prot-common-completion-category) and press RET. In the echo area you will either get nil or the symbol of the category.

[ We can, of course, do this differently such as by defining a command that we bind to a key to ultimately copy the completion category to the kill-ring, but I wanted to keep it generic. ]

Now you can write more entries for the completion-category-overrides.

Completion categories and all the other completion-metadata

When we modify the completion-category-overrides we can set the variable completion-styles as well as every single function specified by the documentation of function completion-metadata. Here is the anatomy of an override:

(CATEGORY . ((styles STYLES)
             (eager-update . BOOLEAN)
             (eager-display . BOOLEAN)
             (group-function . GROUP-FN)
             (annotation-function . ANNOTATION-FN)
             (affixation-function . AFFIXATION-FN)
             (display-sort-function . SORT-FN)))

• STYLES is one or more completion-styles.
• BOOLEAN is nil or t.
• *-FN are functions as explained by completion-metadata.

A concrete yet basic example, with comments:

;; To set `eager-display' and `eager-update' in the overrides, we need
;; to have these variables configured accordingly:
(setq completion-eager-display 'auto
      completion-eager-update 'auto)

(setq completion-category-overrides
      '((file . ((styles partial-completion)
                 ;; Do not automatically pop up the Completions buffer
                 ;; because, for example, we have private files we do
                 ;; not want to show while doing a live stream.
                 (eager-display . nil)
                 ;; But if the Completions buffer is already
                 ;; displayed, do update it as you type.
                 (eager-update . t)))
        ;; For buffers we do not care about showing them, so display
        ;; them outright and automatically update them as you type.
        (buffer . ((eager-display . t)
                   (eager-update . t)))
        ;; For this I want the completion styles to either be
        ;; interpreted as a prefix or a substring, but I do not want,
        ;; for example, the flex style here. And then I want the same
        ;; behaviour as for the buffer category.
        (imenu . ((styles basic substring)
                  (eager-display . t)
                  (eager-update . t)))))

And here is an advanced example with all the custom functions:

(defun prot-minibuffer-file-group (file transform)
  "Return FILE group name unless TRANSFORM is non-nil."
  (cond
   ;; Here we have the power to completely change how candidates look
   ;; under a group, such as to remove a prefix. But I just want the
   ;; group title and otherwise want to keep the candidates as they
   ;; are by default.
   (transform file)
   ;; Create a group for directories and give it the group title
   ;; "Directories".
   ((string-suffix-p "/" file) "Directories")
   ;; Create a group for dotfiles and give it the group title
   ;; "Hidden files".
   ((string-prefix-p "." file) "Hidden files")
   ;; Then group every other file by its file extension and name the
   ;; corresponding group like ".org", ".txt.", and so on.
   ((when-let* ((extension (file-name-extension file :include-dot))
                (_ (not (string-blank-p extension))))
      extension))
   ;; In every other case, just group the candidates under the "Other"
   ;; heading.
   (t "Other")))

(defun prot-minibuffer-file-sort (files)
  "Sort FILES to have directories first and the rest alphabetically.
Omit the .. directory from FILES."
  ;; Remove the implicit files from the candidates.
  (setq files (delete "../" files))
  ;; Sort them alphabetically.
  (setq files (minibuffer-sort-alphabetically files))
  ;; Now put the directories before the rest.
  (let ((directory-p (lambda (file) (string-suffix-p "/" file))))
    (nconc (seq-filter directory-p files)
           (seq-remove directory-p files))))

;; To set `eager-display' and `eager-update' in the overrides, we need
;; to have these variables configured accordingly:
(setq completion-eager-display 'auto
      completion-eager-update 'auto)

(setq completion-category-overrides
      '((file . ((styles partial-completion)
                 (eager-display . nil)
                 (eager-update . t)
                 ;; I am not including examples for the annotation and
                 ;; affixation functions because those are more
                 ;; involved and you anyway get the point.
                 (group-function . prot-minibuffer-file-group)
                 (display-sort-function . prot-minibuffer-file-sort)))
        (buffer . ((eager-display . t)
                   (eager-update . t)))
        (imenu . ((styles basic substring)
                  (eager-display . t)
                  (eager-update . t)))))

The default completions and related packages

The modern stack is vertico, marginalia, orderless, embark, and consult.

The default completion interface can be used instead of the vertico package. Though you can still benefit from marginalia, orderless, embark, and consult.

If you really want to customise everything extensively through the completion-category-overrides, then you can skip marginalia and maybe even get completion-styles that are still good enough without orderless.

But there still is no built-in alternative for the powerful embark and consult packages, so plan accordingly. Granted, you can be productive without embark and consult, but the advantage of those packages is that they make it easier to achieve those same tasks (plus extra features).

I’ve been writing a bit lately about my growing use of EWW [1, 2, 3, 4]. I was always a little skeptical of those who said they made significant use of EWW for their browsing but then I realized that I had started doing the same thing. It certainly hasn’t replaced Safari but I am using it more and more.

It started fairly innocently. I use elfeed-webkit to render the web pages from my RSS feed. That has the significant disadvantage that my ad and tracking blocker doesn’t work for them. That, in turn, means that I get all sorts of junk displayed. It’s usually a dickover but sometimes there’s a seemingly never ending train of popup ads. Fortunately, elfeed (and elfeed-webkit) have a hot key to display the page in EWW and avoid all that. Now as soon as a dickover covers up the text or a avalanche of ads starting popping up, I simply switch over to EWW and read in peace. It’s surprising how little I need JavaScript.

As I said, I find myself using EWW more and more. It’s easy to call it from Embark when the point is on a URL and often I’ll just use it instead of invoking Safari. Of course, that brings up question. Can I switch from Safari to EWW when I need to? I couldn’t find any builtin way but I realized I already had everything I needed to do it. The first part is to retrieve the URL of the current Safari Web page. I’ve had a function to do this for a long time and use it all the time to capture links to the current Web page into Org. It’s pretty simple but restricted to macOS. Here it is.

(defun jcs-retrieve-url ()
  "Retrieve the URL of the current Safari page as a string."
  ;; (org-trim (shell-command-to-string
  ;;   "osascript -e 'tell application \"Safari\" to return URL of document 1'")))
  (do-applescript "tell application \"Safari\" to return URL of document 1"))

The way to do this varies by browser and OS but is usually straightforward.

The second part is doing the actual switch. Again, it’s simple:

(defun jcs-switch-to-eww ()
  "Invoke EWW for the current Safari web page"
  (interactive)
  (eww (jcs-retrieve-url)))

I put this in iCanHazShortcut and bound it to Ctrl+F7. It works fine except I haven’t yet figured out how to switch to Emacs from Safari so I have to press F6 for that. That’s a small price to play until I figure out the rest of the magic spell.

EWW, of course, has a way to switch to the default browser so it’s easy to pop back and forth as needed. It’s a small thing but makes my workflow easier.

Emacs

I got distracted by MojoPad and Kosshi for a while there. Emacs has been plugging away. Always launched. Always handling my writing. It is the centerpiece of my efforts. I have been making changes to it. Nothing too big, but designed to improve my experience in it. I will talk about three of those in this article.

Whitespace

I like seeing the marks for return and tabs. Returns are valid for every file but tabs are valid for only content which is copied from other programs or sources. I like seeing them. I made sure that they show up in Emacs.

(setq whitespace-style '(face          ; Use faces to colorize
                         tabs          ; Look for tabs
                         tab-mark      ; Visualise tabs
                         newline       ; Look for newlines
                         newline-mark))  ; Visualise newlines
;;                         trailing))    ; (Optional) Still show ugly trailing spaces

(setq whitespace-display-mappings
      '(
        ;; Customize the tab marker
        ;; 9 is the ASCII code for Tab. 
        ;; ?\u2192 is the Unicode character '→' (Rightwards Arrow).
        ;; [?\n] is the fallback if the arrow can't be rendered.
        (tab-mark 9 [?\u2192 ?\t] [?\t])

        ;; Customize the newline/return marker
        ;; 10 is the ASCII code for Newline (Line Feed).
        ;; ?\u21b5 is the Unicode character '↵' (Downwards Arrow with Corner Left).
        (newline-mark 10 [?\u21b5 ?\n] [?\n])
        ))

Minimal Mode Line

I had been using doom modeline and had a elaborate configuration setup for that. See Much Ado About Emacs 001 - Bicycle For Your Mind.

Decided to make it simpler:

(defun my-modeline-file-path ()
  "Return abbreviated file path if visiting a file."
  (when-let ((file (buffer-file-name)))
    (format " (%s)" (abbreviate-file-name (file-name-directory file)))))

(setq-default mode-line-format
              '("%e"
                "%* "
                my-modeline-buffer-name
                (:eval (my-modeline-file-path)) ;; Displays " (~/projects/app/)"
                mode-line-format-right-align
                "L%l (%p)"
                " "
                my-modeline-major-mode))

(defvar-local my-modeline-buffer-name
  '(:eval
    (when (mode-line-window-selected-p)
      (propertize (format " %s " (buffer-name))))))

(put 'my-modeline-buffer-name 'risky-local-variable t)

(defvar-local my-modeline-major-mode
  '(:eval
    (list
     (propertize "λ" 'face 'shadow)
     " "
     (propertize (capitalize (symbol-name major-mode)) 'face 'bold)))
  "Mode line construct to display the major mode.")

(put 'my-modeline-major-mode 'risky-local-variable t)

Only the information I need, and none of the information I don’t. Looks pretty and minimal too. Added benefit? No external package.

Two Spaces Turn Into a Period and Space. Next Letter Gets Capitalized.

I have picked up some bad habits. Two spaces turns into a period, and the next letter is automatically capitalized. macOS lets me do this automatically in some programs. Not Emacs. I needed to rectify that.

;; two spaces to a period
(defun my/double-space-to-period-and-capitalize ()
  "Convert double space to '. ' and capitalize the next typed character."
  (interactive)
  (if (and (eq (char-before) ?\s)
           (not (eq (char-before (1- (point))) ?\s)))
      (progn
        (delete-char -1)
        (insert ". ")
        ;; Read the next key press directly
        (let ((evt (read-event)))
          (if (characterp evt)
              ;; If it's a character, insert its uppercase version
              (insert (upcase (char-to-string evt)))
            ;; If it's a special key (like an arrow key, backspace, etc.), unread it
            (setq unread-command-events (list evt)))))
    (insert " ")))
;; Enable in text-mode (Org, Markdown, Plain text)
(add-hook 'text-mode-hook
          (lambda ()
            (local-set-key (kbd "SPC") #'my/double-space-to-period-and-capitalize)))

That is all I have for today.

macosxguru at the gmail thingie.

Bozhidar Batsov, who’s been writing about Embark lately has a nice post on integrating CIDER and Projectile into Embark. I don’t use either of them so you might wonder why I care. The answer is that Batsov’s post is a good example of how to add a new application to Embark.

That turns out to be pretty easy. For projectile, Batsov built it into the app so you’ll have to check the source code to see the details. For CIDER, though, he adds the Embark functionality externally so you can see how it’s done. It’s mainly a matter of writing some straightforward wrapper functions, binding them up in a keymap for Embark, providing a target function that identifies symbols, and finally adding the keymap to Embark.

For me, then, the value of Batsov’s post is that it serves as a how to that shows you the recipe for extending Embark to include new applications.

For years, I’ve been using verbatim emphasis in org-mode to mark files and keyboard strokes, while reserving code emphasis to show function names, variables, and other elements of code.

With the reintroduction of <kbd></kbd> tags to the blog yesterday¹, I wanted these tags to follow the same logic derived from my usage in org-mode: if I used verbatim in org-mode to indicate keystrokes and filenames, then I should use <kbd></kbd> tags on the blog to indicate the same thing. I explained in a footnote in the post: “The reason I have it different here is because I often talk about files in my posts without referring to code.” That might have been my preference, but it was wrong. We’ll get back to it in a minute.

I wanted to get my markdown-exported posts to preserve the verbatim emphasis from org-mode. But Markdown doesn’t distinguish between verbatim and code emphasis in org-mode — it treats both as ``, or <code></code> tags in HTML. So I started looking for a way to fix this.

The abridged version (the research took over an hour): I ended up with a wrapper function that would add Markdown raw code injection specifically for that code (I’m still working on it) to work with Pandoc. Why Pandoc and not Emacs’s built-in Markdown exporter? Because Emacs’s built-in exporter outputs certain characters, like my now beloved em-dash again, as character reference numbers, which results in a character reference (&#x2014 specifically) instead of an em-dash. Why’s that? Look, have you eaten breakfast today? Because I haven’t. Let me just tell you, these rabbits dig deep holes.

So now, after I had a working way (more or less) to produce my newly introduced <kbd></kbd> tags, I wanted to start using them for filenames. But I was bothered by the fact that while I can do whatever the hell I want this is not considered standard. And when I say “bothered,” I mean this is the thought I woke up to at around 05:40 this morning, which is what you get from a delirious dork Emacs brain like mine.

I knew HTML has standards, but I didn’t connect the logic behind it to semantic HTML — not until I browsed on my phone, in my bed, for another half an hour of impulsive research. Turns out, this is something that some folks take very seriously. And according to these folks, filenames and paths do not and should not have a dedicated HTML tag (surely not <kbd></kbd>, which is for keystrokes only — actually, it’s for “textual user input” which can include voice, for example). Authority has it that I should be indicating filenames using the <code></code> tags (and code emphasis in org-mode), and there’s a good reason for that. Just take my word for it for now (breakfast, remember?)

Reading through their tomb of standards, I realized I need to correct my headings on the blog too (I jump directly to <h3></h3> tags instead of going by order, because the CSS for these tags looks better — in other words, I’ve been lazy by not fixing this), among potentially many other things. There are over a hundred semantic tags in HTML, and there’s a reason for each one.

Damn those rabbits.

Footnotes

Lots of discussion around Emacs is a Lispboard (HN) and Malleable Computing, Emacs, and You (HN). Also, last call for Emacs Carnival posts for June (theme: Programming). The theme for August is The Search for Knowledge. Enjoy!

• Emacs 31:
  • Emacs 31.0.91 pretest is available (Reddit, Irreal)
• Upcoming events (iCal file, Org):
  • Emacs Berlin: Emacs-Berlin Hybrid Meetup https://emacs-berlin.org/ Wed Jul 29 1000 America/Vancouver - 1200 America/Chicago - 1300 America/Toronto - 1700 Etc/UTC - 1900 Europe/Berlin - 2230 Asia/Kolkata – Thu Jul 30 0100 Asia/Singapore
  • Emacs.si (in person): Emacs.si meetup #8 2026 (v #živo) https://dogodki.kompot.si/events/3944ee8f-6da1-4720-b086-b9217e4f5c7b Mon Aug 3 1900 CET
  • EmacsATX: Emacs Social https://www.meetup.com/emacsatx/events/315091679/ Thu Aug 6 1600 America/Vancouver - 1800 America/Chicago - 1900 America/Toronto - 2300 Etc/UTC – Fri Aug 7 0100 Europe/Berlin - 0430 Asia/Kolkata - 0700 Asia/Singapore
  • M-x Research: TBA https://m-x-research.github.io/ Fri Aug 7 0800 America/Vancouver - 1000 America/Chicago - 1100 America/Toronto - 1500 Etc/UTC - 1700 Europe/Berlin - 2030 Asia/Kolkata - 2300 Asia/Singapore
• Emacs configuration:
  • TAONAW - Emacs and Org Mode: Emacs Config Gems - Part 1 (Irreal)
  • Emacs Redux: CIDER and Projectile Meet Embark (Irreal)
  • An emacs config (Reddit)
• Emacs Lisp:
  • Shuffle filenames (@FoxFunction@tech.lgbt)
  • Color picker for emacs (Reddit)
• Appearance:
  • Emacs Redux: Right-aligned Mode Line Elements (Irreal)
  • Mode line maker (Reddit)
  • Arthur A. Gleckler: mode-line-path
  • Introducing trailing-newline-indicator: Visual clarity for file-ending newlines in Emacs (Reddit)
  • New Emacs icon theme package (out of the box, supports dired, ibuffer, speedbar) with 1200+ SVG icons (Reddit)
  • Protesilaos: Emacs: pulsar version 1.4.0
• Navigation:
  • Marcin Borkowski: Hideshow mode
  • Emacs Redux: Dedicate Windows with toggle-window-dedicated (Irreal)
  • Meta Redux: Projectile 3.3
  • Emacs | Project.el (16:57)
• Dired:
  • My Emacs configuration (Dired) (HN)
  • James Dyer: Borrowing from Jasspa MicroEmacs: Dired Sort Keybindings
  • TAONAW: Dragging and dropping into Dired copies files
  • Tip: (setq dired-mouse-drag-files t) (@gijs@post.hillenius.net)
• Writing:
  • md-mode: Org-style structural editing and same-buffer rendering for Markdown (Reddit)
  • Irreal: A Small Jinx Tweak
• Org Mode:
  • Org Mode requests: [TODO] Fix obsolete/wrong info in worg/org-faq.org
  • Org Mode requests: [RFC] org-agenda: combine Clocked and Closed entries
  • Org Mode requests: [RFC] PDF document tagging: language code
  • Org Mode requests: [RFC] Font control as of today
  • Org Mode requests: [RFC] Small restriction in BEAMER_HEADER: WDYT?
  • Show current tasks after init (@FoxFunction@tech.lgbt)
  • Raymond Zeitler: The Problem With Tags Lists
  • Reviewing finished tasks from last week in org-agenda and emacs (@paniash@mas.to)
  • org-block-wrap: fix unsightly notches in org blocks (Reddit)
  • Kalender von Emacs Org-mode in Thunderbird exportieren - GNU/Linux.ch (@Verfassungklage@troet.cafe)
  • Org development:
    • org-odt-verse-block: Fix invalid tab indentation alignment
    • lisp/ox-html: New export option for file links
    • ox-beamer.el: Move Beamer theme definition right after documentclass
    • ox-latex: Add org-latex-default-example-options
• Completion:
  • `flex-x: built-in flex completion with AND filtering, history-aware sorting, and migemo/pyim support` (Reddit)
• Coding:
  • ryanprior/xc.el: Integrate the xc task runner with Emacs - Codeberg.org (@ryanprior)
  • jsonschema-treesit: JSON object key completion using JSON Schema and treesit
  • Seamless Lombok, JaCoCo, and Other Java Agent Integration in Emacs with JAL (Reddit)
  • Meta Redux: Making CIDER More Discoverable
  • Meta Redux: Modernizing CIDER’s Completion
  • Meta Redux: Closing the Find-Usages Gap in CIDER
• Web:
  • Raymond Zeitler: How to Copy the Link at Point – an Undocumented Feature in EWW (Irreal)
  • How to enable ace-link for elpher (@zrzz@fosstodon.org)
• Mail, news, and chat:
  • Aimé Bertrand: iMessage in Emacs
  • my-jabber-esperanto-conversation - enable input methods based on chat participants (@tennoseremel@gts.skobk.in)
• LLMs:
  • emacs-semantic: Semantic search for all GNU Emacs functions. Find functions by describing what you want to do in plain English. (@hajovonta@mastodon.online)
  • llm-buddy demo: automatic error detection and fixing in Emacs! (10:26)
  • Alvaro Ramirez: agent-shell 0.63 updates (Reddit, lobste.rs)
• Community:
  • Charlie Holland: The Search for Knowledge: Emacs Carnival August 2026
  • What do you NOT use Emacs for, that Emacs is (reasonably) capable of doing?
  • My Experience Using Emacs for a Month as a Long-Time Neovim User
• Other:
  • Emacs is a Lispboard (Reddit, HN)
  • Malleable Computing, Emacs, and You (Reddit, HN)
  • bartbunting/emacspeak-support: Speech enabling emacs packages · GitHub (@pixelate@tweesecake.social)
  • Emacs on the iPad: first release (v0.1.0, sideloadable .ipa) (Reddit)
  • A light-weight Clojure-like language that runs directly in Emacs Lisp (Reddit)
  • Raymond Zeitler: Modeling Browser History in Emacs
  • Lars Ingebrigtsen: It’s time to wake up: An Emacs alarm clock
  • Protesilaos: Emacs: Substitute version 0.5.0
  • Chung-hong Chan: Emacs Writing Machine (lobste.rs)
  • TAONAW - Emacs and Org Mode: Emacs Config Gems - Part 2
• Emacs development:
  • vc-dir: Don't resolve DIR to truename unnecessarily (reworded)
  • current-time-list now defaults to nil
  • timeclock: Optionally use 24-hour clock
• New packages:
  • fnm: Manage Node versions using fnm (MELPA)
  • grpclient: Grpcurl interactive builder (MELPA)
  • gruber-darker-ayu-theme: Gruber Darker + Ayu Dark color theme (MELPA)
  • keycoach: Learn keybindings (MELPA)
  • mode-line-maker: Mode-line helper tools (GNU ELPA)
  • project-x: Extra convenience features for project.el (MELPA)
  • smali-mode: Major mode for editing Smali/Baksmali files (MELPA)
  • snippy: Vscode snippet support with Yasnippet (MELPA)

Links from reddit.com/r/emacs, r/orgmode, r/spacemacs, Mastodon #emacs, Bluesky #emacs, Hacker News, lobste.rs, programming.dev, lemmy.world, lemmy.ml, planet.emacslife.com, YouTube, the Emacs NEWS file, Emacs Calendar, and emacs-devel. Thanks to Andrés Ramírez for emacs-devel links. Do you have an Emacs-related link or announcement? Please e-mail me at sacha@sachachua.com. Thank you!

*

You can e-mail me at sacha@sachachua.com.

Nous allons parler en direct avec Fabrice Niessen (Formation Emacs Boost) d'Emacs, de ses flux de travail, de sa configuration, et d'autres sujets en français. Je suis un peu intimidée, mais si vous posez vos questions dans le chat, je pense que nous pouvons survivre à mon faible niveau de français. =)

La diffusion en direct aura lieu le [2026-08-13 Thu 07:30]–[2026-08-13 Thu 08:30] dans le fuseau horaire America/Toronto, soit 0730H EDT / 0630H CDT / 0530H MDT / 0430H PDT / 1130H UTC / 1330H CEST / 1430H EEST / 1700H IST / 1930H +08 / 2030H JST.

Si vous voulez parler d'Emacs avec Prot et moi en français, n'hésitez pas à m'envoyer un courriel !

You can e-mail me at sacha@sachachua.com.

Projectile 3.3 is out! That’s the fourth release this month, which probably tells you something about how much fun I’ve been having with Projectile lately.

This one is mostly about a single theme - Projectile knowing more about your project without you having to tell it anything.

Tasks you never configured

Projectile has had named tasks for a while now - you put an alist in projectile-tasks (or in your project’s .dir-locals.el) and projectile-run-task (s-p c x) offers them with completion. Useful, but there was a catch that always bugged me: the variable starts out empty, so the command did precisely nothing until you sat down and filled it in.

Meanwhile every project I work on already has its tasks written down somewhere. The npm scripts are in package.json. The Makefile targets are in the Makefile. So now Projectile just reads them:

That’s a fresh checkout with zero Projectile configuration. Out of the box it knows about npm scripts (running them through whichever package manager your lock file implies - npm, yarn, pnpm or bun), Deno tasks, Composer scripts, just recipes, go-task tasks and Makefile targets. The tool name is part of the task name, so npm:build and make:build can happily coexist and you can see at a glance where something came from.

If you don’t want this, projectile-discover-tasks turns it off. If you want more of it, projectile-task-providers is just a list of functions that take a project root and return an alist - adding support for your favorite task runner is a few lines.

A lot more project types

Projectile ships with a registry of project types, and I finally sat down and went through it properly. The result is 34 new types.

The one that surprised me most was that a package.json without a lock file next to it matched nothing at all - such a project came out as generic, with no compile or test command. That can’t have been a rare situation. Also missing: Bun, Deno, uv (which has pretty much taken over new Python projects), plain Composer, Laravel, Xcode, Flutter, Terraform, Pulumi, Helm, Ansible, just, mise, Gleam, Babashka, scala-cli, Godot, PlatformIO, and the static site generators (Hugo, Jekyll, Zola, MkDocs, Quarto).

Going through the registry also turned up three bugs that had been sitting there quietly:

• The angular type could never match anything. It listed two markers, angular.json and .angular-cli.json, and marker lists are ANDed - but a project has one or the other, never both. So the type had been dead since the day angular.json was added.
• pyproject.toml was checked before django, python-poetry, python-pipenv and python-tox. Since just about every Python project has a pyproject.toml these days, those four types effectively never matched. A Django project would come out as python-toml and lose its file kinds along with its commands.
• php-symfony required an app directory, which Symfony dropped in version 3, and a vendor directory, which only exists after someone runs composer. Modern Symfony projects weren’t detected at all.

I’ve also brought the stale markers up to date (Bazel’s MODULE.bazel, Gradle’s Kotlin DSL, Zig’s build.zig) and fixed a pile of lifecycle commands that had rotted - Symfony’s console moved to bin/ years ago, the Dart CLI absorbed pub, setup.py build is deprecated by the PyPA, and poetry projects run pytest rather than unittest discovery.

There’s a new (:any "file1" "file2") form for markers, which is what made most of this expressible as plain data rather than yet another predicate function.¹

Monorepos

If you work in a monorepo you know the problem: the repository is one project as far as git (and therefore Projectile) is concerned, but you’re usually working on one piece of it, and building or testing the whole thing is a waste of time.

Projectile now understands that a directory holding a manifest of its own is a subproject. projectile-find-file-in-subproject (s-p c m f) asks which one you want and then scopes file completion to it:

And every lifecycle command has a subproject variant now - s-p c m c compiles, s-p c m t tests, s-p c m r runs, and so on. They use the project’s own command and simply run it in the nearest subproject, which is exactly what workspace-aware tools like Cargo, npm and Maven need in order to scope their work.

There were subproject compile and test commands before this release, but they only looked for the marker of the project’s own type, which meant they were useless in a polyglot repository - a Rust crate sitting under a package.json project was invisible to them. Now the markers come from every registered project type, so it works regardless of what the repo looks like from the top.

Two commands for looking at a project

projectile-dashboard (s-p P) summarizes the project you’re in:

Everything in there is a button, so you can jump to a file, run a task or kick off a build without leaving the buffer. It never indexes the project and only queries git when the project is a local git repo, which makes it cheap enough to use as your projectile-switch-project-action - which is exactly what I do now.

The other one is projectile-doctor (s-p H), which explains how Projectile sees the current project:

Root, which detection function found it and on which marker, the type and its marker, the indexing method and the exact command that will run, which external tools are available, the cache state, the effective ignore rules - and then a list of findings, each either ok or a concrete suggestion. It’s plain text, meant to be pasted into a bug report. Selfishly, I’m hoping this saves us both some back-and-forth in the issue tracker.

Odds and ends

A few smaller things worth knowing about:

• projectile-todos (s-p s t) collects the project’s TODO/FIXME annotations into the reviewable search buffer.
• Project-scoped bookmarks - s-p B s, s-p B j, s-p B d. They’re plain Emacs bookmarks, Projectile just scopes the completion to the current project.
• projectile-replace-undo (s-p u) reverts the last replace you applied from the review buffer, and it’s careful about it - a file whose text has changed since is reported and left alone.
• projectile-per-command-compilation-buffer gives compile, test and run separate compilation buffers, so running the tests no longer discards your build output.
• An optional Embark and Marginalia integration, wired up with with-eval-after-load so neither package becomes a dependency.

Bug fixes

Three worth calling out.

The first is embarrassing and recent: with asynchronous indexing enabled, projectile-find-file could show “Projectile is indexing” and spin forever. Projectile was waiting on the indexing process’s sentinel, and Emacs doesn’t actually promise to run one while a command sits waiting on the process. It now waits on the process itself and collects the output on its own if the sentinel doesn’t show up.² Thanks to Mike Crowe for a bug report with enough detail in it (strace output included) that I could work backwards to the cause.

The second: in CMake projects, editing the compile command at the prompt didn’t stick, and you’d get the default offered again on the next run. That was a side effect of a fix from 3.2 that made function-valued commands re-resolve on every run so the preset picker could prompt again. It threw away your edit along with the cached command. Both behaviors work now - your edit is remembered, the picker still gets to prompt.

The third one has been open since 2016. If you opened a file that git ignores, Projectile would happily add it to the file cache, and it would then keep showing up in projectile-find-file even though indexing had correctly left it out. Projectile’s own ignore rules simply don’t know anything about .gitignore, so it now asks git directly before caching a file it hasn’t seen before.

Upgrade notes

A few changes might alter what you see, so it’s worth knowing about them before you upgrade:

• Alien indexing now honors Projectile’s ignore rules, which it used to skip entirely. This means alien projects will list fewer files than before. Set projectile-alien-honors-ignores to nil if you want the old behavior.
• The ignore configuration speaks gitignore patterns everywhere now, matched the same way by every indexing method. Mostly this just works, but a leading * used to mean “at any depth” and is now a plain wildcard, so *node_modules should become node_modules.
• projectile-globally-ignored-directories now includes the build and dependency directories of the common ecosystems - node_modules, target, __pycache__, .venv, .next, .terraform and a couple of dozen more. Directories that projects sometimes do commit (vendor, dist, public, build) are deliberately not on the list.

The full changelog is here, and the manual is at docs.projectile.mx.

That’s all I have for you today. Keep hacking!

Next up in the series on the notable changes in CIDER 2.0: cross-references. Or, as most people call the feature, “find usages” - for years the most commonly cited reason to run clojure-lsp alongside (or instead of) CIDER. Let’s talk about why that gap existed and how we finally closed it.

Why runtime xref wasn’t enough

CIDER has had runtime cross-referencing for a while: the cider/fn-refs op walks the loaded vars in your REPL and reports which functions reference the one at point. It’s a genuinely cool trick - the REPL literally knows your program - but as a “find usages” answer it has three structural problems:

• It only sees loaded code. Namespaces you haven’t required yet - often most of the codebase - are invisible.
• It reports functions, not occurrences. Each hit points at the caller’s definition, not the exact call site, and a function that calls yours three times shows up once.
• It’s JVM-only, so ClojureScript users got nothing.

clojure-lsp, by contrast, builds a static index of your whole project with clj-kondo’s analyzer and answers instantly, loaded or not. For occurrence-oriented questions (“show me every place this is used, so I can change all of them”), static analysis is simply the right tool. No amount of runtime cleverness fixes “the code isn’t loaded”.

The fix: search the source

So CIDER 2.0 does the obvious thing we should have done years ago: xref-find-references (M-?) now finds references by searching the project’s source files on disk. Unloaded code, cljs files, commented-out drafts - if the name occurs in the project, you’ll see the exact occurrence, in the standard xref UI you already use for everything else in Emacs. To borrow the franchise that has been handing programmers debugging metaphors for over two decades now: the runtime is the Matrix, a tidy compiled illusion of your program, and to see every place a thing is really used you sometimes have to unplug and look at the source itself.¹

Here’s the difference in one picture - the same query on orchard.misc/require-and-resolve, first in runtime mode, then in source mode:

The runtime knows about three callers - and points you at each caller’s definition. The source scan turns up all ten actual occurrences, across five files, including the ones written as misc/require-and-resolve in namespaces the REPL never loaded. That’s the gap, in one screenshot.

Now, “search the source” makes it sound like a grep, and I want to be clear that it isn’t a dumb one. Say you’re chasing orchard.misc/require-and-resolve. The search runs in three stages:

1. First CIDER asks the REPL to resolve the symbol at point to its fully qualified name, orchard.misc/require-and-resolve. The REPL is right there on the other end of the wire, so why guess when you can ask?
2. A fast first pass (ripgrep, via Emacs’ own xref-matches-in-files) finds every file that so much as mentions require-and-resolve, purely to narrow the field.
3. Then the Clojure-aware part. For each of those files, CIDER reads its (ns ...) form to learn how that file pulls in orchard.misc - aliased as [orchard.misc :as misc], brought in with :refer [require-and-resolve], or is this orchard.misc itself? - and builds a regexp that matches only the forms that file could legitimately use: the qualified orchard.misc/require-and-resolve, the aliased misc/require-and-resolve, or a bare require-and-resolve where the namespace declaration makes that valid. The requires inside the ns form are excluded, so the import line doesn’t show up as a “usage”.²

Is any of this as smart as clj-kondo’s full analysis? No - it’s ultimately a syntactic search, so an identically named var in another namespace can still sneak through as a false positive. But because it’s ns-aware rather than a blind text match, a bare require-and-resolve in some file that never requires orchard.misc (and has a require-and-resolve of its own) won’t be mistaken for yours. For the daily “where is this used?” question it turns out to be remarkably close to the real thing in practice, it requires zero extra infrastructure, and it composes with what only CIDER has: the running REPL.

That composition is configurable via cider-xref-references-mode:

• source (the default) - occurrences from the project’s files.
• runtime - the historical loaded-vars behavior.
• both - source occurrences first, plus the runtime hits the scan can’t see. And there are such hits: references generated by macro expansion leave no textual trace in your source, but the runtime knows about them. Static analysis can’t ever tell you those; your REPL can.

(There’s also cider-xref-fn-refs-in-source, C-c C-? s, when you want the source search explicitly, and outside a project the source mode gracefully falls back to the runtime search.)

Beyond find usages: the who-* family

While closing the gap, we went further and built out a whole family of SLIME-inspired cross-referencing commands under C-c C-w, most of them rendered as expandable trees:

• cider-who-calls / cider-who-is-called - the call graph, upward and downward. Expand a caller to see its callers; spelunk as deep as you like:

  

• cider-who-implements - a protocol’s implementing types (inline defrecord/deftype implementations included) or a multimethod’s dispatch values, each jumping to the implementation’s source. Multimethods are a nice case study in hybrid thinking: the method functions carry no source metadata at runtime, so CIDER locates the defmethod forms by - you guessed it - searching the source.
• cider-type-protocols / cider-protocols-with-method - the reverse lookups: what does this type implement, and which protocols declare this method?
• cider-who-macroexpands - a macro’s use sites, found via source search, because macro invocations are expanded away at compile time and the runtime literally cannot see them.

Much of this is powered by new ops in cider-nrepl (and Orchard underneath), and much of the inspiration came straight from SLIME and swank-clojure, which offered who-calls back when Clojure itself was barely out of the crib. And here’s the part I love: the whole “go read the source instead of trusting the runtime” instinct was already there in swank-clojure’s implementation. Its who-calls would find candidate callers among the loaded vars, sure, but then it went and read the actual source form of each one off disk and walked the parsed code looking for your symbol, rather than believing whatever the compiled runtime claimed. It was still anchored to loaded code - it never scanned the whole project the way CIDER 2.0 does - but the core idea, that the source on disk is the ground truth and the runtime is just a convenient approximation, predates this release by about fifteen years. Good ideas don’t expire. Sometimes nothing beats revisiting the classics.³

So do you still need clojure-lsp?

If you were running clojure-lsp primarily for find-usages - the most common answer I heard when I asked - then CIDER now covers you out of the box. If you use it for project-wide renames, unused-var linting, or editing without a REPL, carry on; those are real strengths of static analysis and CIDER doesn’t try to replicate them. The two continue to work fine side by side, and the new async eldoc even yields politely so LSP-provided docs can compose with CIDER’s.

My goal was never to “beat” clojure-lsp - it was to make a freshly installed CIDER answer the questions every Clojure programmer asks a dozen times a day, with no extra moving parts, and with the one advantage nobody else has: a live runtime on the other end of the wire.

The full story is in the navigation docs. Keep hacking!

Articles in the Series

• CIDER 2.0: Sky is the Limit
• Simplifying Session Management in CIDER
• Stepping Through Macros in CIDER
• Making CIDER More Discoverable
• Modernizing CIDER's Completion
• Closing the Find-Usages Gap in CIDER
• Sharpening CIDER's Debugging Tools
• Leveling Up CIDER's ClojureScript Support

You know how I said last time Part 1 was just the introduction? I lied.

My emacs-settings.org file includes an introduction that covers what I already went over and more. I thought I’d skip it, but as I looked through the notes I left to myself — various guidelines, warnings, and tips — I realized that this is exactly the kind of stuff I should share.

Style

As I was writing this, I fell into a rabbit hole (of course) and made a couple of additional changes.

Style and style guides are important to me. In college, as an editor, I used the AP Stylebook as a bible almost, along with the Chicago Manual of Style for academic papers. When I worked as a technical writer, it was Microsoft’s stylebook I checked constantly — and some of it stuck (don’t say “click”; say “select”, don’t say “sign in”; say “log in,” etc.) The main point is to stick to a style and keep using it — which one matters less.

Here are the notes:

1. Emacs keyboard shortcuts and file paths should be placed in verbatim (between = and =)¹
2. Code (as part of an explanation) should be placed in code (between and )

Code blocks: use structure templates (C-c C-,) and choose emacs-lisp from the list (this is defined below). It should be in lower case: #+begin_src emacs-lisp and #+end_src.

When explaining code: the explanation follows the code immediately (no space). Use a space after the code (new line) for the next item:

 explanation for item 1
 #+begin_src emacs-lisp
 code for item 1
 #+end_src
 
 explanation for item 2
 #+begin_src emacs-lisp
 code for item 2
 #+end_src

Navigation Tips

My settings file is long and requires that I jump around to different sections. As I was working on revamping it, I’ve learned quite a few useful “tricks” that I started sharing in earlier posts. These are always good to know, not just in our setting file.

Jump Back With the Mark Ring

While registers (I have a section about them below) are a nice org-mode feature I keep forgetting about, they’re a bit of an in-between too much or too little for most cases in this file. For quickly getting around, we should use the mark ring:

Use C-u C-SPC (built on set-mark-command) to jump back to where our marker was before, which is usually where we ended scrolling or moving to see something. Keep pressing to keep going back — it remembers all the positions we landed on. By default, it remembers the last 16 positions.

Editing Code Blocks

Edit code blocks with C-c ‘ instead of just working with the text inside the org buffer directly²

Don’t edit the text in a code block (#+begin_src… #+end_src) directly. While it works, we’re missing out on the power of org-edit-special, and this is one powerful org-mode feature. Here are some of the highlights relevant to me, in bold:

  *When at a table, call the formula editor with 'org-table-edit-formulas'.*
 When at table.el table, edit it in dedicated buffer.
 When in a source code block, call 'org-edit-src-code'; with prefix
   argument, switch to session buffer.
 When in an example block, call 'org-edit-src-code'.
 *When in an inline code block, call 'org-edit-inline-src-code'.* **(this is what we're doing here!)**
 When in a fixed-width region, call 'org-edit-fixed-width-region'.
 When in an export block, call 'org-edit-export-block'.
 When in a comment block, call 'org-edit-comment-block'.
 When in a LaTeX environment, call 'org-edit-latex-environment'.
 When at an INCLUDE, SETUPFILE or BIBLIOGRAPHY keyword, visit the included file.
 *When at a footnote reference, call 'org-edit-footnote-reference'.*
 When at a planning line call, 'org-deadline' and/or 'org-schedule'.
 When at an active timestamp, call 'org-timestamp'.

What it gives us when we work with the settings here:

1. A separate temporary buffer, without the #+begin_src… #+end_src, which we can evaluate any time, without worrying about being at the end of an expression (parentheses) and use C-x C-e³.
2. Safety net: as long as we don’t close it with another C-c ‘, it doesn’t save the code, and we can run it in that separate buffer to see what it does.

Also, nice bonus: it highlights the code we’re in with a separate color, and it will keep highlighting it as long as org-edit-special is open. Need a coffee refill? No problem, you know exactly where you left off.

Links

In my config, I started using links more often instead of setting registers (as I noted earlier, registers are too much for moving around, but too little as permanent location savers). I stole the thunder from this section in this post, but it deserves its own post anyway. org-mode internal links are very powerful, and I don’t think the manual explains them well enough (examples would be good), so go check it out.

Registers

Registers can save a location in a file to be recalled later from anywhere else in Emacs, or, to save a chunk of code to be pasted (yanked) later.

1. To save a location: C-x r SPC, then a number or a letter to name the register. So C-x r SPC and then 1 will save a register called “1” in the position the marker is on.
2. To jump to a saved location in a register: C-x r j, then the number/letter we previously selected. So in this example, C-x r j and then 1 will take us back to the location we saved as “1”.
3. To save a region in a register: First, highlight (select) a region in Emacs. Then C-x r s, then a number or a letter to name the register. So selecting this sentence, then C-x r s and then 1 will save the sentence in register 1.⁴
4. To insert a saved region: C-x r i, then the number/letter we previously selected.
5. To view saved registers: M-x view-register, which allows you to select one by number. A good replacement for C-x r j if you need a visual reminder like I do.

It’s a good idea to keep numbers for positions and letters for text so we don’t get them confused and overwrite our registers.

Footnotes

¹ Most Emacs users, I believe, use code for file paths. The reason I have it different here is because I often talk about files in my posts without referring to code, and I will now make use of the <kbd></kbd> tags as well, which I forgot about. This is good for clarity, especially when we talk about Emacs, since Emacs and keyboard shortcuts are mentioned together all the time.

² Those of you who code and write functions on Emacs regularly would probably find this “trick” trivial. However, as a person who does not have this background, I’ve been editing my code blocks directly in org for years — I had no idea org-edit-special exists. I’m sure some folks out there are in the same boat.

³ Which is, as I explained in my previous footnote, exactly what I’ve been doing for years. It works, but it can lead to mistakes, and it’s not as safe (you’re changing your settings, so if something goes wrong, Emacs’ startup will stop at the error).

⁴ In a usual discovery manner, I found out that C-x r + appends text to the register. So, if you were to select this footer here from the word “In” to the dot after “register”, you could then go to the word “So” and mark again to the word “footer” 7 words later, hit C-x r +, and then when you ready to yank (paste), hit C-x r i and both sections will be yanked as one. Actually, you could forgo C-x r i altogether and use C-x r + from the start, because if you append to an empty register, it will just append that first chunk.

Raymond Zeitler over at Ray on Emacs has a nice post on copying the link at point in EWW. It’s sort of hidden so that’s the reason for his post and this one. He decided to write his own because he couldn’t find anything that already did the job. It was only after he wrote it that he stumbled on the existing functionality.

The short answer is that the u key does just what he wanted. The longer answer is that sometimes w also works. The documentation says that w copies the URL of the current page but if the point is on a link, it will copy the link’s URL instead.

I’m finding that I’m using EWW more and more so I’m glad to have this information. Zeitler has more details so be sure to take a look at his post.

Being a PhD student within a research group entails some structure to tracking your progress as your proceed with research. Within the current team that I'm in, we have weekly group meetings where each member presents the tasks that they've completed during the previous week and discuss any issues they might've faced (if any), to our supervisor.

Usually before the meeting, I jot down things that I've finished with pen and paper. But since I'm in the spirit of integrating my workflow with emacs and orgmode, I thought why don't I try implementing this part of my routine also into orgmode.

Enter org-agenda

All my todo items are tracked with org-agenda where I capture every task I need to finish with org-capture¹.

I have a custom org-agenda view just for viewing my daily and weekly TODO items, events/meetings scheduled at a certain time and tasks that have a deadline associated with them. Suffice to say, this workflow has replaced all my needs for having a calendar over the cloud, be it Google, Outlook, what have you². The only downside that I haven't figured out (yet) is to incorporate calendar invites that I receive via email, into my org-agenda automatically instead of manually capturing an event into the agenda view.

With this custom agenda view, as I finish tasks and mark them DONE, they disappear from the current view. This is by design. I figured I could just review my completed tasks by visiting the relevant files (tasks.org, meetings.org, etc. in my case). But who wants to sift through all the completed tasks and filter them manually to only note down the tasks completed during the previous week? Why not automate this with the power of emacs?

Elisp snippet that implements this weekly review

The idea is fairly simple. I'd like to look at the tasks that I've completed since the last group meeting. This assumes I review these tasks on the day of the group meeting (which I do currently³).

We simply then instruct orgmode to filter out the DONE items from the last 7 days. The org-agenda-custom-commands variable is what we'll use to define this custom org-agenda view.

(setq org-agenda-custom-commands
      '(("w" "Finished tasks from last week" tags "CLOSED>=\"<-7d>\""
         ((org-agenda-overriding-header "Finished tasks from last week")
         (org-agenda-archives-mode t)
         (org-agenda-tag-filter-preset '("-emacs" "-personal" "-email"))
         (org-agenda-prefix-format '((tags . " ")))
         (org-agenda-remove-tags nil)))))

Let's go over the various config options one by one:

• The first line defines the keybinding in the primary org-agenda dashboard and the associated title for the keybinding.
• tags "CLOSED>=\"<-7d>\"" is pretty self-explanatory. We filter for items that were completed in the last 7 days.
• org-agenda-overriding-header: Simply defines the title of the agenda view.
• org-agenda-archives-mode: This is set to t (True) meaning to also look at the archived entries from last week. I typically archive my entries frequently so this is helpful.
• org-agenda-tag-filter-preset: I don't want personal tasks appearing in this view, so I remove any items that have the relevant tags.
• org-agenda-prefix-format: By default, the agenda view contains information about which file the entries belong to (in my case, it's tasks.org). This appears as tasks: per entry in the agenda which unnecessarily clutters the view.
• org-agenda-remove-tags: I don't want to remove the tags of the various entries (they are useful to me) that appear in the right margin. Hence this variable is set to nil (False).

To invoke the view, we can simply run M-x org-agenda and hit w to get into the view. My org-agenda dashboard looks like this:

All the above keys are present in the default view, except my custom views (depicted by j and w keys).

Invoking custom org-agenda views (slightly) faster

For my workflow, I mostly deal with just the two org-agenda views (represented by j and w). It's a good idea to have a global keybinding to quickly invoke these views. Let's define the function and keybinding for it.

(defun pani/done-items-prev-week-org-agenda ()
  "Custom function to immediately jump to my custom org-agenda view."
  (interactive)
  (org-agenda nil "w"))

To invoke the function, we define the keybinding like via a use-package macro so:

(use-package org-agenda
  :ensure nil
  ;; Don't need to go through org-agenda template for custom agenda
  :bind (:map global-map
	      ("C-c w" . pani/done-items-prev-week-org-agenda)))

I can then just hit CTRL c w to bring up this new agenda view.

That's it! This should make things easier for me during our group's weekly meetings.

Over at The Art Of Not Asking Why, JTR has begun a series on his Emacs configuration. This post covers his special arrangements for macOS. There are two tips, in particular, that seem to come up all the time.

The first is setting the path. That, of course, is supposed to be a simple process on Unix-like systems but doesn’t work correctly for Emacs on macOS. A long time ago, Steve Purcell solved this problem with his exec-path-from-shell package. You can read the details and what the exact problem is at the package’s GitHub repository. If you’re using Emacs on a Mac, you definitely need this package.

The second problem involves Dired. It’s obvious, if you think about it, that Dired depends on the Unix ‘ls’ command to produce its listings and some of its other operations. The problem is that the macOS version of ls is missing some of the options that Dired needs. The solution is to use the GNU version of ls, called gls. That’s easy to do but you first have to install it. The easy way to do that is through Homebrew. Once gls is installed, you need merely tell Dired to use it.

All the details for solving these two problems are in JTR’s post so if you’re running on macOS, you should definitely take a look at it. I’ve had both those changes installed for as long as I can remember but I do recall struggling with these issues until I found the solutions. Happily, if you’re new to Emacs on the Mac, JTR has both solutions for you in one place.

Embark is one of those packages that quietly rewires how you use Emacs. Think of it as a context-aware right-click: you invoke embark-act (I keep it on C-.) on whatever’s at point - a file name, a symbol, a URL - and Embark offers a menu of things you can do with it. The neat part is that it’s completely extensible, so you can teach it about new kinds of targets. Lately two of my projects, CIDER and Projectile, have grown Embark integrations, in slightly different ways, and both are worth a look.

Let’s start with CIDER, and teach Embark about Clojure symbols, so embark-act on one offers a bunch of CIDER commands:

So d shows the documentation, . jumps to the definition, r finds references, i inspects the value, c opens ClojureDocs and a runs apropos - the usual CIDER commands, a keystroke away from wherever your cursor happens to be.

Here’s the setup. It’s a handful of little wrappers around the CIDER commands, a keymap that binds them, a target finder that spots a Clojure symbol at point, and the bit of wiring that ties it all together:

(defun my-cider-embark-doc (sym)
  (interactive "sClojure symbol: ")
  (cider-doc-lookup sym))

(defun my-cider-embark-find-def (sym)
  (interactive "sClojure symbol: ")
  (cider-find-var nil sym))

(defun my-cider-embark-fn-refs (sym)
  (interactive "sClojure symbol: ")
  (cider-xref-fn-refs nil sym))

(defun my-cider-embark-inspect (sym)
  (interactive "sClojure symbol: ")
  (cider-inspect-expr sym (cider-current-ns)))

(defun my-cider-embark-clojuredocs (sym)
  (interactive "sClojure symbol: ")
  (cider-clojuredocs-lookup sym))

(defun my-cider-embark-apropos (sym)
  (interactive "sClojure symbol: ")
  (cider-apropos sym))

(defvar my-cider-embark-symbol-map
  (let ((map (make-sparse-keymap)))
    (define-key map "d" #'my-cider-embark-doc)
    (define-key map "." #'my-cider-embark-find-def)
    (define-key map "r" #'my-cider-embark-fn-refs)
    (define-key map "i" #'my-cider-embark-inspect)
    (define-key map "c" #'my-cider-embark-clojuredocs)
    (define-key map "a" #'my-cider-embark-apropos)
    map))

(defun my-cider-embark-target ()
  (when (derived-mode-p 'clojure-mode 'clojurescript-mode 'clojurec-mode
                        'clojure-ts-mode 'cider-repl-mode)
    (when-let* ((bounds (bounds-of-thing-at-point 'symbol))
                (sym (cider-symbol-at-point)))
      (unless (string-empty-p sym)
        `(cider-clojure-symbol ,sym . ,bounds)))))

(with-eval-after-load 'embark
  (add-to-list 'embark-target-finders #'my-cider-embark-target)
  (add-to-list 'embark-keymap-alist '(cider-clojure-symbol my-cider-embark-symbol-map))
  (add-to-list 'embark-keymap-alist '(cider my-cider-embark-symbol-map)))

That last cider line is my favorite bit. CIDER’s symbol prompts (things like cider-doc and cider-find-var) can read through completing-read and tag their candidates with the cider completion category, so pointing that category at the same keymap means embark-act works on the candidates too. You start typing a symbol to read its docs, spot it in the candidate list, decide you’d rather jump to its definition - C-. . and you’re there, no retyping. Symbols in your code and candidates in the minibuffer end up sharing one set of actions.

Projectile took the opposite tack and ships its Embark integration out of the box - there’s nothing to configure, it wires itself up as soon as Embark is loaded. Two things happen. Acting on a project candidate (say, in projectile-switch-project) gives you project-specific actions - switch to it, open its VC interface, drop into dired, or remove it from the known-projects list - instead of the generic file actions you’d otherwise get:

And when you act on a project file candidate, Projectile makes sure the path resolves against the project root, so Embark’s file actions land on the right file no matter what your default-directory happens to be.

You might wonder why Projectile ships this while CIDER leaves it to you. It comes down to what each integration is. Projectile’s is mostly about making the completion categories it already exposes behave correctly under Embark, plus a small and fairly obvious set of project actions - there isn’t much to bikeshed there. CIDER’s symbol actions are a bigger, more personal grab-bag: which commands you want on that menu, and which keys you put them on, is very much a matter of taste. A recipe you copy and tailor felt like the better fit. Same idea, two problems that wanted different answers.

That’s all I have for you today. Keep hacking!

P.S. If you’re not using Embark yet, the actions above are just the start - once you start thinking of embark-act as “do something with the thing at point”, it’s hard to stop.

CIDER’s code completion has quietly gotten quite good over the years, and I don’t think it gets enough credit. It’s all built on Emacs’s standard completion-at-point, so it works with whatever completion UI you prefer - the built-in one, Corfu, company - without any special setup. Under the hood compliment does the heavy lifting for Clojure (and clj-suitable for ClojureScript), which means smart, backend-driven matching: mai completes to map-indexed, cji to clojure.java.io, and an unimported BiFun to java.util.function.BiFunction. The candidates come back ranked by the backend and are context-aware - it knows when you’re inside a -> or completing a deftype field.

Lately I’ve been giving the Emacs side of things some attention, to bring it in line with the modern completion stack so many of us now use - Vertico, Corfu, Consult, Marginalia and friends. Two changes are worth calling out.

The first is about the symbol prompts. A number of CIDER commands ask you for a Clojure symbol when there’s nothing at point - cider-doc, cider-find-var and the like. Historically those prompts used the older completion machinery, so your completing-read UI didn’t kick in and you were left with TAB and a *Completions* buffer. There’s now cider-use-completing-read-for-symbol (off by default for now); turn it on and those prompts go through completing-read over a collection that queries the running REPL lazily as you type. Vertico, Ivy, Helm - whatever you drive completing-read with - just works, and the candidates carry their type and namespace.

The second is smaller, but I like it a lot: annotations now line up in a proper column instead of trailing raggedly after each candidate.

This comes from an affixation-function, the richer successor to the old annotation-function, so every frontend that understands it - the built-in *Completions*, Corfu, Vertico - renders the aligned version. company keeps showing its own trailing annotations, same as before.

Both changes are in the latest CIDER MELPA build and will ship in the next stable release. As always, I’d love to hear how they work out for you.

That’s all I have for you today. Keep hacking!

P.S. If you use Embark, I wrote up a fun way to act on Clojure symbols with it - documentation, jump-to-definition, inspect and so on - over on Emacs Redux.

Articles in the Series

• CIDER 2.0: Sky is the Limit
• Simplifying Session Management in CIDER
• Stepping Through Macros in CIDER
• Making CIDER More Discoverable
• Modernizing CIDER's Completion
• Closing the Find-Usages Gap in CIDER
• Sharpening CIDER's Debugging Tools
• Leveling Up CIDER's ClojureScript Support

I like writing. Really.

However, I have problem finishing my drafts. As you might be able to read in my OKRs, I mentioned multiple times that I have quite a lot of blog drafts that I haven’t completed. I don’t want to blame anyone and it’s completely my fault: I have problem focusing on a task. I have an attention problem. In the past, I could blame things like Twitter for distracting me from getting shit done. But now, I don’t use any of these social media services anymore. I am running out of excuses.

I wanted to change my writing routine and would like to see if it would make a difference. Then, I watched a video by Veronica (of Veronica Explains) on her (new) writing setup. She reused an old laptop and made it a dedicated writing machine, or “writerdeck.” In that writing machine, she only used command-line only Debian and neovim (her preferred text editor). Her blog post has details on her machine. I find the idea very interesting and wanted to give it a try.

First, I needed a spare laptop. ¹ In fact, over the years my wife and I have accumulated a few unused but still functional laptops. I decided to take my wife’s previous ThinkPad T440 with Intel i5 and 8G of RAM. ² It is a perfectly capable machine, only it is unbelievably slow for my wife’s relatively simple tasks such as watching YouTube. Modern web browsers are memory hog. And this is exactly the category of software a dedicated writing machine doesn’t need.

I followed Veronica’s blog post and installed Debian without any desktop environment and kmscon. My first diversion from Veronica is that I use emacs. I just quickly pulled my emacs configuration on my main machine from Git and removed all configurations about programming. emacs launches extremely fast ³ and should be so. You know, people bought 386 back in the late 80s to 90s to do similar things: launching DOS and write with Word Perfect or Word Star. ⁴ There is no way that an i5 machine cannot do that perfectly as it is perhaps 1000 times better than a 386.

With my own configuration, it also has all the emacs packages that I need for writing. And in fact, not that many: I only need deft to organize my files and Markdown mode (sorry I don’t use org mode). I feel quite at home writing there. I don’t want to waste a lot of time customizing. So I don’t even want to install vterm and simply use eshell, as I probably don’t need to do a lot of command line works. The machine now directly boots to emacs (just put emacs in .bashrc). More concretely, directly to deft (just add (deft) to my emacs configuration file).

Another diversion from Veronica is how I get the text files from the writing machine to other machines. I do not want to set up syncthing to sync text files across machines. I don’t even want to have ssh server on any of my computers. My overkill solution is to just have a Git repository and have a remote on Codeberg. magit is also useful here to further reduce the command line usage. It is only my lack of imagination for using Git. Maybe in the future I will have something like rsync.

Then, I write. It is really great! It’s extremely snappy and extremely minimal. And I can really focus on the writing, rather than being distracted (and frustrated) by the bullshit on MS Teams about my work. I also don’t need to sit around my “work desk.” I can also write from my couch while watching Tour de France.

There are still some minor nitpicks that I want to fix for this setup. One is the blinking cursor of kmscon 10.0.1. I can be easily frustrated by any blinking cursor. I think it will be fixed in the next official release. I see it over the official GitHub repository. ⁵ Another nitpick is the emacs theme. Many emacs themes were developed for the graphical mode. I want to use a bright theme (e.g., solarized). But it displays quite badly on kmscon. But the default dark theme is fine.

With this new setup, I think I will be able to finish my backlog of drafts and also some new academic writing tasks.

If you've ever written an Emacs function only to find out that it was there all along, masquerading as something else, this post is for you.

I just finished writing an Emacs function that copies the link at point to the kill ring in EWW. It will remain unpublished. Why? Because I discovered that shr-maybe-probe-and-copy-url (bound to u and w in eww-mode) does the same thing. Just position point on a link and invoke it.

It's not obvious that pressing w will do this. In fact the major mode help for eww-mode suggests that w will not copy the link because it's bound to eww-copy-page-url. But it turns out that if point is on a link, w will invoke shr-maybe-probe-and-copy-url, "which copies this link's URL to the kill ring." The manual goes on to say, "If point is not on a link, pressing w calls eww-copy-page-url, which will copy the current page's URL to the kill ring instead."¹

Before writing my function I had been looking through the mode help (C-h m from within a EWW buffer) and the EWW source code for any function that looked like copy-link-at-point.

So how did I find out about this? I wanted to ensure that I was following the standard for capitalizing EWW, so I searched the web. This took me to the GNU Emacs manual, which has a section on EWW and shows it in all caps. But then my distractibility encouraged me to read a great deal more.

I've known that keybindings can change depending on the major mode. But it seems a keybinding can change based on context (i.e. the position of point). This idea is new to me. Maybe it's common for a function to "hand off" to another based on context. But in this case it seems irresponsible to omit documentation for the alternate behavior of a w key press. Suppose a user expects to copy the page URL and gets the URL of a link, instead?

While this was a frustrating experience, it is yet another reminder to RTFM. WDYT?

This month’s Emacs Asia-Pacific (APAC) virtual meetup is scheduled for Saturday, July 25, 2026 with BigBlueButton and #emacs on Libera Chat IRC. The timing will be 1400 to 1500 IST.

The meetup might get extended by 30 minutes if there is any talk, this page will be updated accordingly.

If you would like to give a demo or talk (maximum 20 minutes) on GNU Emacs or any variant, please contact bhavin192 on Libera Chat with your talk details:

Sean Whitton writes to say that Emacs 31.0.91, the second Emacs 31 pretest, is now available. If you’re interested in trying it out, you can get a copy from https://alpha.gnu.org/gnu/emacs/pretest/emacs-31.0.91.tar.xz. It’s signed so you should also get the signature file from https://alpha.gnu.org/gnu/emacs/pretest/emacs-31.0.91.tar.xz.sig.

This is good news, of course, because it means that Emacs 31 is that much closer to release. There’s some great new features coming in Emacs 31 (see the NEWS file for details) so I’m looking forward to its release. On the other hand, it’s good that the devs are being conservative and trying to wring all the bugs out before the official release.

If you don’t mind living (slightly) on the edge, try it out and let the devs know if you find any problems.

Substitute provides a set of commands that perform text replacement (i) throughout the buffer, (ii) limited to the current definition (per narrow-to-defun), (iii) from point to the end of the buffer, and (iv) from point to the beginning of the buffer. Variations of these scopes are also available.

These substitutions are meant to be as quick as possible and, as such, differ from the standard query-replace (which I still use when necessary). The provided commands prompt for substitute text and perform the substitution outright, without moving the point. The target is the symbol/word at point or the text corresponding to the currently marked region. All matches in the given scope are highlighted by default.

• Package name (GNU ELPA): substitute
• Official manual: https://protesilaos.com/emacs/substitute
• Git repositories:
  • GitHub: https://github.com/protesilaos/substitute
  • GitLab: https://gitlab.com/protesilaos/substitute
• Video demo: https://protesilaos.com/codelog/2023-01-16-emacs-substitute-package-demo/
• Backronym: Substitutions Uniformly Beget Standardisation for Text Invariably Transfigured Unto This Entry.

Below are the release notes.

Version 0.6.0 on 2026-07-24

This version brings quality-of-life improvements to an already stable package. The user-facing changes are as follows:

1. When performing a substitution, the minibuffer prompt now reports how many matches there are in the given scope. For example, if I call substitute-target-in-defun, I get something like this prompt:

   "Substitute `this-symbol' (3 times) in the current DEFUN with:"
   

2. substitute-target-in-line is a new command that behaves like all the others within the boundaries of the current line.

3. The face used at the prompt to highlight the target of the given substitution is now defined as substitute-prompt-target-highlight. Users or theme developers can update as needed, though the default value should work in virtually every setup.

4. Aliases of certain commands are also autoloaded. Concretely, this means that Emacs is aware of them even before substitute.el is loaded, so they can be bound to keys or called with M-x at any time. Thanks to Morgan Willcock for the patch. Morgan has assigned copyright to the Free Software Foundation.

5. The command substitute-target-in-page should correctly target the current page. Thanks to Morgan Willcock for the patch.

I’ve been working on my Emacs config for three weeks now, coming this weekend. It’s one of the deepest and most fun rabbit holes I’ve been exploring. As I stumble upon new ways to do things, I dig deeper, learn more, and keep tweaking my config, which makes this rabbit lair even bigger.

Eventually I realized that if I wait until I’m done to upload the config file, it will never happen: by the time I’m done, I will accumulate enough fixes and additional tricks and tweaks to warrant a whole new file.

The conclusion is what I should have done from the beginning: apply changes in chunks and explain what I’m doing and why as these happen.

I’m starting with changes to my .emacs¹ file on my mac², before we’re even touching the “good stuff” in my main emacs-settings.org file. Why? Because Emacs was built with Linux in mind, and we need to make some important adjustments to how Emacs works on a Mac before we use it. As you will see, I’m using this conceptually too: while some of the configurations in the .emacs file (the “init” file) could technically be placed in the big emacs-settings.org file, I still place them in what I consider Emacs’ “booting” process.

My .emacs file contains only these four code blocks, which are separated with spaces for visual convenience:

    (when (memq window-system '(mac ns x))
      (exec-path-from-shell-initialize))
    
    (setq insert-directory-program "gls" dired-use-ls-dired t)
    
    (setq custom-file (expand-file-name "emacs_custom.el" user-emacs-directory))
    (load custom-file 'noerror)
    
    (org-babel-load-file
     "/Users/user/Sync/Public/emacs_settings/emacs_settings.org")

exec-path-from-shell-initialize

    (when (memq window-system '(mac ns x))
      (exec-path-from-shell-initialize))

This tells Emacs that if its windowing system is macOS-related (ns or x; there’s also the old mac version of Emacs that is not being used today — the Homebrew emacs-plus one we are using here is ns, which can be checked with M-x emacs-version), it should run exec-path-from-shell-initialize.

This function copies the PATH from the shell, as if we were using a terminal program. By design, macOS GUI applications (those that live in the user’s Applications folder and have an .app extension) are not exposed to this PATH because they’re launched by a different process altogether (launchd)³. But Emacs needs this PATH, as many of its core components integrate with the OS as a terminal application, which is what it is, at its core.

In fact, this is why we need this condition in a file that resides on a Mac, and why this condition is triggered by the windowing system, and not the OS itself (every other condition in our config would be written as eq system-type 'darwin or similar). If we run Emacs in terminal, the program already has access to PATH, and this execution is not needed.

Use gls in Dired

    (setq insert-directory-program "gls" dired-use-ls-dired t)

This doesn’t have to live in our .emacs file, as it can live as part of our Dired options in emacs-settings.org, which will come later. However, this is a macOS-only thing, and since we need to get gls from Homebrew, it’s one of those things to prepare before we start Emacs for the first time. After all, we will probably use Dired right away after install, and we want to make sure it’s ready.

gls, GNU’s ls command, is bundled with other utilities inside coreutils, so we install it with brew install coreutils. Then the above command makes sense — we’re telling Emacs to use this flavor of this ls command instead of the one that comes with macOS, which is lighter and doesn’t have what we’re used to seeing in Emacs Dired (at least, not for me). As it turns out, there are other well-known utilities in this package, such as rm and mkdir, but we don’t use them, so it’s really just for gls.

Changing Emacs’ custom default file to emacs_custom.el

    (setq custom-file (expand-file-name "emacs_custom.el" user-emacs-directory))
    (load custom-file 'noerror)

This is something I discovered while working on my .emacs file. It was cluttered with comments and configurations from Emacs’s custom, Emacs’ settings wizard. This is because by default, Emacs doesn’t have a definition for it:

File used for storing customization information. The default is nil, which means to use your init file as specified by ‘user-init-file’. If the value is not nil, it should be an absolute file name.

It makes sense if you use custom often, which probably means you don’t bother with babel (coming up) and writing long Emacs posts like this one, but in reality, I haven’t met an Emacs user who used it for more than a few months at most without getting their hands dirty. It’s just too tempting.

The first line tells Emacs where the custom file config is (inside /.emacs.d/, the default for user-emacs-directory), and the second line tells it to “not worry” if the file is not there. Why? Because the first time we run Emacs (or a clean reinstall), we might not have this file at all yet, as it’s created by custom. If we don’t have this file, Emacs will do whatever it does whenever it encounters an error: tell us there’s an error and stop running the rest of the config. And this happens right at the beginning, so essentially our entire config will be skipped. So this is a good safety option⁴, and probably good practice.

Org-babel: load the configuration from an org file

    (org-babel-load-file
     "/Users/user/Sync/Public/emacs_settings/emacs_settings.org")

Now, after we put all the critical macOS⁵ configuration in place, it’s time to tell Emacs where the rest of the configurations are. This here was just the introduction, the Emacs “boot” for Mac only, after all⁶.

So here we are, done with part 1. It took me way longer to write than I thought it would take (I’ve been standing at my desk for about 2 hours now), but this is exactly the sort of thing that keeps me hooked on Emacs. Everything leads to more… everything. There’s a story behind every dot, apparently. As you can see from my footnotes, I’ve found additional tangents to go on while writing this just now, and that’s on top of a growing list I already have, of about 10 other things I want to check — and my config is only about 25% done. And as I said, by the time I’m done, it will be time for round 2, which in turn will probably lead to round 3…

“Emacs. It really whips the GNU’s…” errm. Anyway. See you next time!

Footnotes

¹ The story of dot files (files that start with a dot, like .emacs) is an interesting one. Turns out it was a programming mistake back in the days when Unix started, and it stuck as an idea. These became convenient to use as configuration files because they are the sort of files that are usually created when you install something and configure it once, probably to never see it again (this was before Emacs users started popping up, obviously), so the bug became a feature.

² On a Mac, you have several options when installing Emacs. The one I’ve been using over the years, and what seems to be the most popular, is emacs-plus at https://github.com/d12frosted/homebrew-emacs-plus. Some of the choices I made in my .emacs file are based on this fact.

³ There’s another rabbit hole here I didn’t explore much: Emacs on Homebrew, at least in some versions, has incorporated the option to grab the PATH during installation; however, it seems Apple blocked this option at some point, so we need to run it like this. I don’t recall ever getting a warning that Emacs needs access to my PATH or something similar, but I wouldn’t be surprised if something to that effect is happening when you first install it.

⁴ As I’m writing this, I realize there’s another worthwhile rabbit hole here: the option to tell Emacs to ignore errors for non-critical configurations, such as the theme, or the way org-mode displays, etc. While I want these in place, if there’s an error, I’d like Emacs to keep loading the config if it can. Since there are different “skip error” options depending on where and what is being skipped, and since I need to be sure what I’m skipping, I’ll do more digging another time.

⁵ Ah ha, but that last one, the custom file location, is also good on Linux! Good thing I’m writing this blog post. When I go back to my Linux machine, I will include this line there as well.

⁶ By the way, while there is no org-babel.el, it can almost be one from a quick look (yes, yet another rabbit hole). There are many different .el files scattered in Emacs that relate to org-babel which can do different things.

This series about the notable changes in CIDER 2.0 continues with the change you’ll bump into first, whatever your workflow: the transient menus, and the broader push to make CIDER’s functionality discoverable.

The problem: CIDER is huge

CIDER has well over 300 interactive commands. I’ll admit something I’ve said before: there are features in CIDER that even I forget exist, and I wrote half of them. For users, historically, the options for finding functionality were:

• memorize cryptic key chords (C-c C-w i, anyone?)
• grep the (very long) manual
• read the source
• stumble on a feature by accident three years in and feel robbed

That’s not great for a tool whose whole pitch is making you more productive. The Emacs answer to this problem was demonstrated years ago by Magit: transient menus, which turn every prefix into a self-documenting popup. It took us embarrassingly long to follow suit, but CIDER 2.0 finally does.

Transient everywhere

Every command group in CIDER now opens a transient menu: cider-eval-menu at C-c C-v, cider-doc-menu at C-c C-d, and likewise for test, namespace, macroexpand, profile, trace and references. A top-level cider-menu ties them all together, and even the debugger (? mid-session) and the inspector (m) got menus of their own. Jack-in and connect live in cider-start-menu at C-c C-x.

Here’s the evaluation menu, which is a good illustration of the problem the menus solve - I doubt many people knew all of this was hiding behind C-c C-v:

One design constraint was non-negotiable: your muscle memory is safe. These menus replace bare prefix keymaps, so every existing keybinding works exactly as before, at full speed - C-c C-v e still evaluates instantly, menu or no menu. And if you’d rather not see the menus at all unless you actually hesitate mid-chord, set transient-show-popup to a short delay and they’ll appear only in that moment of doubt - which is precisely when you need them.

Transient also gave us something the old keymaps never could: arguments. Menus now carry flags for the things that vary per invocation - pick a pretty-printer with --print-fn=, set test selectors with --include=/--exclude= and reuse them across runs, toggle cider-ns-refresh’s modes explicitly, pass Clojure CLI aliases at jack-in time. All those “this command behaves differently with a prefix argument” paragraphs in the manual are becoming visible checkboxes instead.

The test menu shows this nicely - set the selectors once and every run below them picks them up:

Discovery beyond menus

The menus are the headline, but the discoverability push in the 2.0 cycle went wider:

• A new keybindings reference page collects every binding in one place, and the printable refcard was brought back up to date.
• The REPL’s shouty welcome banner is gone, replaced by a one-line hint; the getting-started material now lives in a summonable reference card (C-c C-h, or the ,refcard REPL shortcut) - available when you want it, invisible when you don’t.
• CIDER now warns (once per session) when you use a deprecated keybinding, so bindings can actually be retired someday without silently breaking people. M-x cider-list-deprecated-keybindings shows what’s on the way out.
• The 1.22 cycle’s big audit already made the mode menus expose dozens of commands that were technically present but practically invisible; 2.0 builds on that foundation.
• Even cider-doctor is discoverability of a sort - it surfaces the problems in your setup that you’d otherwise discover one confusing bug report at a time.

The philosophy

If I had to compress the 2.0 discoverability work into one sentence: the features were always there; now the tool tells you about them. Documentation is where knowledge goes to be forgotten - the only reliable place to teach a user about a feature is inside the workflow itself, at the moment of hesitation. Transient menus are exactly that, and Magit proved the pattern scales to enormous command sets.

If some menu feels wrong - a missing command, a flag that should exist, a grouping that doesn’t match how you think - please file an issue. This part of CIDER is young and very much open to feedback.

The keybindings docs have the full picture. Keep hacking!

Articles in the Series

• CIDER 2.0: Sky is the Limit
• Simplifying Session Management in CIDER
• Stepping Through Macros in CIDER
• Making CIDER More Discoverable
• Modernizing CIDER's Completion
• Closing the Find-Usages Gap in CIDER
• Sharpening CIDER's Debugging Tools
• Leveling Up CIDER's ClojureScript Support

What would have happened if Emacs' default buffer had been a terminal emulator? Conceptually, from the outside, it would be perceived as a terminal on steroids with Lisp as its scripting language. Maybe we would be talking about iTerm2 vs Emacs, or Kitty vs Emacs, or even Bash vs Emacs. And what if the default buffer had been Dired, the file manager? History might have created rivalries such as Total Commander vs Emacs, or Finder vs Emacs.

But history took another path. We already know that if you launch an Emacs instance without any configuration whatsoever, what you see is a buffer with the following message:

;; This buffer is for text that is not saved, and for Lisp evaluation.
;; To create a file, visit it with ‘C-x C-f’ and enter text in its buffer.

A notepad with an embedded Lisp interpreter. Its natural rival is Vim with an embedded interpreter (Vimscript). However, the editor that made us all memorize :q! stayed in the buffer, while Emacs kept expanding with more and more software until it became an interface to the operating system.

I'm an Emacs enthusiast, and maybe that costs this article some credibility. However, I'm not here to tell you how fantastic the GNU editor is, nor to convince you to use it. My goal is to explain why the web browser is its true natural rival, and why Emacs is a Lispboard where you build the way you want to work.

Let's imagine a perfect working environment

To set the stage, let's do a little thought experiment.

Suppose I want to work in a single place for all my contexts, both personal and professional. That way I memorize my shortcuts, apply my configurations and never have to switch contexts. Everything lives under the same window.

It's a problem, because it means merging programs that have nothing to do with each other but need to collaborate. For example, a terminal emulator, an email client and a code editor (or IDE). With a layout system, inside the same window, I could have one column with my email inbox, another with the terminal and a third with my IDE ready to write whatever I need. In this space, it would be easy to write a bash script, launch it from the terminal and receive an email with the result. All in the same window, without switching context, with the same shortcuts, the same typography and the same theme. I could even add a fourth column with a Git client to version the script and push it to a remote repository. Or while we're at it, a fifth column with my favorite AI agent, able to read both my code and the rest of the panels.

We have just created an interface.

But this wouldn't be the most useful part: the programs would be integrated with each other, each one living in its own scope and, at the same time, in a global one. That means that if I enable the spell checker in the code editor with a certain configuration, it also becomes active in the terminal, in the email client when composing messages, or when I write commits. All with the same interactivity and configuration. They are not four isolated binaries connected with pipes: they are programs written in the same language, running on the same runtime and sharing the same event bus.

We have just created a connector.

Now let's remove an unnecessary layer: the bash script. If I already have an interpreter embedded in this very window, I can create my own scripts. I don't need an external binary. I no longer need to leave the window, nor touch the operating system. All my scripts, prototypes and workflows can live together.

We have just created a habitat.

There's only one problem left with the runtime: tomorrow I'll change laptops, or I'll want to work from a server, and I have no intention of rebuilding my environment from scratch. I want my scripts to work exactly the same regardless of the operating system and the hardware. A script should behave the same way on Windows, on a Raspberry Pi or on a cheap Android device. I need the whole environment to be a cross-platform runtime with bytecode that runs anywhere.

We have just created a virtual machine.

Now, to round off the idea, we'll use Lisp as the scripting language and we'll call the whole thing Emacs. Although I prefer to call it something else: a Lispboard. Like an electronics breadboard, a board where every module you plug in shares a bus with all the others, except here the modules are written in Lisp.

And if during this exercise you thought "this sounds familiar: tabs, applications and a cross-platform virtual machine... that's my browser", hold on to that intuition. We'll come back to it at the end of the article.

What is Emacs not?

With everything mentioned so far, I want to debunk some myths surrounding Emacs:

• It's not a text editor: it's a complete working environment, with an embedded scripting language, its own software and a cross-platform runtime. The editor is just one more program inside that environment, as are the terminal, the email client, IRC, the file manager or the web browser (yes, Emacs ships with one).
• It's not an operating system: it's a working environment that runs on top of an operating system, and that can replace many of the programs it offers. But it has no drivers, no kernel, no low-level tools. It cannot run without an operating system.
• It's not an IDE: there is no default set of tools focused on programming in a specific language. For that you need LSP backends, debuggers and linters, which are installed as packages. But you can certainly get there; it's one of its most common uses.

What it is: a Lisp interpreter and a framework that run on top of the operating system in the most agnostic way possible, and that reimplement a good part of the programs it offers.

My workflow

Scripting and prototyping

When you think: "I'm going to write a simple bash script to automate a task", I think: "I'm going to write an Elisp function". And on top of that, I'll give it a graphical interface if I need flags or text input.

For example, suppose you need to create a script for yourself, not for a CI/CD process or cron. The goal is to back up a specific folder (maybe to the cloud). You could end up with a command like this:

./backup.sh /home/user/folder /home/user/backup

But you also include a flag to create a zip:

./backup.sh -z /home/user/folder /home/user/backup

Well, instead of going through the terminal, I create an Elisp function that does the same thing, and I add a small panel to it.

I run:

M-x my/backup RET

And a buffer will show up with an interface like this:

Folder backup

Folder: [ /home/user/folder ]
Target: [ /home/user/backup ]
[ ] Compress into zip

[ Cancel ] [ Run ]

With inputs, checkboxes and buttons. Without having to remember where it was, or its parameters, or their order.

If you have worked with Lisp before, you'll see the code is very basic:

(require 'widget)

;; Logic

(defun my/backup-run (folder target zip)
  "Sync FOLDER into TARGET with rsync, or compress it to a zip when ZIP."
  (let* ((folder (expand-file-name folder))
         (target (expand-file-name target))
         (command
          (if zip
              (format "zip -r %s %s"
                      (shell-quote-argument
                       (expand-file-name
                        (format-time-string "backup-%Y-%m-%d.zip") target))
                      (shell-quote-argument folder))
            (format "rsync -a %s/ %s"
                    (shell-quote-argument folder)
                    (shell-quote-argument target)))))
    (async-shell-command command "*Backup log*")))

;; UI

(defun my/backup ()
  "Open a panel to back up a folder."
  (interactive)
  (switch-to-buffer "*Backup*")
  (kill-all-local-variables)
  (let ((inhibit-read-only t))
    (erase-buffer))
  (remove-overlays)
  (widget-insert "Folder backup\n\n")
  (let* ((folder (widget-create 'editable-field
                                :format "Folder: %v\n"
                                "/home/user/folder"))
         (target (widget-create 'editable-field
                                :format "Target: %v\n"
                                "/home/user/backup"))
         (zip (widget-create 'checkbox nil)))
    (widget-insert " Compress into zip\n\n")
    (widget-create 'push-button
                   :notify (lambda (&rest _) (kill-buffer))
                   "Cancel")
    (widget-insert " ")
    (widget-create 'push-button
                   :notify (lambda (&rest _)
                             (my/backup-run (widget-value folder)
                                            (widget-value target)
                                            (widget-value zip))
                             (kill-buffer))
                   "Run"))
  (use-local-map widget-keymap)
  (widget-setup))

And this scales beyond toys. With this same approach I have built systems of all kinds. For example, this blog's newsletter: I manage subscribers, generate the emails' HTML from org files, send them out, send myself previews and analyze the data. All in Elisp, local, and with a simple control panel integrated with other tools.

The key of the example is that I'm not writing a script for an operating system or an interpreter, but a function for my working environment. I'm building a new workflow, in a space where I can program my own tools, connect them to each other or build one on top of another. I could create an asynchronous notification system to alert me when something finishes, and later connect it to the previous tool at no cost.

And I can do all of this because I have an embedded scripting language, a set of libraries (like widget.el to build graphical interfaces) and a cross-platform runtime that guarantees my scripts will work the same on any operating system. That is a Lispboard.

Programming and development

I want to stress that I separate tasks or environments by tabs. And inside each tab I have a layout with the buffers (or software) I need.

In the IDE tab I usually open:

• A text editor with some LSP backend and debugger (dap-mode, Eglot, etc.).
• An AI pair programming partner (chatgpt-shell connected to Claude).
• A Git client (Magit) to version and review the AI's changes.

Although I keep weaving in temporary ones such as the file manager (Dired, with or without TRAMP), the terminal (vterm), the HTTP client (verb), Docker (docker.el), the web browser (eww) or the project manager (Projectile).

Working in Emacs with this level of integration is a pleasure that's hard to describe. You understand why it makes those who program in it fall in love.

Notes and study

Everything I think, plan or study ends up in plain text. The foundation is org-mode: notes, tasks and planning. On top of it, I manage my study notes with Denote: each note is a file with the metadata in its own name, all linked to each other. And when the study material is a PDF or an EPUB, I read it without leaving, with pdf-tools or nov.

Around them orbit small pieces that complete the routine, like jit-spell underlining my mistakes on the fly (remember the spell checker you configure once and it works everywhere? This is it) and wallabag to read or save articles I want to study later, calmly.

Communication: chats, email and social networks

Although it may not seem like it, over the decades the community has built an excellent pack of communication tools. Even for the same protocol there are several implementations, and each one has its advantages.

In my case, I have a tab exclusively for email with mu4e. It covers every need I can expect from an email client: composing, replying, forwarding, filtering, searching, tagging, marking as read/unread, etc. And it had better do it well, because it's the most important communication channel I have: mailing lists, discussions around a Pull Request, messages from other developers, service notifications, and everything that comes with a personal and professional life.

In another tab I keep a set of chats:

• IRC with ERC connected to Libera.Chat. Curiously, this is where I've met the most people and been able to talk with many free software developers. I don't understand the eagerness to consider it obsolete.
• Mastodon with mastodon.el for the Fediverse.
• Org Social with org-social.el to read the posts on my favorite social network (I'm not impartial, I know, and I don't care).
• Telegram with telega.el, which lets me read and reply to messages from groups and channels.

I only leave for Teams and Discord, both communication channels at my job. And WhatsApp, whose use in Emacs still doesn't convince me.

News and reading

My main source of information is RSS with Elfeed, almost all personal blogs. I use clients for the aggregators, hackernews-modern and lobsters (both made by me). With Gnus I read some Usenet newsgroups (it's still alive, and it reads wonderfully) and with Elpher I wander around Gemini and Gopher. When I want to open a web link, I give eww, the Emacs web browser, a chance. If it's unreadable, then I go to Firefox or the like (I have a shortcut).

Leisure

The workday is more pleasant with some music playing, hence EMMS backed by mpv. And when I want to disconnect for a while, I like playing chess with chess, either alone or with a friend online. After all, the board is also there to have fun.

Emacs is a Lispboard

The community has an expression for this way of working: living in Emacs. People have been writing about it for decades, and at the end of the article I leave you the readings that have marked me the most. But notice that living in Emacs describes a habit; what I have tried to show you is the consequence. Everything you've seen is not a collection of programs, it's a single board where every module shares a bus with the rest. An interface, a connector, a habitat and a virtual machine (literally: Elisp compiles to bytecode). A Lispboard to play with, or to make your work more efficient.

Its rival is the web browser. It meets more of the requirements than we like to admit: it's a cross-platform virtual machine (for JavaScript) and half of humanity lives inside it, with their email, their chat, their music and their office suite. But it fails at the essential part: tabs are silos that don't share a bus, you can't wire your email to your chat, and no module is yours: each one belongs to a third party that can change it, fill it with ads or shut it down tomorrow. On top of that, access to the host itself is limited: it's not easy to touch the disk or talk to the operating system. The browser is a rented Lispboard, with a landlord. Emacs is the only one you can own.

To wrap up, I want to make clear that using Emacs is not nostalgia: it's that nothing comparable has appeared yet. The 0.1% of us who use it and squeeze it daily do so because it lets us work in a way no other software allows. We will probably have a lifelong relationship with our configuration. There's always something to tweak, improve or automate. And if there isn't, we create it. Emacs is not free because of its GPL license, but because it's the only place where you can live and work your way.

References

• Why Emacs is still my interface to my computer, the article that encouraged me to write this one.
• Living in Emacs, by Irreal: living in Emacs as a Japanese garden, a process that seeks perfection but is never complete.
• Living in the Browser vs. Living in Emacs, also by Irreal, on the dichotomy between the two great interfaces of our time.
• Emacs: Everything's a Buffer, on the buffer as the universal unit of interaction.
• How I use Emacs, by Joshua Blais.
• I Tried Living Completely Using Just Emacs, by FadinGeek: the experiment of living only in Emacs told from the outside.
• Life in Emacs (revisited), by scut.
• ¿Por qué los usuarios de Emacs lo usan para todo? (in Spanish). If you want more reasons of my own, it's a good companion piece.

Will you buy me a coffee? This is how I keep writing without ads or paywalls. Sure, it's on me!

Send an email to comment+article-06bfd107@andros.dev to leave a comment. The subject will be ignored.

Bozhidar Batsov has been a writing a very nice series of posts on recent Emacs additions that are worth knowing. His latest is on making a window dedicated. A dedicated window is one that is locked to its current buffer. That means, for instance, that if you have a particular window configuration in place and call some other function, the new function can’t hijack the dedicated window and spoil your configuration. Batsov has an animated Gif that shows this in action.

The notion of a dedicated window has been in Emacs for some time but what’s new is a quick way of dedicating a window. That way is toggle-window-dedicated, which is bound to Ctrl+x w d by default. As shown in Batsov’s Gif, that toggles the dedicated state for the current window on and off.

Sadly, I have Ctrl+x w bound to a function that starts up elfeed. I use that several times a day and have a significant investment in muscle memory so I either have to change the toggle-window-dedicated binding or simply call it directly. Since I doubt I’ll be using it that often, I’ll probably just call it directly. With my fuzzy command completion I need only enter Meta+x tog win to get the desired result.

There’s one other aspect that Batsov mentions but doesn’t explain: strongly dedicated windows. If a window is strongly dedicated, you can’t change the buffer displayed by the window. You can make a window strongly dedicated by specifying the universal argument in the call to toggle-window-dedicated.

If you like to set up a specific window configuration for some of your workflows and you don’t like random commands stepping on it, toggle-window-dedicated is just what you need.

Interesting trick, discovered by mistake:

Dragging and dropping a file into Emacs while in a folder with Dired copies it there, just as Finder would. Did you know that? I didn’t!

A Tags List is an alternative to the Agenda that the user can configure with org-agenda-custom-commands. The list shows subheadings that have a certain tag. You can edit these list items with the same commands used for the item on the standard Agenda View. For example, you can invoke org-agenda-todo (bound to t) while on a tag list item to change its TODO state. However, the display doesn't always reflect the action that was performed. That can mislead the user into thinking the command had no effect.

For example, you can change an item's TODO state to DONE. When you do that for an Agenda item, usually Org Agenda removes the item from the Agenda. However, that doesn't happen to an item on a Tags List. The TODO keyword changes to DONE, but the item remains visible. However, if it's a recurring task, the state will remain at "TODO" as if nothing happened. That's because Org reverts the state back to TODO after advancing the date in accordance with the repeater.

The lack of visual feedback can lead the user to invoke the command a second time. Then the item's deadline (or schedule) will be advanced more than once, skipping the next reminder.

Here's a real world example. Suppose the TODO item is a reminder to pay the rent. It's set up with a +1m repeater so that it shows up monthly. The user pays the rent and marks it done. The deadline advances to the next month, which is fine. But nothing changes on the Tags List -- the TODO item is still there. Then the user becomes distracted¹ and forgets that "Pay the Rent" was marked DONE, and so the user marks it DONE again. The deadline advances another month, so the reminder for next month's rent never appears.

A slightly better approach is to filter the Agenda View with org-agenda-tag-filter-preset to avoid generating a Tags List. But I found it tricky to use. I couldn't figure out how to use Customize to include it in one of my org-agenda-custom-commands. Instead I edited my init file to change the custom command from:

;; Dangerous!
("Bm" "Bills for the Month (Recurring)" agenda "Bills"
 ((org-agenda-span 'month) (org-agenda-files '("~/bills.org"))))

…to:

;; Less Dangerous
("Bm" "Bills for the Month (Recurring)" agenda ""
 ((org-agenda-tag-filter-preset '("+bills") nil)))

This is a better approach because when marked DONE, an item's TODO status changes to DONE even if it had a repeater, so the user has a clear indication of its status. Unfortunately, this isn't ideal because the date of the deadline doesn't advance according to the repeater; it's necessary to edit the org file manually to change DONE to TODO and then mark it DONE using org-todo² (which enacts the repeater).

If there were such a thing as org-agenda-todo-before-hook, I'd add a call to org-agenda-check-type and abort if it returned anything other than agenda.

Another approach is to disable org-agenda-todo. I tried it. It works, but it's annoying.

My eventual solution was to modify org-agenda-todo in org-agenda.el³ so that it aborts unless the item is an agenda item. The only required change was adding (org-agenda-check-type nil 'agenda) to the begining of the function. Now when I invoke org-agenda-todo on an item in a Tags List, Emacs responds with "Not allowed in `tags'-type agenda buffer or component." Perfect!

(defun org-agenda-todo (&optional arg)
  "Cycle TODO state of line at point, also in Org file.
This changes the line at point, all other lines in the agenda referring to
the same tree node, and the headline of the tree node in the Org file."
  (interactive "P")
  (org-agenda-check-no-diary)
  (org-agenda-check-type t 'agenda) ;; add this!
  (org-agenda-maybe-loop
   #'org-agenda-todo arg nil nil
   (let* ((col (current-column))

Although this is only a one-line change, it's a good example of why I appreciate Free and Open Source Software (FOSS). Users have the freedom to choose how it operates! In a sense, we're all owners and collaborators. And even if you're not able to make the change on your own, you're part of a supportive community that will help you.

Is there something that irks you about Emacs? Have you asked for help on how to change it? Let's do that now!

¹ The hypothetical user is me.

² org-todo operates within org files; org-agenda-todo works from within the Agenda.

³ When modifying an Emacs source file, save a backup of the original and rename the corresponding .elc file. Otherwise Emacs will continue loading the compiled version, making it appear that your changes had no effect. Recompile the modified source if desired.

The why

Regular readers know the pattern by now: if something can be done in Emacs, I will eventually do it in Emacs.

Then why not have my iMessages living here as well?!

So I made timu-imessage – a package to read and send iMessages without leaving Emacs. Well… I told Claude Code what I wanted.

What does it do?

• A chat list with your entire message history, unread counts included.
• Conversation buffers that update live as messages arrive – with tapbacks, threaded replies and inline images.
• Full-text search across every message you ever received, in milliseconds.
• Sending from the minibuffer.
• Org integration: a single key captures the message at point with a link back to it.

It reads straight from the Messages database on your Mac. Sending goes through a small companion Shortcut.

Installation

Clone the repository, then:

(use-package timu-imessage
  :load-path "/path/to/emacs-imessage"
  :commands (timu-imessage timu-imessage-search timu-imessage-doctor)
  :bind (("C-c i i" . timu-imessage) ;; or whatever keybindings you prefer
         ("C-c i s" . timu-imessage-search)))

You need Emacs 29.1+ with built-in SQLite, Full Disk Access for Emacs and the companion Shortcut from the shortcuts/ directory in the repo – double-click, confirm, done.

My favorite part: M-x timu-imessage-doctor checks all of the above for you and even opens the right System Settings pane for anything missing.

Usage

M-x timu-imessage opens the chat list, RET opens the conversation at point. In a conversation:

Bottom line

Does this thing really need to exist? No. Is it really cool, that I can prompt this in a few hours combined though? Damn right it is.

I have been using this for my messages for a little while now and it works like a charm.

Bonus: This beeing on a Mac and pulling from the Messages.app db, I get SMSs in here as well.

Feel free to give it a spin and give me some pointers!

It all started with a routine task. I use GitHub issues for all of my public-facing projects but my preference is keeping track of things in Org Agenda. To reconcile the two, I would manually copy over the GitHub issue to an Org file, typically the title and description, like an animal.

Despite this separation, the duplicated issue allowed me to treat it as a scratchpad for anything I could express in Org. In this way, I used the duplicated issue in Org as both a dedicated area to take notes and a “staging” area to compose follow-up comments that I’d want to share in the public facing issue.

I manually copied for far longer than I care to admit. Repeat a task enough times in Emacs and the inevitable thought arises: “I should automate this.”

This post recounts how I automated this task and in doing so, highlight the malleable computing capabilities of Emacs. It should also be considered a follow-up to my earlier post “In Emacs, Everything Looks Like a Service”.

Requirements

An essential question to ask in any automation exercise is “What do I want done?”

I wanted to be able to:

• Easily copy a GitHub issue (title, description, some metadata) as an Org task that can be tracked in an Agenda view.
• Work primarily from Emacs to minimize the context switching between it and a web browser.
• Express my thoughts in Org syntax.
• Create a new GitHub issue.
• Avoid dealing with GitHub authentication.
• From Emacs, open a GitHub issue in a web browser.

Another essential question to ask is “What do I not want to do?”

• Install or write a full-featured GitHub client.
  • Worry too much about synchronization logic between local (Emacs) and server (GitHub) state.
• Spend a lot of time on this (ideally have something working in a day, no more than a week).

Specification

With the above requirements in place, the next question is “how do I build this?”

For this particular exercise, I decided to leverage my existing install of the GitHub command line utility gh. The benefits for this are:

• GitHub authentication is delegated to gh; no need to mess with it directly from Emacs.

• Emacs can treat gh as a REST service to GitHub as shown in the diagram below

  

To flesh out the rest of our tool, we can leverage using different Elisp packages and programs:

• For the user interface, the Transient and Variable Pitch Table (vtable) packages are used for menus and display respectively.

• For Org to Markdown translation, ox-gfm will be used.

• For Markdown to Org translation, Pandoc will be used.

• Elisp native JSON support will be used for deserializing the JSON responses from gh.

Implementation

The implementation of the above is published as the package gah with its source available for examination in the file gah.el. Of note is the function gah-request-issues which does the work of retrieving GitHub issues via gh as shown below.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

(defun gah-request-issues (repo)
  "Request issues for REPO."
  (let* ((fields gah-browser-fields)
         (cmd-list (list "gh"
                         "--repo"
                         (format "'%s'" repo)
                         "issue"
                         "list"
                         "--limit"
                         (number-to-string gah-request-issue-count)
                         "--json"
                         (string-join fields ","))))

    (json-parse-string (shell-command-to-string
                        (string-join cmd-list " "))
                       :null-object nil)))

Consider the high degree of abstraction provided by gah-request-issues:

• The list cmd-list forms the request (in this case, the arguments to invoke gh with).
• shell-command-to-string dispatches the request to gh.
• The returned JSON response is handled by json-parse-string to deserialize the JSON into an Elisp hash table.
• All of the above is accomplished in less than 20 lines of code.

The returned hash table result is subsequently processed to populate a vtable as shown below. From the vtable, the user can navigate the list of issues with an ancillary window updated to show the details of a selected issue.

Multiple commands and functions working with said hash-table were made to satisfy the requirements above. They are accessible via the Transient menu shown below:

Malleable Computing Observations

As Elisp is a dynamic programming language, the above function (or some variant of it) can be coded and evaluated within a running Emacs session. In Emacs it is routine practice to prototype code behavior without the need to restart it. Contrast this with tools that are built with a static language and have no extensibility, where the edit-compile-debug development cycle must be applied to exercise behavior, provided the source code is available.

Emacs provides numerous ways to edit and evaluate Elisp code, among them:

• A scratch buffer
• An Elisp file
• An Org source block
• IELM REPL
• Eshell
• eval-expression (M-:)

Because there is no isolation between loaded Elisp code, all of it can be orchestrated together in an improvised fashion. Any program accessible to Emacs via shell further adds to this mix.

Provided high abstractions, the amount of code needed to be written for desired behavior can be small. At the time of this writing, gah.el has approximately 400 lines of code has been measured by cloc:

1
2
3
4
5
6

github.com/AlDanial/cloc v 2.08  T=0.01 s (146.4 files/s, 76550.1 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Lisp                             1             93             38            392
-------------------------------------------------------------------------------

It took me about 2½ hours to build the basic behavior I wanted (request issues from GitHub, then display) and the rest of the day to cover all the original requirements. Everything after that was just refactoring.

Motivated readers are invited to examine gah.el to understand its details. At this point though, I’d like to take the opportunity to muse on software engineering and malleable computing.

Software Scope - Some Percentage Anecdotes

The 90/90 rule posits that “The first 90 percent of the code accounts for the first 90 percent of the development time. The remaining 10 percent of the code accounts for the other 90 percent of the development time”. Closely related is the Pareto principle (aka the 80/20 rule) as applied (or more mis-applied) to software development: only 20% of your features will be actually used by 80% of your users.

From control theory there is the concept of bounded input, bounded output (BIBO) stability. If the system is BIBO stable, then whatever input that is bounded will have an output that is also bounded.

Coupling these ideas together, if the functionality you want (BIBO stability) is within that 20% deliverable then you are positioned to get a desired result faster.

Unfortunately, this observation is not available for many producers shipping a tool that must satisfy a large audience. In Sinofsky’s post “What is Software Bloat, Really?”, he describes the product definition issues with shipping Microsoft Office, particularly with feature set. From their user research, they were led to this finding: “… the data was entirely conclusive: Most of Office was used. But no one person used the entire product.”

When discussing product definition, it is helpful to distinguish two informal dynamics: supply and demand.

With software that is only supply-provided (such as the case with MS Office), the weight of product definition is shouldered by the producer. If the producer wants to serve a vast audience, it is likely their feature set and corresponding development scope will be vast as well. On the demand-side, consumers can make requests for new features, but their prioritization is controlled by the producer. In this situation, the roles of producer and consumer are strongly delineated.

Malleable software, where users have agency to adapt and reshape their digital tools, offers a different possibility: producers provide the building blocks and let consumers make their own tools. In this, both existing code and programs are recombined to make new behavior. Stated another way, malleable software takes advantage of combinatorial explosion in that a desired subset of behavior can likely be found within the state space of combining existing libraries (in this case Elisp) with different programs. With malleable software, the roles between producer and consumer are less delineated. A consumer building a new tool out of malleable building blocks now must shoulder the weight of product definition.

Build for 1 or N

The scope to build for 1 vs N can be an order of magnitude with the kicker that N need not be large. Choosing to write code for another person (N=2) escalates concerns that could otherwise be brushed aside:

• Error handling
• Code maintainability
  • Modularity/Reuse
• Documentation
• Unit and Integration Testing
• Packaging
• Distribution

Both a blessing and curse of malleable techniques is that they allow for “just good enough” capability. Malleable techniques encourage building for 1 as reaching a state of “it works for me” is often sufficient to declare victory.

For most software that is only supply-provided, building for N is a requirement. For most software built with malleable techniques, building for N is a choice.

Malleable Software and User Agency

Returning back to gah, the benefits of building for 1 are evident:

From within Emacs I can now easily:

• Peruse GitHub issues for a specified repository.
• Copy a GitHub issue into a Org file.
• Create a new GitHub issue using Org syntax.
• Open a GitHub issue in a web browser.

Implementing gah in Emacs was straightforward as I could leverage Elisp packages (both built-in and 3rd party) and external applications (gh, pandoc) to build it. Within a day I had a tool that did what I wanted. I did not have to ask for permission nor required privileged materials (source code) to build gah. With Emacs, I could just do it. Such individual empowerment advanced by malleable techniques is liberating in contrast to working with siloed applications with little to no integration between them.

Closing Thoughts

This post muses about the malleable computing capabilities provided by Emacs, showing by concrete example (gah.el) how new behavior can be created leveraging both code and program reuse in an improvised fashion. With measured expectations (requirements, feature set, audience), malleable techniques allow for building tools that would otherwise be infeasible without it.

Links

• https://github.com/kickingvegas/gah
• “What Is Software Bloat, Really?”, Steven Sinofsky.

Addendum 2026-07-23 11:30 PST

Doh. Because this started out as a personal project, I did not do any due diligence on the project naming. Turns out the name fj is already used as a client for Forgejo.

As such I've renamed my project to gah and amended this post accordingly. My apologies for any slights this has caused.