the DyerDwelling!

Highlighting git changes in a buffer with diff-hl

2026-04-21T08:00:00+0100

Lately I’ve found myself wanting a better, more fine-grained view of what’s going on in a file under git. For some reason, my default workflow has been to keep jumping in and out of project-vc-dir to check changes. It gets the job done, but honestly it’s a bit of a hassle.

What I really wanted was something right there in the buffer. Not a full-on inline diff (that gets messy fast I would guess), but just a small visual hint, something that lets me "see" what’s changed without breaking my flow.

Turns out, that’s exactly what diff-hl does

It’s super lightweight and just highlights changes in the fringe. Nothing flashy but just enough to keep you aware of what you’ve modified. Once you start using it, it feels kind of weird not having it.

One thing I really like is how nicely it plays with the built-in VC tools, move to a buffer position that aligns with a highlighted change, hit C-x v = and it jumps straight to the relevant hunk in the diff. No friction, no extra thinking, it just works.

Here’s the setup I’m using:

(use-package diff-hl
  :ensure t
  :hook (dired-mode . diff-hl-dired-mode)
  :config
  (global-diff-hl-mode 1)
  (diff-hl-flydiff-mode 1)
  (unless (display-graphic-p)
    (diff-hl-margin-mode 1)))

By default, diff-hl-mode only updates when you save the file. That’s okay, but enabling diff-hl-flydiff-mode makes it update as you type, which feels more intuitive.

Oh, and that dired-mode hook? That turns on diff-hl-dired-mode, which gives you a quick visual overview of changed files right inside dired. It’s one of those small touches that ends up being surprisingly useful.

