Ramblings of an aging IT geek

Decisions, Weighted

2026-08-01T00:00:00Z

aide keeps a project's architectural decisions in the repo and injects them into every session, so agents are taught the rules rather than guessing at them. You can think of the decision store as the project's rule book: the conventions, constraints and background knowledge that need to be known and followed, written down once instead of re-explained every time somebody opens a session.

Blueprints are groupings of those decisions that align to some body of guidance or best practice, so you can onboard a new project in one command rather than typing out the same opinions about Go that you type out every time. Estates are the other half of it, decisions travelling between related projects, usually from a parent repo down into the subprojects it contains. All of it is about getting the right information in front of the model so it makes sensible choices and doesn't invent its own.

Until recently I never had any need for priorities between decisions. The latest revision for a given topic wins, and I think that is still the right model. What changed is that I added a blueprint for working in existing projects, honouring the conventions that are already there, and that immediately raised a problem: a language blueprint full of modern best practice will quite happily override the norms of a codebase that has been doing it another way for years. This release fixes that, along with a few other things I'd been meaning to get to.

Precedence, and One Threshold

Decisions now carry an integer precedence, where higher gets injected earlier. For most of them that is all it does, it's a sort key and nothing more.

aide decision set house-style "Follow the repo" --precedence=100

The exception is 100. At or above that threshold a decision comes out of the ordinary set altogether and gets rendered in a block of its own, ahead of everything else, with the relationship spelled out rather than left to inference:

## Overriding Decisions

These take precedence over every decision below and over general best practice.
Where they conflict with anything else, these win:

- **existing-codebase-precedence**: The repository is the authority…

So something at 200 outranks something at 100 inside that block, while something at 80 stays in the ordinary set, sorted above the defaults but not claiming anything over them.

Precedence	Renders in	Claims
`>= 100`	`## Overriding Decisions`	"where this conflicts with anything below, this wins"
`1`–`99`	`## Project Decisions`, above the defaults	nothing
`0` (default)	`## Project Decisions`	nothing
negative	`## Project Decisions`, last	nothing

The explicit header on that block is what makes the override clear, rather than leaving it to be inferred from where a decision happens to appear in the list.

The weight itself is plumbed through the proto field, the Bolt store, the gRPC server, the CLI, share export and import, blueprints, the web API and its badge, and both session-start and subagent injection, so a decision that overrides in your session overrides in a subagent's too.

flowchart TD
    L[local store] --> S{precedence}
    P[parent estate] --> S
    R[peer rings] --> S
    S -->|100 and above| O["## Overriding Decisions"]
    S -->|below 100| D["## Project Decisions"]

One useful property of the design is that an omitted precedence inherits whatever the current revision carries:

func ResolvePrecedence(g DecisionGetter, topic string, requested *int) int {
	if requested != nil {
		return *requested
	}
	if prev, err := g.GetDecision(topic); err == nil && prev != nil {
		return prev.Precedence
	}
	return memory.PrecedenceDefault
}

Decision writes are revisions rather than mutations, so without that, rewording a guardrail from the CLI would write a new revision at the default weight and silently demote a 100 down to a 0. An explicit value still wins, including an explicit 0, so you can demote something deliberately if you want to. All three write paths go through the same resolver, which is the only reason I trust it.

I also fixed an existing bug I hadn't found until now. sessionFetchContext was ranging a map:

// Ranging a map made this block reorder on every session, which is
// noise in agent context and defeats prompt caching on the prefix.

Go randomises map iteration, so the injected block was coming out in a different order every session despite the content being identical, which is noise in the context and leaves the prompt cache without a stable prefix to reuse. It's now topic-sorted within each precedence band with the ring order preserved inside a weight, so local decisions still come before inherited ones, and three consecutive runs come out byte-identical.

The Blueprint That Started It

existing-software-project is the blueprint that prompted all of the above, and the only one that ships above the threshold. It's a bundle of decisions about working in a codebase you didn't write, all at default_precedence: 100, and unlike the language blueprints it includes nothing of its own, since it's meant to sit alongside whatever language blueprints you already have:

aide blueprint import existing-software-project

The existing-* decisions are there to honour a project's existing style, rules and process: read the surrounding code before editing it, use the committed toolchain, treat linter config as binding, keep the diff to what the task needs. An explicit instruction in the current task still outranks all of it and general best practice comes last, so the bundle won't impose something like Conventional Commits on a repository whose history has never used them.

And Some Python

I've been working on more Python projects recently, so those decisions are now a blueprint too: python, with python-django, python-api and python-github-actions on top. Detection also picks up requirements.txt and uv.lock for Python, and manage.py for Django.

The blueprints documentation has the per-decision breakdowns for each of the new bundles if you want the detail.

Decisions, Inherited

2026-07-21T00:00:00Z

aide records the architectural decisions a project has made and injects them into every session. That works right up until your project contains other projects: a superrepo full of submodules is really one estate with one set of opinions, but each subproject's store had no idea the others existed. As of v0.1.8, decisions travel: down from ancestors, and sideways between teams.

The Estate

aide now works out where it is (and what sits above it) from VCS evidence, with exactly one resolver:

aide anchor --json

Everything else reads that one answer, which also fixed a family of bugs where a session opened at the superrepo wrote into the wrong project's store. Sorry about those. Session context gains an Estate section (parents above, subprojects below), and aide-web draws the whole tree.

Inherit from Ancestors

Nothing to configure. At session start aide walks up the chain and overlays each ancestor's decisions onto your context, labelled with where they came from. A worked example: parent repo tl decides fav-colour = orange and team-editor = vim; the nested repo tl/webshop has its own store with api-style = REST and fav-colour = blue. A session inside webshop sees:

api-style:   REST   [local]
fav-colour:  blue   [local]        <- shadows the parent's orange
team-editor: vim    [parent: tl]   <- inherited

Shadowing is by topic and nearest wins: webshop's blue means the parent's orange is never even looked at, and the parent is none the wiser. Nothing is copied between stores; provenance is synthesised at read time, so renaming or re-nesting a project can't corrupt anything. It isn't just plumbing, either: ask a headless Claude in each directory and the one in webshop explains that fav-colour is blue, decided locally, overriding the parent estate; the one in tl still answers orange. The labels carry the semantics, not just the values.

To override a parent, then, you just set your own (theirs stays intact upstream):

aide decision set fav-colour "blue"

To record a decision at the estate level instead, aim the write upwards:

aide --store parent decision set logging "slog, structured"   # nearest container
aide --store top decision set go-version "1.26"               # the estate root

And AIDE_CASCADE_DISABLED=1 switches the whole cascade off.

For teams that don't share a filesystem, subscriptions run over plain git. Name your sources in .aide/config/aide.json:

{ "subscriptions": [
    { "name": "platform-team", "url": "git@host:platform/context.git", "branch": "main" },
    { "name": "proto-repo",    "path": "../protos" }
] }

That's the setup done: the next session start fetches them, and peer decisions appear in your context as a read-only layer labelled from peer platform-team. Where you override a parent, you adopt a peer:

aide decision adopt api-style --from=platform-team

which copies it into your store with adoption provenance. Add "publish": true to a subscription and the loop runs both ways: your own decisions go back out for others to subscribe to. Decisions only, mind; memories never cross a project boundary.

Why Not Just Import?

aide already had two ways to get decisions into a store from outside: blueprints (curated best-practice defaults you import when bootstrapping a project) and aide share import (a point-in-time merge from a directory a teammate exported). Both are copies, and both are exactly right for what they do: a blueprint is a template, and once imported the decision is genuinely yours to keep or overturn; a share import is one team converging one project's stores.

Copies are the wrong tool for a living ADR owned by somebody else, though. The platform team's api-style decision is theirs; they will re-decide it, and a copy you took in March says nothing about what they think in July. Copies rot, silently, and worse, they lie with confidence. A subscription is a reference: you always read the owning team's current word, it arrives labelled with where it came from, and it never leaks back out of your store (you can't accidentally re-publish somebody else's ADR as your own). Adoption is the deliberate act that turns a reference into a copy, with a stamp saying so. Ownership stays where the decision lives; that's the entire justification, and it's the same one that makes the ancestor cascade read at session start rather than syncing records downward.

The Session Is the Scheduler

My first instinct for the publishing side was a systemd timer, and it was wrong. Nothing here needs a scheduler, because aide already has one: the session lifecycle.

Decisions are only ever made inside sessions. So session start pulls (any subscription cache older than an hour is refreshed, quietly, offline-silent) and session end pushes (publish-enabled subscriptions ship whatever the session decided, bounded to a few seconds, silent if the network is away; unpublished records simply go out at the next session end). The event that creates the record is the event that ships it. If you find yourself writing a cron job for this, that's a bug report.

The other cases need even less. Inside a superrepo there's nothing to sync at all: the cascade reads the ancestor's store directly at session start, same disk, always current. And a team sharing one repo already has its sync mechanism: the context records are files that commit with the repo, so git pull is the import, git push is the publish, and a pull request is the review process. Teams that want ADR changes reviewed before they propagate can publish through a PR into the context repo instead of enabling the automatic path; subscribers can't tell the difference. aide sync survives as the manual lever, and it exits non-zero when a subscription fails, for the CI-inclined who want a red light rather than silence.

Precedence in one line: local beats nearest ancestor, ancestors beat peers. Your project gets the last word; it just no longer starts the conversation ignorant.

rosec 0.0.33: The Security Key Signs In

2026-07-09T00:00:00Z

This is a pretty chunky release for rosec, big enough that I genuinely flirted with calling it 0.1.0 before coming to my senses.

The star of the show is something I've been waiting for: WebAuthn support. An unmodified browser can now register a passkey with rosec and log in with it, full ceremony, no extensions, browser ↔ vault and back. Passkeys, end-to-end.

A passkey is really just a private key with some metadata, and since rosec's providers already know how to look after private keys, it was mostly a matter of exposing them properly. The local vault, Bitwarden items, and KeePassXC databases all feed into the same model now. rosec only hands the key over at the exact moment of signing, then zeroizes it immediately. That's the "don't lose it" part handled.

The tricky half was the "make the browser happy" part. Browsers talk CTAP2 to actual security keys, not random files, so FUSE was never going to cut it. We had to become a real (virtual) security key. /dev/uhid lets userspace create one… but it's root-only, because the same interface could just as easily pretend to be a keyboard and type whatever it likes.

Enter the tiny socket-activated broker rosec-uhid. It runs as root for a few milliseconds, spins up a FIDO-only device from a hard-coded descriptor, hands the file descriptor to your unprivileged daemon, and immediately exits. Close the fd and the device disappears. Crash the daemon? No phantom key left behind. Lock the vault? It's the digital equivalent of yanking the USB stick. It's off by default and desktop-only: install the broker and set fido2 = true if you want it.

Trust you can actually rotate

The other notable change is how we handle trust for provider plugins. They were already signed WASM modules, but the daemon only trusted one hardcoded key. Rotating it was… awkward. Now we have a proper set of trust roots, so key rotation gets a graceful deprecation period instead of a surprise flag day. There's also a user-configurable trust anchor in rosec.toml, so third-party authors can ship signed plugins without forcing people to turn off verification entirely.

We also added proper tooling: rosec-package-wasm for authors and rosec provider validate for users. It even schema-validates the sandbox policy before signing, so any silly mistakes blow up on the author's machine instead of yours. Considerate, aren't we?

The rest

We did a full security review on the new code and the wider daemon: the virtual authenticator's device node is now 0600 owned by you (no more leaning on seat uaccess), passed file descriptors are close-on-exec, the portal backend properly verifies its caller, and we sprinkled in some DoS and zeroization fixes for good measure.

The prompt also gained a scrollable single-select mode, very handy when you have multiple passkeys that match the same site.

Usual caveat: these are software passkeys, not hardware-bound. So sites that demand hardware attestation will still turn up their noses. That's the trade-off for keys you can actually back up and move between machines.

Repo and docs are on GitHub.

clipferry: An X11 to Wayland Clipboard Bridge

2026-07-04T00:00:00Z

Clipferry solves the problem of X11 ↔ Wayland clipboard sync. Let me explain why I built this.

I often use niri or Hyprland with Steam. Steam, Proton and Wine are all X11 clients: they reach Wayland via xwayland-satellite on niri, and via Hyprland's builtin Xwayland on Hyprland.

Copying inside a Wayland app and pasting into a Wine window works. Copying out of an X11 app doesn't: the X11 selection never crosses back. A WoW SimC dump you want in raidbots, a talent or WeakAuras import string bound for Discord, a Path of Building code, a Factorio blueprint, an FFXIV gear set string: all stuck on the X11 side.

Recent xwayland-satellite releases have closed some of these gaps, but apps that don't play the usual focus games, and less-common MIME types, still fall through on both stacks.

dnut/clipboard-sync hasn't been touched since 2023 and has a much broader scope than I wanted. Everything else was bash around wl-copy and xclip, polling in a loop with content hashes for loop suppression and a pipe cost paid on every copy whether anyone pastes or not. Fine for text; grim for a 30 MB screenshot.

clipferry is a small Rust daemon that speaks both clipboard protocols directly and shuttles selections across on demand.

The design is deliberately narrow.

Lazy by default. When you copy, clipferry exchanges the list of MIME types with the other side. The bytes themselves only move when someone actually pastes. A 50 MB image copy is a handful of strings until a paste happens, not two full transfers up-front.
All the MIME types, not just text. Images, HTML, text/uri-list, and a small translation table for the X11-isms (x-special/gnome-copied-files, a couple of WeChat and Wine quirks), plus INCR in both directions for the awkwardly large ones.
Loop prevention by ownership identity, not hashing. clipferry knows which selection claims are its own, so it never chases its own tail. No content hashes, no sleeps, no races.
Sandboxed. It applies Landlock to itself: no filesystem, no TCP. Plus the usual systemd hardening. Clipboard content is never logged, and payload buffers are zeroed when they die.
Small. One process, a ~1 MiB binary, under 5 MiB resident.

By default it runs in backstop mode: it watches both clipboards passively, and only claims a selection when nothing else has bridged the other side within ~200 ms of a copy. If satellite's builtin sync handles a case, clipferry stays out of the way. Clipboard history managers (cliphist, clipse) coexist as designed.

Install is short:

# Arch
paru -S clipferry

# any distro
cargo install --git https://github.com/jmylchreest/clipferry
sudo cp contrib/clipferry.service /usr/lib/systemd/user/
systemctl --user enable --now clipferry.service
clipferry --oneshot-check    # sanity: both displays reachable?

There isn't much to configure, but there are a handful of flags to deal with edge cases. For most people the defaults will work. The README documents them.

If copy-out-of-X11 has been annoying you, give it a go. Issues and patches welcome on the repo.

Escribí mi propio generador de sitios. ¿Deberías usarlo?

2026-06-28T00:00:00Z

Construí colophon, el generador con el que funciona este blog, así que toma todo lo que sigue como la opinión de alguien que corrige sus propios deberes. He intentado ceñirme a hechos y características, no al cariño. Donde colophon sea la elección equivocada lo diré, porque fingir lo contrario no ayuda a nadie, y a mí menos que a nadie.

La verdad aburrida primero: casi todos los generadores de sitios estáticos hacen el mismo trabajo de fondo. Entra Markdown, sale un montón rápido de HTML estático, y lo alojas en algún sitio barato. Se diferencian en tres cosas que de verdad importan: lo maduro y bien respaldado que está el proyecto, qué viene incluido frente a lo que tienes que añadir tú, y para quién se escribió.

Los consagrados

Estas son las herramientas a las que deberías recurrir por defecto.

Herramienta	Entorno	Forma	Mejor para
Hugo	Go, binario único	Enorme, rápido, maduro	Casi cualquier blog o sitio: velocidad, un catálogo enorme de temas y extensiones, una década de respuestas en internet
Jekyll	Ruby	El original, el motor nativo de GitHub Pages	Publicar sin configuración directamente desde un repositorio de GitHub
Zola	Rust, binario único	Con pilas incluidas, sin extensiones por diseño	Un binario único y rápido con Sass, búsqueda y resaltado incluidos, si no necesitas extensiones
Eleventy	Node	Mínimo, infinitamente flexible	Gente de JavaScript que quiere control total y diez lenguajes de plantillas para elegir
Astro	Node	Framework de contenido con islas interactivas	Sitios de contenido que además necesitan componentes interactivos de verdad

Hugo es la respuesta sensata para la mayoría, y es con lo que funcionaba este blog al principio. Renderiza un sitio grande en segundos, tiene con diferencia el mayor catálogo de temas, y si te topas con un muro, alguien lo resolvió hace años y lo dejó escrito. Jekyll es más antiguo y más lento en sitios grandes, pero si solo quieres empujar Markdown a GitHub Pages y olvidarte, nada es más simple. Zola es el más parecido a colophon en espíritu: un binario de Rust, cosas sensatas incluidas, y una negativa deliberada a hacer crecer un sistema de extensiones. Eleventy y Astro son el extremo JavaScript de la sala, Eleventy todo flexibilidad y ninguna opinión, Astro un framework de verdad para cuando un blog es en realidad una aplicación disfrazada de blog.

Ninguno de ellos incluye de fábrica generación de imágenes con IA, lecturas de audio habladas, webmentions de la IndieWeb ni sindicación POSSE. No es una crítica: es una decisión de alcance, y puedes añadir casi todo con extensiones y un par de servicios externos.

En qué se diferencia colophon de verdad

colophon también es un único binario de Go que convierte Markdown en un sitio estático, así que en el trabajo de fondo es de lo más corriente. La diferencia está en lo que integra como funciones de primera clase, las piezas que de otro modo armarías con una extensión por aquí y un servicio por allá:

Imágenes de portada generadas con IA a partir de una referencia gen:, y lecturas de audio (TTS) habladas de cada entrada, direccionadas por contenido y cacheadas
Fontanería de la IndieWeb: microformatos, webmentions y sindicación POSSE a Bluesky y Mastodon, incluidos
Un glosario con enlaces de referencia, presentaciones derivadas de la entrada, y un almacén Obsidian como fuente de primera clase

La búsqueda en el propio sitio merece una mención concreta, y una honestidad concreta. La arquitectura no es original: es el modelo que popularizó Pagefind, un índice fragmentado construido a partir de la salida renderizada, donde el navegador solo descarga los fragmentos que una consulta toca de verdad, y las notas de diseño de colophon lo dicen tal cual. Lo distinto es que es nativa de Go y sin dependencias, con su propio formato abierto en lugar de uno de ingeniería inversa, un lector en JavaScript puro y sin WASM, cuando la forma habitual de conseguir esto es invocar la cadena de herramientas en Rust de Pagefind. Vive como un módulo independiente con una especificación neutral respecto al lenguaje y vectores de prueba dorados, así que indexa cualquier documento {id, url, title, body} y cualquiera puede escribir un lector conforme en otro lenguaje. Estoy contento con cómo quedó, pero la idea no es mía.

Ese paquete es toda la propuesta.

Accesibilidad e idiomas

Dos cosas en las que colophon se esfuerza de verdad, con resultados muy distintos hasta ahora.

La accesibilidad se trata como trabajo del motor, no como algo que heredas del tema que te haya tocado elegir. Ha habido un barrido deliberado hacia WCAG AAA: los bloques de código, los diagramas y las matemáticas en bloque son regiones desplazables enfocables con el teclado, todos los controles tienen un indicador de foco visible, el texto atenuado y los enlaces se llevan al ratio de contraste 7:1 que pide AAA, los marcadores de audio y adjuntos llevan etiquetas reales, las ventanas emergentes del glosario son tooltips accesibles de verdad, y todo el sitio sigue funcionando con JavaScript desactivado. Cualquiera de las herramientas consagradas puede hacerse igual de accesible con un tema cuidadoso; la diferencia es quién carga con ese peso. Aquí va integrado en el motor, no se te deja a ti.

La internacionalización es la parte que todavía se mueve. Los cimientos llevan tiempo ahí: una etiqueta de idioma por entrada que fluye a <html lang>, a los feeds y a Open Graph, además de la interfaz del reproductor y tablas de pronunciación localizadas en seis idiomas. Más reciente, y ahora mismo en pruebas, están las entradas multiidioma de verdad: pones un mi-entrada.es.md junto a la inglesa y obtienes una versión en español en /es/posts/mi-entrada/, enlazada por un slug compartido, con alternativas hreflang, un selector de idioma en la cabecera, y un aviso discreto según la preferencia del navegador que nunca te redirige a la fuerza. Cada traducción es una entrada completa, así que tiene su propia lectura, sus feeds y sus diapositivas. Esta misma página es la prueba: existe una versión en inglés, y el selector de arriba te llevará a ella. Es un experimento con la función, no un cambio de idioma: no voy a empezar a publicar en español, y esta versión es una traducción de la entrada en inglés y no algo escrito por separado, así que léela como una demostración de la fontanería más que como prosa en español. Es pronto, y el soporte multiidioma de Hugo sigue siendo más completo y más probado, pero la base es buena, y es justo el tipo de cosa donde la ayuda sería muy bienvenida.

La parte honesta

No hay ninguna herramienta popular que iguale a colophon función por función. El nicho de binario único con pilas incluidas lo ocupan Zola y Hugo; el espíritu de posee-tu-contenido y federa-por-defecto lo encarna mejor Micro.blog, que es algo encantador pero una plataforma alojada y de pago, no un generador que ejecutas tú. La combinación concreta de colophon no existe en ningún otro sitio en una sola caja, y eso corta por los dos lados: es la razón para mirarlo, y la razón para no hacerlo.

colophon es un trabajo en curso y ahora mismo soy solo yo, así que las contribuciones son muy bienvenidas. La suposición es que la mayoría interactuará con él a través de un LLM y las habilidades que incluye, porque eso es lo que hace que plasmar tus ideas sea rápido, y espero lo mismo de quien quiera trabajar en él. ¿Has encontrado un fallo? Saca tu LLM preferido y manda un PR. Uso mis propias herramientas de agentes (aide), y si tú también las usas heredarás las mismas decisiones capturadas y los mismos estándares de implementación.

Para ser justos en el otro sentido: tus palabras no quedan atrapadas si decides probarlo. La entrada es Markdown plano y la salida es HTML estático corriente, así que mudarte a otra herramienta significa reescribir plantillas y configuración, no rescatar tu contenido. El bloqueo está en las comodidades, no en lo que escribes. Esa es la parte que más me importa, y es cierta para todas las herramientas de aquí.

Entonces, ¿cuándo es colophon lo correcto, si es que alguna vez lo es?

Elige a uno de los consagrados si quieres un blog que simplemente funcione durante la próxima década. Para la mayoría, casi siempre, eso significa Hugo. Elige Jekyll si vives en GitHub Pages, Astro si necesitas componentes, Eleventy si quieres construirlo a tu manera, y Micro.blog si quieres la mitad de IndieWeb y la publicación cruzada sin ejecutar nada en absoluto. O simplemente, cualquiera de los cientos de herramientas que hacen algo parecido, ¡o constrúyete la tuya!

colophon se gana su sitio en un caso concreto: quieres precisamente ese paquete con opinión, imágenes generadas, lecturas habladas, IndieWeb y POSSE, glosario y diapositivas, en un único binario en lugar de cosido a mano.

Es especialmente útil si escribes en Obsidian, y puedes vivir tan tranquilo al borde de un proyecto joven y de un solo mantenedor. Es una razón real. Solo que no es universal, y hoy la persona a la que mejor le encaja soy yo. Lo uso porque quería exactamente estas funciones en un mismo sitio y me conformo con ser mi propio servicio de soporte.

Relacionado

Un blog colophon en Cloudflare Pages y R2: cómo está construido y alojado este blog en realidad.
Conectando el blog a la IndieWeb: la mitad de federación y POSSE, en la práctica.
La entrada es la presentación: una de las funciones incluidas, presentaciones derivadas de una entrada.
Reconstruí el blog. Otra vez.: por qué me fui de Hugo en primer lugar.

I wrote my own site generator. Should you use it?

2026-06-28T00:00:00Z

I built colophon, the generator this blog runs on, so treat everything here as the opinion of a man reviewing his own homework. I've tried to keep it to facts and features rather than affection. Where colophon is the wrong choice I'll say so, because pretending otherwise helps nobody, least of all me.

The boring truth first: almost every static site generator does the same core job. Markdown goes in, a fast pile of static HTML comes out, and you host it somewhere cheap. They differ on three things that actually matter: how mature and well-supported the tool is, what comes built in versus what you bolt on, and who it was written for.

The grown-ups

These are the tools you should reach for by default.

Tool	Runtime	Shape	Best at
Hugo	Go, single binary	Huge, fast, mature	Almost any blog or site: speed, a vast theme and plugin ecosystem, a decade of answers online
Jekyll	Ruby	The original, GitHub Pages' native engine	Zero-config publishing straight from a GitHub repo
Zola	Rust, single binary	Batteries-ish, no plugins by design	A fast single binary with Sass, search and highlighting built in, if you don't need extensions
Eleventy	Node	Minimal, endlessly flexible	JavaScript people who want full control and ten templating languages to choose from
Astro	Node	Content framework with interactive islands	Content sites that also need real interactive components

Hugo is the sensible answer for most people, and it's what this blog originally ran on. It renders a large site in seconds, has by far the biggest theme catalogue, and if you hit a wall someone solved it years ago and wrote it down. Jekyll is older and slower on big sites, but if you just want to push Markdown to GitHub Pages and walk away, nothing is simpler. Zola is the closest of the lot to colophon in spirit: one Rust binary, sensible things built in, and a deliberate refusal to grow a plugin system. Eleventy and Astro are the JavaScript end of the room, Eleventy all flexibility and no opinions, Astro a proper framework for when a "blog" is really an app wearing a blog's clothes.

None of them ship AI media generation, spoken-audio readings, IndieWeb webmentions or POSSE syndication in the box. That isn't a criticism: it's a scope decision, and you can add most of it with plugins and a few external services.

Where colophon is actually different

colophon is also a single Go binary that turns Markdown into a static site, so on the core job it's unremarkable. The difference is what it folds in as first-party features, the parts you'd otherwise assemble from a plugin here and a SaaS there:

AI-generated hero images from a gen: prompt, and spoken text-to-speech readings of each post, content-addressed and cached
IndieWeb plumbing: microformats, webmentions, and POSSE syndication to Bluesky and Mastodon, built in
A glossary with reference links, slide decks derived from the post, and an Obsidian vault as a first-class source

The on-site search deserves a specific mention, and a specific honesty. The architecture isn't original: it's the model Pagefind popularised, a sharded index built from the rendered output, with the browser fetching only the shards and fragments a query actually touches, and colophon's design notes say exactly that. What's different is that it's Go-native and dependency-free, with its own open format rather than a reverse-engineered one, a vanilla-JavaScript reader and no WASM, where the usual way to get this is to shell out to Pagefind's Rust toolchain. It lives as a standalone module with a language-neutral spec and golden test vectors, so it indexes any {id, url, title, body} documents and anyone can write a conformant reader in another language. I'm pleased with how it turned out, but I'm not claiming the idea.

That bundle is the whole pitch.

Accessibility, and languages

Two things colophon tries genuinely hard at, with very different results so far.

Accessibility is treated as the engine's job rather than something you inherit from whichever theme you happened to pick. There has been a deliberate sweep toward WCAG AAA: code blocks, diagrams and display maths are keyboard-focusable scroll regions, every control has a visible focus indicator, the muted text and link colours are pushed to the 7:1 contrast ratio AAA asks for, audio and attachment markers carry real labels, the glossary pop-overs are proper accessible tooltips, and the whole site still works with JavaScript switched off. Any of the grown-up tools can be made just as accessible with a careful theme; the difference is who carries that weight. Here it's baked into the engine, not left to you.

Internationalisation is the part still in flux. The foundations have been there a while: a per-post language tag that flows into <html lang>, the feeds and Open Graph, plus localised player chrome and pronunciation tables in six languages. Newer, and currently being trialled, is proper multi-language posts: drop a my-post.es.md beside the English one and you get a Spanish version at /es/posts/my-post/, linked by a shared slug, with hreflang alternates, a language selector in the header, and a quiet browser-preference banner that never force-redirects. Each translation is a full post, so it gets its own reading, feeds and deck. This very page is the test: there's a Spanish version, and the selector at the top will take you to it. That's an experiment in the feature rather than a change of language here. I'm not starting to post in Spanish, and the Spanish version is a translation of this post rather than something written separately, so read it as a demonstration of the plumbing rather than as Spanish writing. It's early, and Hugo's multilingual is still more complete and more proven, but the bones are good, and it's exactly the sort of thing where help would be very welcome.

The honest part

There is no popular tool that matches colophon feature-for-feature. The single-binary, batteries-included niche is held by Zola and Hugo; the own-your-content, federate-by-default spirit is best embodied by Micro.blog, which is a lovely thing but a hosted, paid platform rather than a generator you run. colophon's particular combination doesn't exist elsewhere in one box, and that cuts both ways: it's the reason to look at it, and the reason not to.

colophon is a work in progress and right now it's just me, so contributions are very welcome. The assumption is that most people will interact with it through an LLM and the skills it ships, because that's what makes getting your thoughts down quick, and I'd expect the same from anyone who wants to work on it. Found a bug? Pull out your LLM of choice and file a PR. I use my own agent tooling (aide), and if you do too you'll inherit the same captured decisions and implementation standards.

To be fair in the other direction: your words aren't trapped if you did choose to give it a try. The input is plain Markdown and the output is ordinary static HTML, so moving to another tool means rewriting templates and config, not rescuing your content. The lock-in is in the conveniences, not the writing. That's the bit I care about most, and it's true of all the tools here.

So when is colophon the right thing, if ever

Pick one of the grown-ups if you want a blog that simply works for the next decade. For most people, most of the time, that means Hugo. Choose Jekyll if you live on GitHub Pages, Astro if you need components, Eleventy if you want to build it your way, and Micro.blog if you want the IndieWeb and cross-posting half without running anything at all. Or simply, any of the hundreds of other tools that do something similar, or roll your own!

colophon earns its place in a narrow case: you specifically want that opinionated bundle, generated images, spoken readings, IndieWeb and POSSE, glossary and slides, in a single binary instead of stitched together.

It's especially useful if you write in Obsidian, and you can happily live close to the edge of a young, one-maintainer project. That's a real reason. It's just not a universal one, and today the person it fits best is me. I use it because I wanted exactly these features in one place and I'm content to be my own support desk.

A Colophon Blog on Cloudflare Pages and R2: how this blog is actually built and hosted.
Wiring the Blog into the IndieWeb: the federation and POSSE half, in practice.
The Post Is the Slide Deck: one of the bundled features, decks derived from a post.
Rebuilt the Blog. Again.: why I moved off Hugo in the first place.