If you’ve got repeat-mode enabled, you can also hop through changes with C-x v ] and C-x v [, which makes reviewing edits really smooth.

I am enjoying diff-hl and is quietly improving my workflow without getting in my way. Simple, fast, and just really nice to have.

Emacs-DIYer: A Built-in dired-collapse Replacement

2026-04-15T19:20:00+0100

I have been slowly chipping away at my Emacs-DIYer project, which is basically my ongoing experiment in rebuilding popular Emacs packages using only what ships with Emacs itself, no external dependencies, no MELPA, just the built-in pieces bolted together in a literate README.org that tangles to init.el. The latest addition is a DIY version of dired-collapse from the dired-hacks family, which is one of those packages I did not realise I leaned on until I started browsing a deeply-nested Java project and felt the absence immediately.

If you have ever opened a dired buffer on something like a Maven project, or node_modules, or a freshly generated resource bundle, you will know the pain, src/ contains a single main/ which contains a single java/ which contains a single com/ which contains a single example/, and you are pressing RET four times just to get to anything interesting. The dired-collapse minor mode from dired-hacks solves this beautifully, it squashes that whole single-child chain into one dired line so src/main/java/com/example/ shows up as a single row and one RET drops you straight into the deepest directory.

So, as always with the Emacs-DIYer project, I wondered, can I implement this in a few elisp defuns?

Right, so what is the plan?, dired already draws a nice listing with permissions, sizes, dates and filenames, all I really need to do is walk each line, look at the directory, figure out the deepest single-child descendant, and then rewrite the filename column in place with the collapsed path. The trick, and this is the bit that took me a minute to convince myself of, is that dired uses a dired-filename text property to know where the filename lives on the line, and dired-get-filename happily accepts relative paths containing slashes. So if I can rewrite the text and reapply the property, everything else, RET, marking, copying, should just work without me having to touch the rest of dired at all!

First function, my/dired-collapse--deepest, which just walks the directory chain as long as each directory contains exactly one accessible child directory. I added a 100-iteration guard so a pathological symlink cycle cannot wedge the whole thing, which, you know, future me might thank present me for:

(defun my/dired-collapse--deepest (dir)
  "Return the deepest single-child descendant directory of DIR.
Walks the directory chain as long as each directory contains exactly
one entry which is itself an accessible directory.  Stops after 100
iterations to guard against symlink cycles."
  (let ((current dir)
        (depth 0))
    (catch 'done
      (while (< depth 100)
        (let ((entries (condition-case nil
                           (directory-files current t
                                            directory-files-no-dot-files-regexp
                                            t)
                         (error nil))))
          (if (and entries
                   (null (cdr entries))
                   (file-directory-p (car entries))
                   (file-accessible-directory-p (car entries)))
              (setq current (car entries)
                    depth (1+ depth))
            (throw 'done current)))))
    current))

directory-files-no-dot-files-regexp is one of those lovely little built-in constants I keep forgetting exists, it filters out . and .. but keeps dotfiles, which is exactly what you want if you are deciding whether a directory is truly single-child.

Second function does the actual buffer surgery, my/dired-collapse iterates each dired line, grabs the filename with dired-get-filename, asks the walker how deep the chain goes, and if there is anything to collapse it replaces the displayed filename with the collapsed relative path:

(defun my/dired-collapse ()
  "Collapse single-child directory chains in the current dired buffer.
A DIY replacement for `dired-collapse-mode' from the dired-hacks
package.  Rewrites the filename portion of each line in place and
reapplies the `dired-filename' text property so that standard dired
navigation still resolves to the deepest directory."
  (when (derived-mode-p 'dired-mode)
    (let ((inhibit-read-only t))
      (save-excursion
        (goto-char (point-min))
        (while (not (eobp))
          (condition-case nil
              (let ((file (dired-get-filename nil t)))
                (when (and file
                           (file-directory-p file)
                           (not (member (file-name-nondirectory
                                         (directory-file-name file))
                                        '("." "..")))
                           (file-accessible-directory-p file))
                  (let ((deepest (my/dired-collapse--deepest file)))
                    (unless (string= deepest file)
                      (when (dired-move-to-filename)
                        (let* ((start (point))
                               (end (dired-move-to-end-of-filename t))
                               (displayed (buffer-substring-no-properties
                                           start end))
                               (suffix (substring deepest
                                                  (1+ (length file))))
                               (new (concat displayed "/" suffix)))
                          (delete-region start end)
                          (goto-char start)
                          (insert (propertize new
                                              'face 'dired-directory
                                              'mouse-face 'highlight
                                              'dired-filename t))))))))
            (error nil))
          (forward-line))))))

The key bit is the propertize call at the end, the new filename text has to carry dired-filename t so that dired-get-filename picks it up, and dired-directory on face keeps the collapsed entry looking the same as a normal directory line. Because dired-get-filename will happily glue a relative path like main/java/com/example onto the dired buffer's directory, pressing RET on a collapsed line takes you straight to src/main/java/com/example with no extra work from me.

A while back I added a little unicode icon overlay thing to dired (my/dired-add-icons, which puts a little symbol in front of each filename via a zero-length overlay), and I did not want the collapse to fight with it. The icons hook into dired-after-readin-hook as well, so I just gave collapse a negative depth when attaching its hook:

(add-hook 'dired-after-readin-hook #'my/dired-collapse -50)

Lower depth runs earlier, so collapse rewrites the line first, then the icon overlay attaches to the final collapsed filename position. Without this, the icons would happily sit in front of a stub directory that was about to be rewritten, which is, well, fine I suppose, but it felt tidier to have them anchor on the post-collapse text.

Before, a typical Maven project root might look something like this:

drwxr-xr-x 3 jdyer users 4096 Apr  9 08:12 ▶ src
drwxr-xr-x 2 jdyer users 4096 Apr  9 08:11 ▶ target
-rw-r--r-- 1 jdyer users  812 Apr  9 08:10 ◦ pom.xml

After collapse kicks in:

drwxr-xr-x 3 jdyer users 4096 Apr  9 08:12 ▶ src/main/java/com/example
drwxr-xr-x 2 jdyer users 4096 Apr  9 08:11 ▶ target
-rw-r--r-- 1 jdyer users  812 Apr  9 08:10 ◦ pom.xml

One RET and you are in com/example, which is where all the actual code lives anyway. Marking, copying, deleting, renaming, all of it still behaves because the dired-filename text property points at the real deepest path.

One thing that initially bit me, is navigating out of a collapsed chain. If I hit RET on a collapsed src/main/java/com/example line I land in the deepest directory, which is great, but then pressing my usual M-e to go back up was doing the wrong thing. M-e in my config has always been bound to dired-jump, and dired-jump called from inside a dired buffer does a "pop up a level" thing that ended up spawning a fresh dired for com/, bypassing the collapsed view entirely and leaving me staring at a directory I never wanted to see.

My first attempt at fixing this was to put some around-advice on dired-jump so that if an existing dired buffer already had a collapsed line covering the jump target, it would switch to that buffer and land on the collapsed line instead of splicing in a duplicate subdir. It worked, sort of, but dired-jump in general felt a bit janky inside dired, it does a lot of "refresh the buffer and try again" under the hood and the in-dired pop-up-a-level path was always the weak link. So I stepped back and split the two cases apart with a tiny dispatch wrapper:

(defun my/dired-jump-or-up ()
  "If in Dired, go up a directory; otherwise dired-jump for current buffer."
  (interactive)
  (if (derived-mode-p 'dired-mode)
      (dired-up-directory)
    (dired-jump)))

(global-set-key (kbd "M-e") #'my/dired-jump-or-up)

From a file buffer, dired-jump is still exactly the right thing as you want the directory the file is in of course. From inside a dired buffer, dired-up-directory is just a much cleaner operation, it walks up one real level, no refresh, no splicing, nothing weird. But on its own that would lose the collapsed round-trip, so I gave dired-up-directory its own bit of advice that looks for a collapsed-ancestor buffer before falling through to the default behaviour.

(defun my/dired-collapse--find-hit (target-dir)
  "Return (BUFFER . POS) of a dired buffer with a collapsed line covering TARGET-DIR."
  (let ((target (file-name-as-directory (expand-file-name target-dir)))
        hit)
    (dolist (buf (buffer-list))
      (unless hit
        (with-current-buffer buf
          (when (and (derived-mode-p 'dired-mode)
                     (stringp default-directory))
            (let ((buf-dir (file-name-as-directory
                            (expand-file-name default-directory))))
              (when (and (string-prefix-p buf-dir target)
                         (not (string= buf-dir target)))
                (save-excursion
                  (goto-char (point-min))
                  (catch 'found
                    (while (not (eobp))
                      (let ((line-file (ignore-errors
                                         (dired-get-filename nil t))))
                        (when (and line-file
                                   (file-directory-p line-file))
                          (let ((line-dir (file-name-as-directory
                                           (expand-file-name line-file))))
                            (when (string-prefix-p target line-dir)
                              (setq hit (cons buf (point)))
                              (throw 'found nil)))))
                      (forward-line))))))))))
    hit))

The dired-up-directory only fires when the literal parent is not already open as a dired buffer, which keeps normal upward navigation completely unchanged:

(defun my/dired-collapse--up-advice (orig-fn &optional other-window)
  "Around-advice for `dired-up-directory' restoring collapsed round-trip."
  (let* ((dir (and (derived-mode-p 'dired-mode)
                   (stringp default-directory)
                   (expand-file-name default-directory)))
         (up (and dir (file-name-directory (directory-file-name dir))))
         (parent-buf (and up (dired-find-buffer-nocreate up)))
         (hit (and dir (null parent-buf)
                   (my/dired-collapse--find-hit dir))))
    (if hit
        (let ((buf (car hit))
              (pos (cdr hit)))
          (if other-window
              (switch-to-buffer-other-window buf)
            (pop-to-buffer-same-window buf))
          (goto-char pos)
          (dired-move-to-filename))
      (funcall orig-fn other-window))))

(advice-add 'dired-up-directory :around #'my/dired-collapse--up-advice)

If /proj/src/main/java/com/ happens to already exist as a dired buffer, dired-up-directory does its usual thing and just goes there, the up-advice never fires. It is only when the literal parent is absent that the advice kicks in and hands you back to the collapsed ancestor, which I think is the right tradeoff, the advice never surprises you when you were going to get the standard behaviour anyway, it only steps in when the standard behaviour would throw away context you clearly still had in a buffer somewhere.

End result, RET into a collapsed chain drops me deep, M-e walks me back out to the original collapsed line, and none of it requires doing anything clever with dired-jump's "pop up a level" path, which I am increasingly convinced I should not have been using in the first place.

Everything lives in the Emacs-DIYer project on GitHub, in the literate README.org. If you just want the snippet to drop into your own init file, the two functions and the add-hook line above are the whole thing, no require, no use-package, no MELPA, just built-in dired and a bit of buffer shenanigans, and thats it!, phew, and breathe!

Wiring Flymake Diagnostics into a Follow Mode

2026-04-09T06:13:00+0100

Flymake has been quietly sitting in my config for years doing exactly what it says on the tin, squiggly lines under things that are wrong, and I mostly left it alone. But recently I noticed I was doing the same little dance over and over: spot a warning, squint at the modeline counter, run `M-x flymake-show-buffer-diagnostics`, scroll through the list to find the thing I was actually looking at, then flip back. Two windows, zero connection between them.

So I wired it up properly, and while I was in there I gave it a set of keybindings that feel right to my muscle memory.

The obvious bindings for stepping through errors are `M-n` and `M-p`, and most people using flymake bind exactly those. The problem is that in my config `M-n` and `M-p` are already taken, they step through simply-annotate annotations (which is itself a very handy thing and I am not giving it up!). So I shifted a key up and went with the shifted variants: `M-N` for next, `M-P` for previous, and `M-M` to toggle the diagnostics buffer.

(setq flymake-show-diagnostics-at-end-of-line nil)
(with-eval-after-load 'flymake
  (define-key flymake-mode-map (kbd "M-N") #'flymake-goto-next-error)
  (define-key flymake-mode-map (kbd "M-P") #'flymake-goto-prev-error))

With M-M I wanted it to be a bit smarter than just "open the buffer". If it is already visible I want it gone, if it is not I want it up. The standard toggle pattern:

(defun my/flymake--diag-buffer ()
  "Return the visible flymake diagnostics buffer, or nil."
  (seq-some (lambda (b)
              (and (with-current-buffer b
                     (derived-mode-p 'flymake-diagnostics-buffer-mode))
                   (get-buffer-window b)
                   b))
            (buffer-list)))

(defun my/flymake-toggle-diagnostics ()
  "Toggle the flymake diagnostics buffer."
  (interactive)
  (let ((buf (my/flymake--diag-buffer)))
    (if buf
        (quit-window nil (get-buffer-window buf))
      (flymake-show-buffer-diagnostics)
      (my/flymake-sync-diagnostics))))

Now the interesting bit. What I really wanted was a follow mode, something like how the compilation buffer tracks position or how Occur highlights the current hit. When my point lands on an error in the source buffer, the corresponding row in the diagnostics buffer should light up. That way the diagnostics window becomes a live index of where I am rather than a static dump and think in general this is how a lot of other IDEs work.

I tried the lazy route first, turning on hl-line-mode in the diagnostics buffer and calling hl-line-highlight from a post-command-hook in the source buffer. The line lit up once and then refused to move. Nothing I did would shift it. This is because hl-line-highlight is really only designed to be driven from the window whose line is being highlighted, and I was firing it from afar.

Ok, so why not just manage my own overlay:

(defvar my/flymake--sync-overlay nil
  "Overlay used to highlight the current entry in the diagnostics buffer.")

(defun my/flymake-sync-diagnostics ()
  "Highlight the diagnostics buffer entry matching the error at point."
  (when-let* ((buf (my/flymake--diag-buffer))
              (win (get-buffer-window buf))
              (diag (or (car (flymake-diagnostics (point)))
                        (car (flymake-diagnostics (line-beginning-position)
                                                  (line-end-position))))))
    (with-current-buffer buf
      (save-excursion
        (goto-char (point-min))
        (let ((found nil))
          (while (and (not found) (not (eobp)))
            (let ((id (tabulated-list-get-id)))
              (if (and (listp id) (eq (plist-get id :diagnostic) diag))
                  (setq found (point))
                (forward-line 1))))
          (when found
            (unless (overlayp my/flymake--sync-overlay)
              (setq my/flymake--sync-overlay (make-overlay 1 1))
              (overlay-put my/flymake--sync-overlay 'face 'highlight)
              (overlay-put my/flymake--sync-overlay 'priority 100))
            (move-overlay my/flymake--sync-overlay
                          found
                          (min (point-max) (1+ (line-end-position)))
                          buf)
            (set-window-point win found)))))))

My first pass at the walk through the tabulated list did not work. I was comparing (tabulated-list-get-id) directly against the diagnostic returned by flymake-diagnostics using eq, and it was always false, which meant found stayed nil forever and the overlay never moved. A dive into flymake.el revealed why. Each row in the diagnostics buffer stores its ID as a plist, not as the diagnostic itself:

(list :diagnostic diag
      :line line
      :severity ...)

So I need to pluck out :diagnostic before comparing. Obvious in hindsight, as these things always are. With plist-get in place the comparison lines up and the overlay moves exactly where I want it, tracking every navigation command.

The fallback lookup using line-beginning-position and line-end-position is there because flymake-diagnostics (point) only returns something if point is strictly inside the diagnostic span. When I land between errors or on the same line as an error but a few columns off, I still want the diagnostics buffer to track, so I widen the search to the whole line.

Finally, wrap the hook in a minor mode so I can toggle it per buffer and enable it automatically whenever flymake comes up:

(define-minor-mode my/flymake-follow-mode
  "Sync the diagnostics buffer to the error at point."
  :lighter nil
  (if my/flymake-follow-mode
      (add-hook 'post-command-hook #'my/flymake-sync-diagnostics nil t)
    (remove-hook 'post-command-hook #'my/flymake-sync-diagnostics t)))

(add-hook 'flymake-mode-hook #'my/flymake-follow-mode)
(define-key flymake-mode-map (kbd "M-M") #'my/flymake-toggle-diagnostics)

The end result is nice. M-M pops the diagnostics buffer, M-N and M-P walk through the errors, and as I navigate the source the matching row in the diagnostics buffer highlights in step with me. If I close the buffer with another M-M everything goes quiet, and I can still step through with M-N/M-P on their own.

Three little keybindings and twenty lines of elisp, but they turn flymake from a static reporter into something that actually feels connected to where I am in the buffer.

Simply Annotate 0.9.8: Threaded Conversations on Your Code

2026-03-29T09:08:00+0100

I have been busy improving my annotation package! Simply Annotate, the latest release is 0.9.8 and I have put in a bunch of new features, so it felt like a good time to step back and show what the package actually does at this point, because honestly, quite a lot has changed since I last wrote about it.

There are annotation packages out there already, annotate.el being the most established. And they are good! But I kept running into the same friction: I wanted threaded conversations directly on my code, I wanted multiple display styles I could combine, and I wanted the whole thing to be a single file with no dependencies that I could drop onto an air-gapped machine and just use (yup, that again!)

So I built my own!, this is Emacs, after all.

At its core, simply-annotate lets you attach persistent notes to any text file (or Info manual, or dired buffer) without modifying the original content. Annotations are stored in a simple s-expression database at ~/.emacs.d/simply-annotations.el. The entire package is a single elisp file, requires Emacs 28.1+, and has zero external dependencies.

Basic setup is two lines:

(use-package simply-annotate
  :bind-keymap ("C-c a" . simply-annotate-command-map)
  :hook (find-file-hook . simply-annotate-mode))

Or if you prefer require:

(require 'simply-annotate)
(global-set-key (kbd "C-c a") simply-annotate-command-map)
(add-hook 'find-file-hook #'simply-annotate-mode)

Open a file, select some text, press C-c a j, and you have your first annotation. M-n and M-p step through them.

I am always fiddling around with styles, themes, backgrounds e.t.c, so I thought I would build this tinkering enthusiasm into this package. Simply-annotate has five display styles, and you can layer them together:

Highlight – classic background colour on the annotated region
Tint – a subtle background derived from your current theme, lightened by a configurable amount. Adapts automatically when you switch themes
Fringe – a small triangle indicator in the fringe, minimal and unobtrusive
Fringe-bracket – a vertical bracket spanning the full annotated region in the fringe, with a proper top cap, continuous vertical bar, and bottom cap
Subtle – overline and underline bracketing the region, barely visible but there when you need it

You can combine them, so (tint fringe-bracket) gives you a gentle background wash with a clear fringe bracket showing exactly where the annotation spans. Cycle through styles with C-c a '.

Toggle inline display with C-c a / and annotation content appears as box-drawn blocks directly in your buffer:

    some annotated code here
    ▴
┌─ ✎ [OPEN/NORMAL] ──────────────
│ This function needs refactoring.
│ The nested conditionals are hard
│ to follow.
└─────────────────────────────────

New in 0.9.8 is the inline pointer, that little ▴ connecting the box to the annotated text. It is indented to the exact column where the annotation starts, so you always know what the comment refers to.

The fun bit is that the pointer is just a string, and it supports multiline. So you can customise it to whatever shape you like:

;; Simple arrow (default)
(setq simply-annotate-inline-pointer-after "▴")
(setq simply-annotate-inline-pointer-above "▾")

;; Heavy L-bracket (my current favourite)
(setq simply-annotate-inline-pointer-after "┃\n┗━▶")
(setq simply-annotate-inline-pointer-above "┏━▶\n┃")

;; Speech bubble tail
(setq simply-annotate-inline-pointer-after " ╰┐")
(setq simply-annotate-inline-pointer-above " ╰┐")

;; Decorative diamond
(setq simply-annotate-inline-pointer-after "◆")
(setq simply-annotate-inline-pointer-above "◆")

There is a full list of copy-paste options in the Commentary section of the elisp file. Set to nil to disable the pointer entirely.

So I think this is where simply-annotate really differs from other annotation packages. Every annotation is a thread. You can reply to it with C-c a r, and replies can be nested under any comment in the thread, not just the root. It prompts with a hierarchical completing-read menu showing the comment tree.

Each thread has:

Status – open, in-progress, resolved, closed (C-c a s)
Priority – low, normal, high, critical (C-c a p)
Tags – freeform hashtags for organisation (C-c a t)
Author tracking – configurable per-team, per-file, or single-user

The comment tree renders with box-drawing characters so the hierarchy is always clear:

┌— ® [OPEN/NORMAL] —
| james dyer (03/29 08:27)
|   This is the original comment
| L james dyer (03/29 08:27)
| |   here is a reply to this comment
| | L james dyer (@3/29 08:27)
| |     and a reply within a reply!!
| L james dyer (03/29 08:28)
|    Here is another reply to the original comment
└────────────────────

For team collaboration:

(setq simply-annotate-author-list '("Alice" "Bob" "Charlie"))
(setq simply-annotate-prompt-for-author 'threads-only)
(setq simply-annotate-remember-author-per-file t)

Annotations exist at three levels: file (whole-file overview), defun (function or block description), and line (individual elements). There is also an all pseudo-level that shows everything at once, which is the default.

Cycle levels with C-c a ] and C-c a [. The header-line shows counts per level (FILE:2 | DEFUN:5 | LINE:3) with the active level in bold, so you always know where you are, my idea here is to lean towards a coding annotation tool to help teach code or help to remember what has been implemented, so the levels start at a broad file overview and enables you to switch instantly to a more granular level.

The org-mode listing (C-c a l) gives you a foldable, navigable overview of all annotations in the current file, grouped by level. Press n and p to step through headings, RET to jump to source.

New in 0.9.6, the tabular listing (C-c a T) opens a fast, sortable table using tabulated-list-mode (a feature in Emacs I am starting to leverage more). Columns for Level, Line, Status, Priority, Comments, Tags, Author, and the first line of the comment. Click column headers to sort. This is brilliant for getting a quick birds-eye view of all the open items in a file.

For the global view, simply-annotate-show-all gathers annotations from every file in the database into a single org-mode buffer.

Enable simply-annotate-dired-mode and dired buffers show fringe indicators next to files that have annotations. You can see at a glance which files have notes attached:

(add-hook 'dired-mode-hook #'simply-annotate-dired-mode)

Info manuals are also fully supported. Annotations are tracked per-node, and the listing and jump-to-file commands navigate to Info nodes seamlessly.

Press C-c a e and you can edit the raw s-expression data structure of any annotation. Every field is there: thread ID, status, priority, tags, comments with their IDs, parent-IDs, timestamps, and text. C-c C-c to save. This is the escape hatch for when the UI does not quite cover what you need.

Rather than writing paragraphs about how simply-annotate compares to other packages, I have put together a feature matrix in the README. The short version: if you want threaded conversations, multiple combinable display styles, annotation levels, a smart context-aware command, and zero dependencies in a single file, this is the package for you. If you need PDF annotation, go with org-noter or org-remark, they are excellent at that.

(use-package simply-annotate
  :bind-keymap ("C-c a" . simply-annotate-command-map)
  :hook (find-file-hook . simply-annotate-mode))

(with-eval-after-load 'simply-annotate
  (add-hook 'dired-mode-hook #'simply-annotate-dired-mode))

The package is available on GitHub on melpa at simply-annotate or https://github.com/captainflasmr/simply-annotate. There is also an Info manual if you run M-x info and search for simply-annotate.

Ollama Buddy - Seven Lines to Any LLM Provider

2026-03-19T14:50:00+0000

Ever found yourself wanting to add a new AI provider to ollama-buddy? (probably not I would guess 🙂), only to realise you'd need to write an entire Elisp module? Or perhaps you're running a local inference server that speaks the OpenAI API, but can't be bothered with the ceremony of creating a dedicated provider file?

Fair question. That's exactly why I built ollama-buddy-provider-create — a single function that lets you register any LLM provider in seconds, whether it's a cloud API or your own local server.

The traditional approach required a separate .el file for each provider — OpenAI, Claude, Gemini, you name it. Each with its own defcustom variables, configuration boilerplate, and maintenance overhead. It worked, but it felt a bit… heavy-handed for simple use cases.

What if you just wanted to quickly add support for that new local LM Studio instance running on port 1234? Or point ollama-buddy at your company's internal AI gateway? Previously, you'd be looking at copying an existing provider file and modifying dozens of lines. Now? One function call.

The magic (yes, of the elisp kind!) happens in ollama-buddy-provider.el, which provides a generic provider registration system. Instead of requiring separate Elisp files, you can register any provider with a single call:

(ollama-buddy-provider-create
 :name "My Local Server"
 :api-type 'openai
 :endpoint "http://localhost:1234/v1/chat"
 :models-endpoint "http://localhost:1234/v1/models"
 :api-key "your-key-here"
 :prefix "l:")

Three API types are supported out of the box:

openai (default) — Any OpenAI-compatible chat/completions API
claude — Anthropic Claude Messages API
gemini — Google Gemini generateContent API

The system handles all the underlying HTTP requests, error mapping, and session management automatically. Your provider just needs to specify which API flavour it speaks.

Adding a local LM Studio instance:

(ollama-buddy-provider-create
 :name "LM Studio"
 :api-type 'openai
 :endpoint "http://localhost:1234/v1/chat/completions"
 :models-endpoint "http://localhost:1234/v1/models"
 :api-key "not-needed"  ; LM Studio often doesn't require auth
 :model-prefix "l:")

Connecting to OpenRouter (400+ models through one API):

(ollama-buddy-provider-create
 :name "OpenRouter"
 :api-type 'openai
 :endpoint "https://openrouter.ai/api/v1/chat/completions"
 :models-endpoint "https://openrouter.ai/api/v1/models"
 :api-key "your-openrouter-key"
 :model-prefix "r:")

After registration, your new provider appears in the status line and becomes available through the standard model selection interface. The model-prefix (like l: for local or r: for OpenRouter) lets you quickly identify which provider a model belongs to.

The provider system leverages ollama-buddy's shared infrastructure in ollama-buddy-remote.el, which extracts common functionality like request handling, error mapping, and response processing. This means your custom provider gets the same robust error handling as the built-in ones:

Proper HTTP status code mapping (rate limits, timeouts, authentication errors)
Async request support for non-blocking UI
Automatic model listing and caching
Integration with the existing session and conversation system

When you call ollama-buddy-provider-create, it registers your provider with the core system, making it available to all the usual entry points: the transient menu, model selection, and conversation buffers.

This approach is perfect for:

Local inference servers (LM Studio, llama.cpp, vLLM, Ollama's own OpenAI-compat layer)
Company/internal AI gateways
Quick experiments with new APIs

The beauty ojf this system is that it makes ollama-buddy genuinely extensible without requiring deep knowledge of its internals. Want to add support for that new AI service that launched yesterday? You can probably do it in five lines of configuration rather than fifty.

Next up I think this will be the big one, adding tooling for those external providers!!!

Ollama Buddy - In-Buffer LLM Streaming

2026-03-12T11:09:00+0000

There is now an in-buffer replace feature in ollama-buddy, so now an ollama response can work directly on your text, streaming the replacement in real-time, and giving you a simple accept/reject choice!, I have also added an smerge diff inline if desired to show the differences and give the user the ability to accept or reject

Here is how it works : https://www.youtube.com/watch?v=Po7Wqpk0sqY

The feature is tucked away in the transient menu. Here's the workflow:

Toggle it on via C-c O → Actions → W, or run M-x ollama-buddy-toggle-in-buffer-replace
A small ✎ indicator appears in your header line, confirming the mode is active
Select a region of text you want rewritten
Invoke a command from the role menu; for example, C-c o then pick your rewrite command
Watch as the AI streams the replacement directly into your buffer

It is also worth noting that each custom menu can be defined with a :destination option, for either in-buffer or chat, so the global in-buffer replace doesn't need to be selected, and the custom transient menu can be tailored for each command. For example, in the default custom menu, refactor code and proofread have the destination of in-buffer set, but actions like git commit message or describe code will fall back to the global option, which by default is chat, which is probably what you would want for these options.

During streaming, you'll see a dimmed, italic [Rewriting...] placeholder where your selection was. The new text then flows in with a highlight overlay.

Once the stream finishes, you're dropped into a minor mode with two options:

C-c C-c → accept the changes (keep new text, clear highlighting)
C-c C-k → reject and restore your original text

The mode line helpfully shows [Rewrite?] while you're deciding. It's a bit like ediff but for AI-generated changes and uses smerge-mode.

What if the AI starts going off the rails halfway through? No problem. Press C-c C-k at any point during streaming and the network process stops immediately, restoring your original selection. No waiting for it to finish rambling!

Press C-c d and the original text gets inserted below the new text in the same buffer. Word-level differences are highlighted using smerge-refine-regions, so you can see exactly what changed at a glance.

Green overlays mark added or modified words. Red strikethrough overlays show what was removed. It's proper granular diffing, not just a before-and-after comparison.

This workflow is particularly useful for:

Refactoring code blocks you've already written
Rephrasing documentation or prose that feels clunky
Adjusting tone without losing your core message
Quick grammar and style improvements

It's less about "write this for me from scratch" and more "help me iterate on what I've already got."

For best results, I've found that smaller, focused selections work better than trying to rewrite entire files in one go. The AI has more context to work with, and you can make more granular decisions about what to keep.

Next up is probably some more polish on the diff highlighting, or perhaps exploring how this could work with multi-file projects. But for now, again I think this implementation is good enough.

Photos Evie 2026-03-10

2026-03-10T09:10:00+0000

The kitchen chair

Ollama Buddy - Web Search Integration

2026-03-04T09:34:00+0000

One of the fundamental limitations of local LLMs is their knowledge cutoff - they don't know about anything that happened after their training data ended. The new web search integration in ollama-buddy solves this by fetching current information from the web and injecting it into your conversation context. Ollama has a specific API web search section, so it has now been activated!

Here is a demonstration:

https://www.youtube.com/watch?v=05VzAajH404

The web search feature implements a multi-stage pipeline that transforms search queries into clean, LLM-friendly context, your search query is sent to Ollama's Web Search API, the API returns structured search results with URLs and snippets.

I have decided that each URL by default is fetched and processed through Emacs' built-in eww and shr HTML rendering, but this can of course be configured, set ollama-buddy-web-search-content-source to control how content is retrieved:

`eww' (default): Fetch each URL and render through eww/shr for clean text
`api': Use content returned directly from Ollama API (faster, less refined)

The shr (Simple HTML Renderer) library does an excellent job of converting HTML to readable plain text, stripping ads, navigation, and other noise, so I thought why not just use this rather than the return results from the ollama API, as they didn't seem to be particularly accurate.

The cleaned text is formatted with org headings showing the source URL and attached to your conversation context, so when you send your next prompt, the search results are automatically included in the context. The LLM can now reason about current information as if it had this knowledge all along.

There are multiple ways to search; firstly, is inline @search() syntax in your prompts (gradually expanding the inline prompting language!), so for example:

What are the key improvements in @search(Emacs 31 new features)?

Compare @search(Rust async programming) with @search(Go concurrency model)

ollama-buddy automatically detects these markers, executes the searches, attaches the results, and then sends your prompt, so you can carry out multiple searches.

You can also manual Search and Attach, Use C-c / a (or M-x ollama-buddy-web-search-attach)

The search executes, results are attached to your session, and the ♁1 indicator appears in the header line and the results can be viewed from the attachments menu, so for example would display something like:

* Web Searches (1)
** latest Emacs 31 features
*** 1. Hide Minor Modes in the Modeline in Emacs 31
*** 2. New Window Commands For Emacs 31
*** 3. Latest version of Emacs (GNU Emacs FAQ)
*** 4. bug#74145: 31.0.50; Default lexical-binding to t
*** 5. New in Emacs 30 (GNU Emacs FAQ)

with each header foldable, containing the actual search results.

There is a little configuration required to go through the ollama API, first, get an API key from https://ollama.com/settings/keys (it's free). Then configure:

(use-package ollama-buddy
  :bind
  ("C-c o" . ollama-buddy-role-transient-menu)
  ("C-c O" . ollama-buddy-transient-menu-wrapper)
  :custom
  ;; Required: Your Ollama web search API key
  (ollama-buddy-web-search-api-key "your-api-key-here"))

For clarification, the content source options are as follows:

The ollama-buddy-web-search-content-source variable controls how content is retrieved:

eww (default, recommended)

Fetches each URL and renders HTML through Emacs' eww/shr. Produces cleaner, more complete content but requires additional HTTP requests.

Pros:

Much cleaner text extraction
Full page content, not just snippets
Removes ads, navigation, clutter
Works with any website

Cons:

Slightly slower (additional HTTP requests)
Requires network access for each URL

api (experimental)

Uses content returned directly from the Ollama API without fetching individual URLs. Faster but content quality depends on what the API provides.

Pros:

Faster (single API call)
Less network traffic

Cons:

Content may be truncated
Quality varies by source
May miss important context

I strongly recommend sticking with eww - the quality difference is substantial.

By default, web search fetches up to 5 URLs with 2000 characters per result. This provides rich context without overwhelming the LLM's context window.

For longer research sessions, you can adjust:

(setq ollama-buddy-web-search-max-results 10)      ;; More sources
(setq ollama-buddy-web-search-snippet-length 5000) ;; Longer excerpts

Be mindful of your LLM's context window limits. With 5 results at 2000 chars each, you're adding ~10K characters to your context.

The web search integration fundamentally expands what your local LLMs can do. They're no longer limited to their training data - they can reach out, fetch current information, and reason about it just like they would with any other context, so hopefully this will now make ollama-buddy a little more useful

Ollama Buddy v2.5 - RAG (Retrieval-Augmented Generation) Support

2026-02-24T12:10:00+0000

One of the things that has always slightly bothered me about chatting with a local LLM is that it only knows what it was trained on (although I suppose most LLMs are like that) . Ask it about your own codebase, your org notes, your project docs - and it's just guessing. Well, not anymore! Ollama Buddy now ships with proper Retrieval Augmented Generation support built-in

What even is RAG?

If you haven't come across the term before, the basic idea is simple. Instead of asking the LLM a question cold, you first go off and find the most relevant bits of text from your own documents, then you hand those bits to the LLM along with your question. The LLM now has actual context to work with rather than just vibes. The "retrieval" part is done using vector embeddings - each chunk of your documents gets turned into a mathematical representation, and at query time your question gets the same treatment. Chunks that are mathematically "close" to your question are the ones that get retrieved.

In this case, I have worked to keep the whole pipeline inside Emacs; it talks to Ollama directly to contact an embedding model, which then returns the required information. I have tried to make this as Emacs Org-friendly as possible by storing the embedding information in Org files.

Getting started

You'll need an embedding model pulled alongside your chat model. The default is nomic-embed-text which is a solid general-purpose choice:

ollama pull nomic-embed-text

or just do it within ollama-buddy from the Model Management page.

Indexing your documents

The main entry point is M-x ollama-buddy-rag-index-directory. Point it at a directory and it will crawl through, chunk everything up, generate embeddings for each chunk, and save an index file. The first time you run this it can take a while depending on how much content you have and how fast your machine is - subsequent updates are much quicker as it only processes changed files.

Supported file types (and I even managed to get pdf text extraction working!):

Emacs Lisp (.el)
Python, JavaScript, TypeScript, Go, Rust, C/C++, Java, Ruby - basically most languages
Org-mode and Markdown
Plain text
PDF files (if you have pdftotext from poppler-utils installed)
YAML, TOML, JSON, HTML, CSS

Files over 1MB are skipped (configurable), and the usual suspects like .git, node_modules, __pycache__ are excluded automatically.

The index gets saved into ~/.emacs.d/ollama-buddy/rag-indexes/ as a .rag file named after the directory. You can see what you've got with M-x ollama-buddy-rag-list-indexes.

The chunking strategy

One thing I'm quite happy with here is the chunking. Rather than just splitting on a fixed character count, documents are split into overlapping word-based chunks. The defaults are:

(setq ollama-buddy-rag-chunk-size 400)    ; ~500 tokens per chunk
(setq ollama-buddy-rag-chunk-overlap 50)  ; 50-word overlap between chunks

The overlap is important - it means a piece of information that sits right at a chunk boundary doesn't get lost. Each chunk also tracks its source file and line numbers, so you can see exactly where a result came from.

Searching and attaching context

Once you have an index, there are two main ways to use it:

M-x ollama-buddy-rag-search - searches and displays the results in a dedicated buffer so you can read through them
M-x ollama-buddy-rag-attach - searches and attaches the results directly to your chat context

The second one is the useful one for day-to-day work. After running it, your next chat message will automatically include the retrieved document chunks as context. The status line shows ♁N (where N is the number of attached searches) so you always know what context is in play. Clear everything with M-x ollama-buddy-clear-attachments or C-c 0.

You can also trigger searches inline using the @rag() syntax directly in your prompt and is something fun I have been working on to include an inline command language of sorts, but more about that in a future post.

The similarity search uses cosine similarity with sensible defaults (hopefully!)

(setq ollama-buddy-rag-top-k 5)                  ; return top 5 matching chunks
(setq ollama-buddy-rag-similarity-threshold 0.3)  ; filter out low-relevance results

Bump top-k if you want more context, lower the threshold if you're not getting enough results.

A practical example

Say you've been working on a large Emacs package and you want the LLM to help you understand something specific. You'd do:

M-x ollama-buddy-rag-index-directory → point at your project directory
Wait for indexing to complete (the chat header-line shows progress)
M-x ollama-buddy-rag-attach → type your search query, e.g. "streaming filter process"
Ask your question in the chat buffer as normal

The LLM now has the relevant source chunks as context and can give you a much more grounded answer than it would cold.

And the important aspect, especially regarding local models which don't often have the huge context sizes often found in online LLMs is that it allows for very efficient context retrieval.

That's pretty much it!

The whole thing is self-contained inside Emacs, no external packages or vector databases, you index once, search as needed, and the LLM gets actual information rather than hallucinating answers about your codebase or anything else that you would want to ingest and it will hopefully make working with local LLMs through ollama noticeably more useful and accurate.

Ollama Buddy v2.0 - LLMs can now call Emacs functions!

2026-02-16T08:56:00+0000

Tool calling has landed in ollama-buddy!, it's originally not something I really thought I would end up doing, but as ollama has provided tool enabled models and an API for this feature then I felt obliged to add it. So now LLMs through ollama can now actually do things inside Emacs rather than just talk about them, my original "do things only in the chat buffer and copy and paste" might have gone right out the window in an effort to fully support the ollama API!

What is Tool Calling?

The basic idea is simple: instead of the model only generating text, it can request to invoke functions. You ask "what files are in my project?", and instead of guessing, the model calls list_directory, gets the real answer, and responds with actual information.

This creates a conversational loop:

You send a prompt
The model decides it needs to call a tool
ollama-buddy executes the tool and feeds the result back
The model generates a response using the real data
Steps 2-4 repeat if more tools are needed

All of this is transparent - you just see the final response in the chat buffer.

The new ollama-buddy-tools.el module ships with 8 built-in tools:

Safe tools (read-only, enabled by default):

read_file - read file contents
list_directory - list directory contents
get_buffer_content - read an Emacs buffer
list_buffers - list open buffers with optional regex filtering
search_buffer - regex search within a buffer
calculate - evaluate math expressions via calc-eval

Unsafe tools (require safe mode off):

write_file - write content to files
execute_shell - run shell commands

Safe mode is on by default, so the model can only read - it can't modify anything unless you explicitly allow it, I think this is quite a nice simple implementation, at the moment I generally have safe mode off but always allowing confirmation for each tool action, but of course you can configure as necessary.

Example Session

With a tool-capable model like qwen3:8b and tools enabled (C-c W):

>> PROMPT: What defuns are defined in ollama-buddy-tools.el?

The model calls search_buffer with a regex pattern, gets the list of function definitions, and gives you a nicely formatted summary. No copy-pasting needed.

Custom Tools

You can register your own tools with ollama-buddy-tools-register:

(ollama-buddy-tools-register
 'my-tool
 "Description of what the tool does"
 '((type . "object")
   (required . ["param1"])
   (properties . ((param1 . ((type . "string")
                              (description . "Parameter description"))))))
 (lambda (args)
   (let ((param1 (alist-get 'param1 args)))
     (format "Result: %s" param1)))
 t)  ; t = safe tool

The registration API takes a name, description, JSON schema for parameters, an implementation function, and a safety flag. The model sees the schema and decides when to call your tool based on the conversation.

A ⚒ symbol now appears next to tool-capable models everywhere - header line, model selector (C-c m), and model management buffer (C-c M). This follows the same pattern as the existing ⊙ vision indicator, so you can see at a glance which models support tools.

That's it. Pull a tool-capable model (qwen3, llama3.1, mistral, etc.) or use an online tool enabled model from ollama and start chatting. Next up is probably some web searching!, as again the ollama API supports this, so you will be able to pull in the latest from the interwebs to augment your prompt definition!

Automatically Syncing Emacs Tab Bar Styling With Your Theme

2026-02-11T18:26:00+0000

If you've ever enabled a new theme and noticed your tab-bar faces stubbornly hanging onto old colours or custom tweaks, I have found often that the tab-bar, tab-bar-tab, and tab-bar-tab-inactive faces don’t always blend cleanly with freshly loaded themes - especially of the older variety (a bit like me) and especially ones that came out before the tab bar was introduced into Emacs.

So how about a simple solution?, Can I implement something, that whenever I load a theme, the tab-bar faces update based on the theme’s default faces to establish a visually pleasant and coherent look?

Yes, yes I can!; the result is a tiny Elisp enhancement that hooks directly into Emacs' theme-loading process.

Firstly however we need to have a method that will reliably pass over the themes default faces to the tab-bar. Here’s the function that realigns the tab-bar styling with your active theme:

(defun selected-window-accent-sync-tab-bar-to-theme ()
  "Synchronize tab-bar faces with the current theme."
  (interactive)
  (let ((default-bg (face-background 'default))
        (default-fg (face-foreground 'default))
        (inactive-fg (face-foreground 'mode-line-inactive)))
    (custom-set-faces
     `(tab-bar ((t (:inherit default :background ,default-bg :foreground ,default-fg))))
     `(tab-bar-tab ((t (:inherit default :background ,default-fg :foreground ,default-bg))))
     `(tab-bar-tab-inactive ((t (:inherit default :background ,default-bg :foreground ,inactive-fg)))))))

This simply rebuilds the key tab-bar faces so they derive their colours from the current theme’s normal face definitions, so any old themes should now not leave the tab bar faces hanging.

Now for the function activation; Emacs 29 introduced enable-theme-functions, a hook that runs every time a theme is enabled - perfect for our use case, but as always I have my eye on older Emacs versions, so lets fall back to a classic approach: advice on load-theme.

Here’s a version‑aware setup that does the right thing automatically:

(if (version<= "29.1" emacs-version)
    ;; Emacs 29.1+ - use the official theme hook
    (add-hook 'enable-theme-functions
              (lambda (_theme)
                (selected-window-accent-sync-tab-bar-to-theme)))
  ;; Older Emacs - fall back to advising load-theme
  (progn
    (defun selected-window-accent-sync-tab-bar-to-theme--after (&rest _)
      (selected-window-accent-sync-tab-bar-to-theme))
    (advice-add 'load-theme :after
                #'selected-window-accent-sync-tab-bar-to-theme--after)))

With this tweak in place, every time you change themes, your tab-bar instantly updates, colours stay consistent, clean, and theme‑accurate without you having to do anything at all! The downside to this of course is that any newer themes that were created after the advent of the tab bar in Emacs will have their tab-bar faces overridden, but for me this solution is good enough and gives a pleasant coherent visual tab bar experience.

Yay!, yet another Yak shaved!

Spent a bit of free time polishing ollama-buddy - github Copilot is now onboard!

2026-02-04T10:40:00+0000

I've had a little free time recently (figuring out this baby stuff!) and thought I would spend time revisiting and refining my AI assistant ollama-buddy

I've been playing around with agentic coding and keeping up-to-date on the rapid development of the Emacs AI package landscape and I think I have refined in my own mind my idea of what I would like to see in an Emacs AI assistant.

The headline change regarding the latest release of ollama-buddy is GitHub Copilot integration; the rest of the work is about smoothing the UI and simplifying day-to-day use.

What’s new - the Copilot addition (v1.2)

GitHub Copilot Chat API support via a new file, ollama-buddy-copilot.el, so Copilot models can be used alongside your existing providers.
Authentication uses GitHub’s device flow (OAuth). No API key required: M-x ollama-buddy-copilot-login opens a browser and guides you through secure authentication.
Copilot models are identified with a "p:" prefix (for example, p:gpt-4o). The header line shows a "p" indicator when the Copilot provider is loaded so you always know it’s available.
Copilot access exposes a broad set of models from multiple vendors through the Copilot interface: OpenAI (gpt-4o, gpt-5), Anthropic (claude-sonnet-4, claude-opus-4.5), Google (gemini-2.5-pro), and xAI models.
Quick usage notes:
1. Ensure you have an active GitHub Copilot subscription.
2. Run M-x ollama-buddy-copilot-login.
3. Enter the device code in your browser at github.com/login/device when prompted.
4. Select a Copilot model with C-c m (e.g., p:gpt-4o).
Example config to load Copilot support:

(use-package ollama-buddy
  :bind
  ("C-c o" . ollama-buddy-menu)
  ("C-c O" . ollama-buddy-transient-menu-wrapper)
  :config
  (require 'ollama-buddy-copilot nil t))

Other notable updates in this release series

v1.2.1 (2026-02-02)
- Attachment count indicator on the header line so you get a constant visual reminder that the session has attachments.
v1.1.5 (2026-01-31)
- Global system prompt feature (enabled by default): sets a baseline set of instructions (for example, to prefer plain prose and avoid markdown tables) that is prepended to session-specific system prompts. This helps keep responses consistent across providers and things like malformed markdown tables for example, which seems to be common. There’s a toggle (ollama-buddy-global-system-prompt-enabled) and a quick command to flip it (ollama-buddy-toggle-global-system-prompt), plus a transient-menu entry.
- Consolidated model management: streamlined into a single model management buffer (C-c W) and the welcome screen now points to that buffer for model tasks.
v1.1.4 (2026-01-31)
- Header-line and keybinding cleanup: C-c RET to send prompts (matches gptel, as I feel this seems intuitive), removed a redundant backend indicator, shortened the markdown indicator to "MD", and fixed markdown → org heading conversion to keep structure sane.
v1.1.3 (2026-01-31)
- Chat UX improvements and simplification: added ollama-buddy-auto-scroll (default nil - don’t auto-scroll so you can read while streaming) and ollama-buddy-pulse-response (flashes the response on completion, taking from gptel again, as if there is no autoscrolling it is useful to visually see when the response has completed). Removed the model name coloring feature and related toggles to simplify code and improve org-mode performance.
v1.1.2 (2026-01-30)
- Streamlined welcome screen and model selection, clearer provider indicators in the header line and an improved list of enabled online LLM providers.

Ollama buddy now supports cloud models!

2026-01-28T08:29:00+0000

Having another look at my AI assistant - ollama-buddy, its been a while and it seems ollama has moved on since I started creating this package last year, so I have developed a new roadmap and the first step is to add ollama cloud models!

Here are some references to the project, including a youtube channel where I upload ollama-buddy demonstrations:

https://melpa.org/#/ollama-buddy

https://github.com/captainflasmr/ollama-buddy

Here is the changelog for the cloud model implementation:

<2026-01-28 Wed> 1.1

Added Ollama Cloud Models support

Cloud models (running on ollama.com infrastructure) now work seamlessly
ollama-buddy-cloud-signin to automatically open browser for authentication
Cloud models are proxied through the local Ollama server which handles authentication
Use C-u C-c m or transient menu "Model > Cloud" to select cloud models
Status line shows ☁ indicator when using a cloud model
Available cloud models include: qwen3-coder:480b-cloud, deepseek-v3.1:671b-cloud, gpt-oss:120b-cloud, minimax-m2.1:cloud, and more

Auto-Populating Weekly Dates in Org-Mode Tables

2026-01-26T10:13:00+0000

Here is just a quick one, I was working with an org-mode table for tracking work weeks and needed to auto-populate a Date column where each row increments by exactly one week. The table structure looked like this:

The first row has a base date (2026-01-05), and I wanted subsequent rows to automatically calculate as weekly increments: 2026-01-12, 2026-01-19, and so on.

Initially, I tried several approaches that seemed logical but encountered #ERROR results and eventually settled on a working solution which is to hardcode the base date directly in the formula:

#+TBLFM: $3='(format-time-string "%Y-%m-%d" (time-add (date-to-time "2026-01-05") (* (- @# 2) 7 24 3600)))

which gave:

and I can now of course extend the table for all the weeks in the year and I don't have to fill in manually any more!

Here's how it works:

(date-to-time "2026-01-05") - Convert the hardcoded base date to Emacs time format
(- @# 2) - Calculate the offset from the base row
(* (- @# 2) 7 24 3600) - Convert the offset to seconds (weeks × days × hours × seconds)
time-add - Add the offset to the base date
format-time-string "%Y-%m-%d" - Format back to ISO date string

Photos Evie 2026-01-23

2026-01-23T11:47:00+0000

Evie in pram

Speed Reading in Emacs: Building an RSVP Reader

2026-01-18T10:30:00+0000

I recently came across a fascinating video titled "How Fast Can You Read? - Speed Reading Challenge" that demonstrated the power of RSVP (Rapid Serial Visual Presentation) for speed reading. The concept is quite nice and simple and I vaguely remember seeing something about it a few years back. Instead of your eyes scanning across lines of text, words are presented one at a time in a fixed position. This eliminates the mechanical overhead of eye movements and can dramatically increase reading speed!

So, I immediately wondered, could I build this into Emacs?, actually no, firstly I thought, are there any packages for Emacs that can do this?, of course there are!, the spray package from MELPA is a more mature, feature-rich option if you're looking for production-ready RSVP reading in Emacs, and also there is speedread. However, there's something satisfying about having a compact, single-function solution that does exactly what you need, so lets see if I can build one!

RSVP works by displaying words sequentially in the same location on screen. Your eyes remain stationary, focused on a single point, while words flash by at a controlled pace. This technique can boost reading speeds to 300-600+ words per minute, compared to typical reading speeds of 200-300 WPM.

The key innovation is the Optimal Recognition Point (ORP) - typically positioned about one-third into each word. This is where your eye naturally fixates when reading. By aligning each word's ORP at the same screen position, RSVP creates an optimal visual flow.

Given Emacs' extensive text processing capabilities, this sounds something that Emacs could eat for breakfast. Here is what I came up with:

Here is a quick video of my implementation:

and the defun:

(defun rsvp-minibuffer ()
  "Display words from point (or mark to point) in minibuffer using RSVP.
Use f/s for speed, [/] for size, b/n to skip, SPC to pause, q to quit."
  (interactive)
  (let* ((start (if (region-active-p) (region-beginning) (point)))
         (end (if (region-active-p) (region-end) (point-max)))
         (text (buffer-substring-no-properties start end))
         (wpm 350) (font-size 200) (orp-column 20)
         (word-positions '()) (pos 0) (i 0)
         (message-log-max nil))  ; Disable message logging
    ;; Build word positions list
    (dolist (word (split-string text))
      (unless (string-blank-p word)
        (when-let ((word-start (string-match (regexp-quote word) text pos)))
          (push (cons word (+ start word-start)) word-positions)
          (setq pos (+ word-start (length word))))))
    (setq word-positions (nreverse word-positions))
    ;; Display loop
    (while (< i (length word-positions))
      (let* ((word (car (nth i word-positions)))
             (word-pos (cdr (nth i word-positions)))
             (word-len (length word))
             (delay (* (/ 60.0 wpm)
                      (cond ((< word-len 3) 0.8) ((> word-len 8) 1.3) (t 1.0))
                      (if (string-match-p "[.!?]$" word) 1.5 1.0)))
             (orp-pos (/ word-len 3))
             (face-mono `(:height ,font-size :family "monospace"))
             (face-orp `(:foreground "red" :weight normal ,@face-mono))
             (padded-word (concat 
                          (propertize (make-string (max 0 (- orp-column orp-pos)) ?\s) 'face face-mono)
                          (propertize (substring word 0 orp-pos) 'face face-mono)
                          (propertize (substring word orp-pos (1+ orp-pos)) 'face face-orp)
                          (propertize (substring word (1+ orp-pos)) 'face face-mono))))
        (goto-char (+ word-pos word-len))
        (message "%s" padded-word)
        (pcase (read-event nil nil delay)
          (?f (setq wpm (min 1000 (+ wpm 50))))
          (?s (setq wpm (max 50 (- wpm 50))))
          (?\[ (setq font-size (max 100 (- font-size 20))))
          (?\] (setq font-size (min 400 (+ font-size 20))))
          (?b (setq i (max 0 (- i 10))))
          (?n (setq i (min (1- (length word-positions)) (+ i 10))))
          (?\s (read-event (format "%s [PAUSED - WPM: %d]" padded-word wpm)))
          (?q (setq i (length word-positions)))
          (_ (setq i (1+ i))))))))

The function calculates the ORP as one-third through each word and highlights it in red. By padding each word with spaces, the ORP character stays perfectly aligned in the same column, creating that crucial stationary focal point.

To ensure pixel-perfect alignment, the function explicitly sets a monospace font family for all displayed text. Without this, proportional fonts would cause the ORP to drift slightly between words, although I think at times there is a little waddle, but it is good enough.

Also, Not all words are created equal:

Short words (< 3 characters) display 20% faster
Long words (> 8 characters) display 30% slower
Words ending in punctuation (.!?) get 50% more time

This mimics natural reading rhythms where you'd naturally pause at sentence boundaries.

While reading, you can try these keybindings: (which I borrowed off spray)

f / s - Speed up or slow down (±50 WPM)
[ / ] - Decrease or increase font size
b / n - Skip backward or forward by 10 words
SPC - Pause (press any key to resume)
q - Quit
C-g - Emergency quit

Also The function tracks each word's position in the original buffer and updates point as you read. This means:

You can see where you are in the text
When you quit, your cursor is at the last word you read
You can resume reading by running the function again

To use it, simply:

Position your cursor where you want to start reading (or select a region)
Run M-x rsvp-minibuffer
Watch the words flow in the minibuffer

The function works from point to end of buffer, or if you have an active region, it only processes the selected text.

If you're curious about RSVP reading, drop this function into your Emacs config and give it a try. Start at 300-350 WPM and see how it feels. You might be surprised at how much faster you can consume text when your eyes aren't constantly moving across the page.

The code is simple enough to customize - adjust the default WPM, change the ORP colour, modify the timing multipliers, or add new controls. That's the beauty of Emacs, if you can imagine it, you can build it.

A single function ripgrep alternative to rgrep

2026-01-09T09:43:00+0000

For years, rgrep has been the go-to solution for searching codebases in Emacs. It's built-in, reliable, and works everywhere. But it's slow on large projects and uses the aging find and grep commands.

Packages like deadgrep and rg.el provide ripgrep integration, and for years I used deadgrep and really liked it. But what if you could get ripgrep's speed with just a single function you paste into your config?

This post introduces a ~100 line defun that replaces rgrep, no packages, no dependencies, just pure Elisp. It's fast, asynchronous, works offline, and mimics rgrep's familiar interface so it can leverage grep-mode

So, why not just use rgrep?

I think that rgrep has three main limitations:

Firstly, speed. On a project with 10,000+ files, rgrep can take 15-30 seconds. Ripgrep completes the same search in under a second.

Secondly, file ignoring, rgrep requires manually configuring grep-find-ignored-directories or grep-find-ignored-files, I had the following typical configuration for rgrep, but it wasn't as flexible as I would like it to be:

(eval-after-load 'grep
  '(progn
     (dolist (dir '("nas" ".cache" "cache" "elpa" "chromium" ".local/share" "syncthing" ".mozilla" ".local/lib" "Games"))
       (push dir grep-find-ignored-directories))
     (dolist (file '(".cache" "*cache*" "*.iso" "*.xmp" "*.jpg" "*.mp4"))
       (push file grep-find-ignored-files))
     ))

Ripgrep automatically respects an .ignore file. Just create an .ignore file in your project root and list patterns to exclude, this is just a simple text file, universally applied across all searches and any changes can be easily applied.

Thirdly, modern features. Ripgrep includes smart-case search, better regex support, and automatic binary file detection. Of course, there is a context that can be displayed around the found line, but in order to get ripgrep to work with grep-mode, this is not really doable, and it's not something I need anyway.

Here is the complete ripgrep implementation that you can paste directly into your init.el:

(defun my/grep (search-term &optional directory glob)
  "Run ripgrep (rg) with SEARCH-TERM and optionally DIRECTORY and GLOB.
If ripgrep is unavailable, fall back to Emacs's rgrep command. Highlights SEARCH-TERM in results.
By default, only the SEARCH-TERM needs to be provided. If called with a
universal argument, DIRECTORY and GLOB are prompted for as well."
  (interactive
   (let* ((univ-arg current-prefix-arg)
          (default-search-term
           (cond
            ((use-region-p)
             (buffer-substring-no-properties (region-beginning) (region-end)))
            ((thing-at-point 'symbol t))
            ((thing-at-point 'word t))
            (t ""))))
     (list
      (read-string (if (string-empty-p default-search-term)
                       "Search for: "
                     (format "Search for (default `%s`): " default-search-term))
                   nil nil default-search-term)
      (when univ-arg (read-directory-name "Directory: "))
      (when univ-arg (read-string "File pattern (glob, default: ): " nil nil "")))))
  (let* ((directory (expand-file-name (or directory default-directory)))
         (glob (or glob ""))
         (buffer-name "*grep*"))
    (if (executable-find "rg")
        (let ((buffer (get-buffer-create buffer-name)))
          (with-current-buffer buffer
            (setq default-directory directory)
            (let ((inhibit-read-only t))
              (erase-buffer)
              (insert (format "-*- mode: grep; default-directory: \"%s\" -*-\n\n" directory))
              (if (not (string= "" glob))
                  (insert (format "[o] Glob: %s\n\n" glob)))
              (insert "Searching...\n\n"))
            (grep-mode)
            (setq-local my/grep-search-term search-term)
            (setq-local my/grep-directory directory)
            (setq-local my/grep-glob glob))
          
          (pop-to-buffer buffer)
          (goto-char (point-min))
          
          (make-process
           :name "ripgrep"
           :buffer buffer
           :command `("rg" "--color=never" "--max-columns=500" 
                      "--column" "--line-number" "--no-heading" 
                      "--smart-case" "-e" ,search-term
                      "--glob" ,glob ,directory)
           :filter (lambda (proc string)
                     (when (buffer-live-p (process-buffer proc))
                       (with-current-buffer (process-buffer proc)
                         (let ((inhibit-read-only t)
                               (moving (= (point) (process-mark proc))))
                           (setq string (replace-regexp-in-string "[\r\0\x01-\x08\x0B-\x0C\x0E-\x1F]" "" string))
                           ;; Replace full directory path with ./ in the incoming output
                           (setq string (replace-regexp-in-string 
                                         (concat "^" (regexp-quote directory))
                                         "./"
                                         string))
                           (save-excursion
                             (goto-char (process-mark proc))
                             (insert string)
                             (set-marker (process-mark proc) (point)))
                           (if moving (goto-char (process-mark proc)))))))
           :sentinel
           (lambda (proc _event)
             (when (memq (process-status proc) '(exit signal))
               (with-current-buffer (process-buffer proc)
                 (let ((inhibit-read-only t))
                   ;; Remove "Searching..." line
                   (goto-char (point-min))
                   (while (re-search-forward "Searching\\.\\.\\.\n\n" nil t)
                     (replace-match "" nil t))

                   ;; Clean up the output - replace full paths with ./
                   (goto-char (point-min))
                   (forward-line 3)
                   (let ((start-pos (point)))
                     (while (re-search-forward (concat "^" (regexp-quote directory)) nil t)
                       (replace-match "./" t t))
                     
                     ;; Check if any results were found
                     (goto-char start-pos)
                     (when (= (point) (point-max))
                       (insert "No results found.\n")))
                   
                   (goto-char (point-max))
                   (insert "\nRipgrep finished\n")

                   ;; Highlight search terms using grep's match face
                   (goto-char (point-min))
                   (forward-line 3)
                   (save-excursion
                     (while (re-search-forward (regexp-quote search-term) nil t)
                       (put-text-property (match-beginning 0) (match-end 0)
                                          'face 'match)
                       (put-text-property (match-beginning 0) (match-end 0)
                                          'font-lock-face 'match))))
                 
                 ;; Set up keybindings
                 (local-set-key (kbd "D") 
                                (lambda () 
                                  (interactive)
                                  (my/grep my/grep-search-term 
                                           (read-directory-name "New search directory: ")
                                           my/grep-glob)))
                 (local-set-key (kbd "S") 
                                (lambda () 
                                  (interactive)
                                  (my/grep (read-string "New search term: "
                                                        nil nil my/grep-search-term)
                                           my/grep-directory
                                           my/grep-glob)))
                 (local-set-key (kbd "o") 
                                (lambda () 
                                  (interactive)
                                  (my/grep my/grep-search-term
                                           my/grep-directory
                                           (read-string "New glob: "))))
                 (local-set-key (kbd "g") 
                                (lambda () 
                                  (interactive)
                                  (my/grep my/grep-search-term my/grep-directory my/grep-glob)))
                 
                 (goto-char (point-min))
                 (message "ripgrep finished."))))
           )
          (message "ripgrep started..."))
      ;; Fallback to rgrep
      (progn
        (setq default-directory directory)
        (message (format "%s : %s : %s" search-term glob directory))
        (rgrep search-term (if (string= "" glob) "*" glob) directory)))))

That's it. ~100 lines. No dependencies. No packages to manage! (well except ripgrep of course)

Now that I have complete control over this function, I have added further improvements over rgrep, inspired by deadgrep

S - New search term
D - New directory
o - New glob pattern
g - Re-run current search

and a universal argument can be passed through to set these up on the initial grep

I have tried to make the output as similar as possible to rgrep, to be compatible with grep-mode and for familiarity, so it will be something like:

-*- mode: grep; default-directory: "~/project/" -*-

[o] Glob: *.el

./init.el:42:10:(defun my-function ()
./config.el:156:5:  (my-function)
./helpers.el:89:12:;; Helper for my-function

Ripgrep finished

and if a glob is applied it will display the glob pattern.

Its perfect for offline environments, and yes, I'm banging on about this again!, no network, no package manager, no dependencies (except ripgrep of course!)

New package dired-video-thumbnail added to MELPA!

2025-12-31T18:34:00+0000

I have created another package!, this time something that I thought was missing from the mighty Emacs and that is the ability to show video thumbnails in a grid and to be able to filter, sort e.t.c. Basically like an enhanced image-dired. I have been increasingly using image-dired for my image editing and management needs and am always adding little improvements, to such an extent I decided to create a video thumb grid package, enjoy!

Introduction

dired-video-thumbnail is an Emacs package that provides image-dired style thumbnail viewing for video files. It extracts thumbnails from videos using ffmpeg and displays them in a grid layout, allowing you to visually browse and manage video collections directly from Emacs.

Features

Thumbnail grid display - View video thumbnails in a configurable grid layout
Persistent caching - Thumbnails are cached and only regenerated when the source file changes
Async generation - Emacs remains responsive while thumbnails are generated in the background
Dired integration - Marks sync bidirectionally with the associated dired buffer
Visual mark indication - Marked thumbnails display a coloured border (like image-dired)
Dynamic header line - Shows filename, dimensions, duration, and file size for the current video
Click to play - Open videos in your preferred external player
Cross-platform - Works on Linux, macOS, and Windows
Resizable thumbnails - Adjust thumbnail size on the fly
Sorting - Sort videos by name, date, size, or duration
Filtering - Filter videos by name pattern, duration range, or file size
Recursive search - Browse videos across subdirectories with optional auto-recursive mode
Transient menu - Comprehensive command menu accessible via . or C-c .

Whats New

<2025-12-15 Mon> 0.3.0

Added transient menu interface

Introduced a comprehensive transient menu (dired-video-thumbnail-transient) providing quick access to all commands via . or C-c . in the thumbnail buffer. The menu displays current state (sort order, filters, video count, recursive/wrap mode) and organises commands into logical groups: Navigation, Playback, Sorting, Filtering, Marking, Delete, Display, and Other.

<2025-12-15 Mon> 0.2.0

Enhanced package with sorting, filtering, and docs

Added sorting and filtering features to dired-video-thumbnail. Introduced customizable options for sorting and filtering criteria, and implement interactive commands for toggling these settings. Included comprehensive documentation in Texinfo format, covering installation, usage, and customization.

Requirements

Emacs 28.1 or later
ffmpeg and ffprobe installed and available in your PATH
transient 0.4.0 or later (for the transient menu)

Installation

Manual

Download dired-video-thumbnail.el and place it in your load-path:

(add-to-list 'load-path "/path/to/dired-video-thumbnail/")
(require 'dired-video-thumbnail)

use-package

(use-package dired-video-thumbnail
  :load-path "/path/to/dired-video-thumbnail/"
  :bind (:map dired-mode-map
         ("C-t v" . dired-video-thumbnail)))

straight.el

(straight-use-package
 '(dired-video-thumbnail :type git :host github :repo "captainflasmr/dired-video-thumbnail"))

Usage

Basic Usage

Open a directory containing video files in dired
Run M-x dired-video-thumbnail
A new buffer opens displaying thumbnails for all videos in the directory
The cursor automatically moves to the first thumbnail

With Marked Files

In dired, mark specific video files with m
Run M-x dired-video-thumbnail
Only thumbnails for the marked videos are displayed

Recursive Mode

To include videos from subdirectories:

Use C-u M-x dired-video-thumbnail (with prefix argument)
Or run M-x dired-video-thumbnail-recursive
Or press R in the thumbnail buffer to toggle recursive mode

When dired-video-thumbnail-auto-recursive is enabled (the default), the package automatically searches subdirectories if the current directory contains no video files.

Suggested Keybinding

Add a keybinding in dired for quick access:

(with-eval-after-load 'dired
  (define-key dired-mode-map (kbd "C-t v") #'dired-video-thumbnail))

Transient Menu

Press . or C-c . in the thumbnail buffer to open the transient menu. This provides a comprehensive interface to all commands with a live status display.

State: Sort: name ↑ | Videos: 42 | Recursive: OFF | Wrap: ON

Navigation            Playback       Sorting              Filtering
n Next                RET Play video s Sort menu...       / Filter menu...
p Previous            o Play video   S Interactive sort   \ Interactive filter
C-n Next row                         r Reverse order      c Clear filters
C-p Previous row
d Go to dired

Marking               Delete         Display              Other
m Mark menu...        D Delete       v Display menu...    g Regenerate thumbnail
M Mark all            x Delete marked+ Larger thumbnails  G Regenerate all
U Unmark all                         - Smaller thumbnails C Clear cache
t Toggle all marks                   w Toggle wrap        ? Help
                                     R Toggle recursive   q Quit menu
                                                          Q Quit buffer

The status line at the top shows:

Current sort criteria and direction (e.g., name ↑)
Number of videos displayed (and total if filtered)
Recursive mode status
Wrap display mode status
Active filters (if any)

Submenus

Several keys open submenus with additional options:

s - Sort menu: Sort by name, date, size, or duration; reverse order
/ - Filter menu: Filter by name regexp, duration range, or size range; clear filters
m - Mark menu: Mark/unmark current, toggle current, mark/unmark/toggle all
v - Display menu: Adjust size, toggle wrap/recursive, refresh, regenerate thumbnails

Header Line

As you navigate between thumbnails, the header line dynamically displays information about the current video:

Mark indicator - A red * if the video is marked
Filename - The video filename in bold
Dimensions - Video resolution (e.g., 1920x1080)
Duration - Video length (e.g., 5:32 or 1:23:45)
File size - Size in MB (e.g., 45.2 MB)

The header also shows current sort settings (e.g., [name ↑]), active filters, and a [recursive] indicator when browsing subdirectories.

Keybindings

In the *Video Thumbnails* buffer:

Transient Menu

Key	Command	Description
`.`	`dired-video-thumbnail-transient`	Open transient menu
`C-c .`	`dired-video-thumbnail-transient`	Open transient menu

Navigation

Key	Command	Description
`n`	`dired-video-thumbnail-next`	Move to next thumbnail
`p`	`dired-video-thumbnail-previous`	Move to previous thumbnail
`SPC`	`dired-video-thumbnail-play`	Play video at point
`C-f`	`dired-video-thumbnail-forward`	Move to next thumbnail
`C-b`	`dired-video-thumbnail-backward`	Move to previous thumbnail
`<right>`	`dired-video-thumbnail-forward`	Move to next thumbnail
`<left>`	`dired-video-thumbnail-backward`	Move to previous thumbnail
`<up>`	`dired-video-thumbnail-previous-row`	Move up one row
`<down>`	`dired-video-thumbnail-next-row`	Move down one row
`d`	`dired-video-thumbnail-goto-dired`	Switch to associated dired buffer
`q`	`quit-window`	Close the thumbnail buffer
`Q`	`dired-video-thumbnail-quit-and-kill`	Quit and kill the buffer

Playback

Key	Command	Description
`RET`	`dired-video-thumbnail-play`	Play video at point
`o`	`dired-video-thumbnail-play`	Play video at point
`mouse-1`	`dired-video-thumbnail-play`	Play video (click)

On Linux, videos open with xdg-open. On macOS, they open with open. On Windows, they open with the system default player. You can also specify a custom player.

Marking

Marks are synchronised with the associated dired buffer, so marking a video in the thumbnail view also marks it in dired, and vice versa.

Key	Command	Description
`m`	`dired-video-thumbnail-mark`	Mark video and move to next
`u`	`dired-video-thumbnail-unmark`	Unmark video and move to next
`mouse-3`	`dired-video-thumbnail-toggle-mark`	Toggle mark (right-click)
`M`	`dired-video-thumbnail-mark-all`	Mark all videos
`U`	`dired-video-thumbnail-unmark-all`	Unmark all videos
`t`	`dired-video-thumbnail-toggle-all-marks`	Invert all marks

Deletion

Key	Command	Description
`D`	`dired-video-thumbnail-delete`	Delete video at point (with confirmation)
`x`	`dired-video-thumbnail-delete-marked`	Delete marked videos (with confirmation)

Display

Key	Command	Description
`+`	`dired-video-thumbnail-increase-size`	Increase thumbnail size
`-`	`dired-video-thumbnail-decrease-size`	Decrease thumbnail size
`r`	`dired-video-thumbnail-refresh`	Refresh the display
`w`	`dired-video-thumbnail-toggle-wrap`	Toggle wrap mode (flow vs fixed cols)
`R`	`dired-video-thumbnail-toggle-recursive`	Toggle recursive directory search
`g`	`dired-video-thumbnail-regenerate`	Regenerate thumbnail at point
`G`	`dired-video-thumbnail-regenerate-all`	Regenerate all thumbnails

Sorting

Key	Command	Description
`S`	`dired-video-thumbnail-sort`	Interactive sort menu
`sn`	`dired-video-thumbnail-sort-by-name`	Sort by filename
`sd`	`dired-video-thumbnail-sort-by-date`	Sort by modification date
`ss`	`dired-video-thumbnail-sort-by-size`	Sort by file size
`sD`	`dired-video-thumbnail-sort-by-duration`	Sort by video duration
`sr`	`dired-video-thumbnail-sort-reverse`	Reverse sort order

Filtering

Key	Command	Description
`\`	`dired-video-thumbnail-filter`	Interactive filter menu
`/n`	`dired-video-thumbnail-filter-by-name`	Filter by name regexp
`/d`	`dired-video-thumbnail-filter-by-duration`	Filter by duration range
`/s`	`dired-video-thumbnail-filter-by-size`	Filter by size range
`/c`	`dired-video-thumbnail-filter-clear`	Clear all filters
`//`	`dired-video-thumbnail-filter-clear`	Clear all filters

Help

Key	Command	Description
`h`	`dired-video-thumbnail-help`	Show help
`?`	`dired-video-thumbnail-help`	Show help

Customisation

All customisation options are in the dired-video-thumbnail group. Use M-x customize-group RET dired-video-thumbnail RET to browse them interactively.

Thumbnail Cache Location

Thumbnails are stored in ~/.emacs.d/dired-video-thumbnails/ by default:

(setq dired-video-thumbnail-cache-dir "~/path/to/cache/")

Thumbnail Size

Control the generated thumbnail size and display height:

(setq dired-video-thumbnail-size 200)           ;; Generated thumbnail size (pixels)
(setq dired-video-thumbnail-display-height 150) ;; Display height in buffer

Thumbnails are generated as squares to ensure consistent grid alignment regardless of video aspect ratio.

Grid Layout

Set the number of columns in the thumbnail grid:

(setq dired-video-thumbnail-columns 4)

Wrap Display

Control whether thumbnails wrap to fill the window width:

(setq dired-video-thumbnail-wrap-display t)   ;; Wrap to window width (default)
(setq dired-video-thumbnail-wrap-display nil) ;; Use fixed columns
(setq dired-video-thumbnail-spacing 4)        ;; Spacing between thumbnails (pixels)

Thumbnail Timestamp

By default, thumbnails are extracted at 5 seconds into the video. Change this to get a more representative frame:

(setq dired-video-thumbnail-timestamp "00:00:10")  ;; 10 seconds in
(setq dired-video-thumbnail-timestamp "00:01:00")  ;; 1 minute in
(setq dired-video-thumbnail-timestamp nil)         ;; Let ffmpeg choose

Video Player

Set your preferred video player:

(setq dired-video-thumbnail-video-player "mpv")
(setq dired-video-thumbnail-video-player "vlc")
(setq dired-video-thumbnail-video-player nil)  ;; Use system default

When set to nil (the default), videos open with:

Linux: xdg-open
macOS: open
Windows: System default player (e.g., Films & TV)

Video Extensions

Add or modify recognised video file extensions:

(setq dired-video-thumbnail-video-extensions
      '("mp4" "mkv" "avi" "mov" "webm" "m4v" "wmv" "flv" "mpeg" "mpg" "ogv" "3gp"))

Mark Border Appearance

Marked thumbnails are indicated with a coloured border. Customise the border width and colour:

(setq dired-video-thumbnail-mark-border-width 4)  ;; Border width in pixels

;; Change border colour via the face
(set-face-foreground 'dired-video-thumbnail-mark "blue")

Default Sorting

Set the default sort criteria and order:

(setq dired-video-thumbnail-sort-by 'name)       ;; Options: name, date, size, duration
(setq dired-video-thumbnail-sort-order 'ascending) ;; Options: ascending, descending

Recursive Search

Control recursive directory searching behaviour:

(setq dired-video-thumbnail-recursive nil)       ;; Always search recursively
(setq dired-video-thumbnail-auto-recursive t)    ;; Auto-recursive when no local videos (default)

When dired-video-thumbnail-auto-recursive is enabled and the current directory has no video files but has subdirectories, the package automatically searches recursively.

ffmpeg Path

If ffmpeg/ffprobe are not in your PATH:

(setq dired-video-thumbnail-ffmpeg-program "/usr/local/bin/ffmpeg")
(setq dired-video-thumbnail-ffprobe-program "/usr/local/bin/ffprobe")

Example Configuration

(use-package dired-video-thumbnail
  :load-path "/path/to/dired-video-thumbnail/"
  :bind (:map dired-mode-map
         ("C-t v" . dired-video-thumbnail))
  :custom
  (dired-video-thumbnail-size 250)
  (dired-video-thumbnail-display-height 180)
  (dired-video-thumbnail-columns 5)
  (dired-video-thumbnail-timestamp "00:00:10")
  (dired-video-thumbnail-video-player nil)  ;; Use system default
  (dired-video-thumbnail-mark-border-width 5)
  (dired-video-thumbnail-sort-by 'date)
  (dired-video-thumbnail-sort-order 'descending)
  (dired-video-thumbnail-auto-recursive t)
  :custom-face
  (dired-video-thumbnail-mark ((t (:foreground "orange")))))

Cache Management

Thumbnails are cached based on the file path and modification time. If you modify a video file, the thumbnail will be automatically regenerated on next view.

Video metadata (dimensions, duration) is also cached in memory to avoid repeated calls to ffprobe.

To manually clear the thumbnail cache:

M-x dired-video-thumbnail-clear-cache

Workflow Examples

Reviewing and Deleting Unwanted Videos

Open a directory with videos in dired
C-t v to open thumbnail view
Browse thumbnails with n, p, SPC, or arrow keys
Press D to delete individual videos, or mark with m and delete with x

Selecting Videos for Processing

Open thumbnail view with C-t v
Mark videos you want to process with m
Press d to switch to dired
Your marked videos are already selected in dired
Use any dired command (C, R, !, etc.) on marked files

Quick Video Preview

In dired, position cursor on a video file
C-t v opens thumbnail view
RET to play the video
q to return to dired

Finding Large Videos

Open thumbnail view with C-t v
Press . to open the transient menu
Press s then s to sort by size
Press r to reverse order (largest first)
Or use / then s to filter by size range

Finding Long Videos

Press . to open the transient menu
Press s then D to sort by duration
Or use / then d to filter by duration range (e.g., 5:00 to 30:00)

Searching by Name

Press . to open the transient menu
Press / then n and enter a regexp pattern
Only matching videos are shown
Press c to clear the filter

Troubleshooting

Thumbnails not generating

Ensure ffmpeg is installed: ffmpeg -version
Check that ffmpeg is in your PATH or set dired-video-thumbnail-ffmpeg-program
Try regenerating with g on a specific thumbnail

Placeholder showing instead of thumbnail

Some videos may fail to generate thumbnails if:

The video is corrupted
The timestamp is beyond the video duration (try setting dired-video-thumbnail-timestamp to nil)
ffmpeg doesn't support the codec

Press g on the thumbnail to retry generation.

Video info not showing in header line

Ensure ffprobe is installed (it comes with ffmpeg). Set dired-video-thumbnail-ffprobe-program if it's not in your PATH.

Marks not syncing with dired

Run M-x dired-video-thumbnail-debug to check if the dired buffer is properly associated. The output should show a live dired buffer reference.

Performance with many videos

The package processes up to 4 videos concurrently by default. For directories with hundreds of videos, initial thumbnail generation may take some time, but Emacs remains responsive and thumbnails appear as they complete.

Related Packages

image-dired - Built-in image thumbnail browser for dired
dirvish - A modern file manager for Emacs with preview support

Photos Evie 2025-12-31

2025-12-31T18:30:00+0000

Roaming around Kates parents house!

Setting Up Emacs for C# Development on Windows

2025-12-16T08:25:00+0000

Introduction

I have been developing C# with .NET 9.0 for the last year on Windows and I thought it was probably time to write down my current setup, and maybe someone might even find this useful!

So, this guide documents my setup for running Emacs 30.1 on Windows with full C# development support, including LSP, debugging (through DAPE), and all the ancillary tools you'd expect from a modern development environment. The setup is designed to be portable and self-contained, which is particularly useful in air-gapped or restricted environments.

A version of this can be found at https://github.com/captainflasmr/Emacs-on-windows which will be a living continually updated version!

Prerequisites

Before we begin, you'll need:

Windows 10 or 11 (64-bit)
.NET 9.0 SDK - Required for csharp-ls and building .NET projects
Visual Studio 2022 (optional) - Useful for MSBuild and if you need the full IDE occasionally
Administrator access - For initial setup only

You can verify your .NET installation by opening a command prompt and running:

dotnet --version

If you see version 9.0.x or later, you're ready to proceed.

The Big Picture

Here's what we're building:

D:\source\emacs-30.1\
├── bin\
│   ├── emacs.exe, runemacs.exe, etc.
│   ├── PortableGit\          # Git for version control
│   ├── Apache-Subversion\    # SVN (if needed)
│   ├── csharp-ls\            # C# Language Server
│   ├── netcoredbg\           # .NET debugger
│   ├── omnisharp-win-x64\    # Alternative C# LSP
│   ├── hunspell\             # Spell checking
│   ├── find\                 # ripgrep for fast searching
│   ├── ffmpeg-7.1.1-.../     # Video processing
│   └── ImageMagick-.../      # Image processing
└── share\
    └── emacs\...

The key insight here is keeping everything within the Emacs installation directory. This makes the whole setup portable-you can copy it to another machine or keep it on a USB drive.

Step 1: Installing Emacs

Download Emacs 30.1 from the GNU Emacs download page. For Windows, grab the installer or the zip archive.

I install to an external drive D:\source\emacs-30.1 rather than Program Files-it avoids permission issues and keeps everything in one place.

Test your installation by running bin\runemacs.exe. You should see a fresh Emacs frame.

Step 2: Setting Up csharp-ls (The C# Language Server)

This is the heart of the C# development experience. csharp-ls provides code completion, go-to-definition, find references, diagnostics, and more through the Language Server Protocol (LSP).

Option A: Installing via dotnet tool (Recommended for Internet Access)

If you have internet access, the easiest way to install csharp-ls is as a .NET global tool:

# Install the latest version globally
dotnet tool install --global csharp-ls

# Or install a specific version
dotnet tool install --global csharp-ls --version 0.20.0

# Verify installation
csharp-ls --version

By default, global tools are installed to:

Windows: %USERPROFILE%\.dotnet\tools

The executable will be csharp-ls.exe and can be called directly once the tools directory is in your PATH.

Option B: Offline Installation via NuGet Package

For air-gapped environments, you can download the NuGet package and extract it manually:

On a machine with internet, download the package:

# Download the nupkg file
nuget install csharp-ls -Version 0.20.0 -OutputDirectory ./packages

# Or download directly from NuGet Gallery:
# https://www.nuget.org/packages/csharp-ls/
# Click "Download package" on the right side

The .nupkg file is just a ZIP archive. Extract it:

# Rename to .zip and extract, or use 7-Zip
# The DLLs are in tools/net9.0/any/

Copy the tools/net9.0/any/ directory to your Emacs bin:

xcopy /E packages\csharp-ls.0.20.0\tools\net9.0\any D:\source\emacs-30.1\bin\csharp-ls\

The language server is now at: D:\source\emacs-30.1\bin\csharp-ls\CSharpLanguageServer.dll

Configuring Eglot for csharp-ls

In your init.el, configure Eglot to use csharp-ls:

(require 'eglot)

;; Option A: If installed as a global tool
(setq eglot-server-programs
      '((csharp-mode . ("csharp-ls"))))

;; Option B: If running from extracted DLL
(setq eglot-server-programs
      '((csharp-mode . ("dotnet" 
                        "D:/source/emacs-30.1/bin/csharp-ls/CSharpLanguageServer.dll"))))

I also have the following commented out if there are some eglot functions that causes slowdowns or I just think I don't need:

(setq eglot-ignored-server-capabilities
      '(
        ;; :hoverProvider                    ; Documentation on hover
        ;; :completionProvider               ; Code completion
        ;; :signatureHelpProvider            ; Function signature help
        ;; :definitionProvider               ; Go to definition
        ;; :typeDefinitionProvider           ; Go to type definition
        ;; :implementationProvider           ; Go to implementation
        ;; :declarationProvider              ; Go to declaration
        ;; :referencesProvider               ; Find references
        ;; :documentHighlightProvider        ; Highlight symbols automatically
        ;; :documentSymbolProvider           ; List symbols in buffer
        ;; :workspaceSymbolProvider          ; List symbols in workspace
        ;; :codeActionProvider               ; Execute code actions
        ;; :codeLensProvider                 ; Code lens
        ;; :documentFormattingProvider       ; Format buffer
        ;; :documentRangeFormattingProvider  ; Format portion of buffer
        ;; :documentOnTypeFormattingProvider ; On-type formatting
        ;; :renameProvider                   ; Rename symbol
        ;; :documentLinkProvider             ; Highlight links in document
        ;; :colorProvider                    ; Decorate color references
        ;; :foldingRangeProvider             ; Fold regions of buffer
        ;; :executeCommandProvider           ; Execute custom commands
        ;; :inlayHintProvider                ; Inlay hints
        ))

Step 3: Setting Up the Debugger (netcoredbg)

For debugging .NET applications, we'll use netcoredbg, which implements the Debug Adapter Protocol (DAP).

Installing netcoredbg

Download from Samsung's GitHub releases
Extract to D:\source\emacs-30.1\bin\netcoredbg\
Verify: netcoredbg.exe --version

Configuring dape for Debugging

dape is an excellent DAP client for Emacs. Here's my configuration:

(use-package dape
  :load-path "z:/SharedVM/source/dape-master"
  :init
  ;; Set key prefix BEFORE loading dape
  (setq dape-key-prefix (kbd "C-c d"))
  :config
  ;; Define common configuration
  (defvar project-netcoredbg-path "d:/source/emacs-30.1/bin/netcoredbg/netcoredbg.exe"
    "Path to netcoredbg executable.")
  (defvar project-netcoredbg-log "d:/source/emacs-30.1/bin/netcoredbg/netcoredbg.log"
    "Path to netcoredbg log file.")
  (defvar project-project-root "d:/source/PROJECT"
    "Root directory of PROJECT project.")
  (defvar project-build-config "Debug"
    "Build configuration (Debug or Release).")
  (defvar project-target-arch "x64"
    "Target architecture (x64, x86, or AnyCPU).")

  ;; Helper function to create component configs
  (defun project-dape-config (component-name dll-name &optional stop-at-entry)
    "Create a dape configuration for a component.
COMPONENT-NAME is the component directory name
DLL-NAME is the DLL filename without extension.
STOP-AT-ENTRY if non-nil, stops at program entry point."
    (let* ((component-dir (format "%s/%s" project-project-root component-name))
           (bin-path (format "%s/bin/%s/%s/net9.0"
                             component-dir
                             project-target-arch
                             project-build-config))
           (dll-path (format "%s/%s.dll" bin-path dll-name))
           (config-name (intern (format "netcoredbg-launch-%s" 
                                        (downcase component-name)))))
      `(,config-name
        modes (csharp-mode csharp-ts-mode)
        command ,project-netcoredbg-path
        command-args (,(format "--interpreter=vscode")
                      ,(format "--engineLogging=%s" project-netcoredbg-log))
        normalize-path-separator 'windows
        :type "coreclr"
        :request "launch"
        :program ,dll-path
        :cwd ,component-dir
        :console "externalTerminal"
        :internalConsoleOptions "neverOpen"
        :suppressJITOptimizations t
        :requireExactSource nil
        :justMyCode t
        :stopAtEntry ,(if stop-at-entry t :json-false))))

  ;; Register all component configurations
  (dolist (config (list
                   (project-dape-config "DM" "DM.MSS" t)
                   (project-dape-config "Demo" "Demo.MSS" t)
                   (project-dape-config "Test_001" "Test" t)))
    (add-to-list 'dape-configs config))
  
  ;; Set buffer arrangement and other options
  (setq dape-buffer-window-arrangement 'gud)
  (setq dape-debug t)
  (setq dape-repl-echo-shell-output t))

Now you can start debugging with M-x dape and selecting your configuration.

Step 4: Installing Supporting Tools

Portable Git

Download PortableGit-2.50.0-64-bit.7z.exe from git-scm.com
Run and extract to D:\source\emacs-30.1\bin\PortableGit\

This gives you git.exe, bash.exe, and a whole Unix-like environment.

ripgrep (Fast Searching)

Download from ripgrep releases
Extract rg.exe to D:\source\emacs-30.1\bin\find\

ripgrep is dramatically faster than grep for searching codebases.

Hunspell (Spell Checking)

Download hunspell-1.3.2-3-w32-bin.zip
Extract to D:\source\emacs-30.1\bin\hunspell\
Download dictionary files (en_GB.dic and en_GB.aff) and place in hunspell\share\hunspell\

ImageMagick (Image Processing)

Download the portable Q16 x64 version from imagemagick.org
Extract to D:\source\emacs-30.1\bin\ImageMagick-7.1.2-9-portable-Q16-x64\

This enables image-dired thumbnail generation.

FFmpeg (Video Processing)

Download from ffmpeg.org (essentials build is fine)
Extract to D:\source\emacs-30.1\bin\ffmpeg-7.1.1-essentials_build\

Useful for video thumbnails in dired and media processing.

Step 5: Configuring the PATH

This is crucial-Emacs needs to find all these tools. Here's the PATH configuration from my init.el:

(when (eq system-type 'windows-nt)
  (let* ((emacs-bin "d:/source/emacs-30.1/bin")
         (xPaths
          `(,emacs-bin
            ,(concat emacs-bin "/PortableGit/bin")
            ,(concat emacs-bin "/PortableGit/usr/bin")
            ,(concat emacs-bin "/hunspell/bin")
            ,(concat emacs-bin "/find")
            ,(concat emacs-bin "/netcoredbg")
            ,(concat emacs-bin "/csharp-ls/tools/net9.0/any")
            ,(concat emacs-bin "/ffmpeg-7.1.1-essentials_build/bin")
            ,(concat emacs-bin "/ImageMagick-7.1.2-9-portable-Q16-x64")))
         (winPaths (getenv "PATH")))
    (setenv "PATH" (concat (mapconcat 'identity xPaths ";") ";" winPaths))
    (setq exec-path (append xPaths (parse-colon-path winPaths)))))

Step 6: Installing Emacs Packages

Extract these to a shared location or download from MELPA

Package	Purpose
corfu	Modern completion UI
dape	Debug Adapter Protocol client
highlight-indent-guides	Visual indentation guides
ztree	Directory tree comparison
web-mode	Web template editing

Example package configuration:

(use-package corfu
  :load-path "z:/SharedVM/source/corfu-main"
  :custom
  (corfu-auto nil)         ; Manual completion trigger
  (corfu-cycle t)          ; Cycle through candidates
  (corfu-preselect 'first))

(use-package ztree
  :load-path "z:/SharedVM/source/ztree"
  :config
  (setq ztree-diff-filter-list
        '("build" "\\.dll" "\\.git" "bin" "obj"))
  (global-set-key (kbd "C-c z d") 'ztree-diff))

(use-package web-mode
  :load-path "z:/SharedVM/source/web-mode-master"
  :mode "\\.cshtml?\\'"
  :hook (html-mode . web-mode)
  :bind (:map web-mode-map ("M-;" . nil)))

Note that I turn off autocomplete for corfu and complete using complete-symbol manually, otherwise the LSP is constantly accessed with slowdown.

I often use Meld but am currently am looking to adapt ztree to perform better for directory comparisons.

Web-mode is the best package I have found for html type file navigation and folding, very useful when developing Razor pages for example.

Step 7: auto open file modes

Of course running and building in windows means in Emacs probably having to open .csproj files from time to time, well nxml-mode comes in useful for this:

(add-to-list 'auto-mode-alist '("\\.csproj\\'" . nxml-mode))

Step 8: build script

Here is my general build script, leveraging msbuild and running generally from eshell

New projects are added to :

set PROJECTS
set PROJECT_NAMES

@echo off
setlocal

REM =================================================================
REM Build Management Script
REM =================================================================
REM Usage: build-selected.bat [action] [verbosity] [configuration] [platform]
REM   action: build, clean, restore, rebuild (default: build)
REM   verbosity: quiet, minimal, normal, detailed, diagnostic (default: minimal)
REM   configuration: Debug, Release (default: Debug)
REM   platform: x64, x86, "Any CPU" (default: x64)
REM =================================================================

REM Set defaults
set ACTION=%1
set VERBOSITY=%2
set CONFIGURATION=%3
set PLATFORM=%4

if "%ACTION%"=="" set ACTION=build
if "%VERBOSITY%"=="" set VERBOSITY=minimal
if "%CONFIGURATION%"=="" set CONFIGURATION=Debug
if "%PLATFORM%"=="" set PLATFORM=x64

echo Build Script - Action=%ACTION%, Verbosity=%VERBOSITY%, Config=%CONFIGURATION%, Platform=%PLATFORM%
echo.

REM Common build parameters
set BUILD_PARAMS=/p:Configuration=%CONFIGURATION% /p:Platform="%PLATFORM%" /verbosity:%VERBOSITY%

REM Set MSBuild target based on action
if /I "%ACTION%"=="build" set TARGET=Build
if /I "%ACTION%"=="clean" set TARGET=Clean
if /I "%ACTION%"=="restore" set TARGET=Restore
if /I "%ACTION%"=="rebuild" set TARGET=Rebuild

if "%TARGET%"=="" (
    echo Error: Invalid action '%ACTION%'. Use: build, clean, restore, or rebuild
    exit /b 1
)

echo Executing %ACTION% action...
echo.

set PROJECTS[1]=Demo/Demo.csproj
set PROJECT_NAMES[1]=Demo

set PROJECTS[2]=Test/Test.csproj
set PROJECT_NAMES[2]=Test

set PROJECT_COUNT=2

REM Special handling for rebuild (clean then build)
if /I "%ACTION%"=="rebuild" (
    echo === CLEANING PHASE ===
    for /L %%i in (1,1,%PROJECT_COUNT%) do (
        call :process_project %%i Clean
        if errorlevel 1 goto :error
    )
    echo.
    echo === BUILDING PHASE ===
    set TARGET=Build
)

REM Process all active projects
for /L %%i in (1,1,%PROJECT_COUNT%) do (
    call :process_project %%i %TARGET%
    if errorlevel 1 goto :error
)

echo.
if /I "%ACTION%"=="clean" (
    echo All selected components cleaned successfully!
) else if /I "%ACTION%"=="restore" (
    echo All selected components restored successfully!
) else if /I "%ACTION%"=="rebuild" (
    echo All selected components rebuilt successfully!
) else (
    echo All selected components built successfully!
)
goto :end

:process_project
    setlocal EnableDelayedExpansion
    set idx=%1
    set target=%2
    
    REM Get project path and name using the index
    for /f "tokens=2 delims==" %%a in ('set PROJECTS[%idx%] 2^>nul') do set PROJECT_PATH=%%a
    for /f "tokens=2 delims==" %%a in ('set PROJECT_NAMES[%idx%] 2^>nul') do set PROJECT_NAME=%%a
    
    if "!PROJECT_PATH!"=="" goto :eof

    echo ----------------------------------------
    echo [%idx%/%PROJECT_COUNT%] %target%ing !PROJECT_NAME!...

    REM Build the project normally
    msbuild "!PROJECT_PATH!" /t:%target% %BUILD_PARAMS%
    if errorlevel 1 exit /b 1
    
goto :eof

:error
echo.
echo %ACTION% failed! Check the output above for errors.
exit /b 1

:end
echo %ACTION% completed at %time%

to launch applications of course, if it is a pure DOTNET project you would use dotnet run

Troubleshooting

"Cannot find csharp-ls" or Eglot won't start

Check the PATH: M-x getenv RET PATH
Verify the DLL exists at the configured location
Try running manually: dotnet path\to\CSharpLanguageServer.dll --version
Check *eglot-events* buffer for detailed error messages

LSP is slow or uses too much memory

Try adding to your configuration:

;; Increase garbage collection threshold during LSP operations
(setq gc-cons-threshold 100000000)  ; 100MB
(setq read-process-output-max (* 1024 1024))  ; 1MB

Debugger won't attach

Ensure the project is built in Debug configuration
Check the DLL path matches your build output
Look at *dape-repl* for error messages
Verify netcoredbg runs: netcoredbg.exe --version

Conclusion

This setup has served me well for my windows .NET 9.0 projects and various other C# work. The key benefits:

Portability: Everything lives in one directory
Speed: csharp-ls is notably faster than OmniSharp
Flexibility: Easy to customise and extend
Offline-capable: Works in air-gapped environments

The initial setup takes some effort, but once it's done, you have a powerful, consistent development environment that travels with you.