The Post Is the Slide Deck

2026-06-28T00:00:00Z

This one is a bit of an experiment. A blog post and a short talk are often the same material, just delivered differently, and people take things in differently too: some will read a post, some would rather sit through a handful of slides. I wanted to see whether one document could be pulled into more than one medium without any significant rewriting. colophon can now do exactly that: a post projects itself into a themed deck, published at /<slug>/slides/ and linked from its Downloads box, with the deck derived from the post rather than maintained beside it. This post is one: open the Slides link and present it.

One document, more than one medium

The same material, read or presented
No second copy to keep in sync
The deck updates when the post does

A post and a short talk are usually the same argument dressed for a different room, so keeping them as one source, with the deck derived from it, means there's nothing to rewrite and nothing to drift. The post stays the source of truth and the deck is just a view of it. That was the experiment, and so far it seems a useful one.

Turn it on

# colophon.yaml: the site default (off, here)
slides:
  enabled: false

# any post: opt in, in the frontmatter
slides: true

The site sets the default and each post overrides it by key, so a single key you set wins and the rest is inherited. On this blog decks are off in production by default, so a post asks for one on purpose. That is the whole setup: one line of frontmatter and the post grows a deck.

What becomes what

flowchart LR
  P["The post"] --> S["Headings: slides"]
  P --> N["Prose: presenter notes"]
  P --> B["Code, images, tables, maths, diagrams: on the slide"]

Headings split the deck into slides
Paragraphs drop into the presenter notes
Everything else stays on the slide: code, images, tables, maths, diagrams, callouts, pull-quotes

Here is the rule that keeps a slide readable: a paragraph is narration, so it lands in the notes and never on the slide itself. If you want something on the slide, make it a bullet, a code block, a quote, or an image. Write the post the way you always would and the split falls out of it.

Where the breaks go

slides:
  enabled: true
  split: [h2]        # h2 opens a slide; h3 and deeper fold into bullets

Heading levels: h1 through h6
Structural: hr, splitslide
Block kinds: image, table, code, math, diagram, audio, video
text:<match>: break before a block whose text starts with the match

By default every heading opens a new slide. Narrow it with split when you'd rather fold the deeper headings into bullets. This post sets split: [h2], which is exactly why each of these sections is its own slide.

Three inline markers

<splitslide> forces a break mid-section
<slide>…</slide> makes one verbatim slide
<noslide>…</noslide> keeps content in the post but out of the deck

These mirror the <tts> family, and they're escape hatches rather than the main event. I reach for <noslide> most: a Related list or a long aside earns its place in the post but would only clutter a deck. The slide just below is a real <slide>, not a screenshot of one.

One idea per slide

Sometimes a slide should be a single line and nothing else. <slide> gives you exactly that, verbatim.

Present it, or read it

← / → or swipe to move
P presenter notes, F fullscreen
Enter plays the slide's media, Esc closes the deck

With JavaScript it's a keyboard-and-swipe presentation. With JavaScript off, the very same file reads as a long-form document, the slides simply stacked as sections. There's no separate export and no PDF to email round, and it degrades to something useful rather than a blank frame.

On in preview, off in prod

environments:
  - name: preview
    slides: { enabled: true }    # decks on while I'm drafting
  - name: production
    # inherits the site default (off)

A talk is rarely ready the moment the post is. An environment can override the slides default, so the deck rides along on the preview deploy while it's still coming together, and only switches on in production once it's actually any good.

Write the talk once. Let the deck be a view of it, not a second copy.

A Colophon Blog on Cloudflare Pages and R2: where this blog, and the build that now derives these decks, were first set up.
ElevenLabs Voices and Pronunciation Dictionaries: another thing a post grows on its own, a spoken reading.
Wiring the Blog into the IndieWeb: more derived-from-the-post plumbing, feeds and webmentions.

ElevenLabs Voices and Pronunciation Dictionaries

2026-06-25T00:00:00Z

Every post on this blog has a spoken reading, generated text-to-speech (TTS), sitting under the title for anyone who'd rather listen. It's been driven by MiniMax since I added it. Two things have changed recently, and I think they're worth writing down. A caveat first: this is all new and still moving, so treat the specifics as a snapshot that may change.

The short version: there's now a second voice provider, ElevenLabs, and pronunciation dictionaries that work across both. Plus a quiet format change underneath.

Pronunciation dictionaries

The honest problem with generated speech is that it mispronounces exactly the words a technical blog uses most. A voice trained mostly on American English says "raowter" for router, gives cache an extra syllable, and has its own ideas about aluminium. Re-recording isn't an option when the audio is generated, so the fix is to tell the voice how to say specific words.

colophon now takes a pronunciation dictionary, and it applies to whichever provider you're on. The cheapest version is the bundled British one:

generation:
  speech:
    pronunciation_dict: en_GB     # the dictionary shipped with colophon

Or point it at your own file, relative to the site root:

generation:
  speech:
    pronunciation_dict: pronunciation.yaml

The format is small on purpose. Each entry is a word plus one of two ways to fix it:

pronunciations:
  - word: router
    ipa: ˈruːtə        # IPA: precise; rendered to each provider's phoneme mechanism
  - word: nginx
    say: engine x      # respelling: substituted as plain text, works on any provider

The two knobs are worth understanding:

ipa is the International Phonetic Alphabet (IPA) transcription, precise and unambiguous. colophon renders it to each provider's own phoneme mechanism (more on the ElevenLabs side of that below).
say is a plain respelling, substituted as ordinary text before synthesis. It's less exact but completely portable, any voice can read "engine x", no phoneme support required.

One piece of hard-won advice that's baked into the bundled dictionary: keep it small. Overriding a word the voice already says correctly almost always makes it worse. Add a word only after you've heard it get one wrong, and audition the fix before you keep it.

A second voice: ElevenLabs

MiniMax is cheap and fine, but ElevenLabs is the one people reach for when they want a specific, higher-fidelity voice, including a clone of their own. colophon now has an elevenlabs speech driver alongside the MiniMax one. Switching is a config change:

generation:
  speech:
    provider: elevenlabs
    model: eleven_multilingual_v2          # the default; override if you like
    voice: "<your ElevenLabs voice id>"    # a premade voice, or your own cloned one
    api_key: "{env:ELEVENLABS_API_KEY}"

As with every secret in colophon, the key only ever arrives through the environment, never written into the config. It's read from ELEVENLABS_API_KEY (or COLOPHON_ELEVENLABS_API_KEY), so it lives in your keyring or CI secrets exactly like the deploy tokens.

The API key permissions

ElevenLabs lets you scope an API key to specific capabilities, and colophon needs:

Text to Speech: to generate the readings. This is the only permission you need if you're not using a pronunciation dictionary.
Pronunciation Dictionaries (read and write): only if you set pronunciation_dict. ElevenLabs doesn't take IPA inline; it applies pronunciation through an uploaded, versioned dictionary tied to your account. So colophon syncs your ipa entries up to ElevenLabs (it lists, creates, and adds or removes rules on a dictionary it manages for you), then references that dictionary when it synthesises. That sync is why the key needs write access to dictionaries, not just speech.

So: a plain ElevenLabs reading needs Text to Speech alone; add Pronunciation Dictionaries (read/write) the moment you want your ipa overrides to take effect. The say respellings, being plain text substitution, need no extra permission on either provider.

The quiet change: WAV now, Opus later

Underneath both providers, the audio format changed. colophon no longer generates MP3; both drivers now return raw PCM (16 kHz mono) which colophon wraps as a WAV file. Two nice consequences fall out of that. The waveform you see under each reading is computed from that same PCM, so there's no second render just to draw it (the old MiniMax path did a separate call for the waveform, which doubled the token spend, that's gone). And WAV is trivially decodable, so the peaks come for free.

The obvious objection is size: WAV is uncompressed. That's the next piece of work, an Opus (SILK) encoder to shrink the readings without a heavyweight dependency. The plumbing already half-knows about it (.opus is a recognised type), it just isn't wired to an encoder yet. For now the trade is deliberate: simple, decoder-free, accurate waveforms, and pay the bytes until the encoder lands.

Putting it together

So the current shape of a reading: pick a provider (MiniMax or ElevenLabs), optionally give it your voice, and hand it a small pronunciation dictionary so it stops saying "raowter". The dictionary is provider-agnostic; the voice and the key are provider-specific; the output is a WAV and a waveform.

All of this is recent and still settling, so the field names and defaults may move. If you're wiring it up from this post, sanity-check against your own colophon.yaml and the current build.

A Colophon Blog on Cloudflare Pages and R2: where this blog, and its MiniMax media generation, were first set up.
A Palette from a Prompt: the same MiniMax provider, generating desktop wallpapers instead of speech.

Wiring the Blog into the IndieWeb

2026-06-22T00:00:00Z

Having put the blog on Cloudflare Pages and R2, the next itch was to stop it being an island. A static site is a lovely thing to own, but on its own it just sits there: no "someone replied", no way for anyone to follow it without an RSS reader they probably don't have. The IndieWeb answer to that is a handful of small, open standards, and colophon speaks them. This is what I turned on, roughly in order of how much faff each one is.

One note on scope before we start: colophon does the whole loop now, sending these interactions, collecting them, and rendering the replies under your posts. So this isn't plumbing for a someday feature; by the end the conversation actually shows up on the page. The order of operations is what matters, and a couple of the steps are easy to get subtly wrong.

WebSub: real-time feeds, no account

The cheapest win. A normal RSS/Atom feed is polled, so a reader finds your new post whenever it next gets round to checking. WebSub flips that: you ping a hub on publish, the hub pushes to every subscriber at once. Pure config, no signup, in colophon.yaml under your site:

federation:
  feeds: [rss, atom, json]
  websub:
    hubs:
      - https://pubsubhubbub.appspot.com/   # Google's public hub

The ping only fires on a real public deploy, not a local build, so check the publish log for WEBSUB … ping ok, and confirm there's a rel="hub" link in rss.xml/atom.xml and a hubs array in feed.json. A slow or down hub logs a failure and is otherwise ignored; it never breaks the publish.

Sending webmentions: also no account

A webmention is the open web's version of an @-mention: when I link to your post, my site POSTs yours a note saying "this URL mentions you", and your site can fetch mine back to verify it. Sending needs nothing set up, but it has to run after a publish, because the source URLs have to be live for the receiver to verify them:

colophon webmention send --env production --dry-run   # report, don't POST
colophon webmention send --env production             # actually send

It walks the built output, takes each page's canonical URL as the source, collects the cross-origin outbound links as targets, discovers each target's endpoint, and POSTs. It keeps a sent-cache at .colophon/cache/webmention-sent.json, so re-runs only notify new links and re-ping ones you've removed (so the receiver re-checks and drops a mention you deleted). I bolted it onto the end of my publish wrapper, so it fires on every deploy.

Receiving: webmention.io

To collect replies, likes and reposts, point a receiver at webmention.io, a hosted endpoint that catches them for you:

federation:
  indieweb:
    webmention:
      receiver: https://webmention.io/blog.i0.pm/webmention

With that set, colophon emits a <link rel="webmention"> discovery tag site-wide, which is how anyone (and Bridgy Fed, if you go that way) knows where to send mentions. The endpoint keys on your domain, so the path stays blog.i0.pm regardless of which page is mentioned.

Showing the responses

Collecting them is only half of it; the point is to show the replies and likes under the post. colophon does this two ways, and the choice is a proper trade-off:

federation:
  indieweb:
    webmention:
      receiver: https://webmention.io/blog.i0.pm/webmention
      display: { mode: live }            # or: asset
      token: "{env:WEBMENTION_IO_TOKEN}" # only used by asset mode

asset self-hosts the data: a colophon webmention fetch pulls your mentions back through the API token, caches them, and bakes a small JSON file per post that ships with the site. The responses are served from your own origin, work without hammering anyone else, and degrade gracefully. The cost is that they only refresh when you fetch and redeploy (a cron job, or a decoupled webmention publish that pushes just the mentions without rebuilding the site).
live skips all of that: the reader's browser fetches the receiver directly on each page load, so a new reply shows up the next time anyone opens the post, no rebuild, no token, no cron. The cost is honesty about two things, it needs JavaScript (so the responses don't exist for a no-JS reader), and it points your visitors' browsers at a third party.

There's a third path you don't pick directly: a no-JS theme. The engine can bake the responses into the HTML at build time from the same asset-mode data, so a theme that ships no JavaScript (the bundled minimal does exactly this) still renders replies and likes, server-side, no client script. The JS themes use a placeholder the script fills; the no-JS ones get it pre-rendered. Same data, the theme decides how it arrives.

I went with live. This is a personal blog, not a fortress; I'd rather a reply appear the moment it lands than run a cron to refresh a cache, and the responses are an enhancement below the article, not the article itself. I've left the token: line in the config anyway, pointing at WEBMENTION_IO_TOKEN (keyring COLOPHON_WEBMENTION_IO_TOKEN, exported by the publish wrapper), so flipping to asset later is a one-word change rather than a dig through the docs.

POSSE: publish here, syndicate everywhere

Webmentions handle the conversation; the other half of owning your content is POSSE, Publish on your Own Site, Syndicate Elsewhere. The canonical copy lives here, and a copy goes out to the silos where people actually are, each one linking back. colophon has a syndicate step for it, deliberately separate from publish so the original is always live first:

federation:
  syndication:
    - id: bsky
      driver: bluesky
      handle: "{env:BLUESKY_HANDLE:-}"
      app_password: "{env:BLUESKY_APP_PASSWORD}"   # an app password, not your login
# and on the environment:
environments:
  - name: production
    syndicate: [bsky]      # only listed targets fire; preview/draft envs omit it, so they never post

There are four drivers, and the choice comes down to who holds the keys: mastodon and bluesky post directly to your account with a token (or a Bluesky app password) you control; bridgy posts on your behalf via Bridgy so colophon holds no silo credentials at all; and command runs any program you like for anything without a built-in driver. I started with Bluesky, direct, my app password, one account to reason about.

The flow mirrors the webmention one, run it after a publish so the canonical URL is live:

colophon syndicate --env production --dry-run        # preview; posts nothing, writes nothing
colophon syndicate --env production --allow-publish    # post the copies, record the ledger

The ledger at .colophon/syndication.json (commit it) is the idempotency guard: it remembers what went where, so re-running never double-posts, and it feeds the "Also posted on…" links back on the post. Per-post you can opt out with syndicate: false, narrow to a subset with syndicate: [bsky], or write a custom blurb with syndicate_text:. Secrets, as ever, only arrive via {env:VAR}.

One thing not to confuse: this is syndication (push a copy out). It's a different job from making the site itself followable from the fediverse, that's Bridgy Fed, which hangs off the webmention receiver, not the syndication list. Same neighbourhood, different houses.

Signing in as your own domain

One detail worth getting right. webmention.io doesn't have its own password; you sign in as your own website using IndieAuth, via indielogin.com. For that to work, the URL you log in with and an identity provider it trusts (GitHub is the easy one) have to link to each other with rel="me", at the same URL on both ends.

colophon emits the rel="me" link from your author's urls:, so set that in authors/<id>.yaml:

# authors/jmylchreest.yaml
urls:
  - https://github.com/jmylchreest

GitHub does the other half for you: the website field on your profile is published with rel="me" automatically. So your site points at GitHub, GitHub points back at your site, the loop closes, and indielogin.com is happy to authenticate you through GitHub.

The catch is which page carries the rel="me". The link rides on colophon's author h-card, and the loop only closes if the page you log in with is the same one GitHub links back to. Make sure your GitHub website field and the URL you sign in with are the same, and that it's a page that actually renders the author card. On current colophon (v0.0.8) the author page does, so:

GitHub profile website: https://blog.i0.pm/authors/jmylchreest/
Sign in to webmention.io with: the same https://blog.i0.pm/authors/jmylchreest/

Match those two and the login goes straight through. Mismatch them, even by a trailing path, and you get "we couldn't find any way to authenticate you", which just means the two pages didn't point at each other.

What you get

So, the full loop: feeds that push instead of waiting to be polled, outgoing webmentions firing on every publish, a receiver banking every reply and like against the domain, and those responses rendering live under each post, the moment someone opens it. If you've replied to this from your own site or boosted it on the fediverse (via Bridgy Fed), you should be looking at the evidence a little further down the page.

It's a strange and rather nice feeling, wiring a static site you fully own into a conversation with the rest of the web, without renting a single feature from anyone. More of the web should work like this.

A Colophon Blog on Cloudflare Pages and R2 — the Pages + R2 setup this builds on.
Rebuilt the Blog. Again. — why the blog runs on colophon in the first place.

A Colophon Blog on Cloudflare Pages and R2

2026-06-21T00:00:00Z

I rebuilt this blog on colophon a few days ago and said it deploys with one command. This is the post that earns that claim: standing up a brand new colophon site on Cloudflare Pages, with the images and search index living in R2 rather than shipping with the deployment. Nothing here is secret sauce, but the order of operations matters, and a couple of the steps are easy to get subtly wrong.

The shape of it: Pages serves the HTML, R2 serves the heavy assets. Pages has a file count and size budget; a blog with a few hundred generated hero images will blow through it. So colophon routes anything matching **/assets/** and the search index to an R2 bucket and rewrites the URLs to point there. The reader's browser fetches pages from one origin and images from another, and neither you nor they have to think about it.

What you need from Cloudflare

Make a Cloudflare account if you haven't, then collect three things.

Account ID

It's in the dashboard URL once you're logged in (dash.cloudflare.com/<account-id>/...), and on the right-hand sidebar of any zone's overview page. This is not a secret, but colophon needs it for both the Pages and R2 publishers.

API Token

Profile → API Tokens → Create Token → Create Custom Token. The publishing docs list the exact permissions, and they are tighter than the "Edit Cloudflare Workers" template you'll be tempted to grab. For one token that does both jobs:

Account → Cloudflare Pages → Edit: deploys the site.
Account → Workers R2 Storage → Edit: reads and writes objects, and creates the bucket.

That second one is the gotcha. The S3-style colophon publish --create step also flips the bucket to public and sets a CORS policy, and that needs R2 Admin read and write, not just object read and write. If --create later complains it "needs R2 Admin Read & Write", this is why. You can use a narrower object-only token for day-to-day publishing once the bucket exists.

An R2 access key pair

R2 → Manage R2 API Tokens → create one. You get an R2_ACCESS_KEY_ID and an R2_SECRET_ACCESS_KEY; R2 speaks S3, so these are the S3 credentials the publisher uses, separate from the Cloudflare API token above.

DNS and a custom domain

Two domains, ideally: one for the site, one for the assets. I serve the blog at blog.i0.pm and assets at assets.i0.pm.

Site: in the Pages project, Custom domains → add blog.example.com. If the zone is on Cloudflare, the CNAME is created for you; if not, add a CNAME to <project>.pages.dev and let it verify.
Assets: in the R2 bucket, Settings → Public access → Custom domains → add assets.example.com. That public hostname is what you'll hand colophon as the R2 public_url, and until it resolves, the asset routing stays dormant and builds keep assets co-located. Handy for local work.

Scaffold the project

init writes the project; publish --create provisions the destinations later. Don't conflate the two.

colophon init blog && cd blog

That gives you a colophon.yaml, a content/ directory (which is also an Obsidian vault, if you want it), an author, and a persona. Open colophon.yaml and wire up the two publishers and a production environment. The key point, and the thing the publishing docs lean on hard: no secret ever goes in this file. Non-secret settings use {env:VAR} interpolation; credentials are read straight from the environment and never touch the YAML.

sites:
  - id: main
    title: "Your blog"
    base_url: "{env:SITE_URL:-http://localhost:8080}"
    routing:
      - match: "**/assets/**"   # heavy assets → R2, not the Pages bundle
        publisher: r2
      - match: "_search/**"     # search index fetched cross-origin → R2 (needs CORS)
        publisher: r2

publishers:
  - id: cf
    driver: cloudflare-pages
    project: "{env:CF_PAGES_PROJECT:-my-blog}"
    account_id: "{env:CLOUDFLARE_ACCOUNT_ID}"
  - id: r2
    driver: cloudflare-r2
    bucket: "{env:R2_BUCKET:-my-blog-assets}"
    account_id: "{env:CLOUDFLARE_ACCOUNT_ID}"
    public_url: "{env:R2_PUBLIC_URL:-}"   # https://assets.example.com; empty keeps routing inert

environments:
  - name: production
    publish: [cf, r2]
    allow_publish: false        # safety latch: deploy needs --allow-publish
    base_url: "https://blog.example.com"
  - name: preview
    publish: [cf, r2]
    include_drafts: true        # drafts visible here, never in production
    overrides:
      cf:
        branch: preview         # its own Pages branch / preview URL

colophon env lists every {env:VAR} the project references, set or not, which is the quickest way to see what you still owe it.

Sites, publishers, environments: why three nouns

colophon deliberately splits the job three ways, and it's worth understanding because it's what makes the rest painless. A site is the content and its identity (title, theme, what gets written). A publisher is pure mechanism: how to ship bytes somewhere (to Pages, to R2, to a local folder), with no opinion about when or why. An environment is the policy that ties them together: a named build-and-deploy profile that says which publishers to use, whether to include drafts, and any overrides. The publishing docs put it as publishers being how and environments being what and where.

That separation is why I run two environments off the one site: production and preview. They share the same content, the same publishers, the same R2 bucket; they differ only in policy.

production ships only finished posts (draft: false), to blog.example.com, on the main Pages branch, and it's behind the allow_publish: false safety latch so a deploy is never accidental.
preview sets include_drafts: true and overrides the Pages branch to preview, so it builds the work-in-progress and Cloudflare serves it at its own preview URL. I can read a draft on my phone, exactly as it'll render, before anyone else sees it.

I publish both because they answer different questions. Preview is "does this actually look right, live, with the real images and search index?" Production is "the world can read this now." Splitting them means a draft can be deployed somewhere real and private without ever risking the public site, and promoting it is just flipping draft: false and publishing production. Same content, two policies, one command each:

colophon publish --env preview --allow-publish      # drafts, preview branch
colophon publish --env production --allow-publish    # finished posts only

Nothing about either environment is special or built in; you could add a staging, a second-site mirror, or a local dist target for diffing output. Two is just the smallest set that gives me "private dress rehearsal" and "live" without duplicating a scrap of content.

Where the secrets live

The interpolated {env:VAR} values split cleanly into two piles:

Not secret (CLOUDFLARE_ACCOUNT_ID, CF_PAGES_PROJECT, R2_BUCKET, R2_PUBLIC_URL, SITE_URL): commit these to a .env.defaults in the repo. colophon loads it automatically.
Secret (CLOUDFLARE_API_TOKEN, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, MINIMAX_API_KEY): never in the repo, never in config. These come from the environment at publish time.

How they reach the environment depends on where you are:

Locally: out of the Secret Service. I keep mine in rosec (the keyring replacement I wrote about in Secrets, Minus the Keyring), namespaced COLOPHON_*, and pull them with secret-tool at publish time so the tokens never sit in a plaintext .env or in my shell history. A small wrapper resolves them to the bare names colophon wants, runs colophon doctor as a preflight, then publishes:
```
# store once: secret-tool store --label='colophon: …' service colophon key COLOPHON_<NAME>
for name in CLOUDFLARE_API_TOKEN R2_ACCESS_KEY_ID R2_SECRET_ACCESS_KEY MINIMAX_API_KEY; do
  export "$name=$(secret-tool lookup service colophon key "COLOPHON_$name")"
done
colophon doctor && colophon publish --env production --allow-publish
```
In CI: as encrypted GitHub Actions secrets, exposed to the job as env vars. colophon scaffolds a workflow that reads CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, R2_ACCESS_KEY_ID and R2_SECRET_ACCESS_KEY straight from secrets.*. Same variable names, different source.

The whole design is that the names are constant and only the source changes, so the same colophon publish runs unmodified on your laptop and in Actions.

Provision, then publish

First time only, let colophon create the Pages project and the R2 bucket (idempotent, so it's safe to leave in):

colophon publish --env production --create --allow-publish

--create makes the Pages project, creates the bucket, and sets the bucket's CORS policy so the cross-origin fetch() of the search index works. A cross-origin <img> needs no CORS; a fetch() or an ES import() does, which is why the search index specifically needs it. After that, the daily incantation is just:

colophon publish --env production --allow-publish

Generative images and a spoken reading

This is the part I enjoy. colophon can generate hero images from a text prompt and a spoken reading of each post. The provider is your choice: image generation can go through Google GenAI or OpenRouter just as happily, and you're not obliged to use any of it. I picked MiniMax (the same provider tinct uses for palettes) because it's cheap and effective, and one key, MINIMAX_API_KEY, drives both the images and the speech. Swap the provider: lines below if you'd rather use something else.

generation:
  image:
    provider: minimax          # image-01; api_key falls back to MINIMAX_API_KEY
    system_prompt: "editorial tech illustration, dark muted palette, full-bleed, no text"
    defaults: { aspect: "16:9" }
  speech:
    provider: minimax          # speech-2.6-hd; same key
    enabled: true              # every post gets a reading unless it sets audio: false

The clever bit, documented in image-generation.md, is that the repo is the cache. Any hero: or inline image whose value starts with gen: is generated from the prompt, content-addressed, and the result is committed to the repo. A normal colophon build ships whatever's cached and never calls the API; you only spend tokens when you explicitly ask:

colophon build --generate-ai      # or: colophon publish ... --generate-ai

So a hero is just a sentence in the frontmatter:

hero: "gen:a worn mechanical keyboard lit by a single monitor in a dark room"
hero_alt: A worn mechanical keyboard lit by a single monitor in a dark room

Change the system_prompt and you change the cache identity, so the next --generate-ai regenerates everything. Useful to know before you tweak it at midnight and wonder why your whole back catalogue is redrawing.

The reading uses one of the provider's stock voices by default, but you don't have to settle for a stranger reading your words. MiniMax (and the others) let you clone a voice from a short sample of your own, which gives you a voice profile ID you can point colophon at. Set it once on the author or persona as voice:, or per post with audio_voice:, and every reading goes out in your own voice rather than a generic one:

audio_voice: "my-cloned-voice-id"   # frontmatter: this post in your own voice

That's on my list: the default here is a placeholder until my own clone is trained.

The frontmatter that actually matters

You don't write most of this by hand, and that's the point. colophon new post "Title" picks a unique pinned slug:, stamps the date:, sets the byline author: and the writing persona:, and leaves the post draft: true. The fields worth understanding, all detailed in content.md and seo.md:

slug:: pinned at creation so the URL never drifts when you retitle. Leave it alone.
draft:: true keeps it out of production but visible in the preview environment.
description:: the one-line summary used in listings and as an SEO fallback.
hero: / hero_alt:: the banner image (a path, an ![[embed]], or a gen: prompt) and its alt text. Always write real alt text for a meaningful image; an empty hero_alt: marks a purely decorative one.
seo:: an optional block for a distinct page title, keywords, and social-card copy when the defaults aren't enough.
audio: false: opt a single post out of the spoken reading.

Writing it with an LLM, in your own voice

If you're writing with an LLM or an agent harness, this is where it gets genuinely pleasant, and it's the part I'm most quietly pleased with. colophon ships a set of agent skills, the most important being write. There are companions for metadata, cross-linking and publishing too, but write is the one that matters, because it solves the thing that makes LLM-written blogs so obviously LLM-written: they all sound the same.

The trick is that the model never starts from a blank prompt. Before it writes a word, the skill runs:

colophon persona context default --topic "what the post is about"

That does two things. It hands over the persona's style guide (the explicit rules: British spelling, no em dashes, lead with the point, the tone), and then it reaches into the corpus of your past posts and pulls back the handful most relevant to this topic, ranked with BM25. So a post about distributed systems gets fed your actual previous writing on distributed systems; a hardware teardown gets your teardowns. The model isn't told "write like a thoughtful British engineer" in the abstract, it's shown concrete examples of how you actually write, about this kind of thing, and asked to continue in that vein. The voice it produces is a reflection of your own corpus, not a generic pastiche of one, and it sharpens as the corpus grows: every post you publish becomes an exemplar the next one can learn from.

With the voice loaded, colophon new post scaffolds the file with the frontmatter contract already correct, and the model fills the body and the prose-level fields (description, alt text, tags), told not to touch the pinned slug or invent links. The harness handles the bookkeeping; you (or the model in your voice) handle the words. This very post was drafted that way.

colophon new post "Raft Leader Election" --author you --persona default --tag distributed-systems
colophon serve --open=latest    # preview before you flip draft: false

Flip draft: false, run the publish command, and it's live. One command, as promised. The infrastructure is your own fault now, which is rather the appeal.

A Palette from a Prompt

2026-06-20T00:00:00Z

A tinct palette can already come from a text prompt, not only from a wallpaper, a photo or a remote theme: it has generative inputs for Google GenAI and OpenRouter already. v0.4.0 adds a third, minimax, which generates an image from a prompt through MiniMax's Hailuo model (image-01) and then extracts the palette the usual way, k-means over the pixels. What it brings to the line-up is being cheap and fast: a single image model, nothing to choose, and a quick endpoint.

The nice part is that it's one step, not two. The same tinct generate call that derives the palette also caches the generated image and exports it as a wallpaper, so a single command turns a prompt into a coherent desktop and the wallpaper that matches it:

export MINIMAX_API_KEY="…"
tinct generate -i minimax \
  --ai.prompt "cyberpunk city street with neon signs at night" \
  -o hyprland,hyprpaper,kitty

Generated images are cached under ~/.cache/tinct/generated/minimax/, keyed by a hash of the prompt and model, so re-running the same prompt is free. One wrinkle worth a fix: MiniMax occasionally pads its output with black letterbox bars, which would skew both the extracted palette and the wallpaper, so the plugin trims them before either step.

It's a small addition, another generative backend sitting alongside Google and OpenRouter, so you can pick whichever provider suits your budget and taste and still theme straight from a prompt. AUR tinct-bin; the full input-plugin list is on the tinct site.

Best Practices, Bootstrapped

2026-06-18T00:00:00Z

A fresh project starts with an empty head. aide records the architectural decisions a codebase has made, so a session and every agent in it argue from the same facts. But on day one there are no decisions, and you're back to either re-litigating the same conventions you settle on in every repo, or letting the agent quietly invent its own.

Blueprints are the fix: curated bundles of best-practice decisions you seed a project with in one command.

aide blueprint import go

That drops a set of idiomatic-Go decisions straight into the project's store: error handling, context use, table-driven tests, slog, golangci-lint, and so on. From that point they behave exactly like decisions you recorded by hand. They're injected into every session's context and enforced by all agents, so the conventions are present before the first line is written rather than discovered halfway through review.

Composable, not monolithic

The thing I like most is that blueprints stack. A blueprint can include others, so they compose along the grain of how projects are actually built:

# go, plus the CI/CD practices, plus the universals they both build on
aide blueprint import go-github-actions

go includes general (commits, PRs, dependency hygiene, secrets), general includes the documentation core, and go-github-actions layers the CI specifics on top. You ask for the leaf you want and the chain underneath comes with it. No copy-paste, no drift between a dozen repos that all meant to follow the same rules.

It detects what you're building

You don't even have to name them. --detect reads the project's markers and imports what fits:

$ aide blueprint import --detect
Detected: go, github-actions, go-github-actions

  general            5 new
  go                18 new
  github-actions     7 new
  go-github-actions  5 new

35 imported, 0 updated

A go.mod triggers the go pack; a .github/workflows/ directory triggers the github-actions label; the two together resolve the compound go-github-actions blueprint. It runs on the same project-marker index the grammar system uses, so a custom marker in your own .aide/grammars/ can trigger an org-specific blueprint automatically. Bootstrapping the house style across a fleet of repos becomes one command per repo.

Versioned, and it knows what it set

Seeding state is easy; keeping it honest later is the part that usually rots. Blueprints carry a version, and an import is careful about what it touches. Anything you set by hand is left alone. A decision a blueprint set earlier is upgraded only if the blueprint's version is newer and the content actually changed. Every imported decision is stamped decided_by: blueprint:<name>@<version>, so you can always tell the curated baseline from the calls you made yourself.

That provenance is what makes the whole thing safe to re-run. aide blueprint import --detect on an existing project is a no-op where nothing moved and a clean upgrade where the upstream advice improved, and it never quietly overwrites a decision you made deliberately.

The shipped blueprints are a starting point, not the ceiling. A blueprint is just a JSON file of decisions, so the more interesting use is writing your own: your team's conventions, the house style, the "we always do it this way, and here's the reasoning" rules that currently live in a wiki page nobody reads twice. Drop one in .aide/blueprints/ to override a shipped blueprint locally, or publish a whole set for everyone.

Sharing is deliberately boring. A registry is just a base URL that serves <name>.json files, so any static host works: an internal web server, an S3 bucket, a GitLab repo on the intranet. Point a project's config at it once,

// .aide/config/aide.json
{ "blueprints": { "registries": ["https://blueprints.corp.internal"] } }

and aide blueprint import acme-standards pulls your org's rules exactly the way go pulls the built-in ones. (There's a --registry= flag for one-offs, and you can import a bare URL too.)

The point, for a team, is that "the way we do things here" stops being tribal knowledge you hope new hires (and their AI assistants) absorb by osmosis. Write the guidelines, styles and general rules down once, host them where your devs already have access, and aide injects them into every session, so every human and every agent on the project works from the same rules without anyone having to remember to bring them up.

Why bother

The honest value isn't the import command, it's the curation. Writing down "use errors.Is, not string matching" once, well, with the reasoning attached, and then having it apply to every Go project you or an agent ever touch, is a different thing from remembering to say it each time. The blueprint is the decisions; the command is just how they arrive. Repo and the full blueprint list are on GitHub.

Rebuilt the Blog. Again.

2026-06-18T00:00:00Z

The previous incarnation of this blog ran on Hugo with a rather nice theme and exactly zero real posts. It had a first post that began "Lorem ipsum dolor sit amet" and an about page extolling Bootstrap 5. A monument to good intentions, lovingly version-controlled and never once written in.

So this is less a migration than a fresh start. There was nothing to port, just demo content and a title I'm rather fond of.

This time it runs on colophon, a static-site generator I've been writing. Markdown in, static HTML out; an Obsidian vault as the source, so I can scribble a note and have it become a post without leaving my editor. Search is static and on-device, there's no JavaScript required to read anything, and the whole thing deploys with one command.

Whether this version accumulates more than one post remains to be seen. But the infrastructure is, at least, my own fault now.

Learning From the Session

2026-06-15T00:00:00Z

aide's memory has always been something you write: you tell it a preference, it remembers. The more interesting question is whether it can notice things you didn't think to write down. That's what the instinct system is for, and it leans on a quieter piece of plumbing that landed first: observability.

aide now instruments itself. Every tool call, every skill it injects, every session is an observed event with a span and a cost, the same stream that feeds the token dashboard. Instinct reads that stream looking for patterns worth keeping: the same correction you've made three times, a tool that keeps failing the same way (friction is a strong signal that something's wrong with the convention, not just the call). When a pattern converges, aide proposes it as a candidate memory, which you accept or bin. The point is that the assistant stops repeating a mistake because the lesson got written down, by the tool, from watching, rather than waiting for you to notice and dictate it.

The mechanism is a Stop hook called reflect: at the end of a session it runs the instinct parser over that session's observe events and surfaces the proposals. It's deliberately opt-in and still experimental, so it's off by default; you turn it on with AIDE_REFLECT=1 or "reflect": { "enabled": true } in .aide/config/aide.json. The newest tier adds an LLM judge for promotion (is this repetition actually a rule, or coincidence?) and a friction detector that treats repeated tool failures as live signal.

It's the part of aide I'm least sure how far to push, which is exactly why it's behind a flag. Memory you write is predictable; memory the tool proposes from watching you is powerful and occasionally presumptuous, and I'd rather earn that trust than assume it. Repo and docs on GitHub.

Two Razer Naga Buttons, One Keycode

2026-06-15T00:00:00Z

I have a Razer Naga V2 HyperSpeed. The whole point of it is the twelve-button grid under your thumb, so I sat down to remap those buttons on Linux with input-remapper, expecting a five-minute job.

It went wrong immediately. Button 11 did exactly what button 6 did; button 12 did exactly what button 2 did. Not "similar": evtest showed them emitting byte-for-byte identical scancodes (7002d → KEY_MINUS for both 6 and 11). input-remapper saw them as the same key, so there was nothing to remap.

The instinct is to go looking for a better remapper. That instinct is wrong, and it's worth seeing why. MSC_SCAN is the HID usage code, what the mouse literally puts on the wire. If two buttons send the same usage, they send the same scancode; there's no hidden serial number. evdev hands userspace (type, code, value) plus that scancode hint, and that's the entire vocabulary. If two events are identical across all of it, any userspace remapper is downstream of the collision. You can't branch on information that doesn't exist.

So the duplicate isn't made in software; it's made upstream, in the mouse, before Linux ever sees it. The Naga has onboard memory, and mine had a junk profile baked into it (button 1 was mapped to Shift+3, and two pairs of buttons collided onto one key). Normally you'd rewrite those slots with Razer Synapse on Windows. Nothing on Linux can: OpenRazer doesn't do button remapping, libratbag refuses Razer over the EULA, and the web tools don't cover this model.

The fix: driver mode

Razer mice expose a device_mode switch through the OpenRazer kernel driver. Normal mode (0x00) replays the onboard profile, my broken one. Driver mode (0x03) makes the firmware ignore the profile and emit its raw factory layout: twelve unique keys. One write does it:

echo -n -e '\x03\x00' | sudo tee /sys/bus/hid/devices/*1532*00B4*/device_mode

And evtest immediately goes clean: button 6 is KEY_6, button 11 is KEY_MINUS. The collision is gone because the firmware stopped lying.

It resets on power cycle, so you need to re-apply it. The cleanest way is to let OpenRazer own it: it re-applies on startup, hotplug and resume, by setting driver_mode = true per device in ~/.config/openrazer/razer.conf. (One trap: the section is keyed by serial, and this unit's serial read is flaky, so I declared both the real serial and the UNKNOWN_… fallback.) A udev rule on bind works too, but won't survive suspend.

That covers boot, hotplug and resume, which is most of it. Every so often a wireless wake still comes back with the broken profile reasserted, so rather than dig through anything mid-game I keep a one-tap "fix my mouse" bind. No sudo this time: I'm in the openrazer group, so the udev-owned sysfs is writable directly, and a tiny script forces driver mode then re-applies my DPI:

bindd = $mainMod, Pause, Naga driver mode, exec, ~/.local/bin/naga-driver-mode

#!/bin/sh
# ~/.local/bin/naga-driver-mode
for dm in /sys/bus/hid/devices/*1532*00B4*/device_mode; do
    [ -e "$dm" ] || continue
    printf '\003\000' > "$dm"
done
~/.config/hypr/scripts/naga-dpi-cycle.sh apply   # a wake can reset DPI too

A button starts lying, I hit the chord, and the mouse is honest again before I've lost the fight.

A few side effects come with bypassing the onboard profile. The dedicated DPI button stops cycling, so I drive DPI from Hyprland instead (below). Reading DPI and device_mode back both lie even though writes work fine. And the battery never shows up in UPower for this mouse, so I read the charge level straight from OpenRazer (charge_level in sysfs, 0–255, or over its D-Bus). None are deal breakers, just the tax for making the hardware honest.

Getting DPI back

Driver mode has one cost worth its own section: the onboard DPI button stops cycling, because the cycling was the onboard profile. OpenRazer can still set DPI by writing the dpi sysfs, though, so I moved the whole thing into Hyprland.

The two profile buttons either side of the wheel emit F13 and F14, which Hyprland sees as code:191 and code:192. I bind those to a small stage-cycler:

bindd = , code:191, Naga DPI down, exec, ~/.config/hypr/scripts/naga-dpi-cycle.sh down
bindd = , code:192, Naga DPI up,   exec, ~/.config/hypr/scripts/naga-dpi-cycle.sh up

The script keeps a list of DPI stages, tracks the current one in a state file (so it survives a reboot), and writes the chosen value to the dpi sysfs as four big-endian bytes (X-hi, X-lo, Y-hi, Y-lo). It never reads DPI back, because that's the part that lies; it only writes.

#!/usr/bin/env bash
# naga-dpi-cycle.sh [up|down|apply]: step the Naga through DPI stages.
# (Trimmed here of the device-not-found guard and the notify-send.)
set -eu
STAGES=(400 800 1000 1200 1600 3200)
state="${XDG_STATE_HOME:-$HOME/.local/state}/naga-dpi-stage"
dpi=$(ls /sys/bus/hid/devices/*1532*00B4*/dpi | head -1)
last=$(( ${#STAGES[@]} - 1 ))

idx=$(cat "$state" 2>/dev/null || echo 3)        # default: stage 4 (1200 dpi)
case "${1:-apply}" in
    up)   idx=$(( idx < last ? idx + 1 : last )) ;;
    down) idx=$(( idx > 0    ? idx - 1 : 0    )) ;;
esac
printf '%s' "$idx" > "$state"

val=${STAGES[idx]}; hi=$(( (val >> 8) & 0xff )); lo=$(( val & 0xff ))
printf "$(printf '\\x%02x\\x%02x\\x%02x\\x%02x' "$hi" "$lo" "$hi" "$lo")" > "$dpi"

One exec-once restores the last stage on login, since a wireless wake can reset that too:

exec-once = ~/.config/hypr/scripts/naga-dpi-cycle.sh apply

The short version: if two buttons send identical evdev events, stop blaming the remapper and go fix the mouse.

For now driver mode is the answer, and it holds. One day I might give in, boot Windows, and write a clean profile with Synapse just once, so the hardware behaves on its own and I can drop the whole arrangement. Or, better yet, Razer decides Linux is worth treating as a first-class citizen and none of this song and dance is necessary. I'm not holding my breath. I would, though, love to be wrong.

One Core, Many Bootloaders

2026-05-29T00:00:00Z

refind-btrfs-snapshots started life answering one question, "how do I make rEFInd offer my btrfs snapshots?", but the interesting work, snapshot discovery, kernel inspection and fstab alignment, was never really about rEFInd. It was about figuring out how a given snapshot wants to boot. rEFInd was just the first thing I rendered that into.

So the project has been refactored into a shared core with a focused binary per boot story:

refind-btrfs-snapshots: rEFInd submenu entries (where it began).
bls-btrfs-snapshots: Boot Loader Spec entries for systemd-boot and BLS-aware GRUB.
uki-btrfs-snapshots: per-snapshot Unified Kernel Images (more on this below).
peseal: a pure-Go Authenticode signer for PE/UKI binaries, sbctl-compatible, so the UKI path stays CGO-free.
kernel-spy: a read-only diagnostic that dumps every kernel, initramfs, microcode and UKI the discovery layer can see.

One core, many front-ends: the same shape I keep coming back to, because the hard part is the analysis, not the output format.

The UKI problem

Unified Kernel Images are where this gets genuinely tricky, and they're the "support other formats more generically" goal I'd been circling. A UKI bundles kernel, initramfs, cmdline and os-release into one signed EFI binary, and crucially the cmdline lives inside the image, in its .cmdline section. Under Secure Boot that embedded cmdline is authoritative: the boot loader can't override it with an external options= string.

That's fatal for snapshot booting, because a snapshot-bootable cmdline has to differ per snapshot: it carries rootflags=subvol=<snapshot>. Neither the rEFInd nor the BLS output can fix this, because the thing that needs to change is sealed inside the UKI. The cmdline has to go inside an image the firmware will actually run.

What ships today is Mode 1, cloned UKIs. For each bootable snapshot, clone the source UKI into <esp>/EFI/Linux/, copying the kernel and initrd straight across and rewriting only the .cmdline to target that snapshot's subvolume. It costs a full UKI's worth of space per snapshot, but it boots anywhere that can launch an .efi, and peseal signs each one so Secure Boot stays intact.

What's still in design

The cheaper approach is Mode 2, a single multi-profile UKI per kernel, with one .profile section per snapshot sharing the kernel and initrd and carrying only its own cmdline. It's a lovely idea with a sharp edge: today, passing a profile selector at boot is essentially a systemd-boot story, so it isn't yet the universal answer cloning is. That, plus a proper reconciliation engine (compute the desired set of entries from scratch each run, diff against what's on the ESP, delete before adding, and pre-flight the free space so it refuses loudly rather than half-filling your boot partition), is written up in the project's wishlist and is what I'm building toward next.

The throughline: a snapshot you can't boot is just a backup you haven't tested. The point of all five binaries is to make "boot last Tuesday" work whatever your firmware, bootloader and Secure Boot setup happen to be. Repo and wishlist on GitHub.

Many Agents, One Repo

2026-05-25T00:00:00Z

"Run a bunch of agents in parallel" is the kind of thing that demos beautifully and then corrupts your working tree the first time two of them edit the same file. The hard part of multi-agent work was never spawning the agents; it's keeping them from standing on each other. That's what aide's swarm is actually about, and it just grew a proper coordination layer.

Two design choices do most of the work.

Isolated git worktrees. Each agent works in its own worktree, not the shared checkout. They can edit, build and test in parallel without colliding, and the results merge back deliberately rather than racing. A blast radius of one worktree is a very different thing from a blast radius of your branch.

Atomic task claiming. Work is a queue of tasks, and an agent claims one atomically before touching it: no two agents pick up the same task, and a crashed agent's task is reclaimable rather than lost. With the new coordination layer that's gRPC streaming over the daemon, an agent CLI to drive it, and a dashboard to watch it happen.

The other half is that the swarm runs work through an actual SDLC pipeline (design → test → implement → verify → docs) rather than asking one agent to do everything in one shot. Each stage is a checkpoint, which is how you get a reviewable result out the far end instead of a pile of plausible diffs.

None of this is "AGI writes your app while you sleep." It's the unglamorous orchestration (worktrees, queues, claims, stages) that makes parallel agents safe enough to be useful. Which, predictably, was far more work than the demo version. Repo and docs on GitHub.

awob: Another Wayland Overlay Bar

2026-05-04T00:00:00Z

If wob covers what you need, use wob. It's tiny, fast, and battle-tested. awob exists for the moment where you want one more thing wob doesn't try to give you.

I've been using wob for years. It does exactly one thing, reading a number from a FIFO and drawing a bar, and it does it without ceremony. Volume up? A bar. Brightness down? A bar. Battery at 5%? A red-ish bar. That's the entire shape of it, and most days it's exactly the right shape.

But the moments where it isn't quite enough kept piling up. I wanted an icon next to the bar to remind me whether I was looking at volume or brightness. I wanted the active sink's name when the volume changed. I wanted a different style for "muted" versus "loud". I wanted a battery OSD to fire on AC plug immediately, not twenty seconds later when UPower's polling timer caught up.

Each of those was solvable in shell glue: a wob call wrapped in a script that read the audio state and rendered text with notify-send. But that's not really wob's fault. It's me wanting something wob doesn't try to be. So I built awob, Another Wayland Overlay Bar.

What's different

Same shape as wob: a transient overlay that appears, draws something, fades out. Same Wayland surface model (wlr-layer-shell-v1, no GTK, no Qt). What changed:

The theme is a data file, not a soup of CLI flags. The whole visual is described in a KDL scene file: a palette, named styles, an element tree (rectangles, text, icons, the bar) and an animation timeline. Hot-reloaded on save: change a colour, see it on the next OSD.
Listeners are processes, not shell glue. PipeWire volume, sysfs battery via udev, backlight, keyboard backlight; each is its own small binary that subscribes to its upstream and forwards typed events. The daemon's supervisor auto-discovers them on PATH and respawns crashes.
IPC is typed, not positional. Instead of writing 78 critical into a FIFO you send awob send --preempt --icon audio-volume-high volume 78 100. The wob FIFO format still works through a shim listener, so existing keybinds keep working.

A theme is one file

The default theme is deliberately "every concept the engine supports, in one self-contained file". It doubles as documentation:

palette {
    bg     "rgba(28,28,35,0.85)"
    fg     "#f3e8d7"
    track  "rgba(255,255,255,0.08)"
    low    "#8fdc55"
    normal "#baea96"
    warn   "#e89a49"
    crit   "#dc8855"
}

surface {
    width 360 height 64 anchor "bottom" offset 0 -56
    fade-in "150ms"  show "2000ms"  fade-out "150ms"
}

scene {
    rect z=0 width="100%" height="100%" radius=12 fill="$bg" shadow="0 8 24 rgba(0,0,0,0.4)"
    image z=1 src="{$icon ?? icon($event)}" x=14 y="center" width=22 height=22
    text z=1 value="{truncate($app ?? label($event), 24)}" x=46 y=14 font="Inter 14 500" colour="$fg"
    text z=1 anchor="top-right" value="{int($progress * 100)}%" x=14 y=14 font="Inter 14 500" colour="$fg"
    bar z=2 x=46 y=42 width="100%-60" height=8 radius=999 fill="$accent" min=0 max="$max" value="$value" from="{$lastValue ?? $value}"
}

$value, $max, $lastValue, $event, $app, $icon are bindings populated at send-time; $lastValue is what makes the bar tween smoothly between consecutive sends. A second shipped theme, wob, is a pixel-faithful clone of upstream (so existing rices keep working), and you switch between them at runtime with awob theme set wob.

The listener that justified the design

The interesting case is the battery listener. The first cut used UPower over D-Bus, because that's what every other Linux app does. The problem: UPower polls the kernel for some events on a thirty-second timer, so plugging in AC at 11% wouldn't fire the "charging" OSD for up to half a minute.

But sysfs has the data already. /sys/class/power_supply/BAT0/status flips from Discharging to Charging the instant the kernel fires a power_supply uevent. So: drop UPower, subscribe to udev, read sysfs directly. AC plug to "charging" OSD now lands in a few hundred milliseconds, and the zbus dependency falls out of the listener entirely.

There's a wrinkle: on some hardware (Dell, ThinkPad, Framework) the battery driver lags the AC-adapter uevent by a few seconds, so reading sysfs at AC-event time sees the old state. A five-second burst-poll window after any uevent re-reads sysfs every second and handles it cleanly. Adding a new event source is a new binary, not a daemon patch, which is the whole point.

Five-minute install on Arch

paru -S awob-bin awob-listeners-all
systemctl --user enable --now awob.service

That's enough anywhere systemd wires up graphical-session.target (Hyprland with uwsm, GNOME, KDE). On Hyprland without uwsm, add exec-once = awob-daemon to hyprland.conf instead.

What it deliberately isn't

It's not a notification daemon: for toast notifications run mako, swaync, or histui (the one I run alongside it). It's not cross-platform; Wayland and Linux only. And it's not a kitchen-sink OSD framework: rectangles, text, icons, a bar, a shadow, a value tween. That's the lot.

Pre-1.0 as I write this, so the wire format and theme schema may still shift; pin a version in scripts. Repo and docs are on GitHub; issues and PRs welcome.

Filling Out the Terminal

2026-05-03T00:00:00Z

tinct could already theme a terminal: the emulator and the editor inside it. But a terminal-centric setup is a lot more than one emulator, and the supporting cast kept missing out: the multiplexer you live in all day, the file manager in the other pane, the system monitor, the launcher. Each was still a hand-rolled config away from matching everything else.

So a batch of output plugins just landed to fill that in:

Terminals: wezterm and foot join kitty, alacritty and ghostty.
Multiplexer: tmux.
TUIs: yazi (files), btop (system monitor), helix (editor).
Launchers: rofi alongside the existing fuzzel and wofi.

With these, a tinct generate … -o all recolours the whole terminal workflow in one shot (emulator, multiplexer, file manager, monitor, launcher) from the same palette that's already doing your desktop. The thing I keep enjoying about the plugin model is that none of this needed changes to tinct itself; each app is just another small output plugin, and the list is now long enough that "does tinct theme X?" is usually "yes".

AUR tinct-bin; the current plugin roster is in the docs.

KeePassXC Joins the Collection

2026-05-02T00:00:00Z

The provider list keeps growing, and this one I'd wanted from the start. rosec can now read a KeePassXC .kdbx file directly: unlock it, list its entries, and serve them on the Secret Service bus next to Bitwarden, your local vault and a migrating GNOME Keyring. A libsecret lookup doesn't care which one answered.

The nice part is what comes along for the ride. KeePassXC stores more than passwords, and rosec picks up the rest of it:

SSH keys in the database, including KeePassXC's own KeeAgent attachments, register with rosec's built-in SSH agent automatically. The keys you already keep in your .kdbx just work with ssh, no ssh-add.
TOTP seeds surface as live files under $XDG_RUNTIME_DIR/rosec/totp/, same as every other provider.

yay -S rosec-provider-keepassxc-file-bin
rosec provider add keepassxc-file
rosec unlock
export SSH_AUTH_SOCK="$XDG_RUNTIME_DIR/rosec/agent.sock"
ssh-add -l            # keys straight out of your .kdbx

It's marked experimental: the .kdbx format has corners, and I'd rather under-promise on a file your whole credential life might live in. Try it against a copy first. Repo and docs, as ever, on GitHub.

Two-Factor Codes You Can `cat`

2026-04-12T00:00:00Z

Back when rosec grew an SSH agent and a FUSE filesystem for keys, the pattern underneath it was the interesting bit: take a secret the daemon already holds and expose it as a file, so any tool that can read a file can use it. This is that same trick, pointed at two-factor codes.

A TOTP seed is just another secret. So if an item in any provider carries one, rosec now surfaces it as a live file under $XDG_RUNTIME_DIR/rosec/totp/, and cat-ing the file gives you the current six-digit code, regenerated every window:

cat "$XDG_RUNTIME_DIR/rosec/totp/GitHub"
# 481922

No app to open, no phone to reach for, no copy-paste dance: the code is a file, which means it's also a shell pipeline, a wofi entry, a keybind. Seeds go in either by storing them on an item directly or with the built-in QR scanner, which reads the setup QR a site shows you and stores the seed in the provider of your choice. Like the SSH filesystem it's behind a toggle (totp_fuse), off until you ask for it, and the prompt helper auto-clears the clipboard after a paste so a code doesn't linger.

Is that safe?

A live 2FA code sitting in a file sounds alarming, so it's worth spelling out, because there's a real trade-off hiding in it.

The mechanics first. The mount lives under $XDG_RUNTIME_DIR/rosec/totp/, which on Linux is /run/user/<your-uid>/: a per-user tmpfs, mode 0700, owned by you, that never touches the disk. rosec insists on XDG_RUNTIME_DIR; if it isn't set the filesystem simply doesn't mount, rather than falling back somewhere world-readable. The mount itself is read-only, nosuid, nodev, noexec, with an owner-only session ACL, so only your uid can traverse it: not other users, not root by default. The code files report mode 0400, owner-read and nothing else.

There's also nothing to steal at rest. It's a virtual filesystem, so there is no GitHub file on a disk anywhere. The six digits are generated fresh on each read, handed back, and the buffer holding them zeroed straight after; nothing is written to disk, and the code is never logged. The seed itself stays in the daemon's memory behind its provider, not in the mount.

So the code is exactly as exposed as your SSH agent socket (same directory, same rules), your keyring, or the passwords your browser has saved: anything running as you can read it, and nothing else can.

That last clause is the trade-off, stated plainly. "Readable only by your user" is the same wall every other secret on your machine already stands behind, and it stops other users and remote attackers cold. It does not stop code running as you: a malicious dependency, a dodgy package build, a hijacked shell can cat the file as easily as you can. For most secrets that's the accepted bargain. For TOTP it deserves a second's thought, because the whole point of a TOTP is to be a second factor on a separate device. Serve it from the same machine that holds the password and you've folded both factors into one trust boundary: own the machine as that user, and you have the password and the current code together.

For me, and I'd guess most people, that's still the right trade, because the threat 2FA actually earns its keep against is the remote one: the phished password, the breach, the credential-stuffing, and none of those can reach the file. But if your threat model genuinely includes "my own machine might be running something hostile", a code on your phone buys you something a code in a file cannot, and that's exactly why the whole thing stays behind the totp_fuse toggle, off until you decide it's worth it.

It's a small feature that I use constantly, and it's the clearest example of why the provider model was worth the effort: unify the secrets once, and "current 2FA code" becomes cat of a path. Repo and docs on GitHub.

aide Is Not a Claude Code Plugin

2026-04-09T00:00:00Z

When I brought aide back, the headline was "context as code": your project's memory and decisions live in the repo as reviewable records rather than in some vendor's hosted store. That's a nice slogan right up until your tool only works with one vendor's assistant, at which point you've just moved the lock-in by one box.

So this is the part that makes the slogan true: aide isn't tied to Claude Code. It started there, picked up OpenCode support a couple of days after the first release, and as of this week runs on Codex CLI too. Three harnesses, one knowledge store.

The trick is an adapter layer. Each assistant has its own lifecycle (session start, tool calls, the hook points where aide injects context or captures a memory) and each names and shapes those events differently. The adapters map every harness's events onto one shared set of core functions; the Go binary doing the actual work (storage, search, the MCP server) doesn't know or care which assistant is on the other end. Add a harness, write an adapter, done.

What the store actually holds

Portability only matters because of what moves with you, and that's the part I care about most. The failure mode of an AI assistant isn't that it's stupid, it's that it confidently works from the wrong context: a stale decision, a half-remembered convention, a fact that was true three refactors ago. Garbage in, plausible garbage out. aide's whole design is aimed at that, by storing only things that are current and checkable and handing them over as fact rather than vibes.

Decisions are constitutional. A decision in aide is an ADR: a topic, a choice, a rationale. It behaves like a clause in a constitution, injected into every new session automatically, so the assistant starts already knowing "we use JWT with refresh tokens, because…". When you change your mind you don't edit the old one, you record a new decision for the same topic; the latest supersedes and the full history stays readable. Amendments, not overwrites. The agent only ever sees the current law, and you can always read how it got there.

Memories are scoped. Not everything should be shouted into every session. A memory carries a scope: scope:global rides along in every project, project:<name> only surfaces in the project it belongs to, and session memories group what was learned in one sitting. The injector pulls the global preferences and the current project's context and leaves the rest in the index, searchable but quiet. The session gets the facts relevant to here, not the union of everything aide has ever heard.

The code index is fact on demand. The other half is structural truth about the code itself, served over MCP: where a symbol is defined, who calls it, the shape of a file, built from a tree-sitter parse rather than a guess. When the assistant needs to know something about the codebase it asks and gets the current answer, instead of pattern-matching from whatever happened to be in the context window.

The through-line is that every one of these surfaces current, material fact and nothing else. That's the antidote to context poisoning: you can't be dragged off course by stale context if the store only hands over what's true now. And because a precise fact is small (the one symbol, the one decision, not a wad of maybe-relevant text) it costs a fraction of the tokens that stuffing the window full of "context" would.

Which is why portability matters

Put those together and the reason to keep it vendor-neutral becomes obvious. This isn't a chat history you'd shrug off losing; it's your team's accumulated, curated, current understanding of a codebase. Switch assistant, or run two side by side, and the .aide/ directory comes with you: same decisions, same scoped memories, same code map. Records you can read, diff and move aren't just tidier than embeddings in someone's cloud, they're the only version of "memory" that survives you changing your mind about which AI you use. Repo and docs on GitHub.

Watching Where the Tokens Go

2026-03-30T00:00:00Z

aide spends its life doing things you can't see: injecting memories and decisions at session start, answering the assistant's MCP queries, deciding which skill to surface. Useful, but invisible, and invisible machinery is hard to trust or tune. So aide grew a web dashboard, aide-web, to make it observable.

The centre of it is token intelligence. Every context aide injects and every fact it serves has a cost and, ideally, a saving: the decision it handed over is tokens you didn't spend re-explaining your auth strategy; the precise code-index answer is the wad of source you didn't have to paste in. The dashboard tracks both sides, spent versus avoided, per tool and over time, so "is this actually helping?" stops being a vibe and starts being a chart.

aide dashboard launches the web UI; aide status gives you the same picture in the terminal if you'd rather not leave it.

One honest caveat, and it's why the feature is labelled experimental: the token counts are estimates. They come from calibrated per-language character ratios, not a real tokeniser, so they're good for relative comparison and spotting trends, not for exact cost accounting. Treat the shape of the graph as the signal, not the third decimal place. Repo and docs on GitHub.

rosec Can Read the Old Keyring

2026-03-04T00:00:00Z

The awkward part of replacing GNOME Keyring is that years of secrets are already in it: Wi-Fi passwords, app tokens, the odd thing you forgot you saved. Switching the Secret Service over to rosec shouldn't mean leaving all of that behind, or doing a big-bang export the night you flip the switch.

So rosec now has a read-only GNOME Keyring provider. Point it at your existing keyring and every secret in there shows up on the bus alongside your other providers (Bitwarden, your local vault) as one unified collection. You can read them, copy the ones worth keeping into a vault you actually control, and retire the keyring whenever you're ready.

Read-only is deliberate. The keyring is the thing you're migrating away from; rosec treats it as a source to drain, not a destination to keep writing to. Nothing new lands back in it.

yay -S rosec-provider-gnome-keyring-bin
rosec provider add gnome-keyring
secret-tool search --all          # your old keyring secrets, now served by rosec

One backend closer to rosec being the only Secret Service on the machine. KeePassXC is next on the list.

rosec Grows a Vault of Its Own

2026-02-28T00:00:00Z

rosec launched reading from Bitwarden, which is the case I built it for. But tying your whole Secret Service to a cloud account isn't for everyone, and "read my secrets from somewhere else" shouldn't require a somewhere-else.

So rosec now has a provider of its own: a local encrypted vault. Secrets live encrypted on your own disk, and the daemon serves them on the bus exactly like any other backend; secret-tool and friends can't tell the difference. It's the answer for anyone who wants the multi-provider Secret Service without a remote dependency in the loop.

The piece that makes it pleasant is PAM unlock, which landed alongside it: log in once and the vault opens with your login password, so there's no second prompt before your first secret lookup of the session.

rosec provider add local
rosec unlock
rosec item add --provider local --label "GitHub" --attr username=alice --secret 'hunter2'
secret-tool lookup label "GitHub"     # → hunter2, from your own disk

This is the provider I'd reach for first now: Bitwarden when I want sync, the local vault when I want nothing leaving the machine. More backends still to come.

SSH Keys That Mount Themselves

2026-02-25T00:00:00Z

The day after rosec started serving secrets on the bus, the most obvious "wait, these are just secrets too" feature landed: SSH keys.

An SSH key is a secret like any other, so why keep it in a separate ~/.ssh/ pile and run ssh-add by hand? rosec now ships a built-in SSH agent. Any private key stored in any provider (a first-class key item, a PEM blob dropped in a note) gets registered automatically at $XDG_RUNTIME_DIR/rosec/agent.sock. Point SSH_AUTH_SOCK at it and your keys are simply there:

export SSH_AUTH_SOCK="$XDG_RUNTIME_DIR/rosec/agent.sock"
ssh-add -l        # every key in your vault, no ssh-add ever run

The part I'm more pleased with is the FUSE filesystem that came with it. The agent holds the private keys, but SSH tooling still wants public keys and config on disk, so rosec mounts a small read-only filesystem under $XDG_RUNTIME_DIR/rosec/ssh/: each key's public half under keys/, and a generated config snippet under config.d/. Nothing private ever touches the disk.

The right key, every time

The config is the part that earns its keep, and it's driven by two custom fields you can set on any key item:

ssh-host is the host pattern (or patterns, one per line) the key is for: github.com, *.internal.example.com, and so on. Each becomes a Host block.
ssh-user is the login user, and if you leave it off rosec falls back to the item's username field. It becomes the User line.

From those, each item gets its own config.d/<name>.conf:

Host git.internal.example.com
    User deploy
    IdentityFile "/run/user/1000/rosec/ssh/keys/by-name/prod-deploy.pub"
    IdentityAgent "/run/user/1000/rosec/agent.sock"
    IdentitiesOnly yes

You wire that into SSH once. I keep a one-line static file so my real ~/.ssh/config never has to change, and it pulls in the live mount:

# ~/.ssh/config
Include configs.d/*.conf

# ~/.ssh/configs.d/10-rosecd.conf
Include /run/user/1000/rosec/ssh/config.d/*.conf

That last directive, IdentitiesOnly yes, is the quiet hero. By default ssh offers the agent every key it holds, one after another, until something works; against a server with MaxAuthTries 6 a well-stocked agent gets you kicked off for "Too many authentication failures" before it ever reaches the right key. Here each host is pinned to exactly its key and told to offer only that one. No guessing which user to connect as, no marching through eight wrong keys first, no lockout. The right key and the right user, first try, written straight from the secret that holds the key. Add a key, set ssh-host, and the config to use it writes itself.

It's optional and behind a config toggle (ssh_fuse), because a self-mounting filesystem is exactly the sort of thing you want to opt into rather than have appear. But with it on, "I added a new SSH key" and "I can use that key everywhere" become the same step.

This is the shape I want the whole project to have: unify the secrets once, and the conveniences fall out as filesystems and sockets over the top. The 2FA codes got the same treatment later. Repo and docs on GitHub.

Secrets, Minus the Keyring

2026-02-24T00:00:00Z

On Linux, org.freedesktop.secrets is how desktop applications store passwords: anything using libsecret or secret-tool talks to it. In practice that means GNOME Keyring, whether or not you run GNOME, and whether or not your secrets actually live there. Mine don't; they're in Bitwarden. I wanted the Secret Service on my machine to read from there, transparently, without every app needing to know.

So rosec is a multi-provider Secret Service daemon. It implements the freedesktop spec, so any libsecret-aware tool keeps working unchanged, but behind the bus it reads from a provider you choose. It launches with Bitwarden, both Password Manager and Secrets Manager, surfaced as one collection on the bus.

Once every secret lives somewhere the daemon can reach, more falls out of it than password lookups: an SSH agent that needs no ssh-add, two-factor codes you can cat. Both got built out in the weeks after launch, so they each get their own post; the foundation underneath them is just this, one spec-compliant Secret Service, reading from a provider you choose.

yay -S rosec-bin
rosec enable        # installs the D-Bus activation, masks gnome-keyring-daemon
secret-tool lookup label "GitHub"     # → reads from Bitwarden via rosec

The point of the design is the provider boundary; Bitwarden is just the first one. A local encrypted vault, KeePassXC files and a read-only GNOME Keyring for migration are what comes next, each as its own backend on the same bus. (I'll post as those land.)

This is squarely a scratch-my-own-itch project sitting on a sensitive part of the stack, so give the threat model your own scrutiny before you trust it with anything that matters; it's young. Repo and docs are on GitHub.

Giving keylightd a Real API

2026-02-10T00:00:00Z

keylightd shipped its HTTP API on the standard library's http.ServeMux, hand-marshalling JSON in each handler. That's fine until it isn't: the routes drift from the docs, every handler repeats the same decode/encode dance, and "what does this endpoint actually return?" is answered by reading the source. So the API got a proper rebuild.

The handlers now run on Chi + Huma, which buys three things at once:

Typed requests and responses. Each endpoint is a Go struct in and a Go struct out; the framework handles validation and serialisation. No more manual JSON plumbing, and the compiler catches the shape errors I used to find at runtime.
An OpenAPI spec for free. Because the types are the contract, the spec is generated from them: it can't drift from the implementation, because it's derived from it. Anything that speaks OpenAPI can now generate a client.
A middleware ecosystem. Rate limiting, structured logging and the rest drop in as Chi middleware instead of bespoke wrappers.

The rule I held myself to: all thirteen existing routes preserved, byte-for-byte. This is infrastructure plumbing (a tray app and a GNOME extension are on the other end) so a rebuild that quietly changed a response shape would be a bug, not an upgrade. Same contract, better foundations.

The same pass added WebSocket events: instead of polling the daemon to ask "is the light on yet?", a client can subscribe and get state changes pushed to it. The GNOME extension reflecting a light you toggled from the CLI, instantly, is the kind of small thing that only happens once the daemon can tell you rather than wait to be asked.

Logging moved to structured slog with hot-reloadable filters in the same sweep: the boring, load-bearing stuff. Repo and docs on GitHub.

aide, Resurrected: Minus the Vector Database

2026-02-07T00:00:00Z

I had a tool called aide memoire, a scratchpad of memory and context for an AI coding assistant, built the way everyone builds these: a local vector database, embeddings of everything, semantic recall. It worked, more or less, and then it bit-rotted into something I no longer trusted. So I brought it back from scratch as aide, and the thing I was most certain about going in was that the vector database wasn't coming with it.

That sounds like a step backwards. Embeddings-in-a-vector-store is the default for coding-assistant memory. But the more I'd lived with the old design, the more the vector DB felt like the wrong tool for this job, so the resurrection drops it. aide runs on lexical full-text search (BBolt + Bleve, BM25-style) and a tree-sitter symbol index instead, and I think it's better for it.

Why no vector DB

The pitch for embeddings is semantic recall: find the chunk that's vibes-similar to your query. But what an agent needs from a project usually isn't vibes; it's facts. Where is this symbol defined? What calls it? What did we decide about retries, and why? What's the convention here? Those are exact, structural questions, and answering them with nearest-neighbour search over a cloud of floats is a fuzzy tool aimed at a precise target. aide's bet is that the power is in factual context, not semantic similarity, and once you take that bet, the wins stack up:

No model in the loop. Embeddings have to be generated, so you end up piggybacking on an LLM just to remember things: tokens and latency to store, more to recall, a whole model dependency for what should be a database lookup. A lexical index and a tree-sitter parse need no model at all. aide remembers without asking anyone's API for permission.
Accuracy. A factual lookup returns the answer, not the five chunks that scored closest. "Where is Foo defined" has a correct result; cosine similarity only has a ranking. For code, exact beats approximate nearly every time.
Fewer tokens. Because the answer is precise it's also small: the one symbol, the one decision, the actual call sites, instead of a wad of semantically-adjacent text padded out to fill the context window. Token reduction and better answers turn out to be the same lever, not a trade-off.
Context as code. Everything aide knows (memories, decisions, findings) lives as plain records in a per-project .aide/ directory and exports to markdown you can commit. It's PR-reviewable, diffable, and you can read why something surfaced. A blob of floats is none of those.
And it's where the field went. Native harnesses converged on a small always-loaded index plus on-demand file reads, not local-vector RAG: no model to run, nothing leaving the machine, an index measured in megabytes, the same behaviour on every box.

For finding code, a tree-sitter symbol index gives you definitions, references and call graphs across a dozen languages with zero setup and no compiler in the loop: error-tolerant, precomputed, whole-repo. For finding knowledge, full-text over short human-written records beats cosine similarity over chunks. Neither needs a GPU.

What it actually does

aide is an MCP plugin that gives an assistant (Claude Code today; more shortly) the things a new contributor would kill for:

Memory + decisions: preferences, context and architectural choices that persist across sessions, injected at startup and enforceable when you write code that contradicts them.
Code intelligence: tree-sitter symbol search, references and call graphs.
Findings: static analysis for complexity, coupling, secrets, duplication and dead code.
Survey: a map of modules, entry points, tech stack and churn hotspots.
Skills + multi-agent orchestration: keyword-triggered workflows, and parallel agents working in isolated git worktrees.

The throughline is that it serves compact, token-budgeted answers instead of whole files, so a long-running agent spends its context window on the work rather than rediscovering the project every session.

It's early and opinionated, which is the way I like a v0. Repo and docs on GitHub. More on the individual pieces, and the opinions behind them, to come.

The Notifications You Missed

2025-12-26T00:00:00Z

Notifications on Wayland are a solved problem right up until you miss one. A toast appears for five seconds while you're looking at another monitor, fades out, and is gone, and there's no good way to ask "what did that say?" dunst and mako are excellent at showing notifications; they're just not built to keep them.

So histui is a notification daemon that does both. It draws notifications (a GTK4 layer-shell daemon with full CSS theming, custom layouts, light/dark switching and hot-reload) and it stores every one of them in SQLite, so your history outlives the toast.

The history is what I built histui for. There's a TUI browser with vim-style keybindings, and a CLI that filters by app, urgency, time range or regex and speaks JSON, dmenu and plain-ID output, so it drops straight into a script or a waybar module showing live counts.

But it turned out not to be the part I appreciate most. What won me over day to day is the presentation side I half-expected to ignore: per-urgency audio, so an error sounds different from a chat ping; GTK theming rich enough to be worth fussing over, wired to tinct so the notifications recolour along with the rest of the desktop and hot-reload while I tweak; and image previews rendered right there in the toast. I set out to build a better history and ended up with a nicer notifier.

It's flexible about how far you let it in. Run it standalone as a full dunst/mako replacement, or keep your existing daemon and run histui in monitor mode purely for the history. There are adapters to import what dunst, mako or swaync already logged, so you don't start from an empty slate.

yay -S histui-bin
systemctl --user enable --now histuid
histui            # browse your history

Early days, and themeable enough that I expect most of the interesting work to happen in other people's CSS. Repo, a demo video and docs are on GitHub.

Wrangling IPTV into One Playlist

2025-12-05T00:00:00Z

If you self-host live TV, you've met the gap tvarr fills. You have a couple of IPTV sources in different formats, each with its own playlist, its own EPG, its own quirks, and a client that wants exactly one tidy M3U and one tidy guide. Stitching those together by hand is miserable, and the tools I tried either did too much or assumed a workflow that wasn't mine.

So tvarr is a self-hosted relay that sits between your sources and your clients. It aggregates M3U and Xtream inputs, merges the EPG data, and generates a single unified playlist. Point your player at tvarr instead of at five different providers, and it sees one coherent channel list. The aggregation is the easy half, though. The interesting half is what happens to the actual streams.

One origin, many players

Most IPTV origins allow a single connection per channel. But you might have a phone on HLS, a TV on MPEG-TS and a browser on DASH all wanting that same channel at once. Open one upstream connection per client and you trip the limit, and waste the bandwidth, immediately.

So tvarr holds one origin connection per channel and fans it out through a shared buffer. Ingest probes the source (HLS, DASH, RTSP or raw MPEG-TS) and demuxes it down to codec-agnostic elementary streams, the raw H.264 or H.265 video and AAC or AC3 audio with their timing intact, written into a per-channel SharedESBuffer. Output processors then mux those same elementary streams into whatever each client actually needs: HLS-TS, HLS-fMP4, DASH or raw TS. One fetch upstream, many formats downstream, and the whole thing tears itself down when the last client disconnects.

If a client needs a codec the source doesn't carry, transcoding happens on demand and once. A single FFmpeg transcode produces, say, a VP9/Opus variant that lands back in the same buffer, and every client that wants that variant is served from it. No per-client transcode, no pre-transcoding a library you might never watch.

Distributed transcoding over gRPC

Transcoding is the expensive part, so tvarr can push it off the box doing the relaying entirely. A separate worker daemon, ffmpegd, connects to tvarr (the coordinator) over gRPC, detects its own FFmpeg capabilities (which encoders, which GPUs) and registers them. Run one embedded locally, or a pool across machines: a couple of GPU boxes for NVENC and VAAPI, a spare CPU server for overflow.

When a variant is needed, the coordinator builds a job and picks a worker on what actually matters: does it have the required encoder, does it have a free job slot, and is there a GPU going spare (preferred over CPU). The job is dispatched down a gRPC stream, the worker spawns FFmpeg, and the transcoded elementary streams come back into the shared buffer. If a worker drops off mid-stream its jobs are reassigned to another. A low-power machine can serve the playlist and the UI while the heavy lifting happens somewhere with a graphics card.

Filters and data mapping

The other half of taming five providers' worth of inconsistent metadata is rules, and tvarr uses an expression language rather than a pile of checkboxes. There are two kinds, applied in order. Data mapping runs first and rewrites messy fields; filters then include or exclude channels on the now-clean values, so you tidy before you decide.

# data mapping (first): normalise the mess
SET group_title = "UK Sports"   where  group_title matches ".*UK.*Sport.*"

# filters (second): include/exclude on the clean values
INCLUDE  group_title contains "Sports"
EXCLUDE  channel_name matches ".*(Test|Backup|XXX).*"

Map the mess into shape, then filter on the result, and a tidy, predictable playlist falls out of a heap of inconsistent sources. Filters apply to EPG entries too, not just channels.

It runs as a single container with a web UI for managing sources, rules and output playlists:

docker run -d -p 8080:8080 -v tvarr-data:/data \
  -e TVARR_SERVER_BASE_URL=http://your-host:8080 \
  ghcr.io/jmylchreest/tvarr:release

If you've used Threadfin or StreamMaster it lives in the same neighbourhood; this is just my take on the shape of the problem. It's early and moving quickly. Repo and docs are on GitHub; if it's useful, brilliant, and if it isn't quite right, open an issue.

A Tray Icon, and a Migration on Hold

2025-11-21T00:00:00Z

Not everyone lives in GNOME, and not everyone wants a shell extension. So keylightd now has a system-tray app: a small Wails desktop application, on Linux and Windows alike, that puts your lights one click away in the system tray.

keylightd already finds every Elgato Key Light on your network over mDNS; the tray app is the friendly face on top of that. The icon toggles the lights on and off, and clicking through opens a little window with brightness and colour-temperature sliders, either for an individual light or for a whole group, plus the option to hide the ones you never reach for. It's a thin client over the daemon's API, mostly icons and a status loop, so it stays in sync no matter where the change came from: this window, the CLI, the GNOME extension or a script hitting the socket.

And of course it's themed. The window is plain CSS with hot reload, and tinct has an output plugin for it, so when I regenerate my palette the tray restyles itself to match the rest of the desktop, no restart. Tiny, but it makes me happy.

That's the good news. Here's the honest part, because I'd rather write it down than pretend.

I tried to move the tray app to Wails v3, which has a much nicer native systray story and cleaner bindings, and the migration is code-complete but on hold. Wails v3 is still in alpha, and the build segfaults during GTK initialisation on Linux (a SIGSEGV in the alpha's GTK path, not in keylightd's code). I could paper over it, but a tray app that crashes on launch for half my users isn't a release; it's a liability. So the v3 branch sits there, finished and pinned, waiting for Wails v3 to go stable, and the shipping tray app stays on v2 where it actually works.

This is the unglamorous reality of building on a fast-moving toolkit: sometimes the right move is to do the work, watch it break on something upstream, and then not ship it. The branch isn't abandoned; it's parked, with a note to revisit when the segfault is fixed. Meanwhile the v2 tray, the GNOME extension, the CLI and the API all drive the same daemon, so nobody's actually waiting on it.

Repo and docs on GitHub.

A Palette for the Whole Desktop

2025-11-18T00:00:00Z

tinct started by theming the parts of my setup that read a plain config file I own: kitty, Hyprland, waybar, dunst, neovim. That covers a terminal-and-Wayland life nicely, right up until you open a GTK file manager or a Qt settings dialog and it's still wearing last month's colours. The toolkit apps were the conspicuous gap: the browser chrome, the file picker, half of GNOME and KDE, all stubbornly default.

That gap is now closed. tinct has output plugins for the desktop toolkits themselves:

GTK: GTK3, GTK4 and libadwaita, so GNOME apps and anything GTK-based pick up the palette.
Qt: Qt5 and Qt6, plus KDE Plasma and konsole.
GNOME Shell: the shell, not just the apps under it.

Which means tinct generate -i image -p wallpaper.jpg -o all now recolours the whole desktop in one go: terminal, window manager, bar, and the GTK/Qt apps that used to sit outside the reach of a Pywal-style tool. Getting these right is fiddlier than a terminal config (toolkits have opinions, and contrast matters more when real UI chrome is involved), which is exactly why having tinct's semantic role-assignment and WCAG checks do it beats hand-templating.

Still early, still moving. AUR is tinct-bin; the full output-plugin list lives in the docs.

One Palette, Many Configs

2025-11-04T00:00:00Z

I like my desktop to feel of a piece: terminal, bar, window borders, launcher, editor, all drawn from the same palette. The usual way to get there is Pywal or Matugen: extract colours from a wallpaper, template them into a pile of config files. They're good tools and I used them for years. But I kept bumping into the same two walls: the inputs I wanted weren't there, and adding a new application meant another bespoke shell template bolted on the side.

So tinct is my answer: an extensible colour-palette generator and theme manager, built around plugins at both ends. A palette is something you produce from an input plugin and apply through output plugins, and either side is open.

On the input side, a palette can come from an image (the Pywal case), from a remote theme (point it at Catppuccin's palette JSON and it pulls the colours straight out), or from a manual specification. On the output side, tinct does the semantic work, assigning colours to roles with WCAG contrast checking, so you don't end up with unreadable text on a bad day's wallpaper, then writes out config. The first batch of output plugins covers the setup I actually run: kitty, Hyprland and hyprpaper, waybar, dunst, fuzzel and wofi, neovim, zellij. -o all writes the lot in one pass, and a new application is a new output plugin, not a fork of the tool.

It's early; this is the "scratch my own itch, then realise other people have the same itch" stage, so expect rough edges and shifting defaults. It's written in Go, installs from the AUR (yay -S tinct-bin) or go install, and the repo and docs are on GitHub. More inputs and a lot more output plugins are where it goes from here.

Booting Into a Snapshot

2025-06-12T00:00:00Z

btrfs snapshots are a wonderful safety net right up to the moment you actually need one, at which point you discover that "roll back to this morning" means booting into a snapshot, and your boot manager has never heard of it. The excellent refind-btrfs solves this, but it's Python with a dependency tree, and I wanted something I could drop onto a machine as one file and forget about.

So refind-btrfs-snapshots is a single static Go binary that discovers your btrfs snapshots and generates rEFInd boot-menu entries for them. Run it as a one-off whenever you like; it's a plain binary, so systemd isn't required. But drop in the optional systemd path unit and it watches your snapshots directory, so the instant Snapper takes a snapshot the boot menu regenerates and that backup is bootable straight away, with nothing for you to remember to run. Either way, you pick a snapshot from the boot menu and boot straight into it.

The part I care about is that it gets the details right, because boot is exactly where you don't want surprises:

Per-snapshot boot-mode detection. Whether a snapshot boots in ESP mode (kernel on a separate /boot) or btrfs mode (kernel inside the snapshot) is read from that snapshot's own /etc/fstab, not assumed globally. So snapshots taken before you changed your disk layout still boot correctly, and one menu can mix both kinds.
Stale-kernel handling, the feature other tools skip. With a separate ESP /boot, a kernel upgrade can leave an old snapshot whose kernel modules no longer match the kernel on the ESP. It would boot, then fail to find its modules. This binary detects that mismatch and, by default, excludes the snapshot rather than offering you a boot that dies halfway, with warn, disable and fallback options if you'd rather handle it differently. Not silently.
The correct config method. It writes an include file rather than abusing refind_linux.conf (which can only override options, not the volume/loader/initrd that btrfs-mode entries need), and it shows you a diff before it touches anything.

And it auto-detects most of what matters: your ESP, each snapshot's boot mode, a standard Snapper layout. The defaults work with no configuration on a typical setup, so for most people it's install, enable the path unit, and forget it's there. Installs from the AUR (refind-btrfs-snapshots-bin) or as a prebuilt binary, and --dry-run is first-class. Repo on GitHub.

Key Lights in the Top Bar

2025-05-18T00:00:00Z

keylightd launched with a CLI and a REST API, which is exactly what you want for scripts and not at all what you want when you're on a call and the light is too bright. A keyboard shortcut to a shell command is fine; reaching for a slider is better.

So keylightd now has a GNOME Shell extension. It sits in the top bar, talks to the daemon over its HTTP API, and gives you the controls you actually reach for mid-task: toggle a light or a whole group on and off, and nudge brightness and colour temperature without leaving what you're doing. It's published on extensions.gnome.org (extension 8185), so it installs like any other.

I'll be honest: I only really use GNOME when I'm not on my own machines; left to my own setup I'm more of a terminal junkie on a tiling Wayland desktop. But there's something quietly nice about a control that feels integrated, a proper top-bar applet that looks like it belongs there, rather than a keybind firing off a shell command. Native beats bolted-on, even on a desktop I barely touch. It's cheap to offer, too, since the extension is just a thin client over the same API the CLI uses, mostly buttons over a daemon that already does the hard part.

Toggle from the bar, script from the shell, both driving the same daemon. Repo and docs on GitHub.

A Daemon for the Key Lights

2025-05-11T00:00:00Z

I have a couple of Elgato Key Lights, and controlling them was always slightly worse than it should be. A phone app, or a hard-coded IP in a script that broke the next time DHCP felt creative. And because there are two of them, every adjustment was really two adjustments: two sliders, remembering which app entry was the left light and which was the right, nudging both and watching them drift out of step. What I actually wanted was to stop thinking of them as two lights and treat them as one: group them, and change them together. The lights speak a perfectly good HTTP API; what was missing was something to find them, remember them, group them, and give me a clean way in.

So I wrote keylightd, a small Go daemon that owns the lights so nothing else has to.

The daemon does three things. It discovers Key Lights on the network over mDNS, so there are no IP addresses to hard-code: plug a light in and it appears. It lets you put lights into named groups and drive a group as one unit, so the two lights either side of my desk turn on together, dim together and stay in step. Each light is still addressable on its own when you want it, but day to day I never touch them individually; "turn the office on" is one command and both come up matched. And it exposes that control through whichever interface suits the caller:

a CLI (keylightctl) talking to the daemon over a low-latency Unix socket;
a REST API with token auth and an auto-generated OpenAPI spec, for anything remote or scripted;
a small client library so Go programs can skip the wire format entirely.

keylightctl group add Office
keylightctl group set Office on true
keylightctl group set Office brightness 40

The point of a daemon, rather than a pile of curl one-liners, is that there's one thing that knows the current state, survives a light dropping off the network, and presents the same view to a script, a desktop applet or a status bar. Everything else stays thin and just asks the daemon.

Because the control point is just keylightctl (or the API), the lights slot into whatever automation you already have. The one I keep meaning to wire up properly: turn the key lights on when the webcam does. keylightd doesn't need to know anything about that; watch for the camera device opening, or a specific app launching, and call keylightctl group set Office on true. I did try building the webcam-detection in natively, but "is the camera in use" is maddeningly sporadic across environments (different stacks, different permission models, PipeWire versus v4l2 versus whatever the app decides to do), so I left it as a hook for you to script rather than a half-working feature pretending to be reliable. If you've wired something like this up, driving the lights off some local condition, drop an issue on the repo; I'd genuinely love to hear how.

It's day one and deliberately small. Repo and docs on GitHub; desktop control and a proper typed API come next.

silicon valley season 3

2016-04-09T00:00:00Z

Since having a friend point out the HBO original Silicon Valley I've been hooked. Such a brilliant TV show, and despite certain attitudes and characters being overdramatised it's a stupidly accurate (albeit satirical) reflection of working in modern IT… at least in most places.

I won't recap on the whole thing, but what I will say is I'm actually, for the first time in a long time, very excited for a TV show to bring back a new season. It premiers on HBO on the 24th.

If you're looking for a quirky version of the IT Crowd, or you just work in IT I recommend you take a watch. It's free to recap on HBO right now, assuming you're in region. Assuming you're not, you'll discover that you get a particularly inelegant CloudFront geo-blocking error when you click the watch now for free link.

igmpqd

2016-04-07T00:00:00Z

I found myself with a bit of time on my hands these last few days, and have a need for an IGMPv2 Querier. Theres a few out there already, but they're either part of a much larger suite (like XORP, a fantastic OSS routing platform), or generally unsuitable to run as a system service.

The IGMPv2 Query message spec is actually very simple as indicated in RFC2236 so I thought, what the heck, I might as well have a stab myself.

After a few hours I had the basic thing together and principally tested. Given that I can't be the only one in need of such a tool I figured I'd also publish it somewhere for other people to use.

To that end, the igmpqd project is now live on github. If it proves useful to you, brilliant… if you find any issues or have any requests for it, please open an issue ticket on github or even better, fork it, hack on it, and put forth a merge request.

Using IGMPQD

Using IGMPQD is simple. Download a binary that matches your platform from the github releases page and run it with ./igmpqd run. By default, it'll do what you most likely want, and thats issue an IGMPv2 Query for all groups to all nodes listening on the all-hosts multicast group address every 30 seconds.

If you want to tune any of those options, check out ./igmpqd run --help or the github page for more information.

back on the grid

2016-04-02T00:00:00Z

I woke up this morning with a startling realization. Despite the internet being full of some of our species finest works, being an enabler for people to connect on all manner of levels, and to provide the typical amongst us with more than our fair share of exciting animated cat gifs and memes it's missing something.

That's right. Yet another IT geek promising opinionated and likely pointless public posts. The kind that are likely to come thick and fast with no useful information what so ever till eventually they get bored. Well… Hopefully this won't be quite as bad as that.

Enough. What should I expect?

Well, I'm glad you asked. What? You didn't? Well let me tell you anyway.

Badly written CSS.
News (related to my own activities) regarding any of the public projects I may be working on.
Guides on specific tuning/best practices as and when I have a need to do something that relates.
Resolutions to problems I face, but hopefully only the complicated ones. Hopefully they might help you, and if not, they'll help me when I forget!
Anything that crops up in the news that really irks or excites me.

So… lets see if I can get it started keep it up.

Ramblings of an aging IT geek

Decisions, Weighted

Precedence, and One Threshold

The Blueprint That Started It

And Some Python

Decisions, Inherited

The Estate

Inherit from Ancestors

Subscribe to Peers

Why Not Just Import?

The Session Is the Scheduler

rosec 0.0.33: The Security Key Signs In

Trust you can actually rotate

The rest

clipferry: An X11 to Wayland Clipboard Bridge

Escribí mi propio generador de sitios. ¿Deberías usarlo?

Los consagrados

En qué se diferencia colophon de verdad

Accesibilidad e idiomas

La parte honesta

Entonces, ¿cuándo es colophon lo correcto, si es que alguna vez lo es?

Relacionado

I wrote my own site generator. Should you use it?

The grown-ups

Where colophon is actually different

Accessibility, and languages

The honest part

So when is colophon the right thing, if ever

Related

The Post Is the Slide Deck

One document, more than one medium

Turn it on

What becomes what

Where the breaks go

Three inline markers

Present it, or read it

On in preview, off in prod

Related

ElevenLabs Voices and Pronunciation Dictionaries

Pronunciation dictionaries

A second voice: ElevenLabs

The API key permissions

The quiet change: WAV now, Opus later

Putting it together

Related

Wiring the Blog into the IndieWeb

WebSub: real-time feeds, no account

Sending webmentions: also no account

Receiving: webmention.io

Showing the responses

POSSE: publish here, syndicate everywhere

Signing in as your own domain

What you get

Related

A Colophon Blog on Cloudflare Pages and R2

What you need from Cloudflare

Account ID

API Token

An R2 access key pair

DNS and a custom domain

Scaffold the project

Sites, publishers, environments: why three nouns

Where the secrets live

Provision, then publish

Generative images and a spoken reading

The frontmatter that actually matters

Writing it with an LLM, in your own voice

A Palette from a Prompt

Best Practices, Bootstrapped

Composable, not monolithic

It detects what you're building

Versioned, and it knows what it set

Roll your own, share them across the team

Why bother

Rebuilt the Blog. Again.

Learning From the Session

Two Razer Naga Buttons, One Keycode

The fix: driver mode

Getting DPI back

One Core, Many Bootloaders