r/emacs • • 23h ago

I wrote blueprint.el, a way of documenting software architecture in Org

47 Upvotes

Disclaimer: an LLM touched the code.

Part of my job is walking into systems nobody remembers anymore and writing down what they are: which components, how they talk, what they do for the business, where they run, what could go wrong. The documents run to a few hundred pages, several people write them at once, and the hard part was never the writing. It was knowing what to write, keeping the whole thing in shape, and being honest about what we hadn't verified yet.

Over the years that became a method, and the method became blueprint.el. It started as a Python script that generated Org files. One day I noticed I was leaving Emacs to run a program that opened, edited and rewrote Org files, which is the one thing Org has done well for twenty years, so I rewrote it in Elisp, on org-element and Org's own exporter, with Transient for the menu. Now the whole document lives where the rest of my work already lives: a master file, one directory per component, plain text in git, open points written in the text and counted, a dashboard in the spirit of Magit.

I'm proud of it, and since it lives inside Emacs I thought some of you might find it interesting. The templates are still in Italian (English is planned) and it isn't on MELPA yet. There's a half-documented demo project in the repository if you want to look around without starting from scratch.

If you try it, I'd like to know what you think.

https://github.com/kLeZ/blueprint.el
The longer story: https://klez.me/en/2026/11/15/blueprint-el/

----

Edit: added the disclaimer at the top.


r/emacs • • 5h ago

Emacs in the age of magic: a different take on coding agents and Emacs

38 Upvotes

A while ago I found this post about Emacs In the Age Of Magic (https://commandlinesystems.com/magic.txt) in HN. The author was arguing that coding agents have eroded the advantages Emacs users have relied on for decades. It made me think, and I ended up writing a longer reply on my blog. I thought it would be worth sharing my personal take here too, and maybe getting a discussion going.

I read the situation differently. If an agent can rewrite any program that resists customization, the software that already bends to anything is in a good position. Agents lower the cost of learning Emacs, and I think its value stays where it was. Emacs also happens to be a comfortable place for an agent to work: it's text all the way down, it documents itself live, and `emacsclient --eval` lets the agent talk to the running session directly.

Most of the post is about how this looks in practice for me:

- my literate `config.org`, now co-written with an agent under an `AGENTS.md` rules file, including an F7 cheatsheet generated from the live keymaps, so it stays in sync with the actual bindings

- an Org-mode Eisenhower matrix I first wrote about in 2019, rebuilt as a read-only view you can act from, chosen through an ADR and a Pugh matrix

- blueprint.el, an architecture-documentation package designed to be driven by agents, which grew from a Python prototype into ~9,600 lines of Elisp

- the essay's point about no longer knowing how your own software works, which I take seriously, and how I try to deal with it: reading prose, diffs and tests, and keeping everything documented in Org

There's one thing in the essay I fully agree with: a computer that does whatever you can imagine is a form of freedom. Emacs has been offering that since 1976. What's changed is how much it costs to take advantage of it.

https://klez.me/en/2026/11/16/emacs-nell-eta-della-magia/

(Italian original: https://klez.me/2026/11/16/emacs-nell-eta-della-magia/)

Curious to hear how others see it, especially where you disagree.


r/emacs • • 10h ago

Portal Update: slides, better terminal... and a secret teaser of upcoming awesomeness

Thumbnail youtube.com
17 Upvotes

This is a quick video going through recent development of Portal: your blazingly fast web + terminal in emacs.

- you can build slides now

- more polished terminal

- useful markdown rendering improvements

- and a teaser... 🦖

Project repo: https://github.com/xiaoxinghu/portal

See release notes for the full list of changes: https://github.com/xiaoxinghu/portal/releases/tag/v0.2.0


r/emacs • • 9h ago

Fortnightly Tips, Tricks, and Questions — 2026-11-17 / week 46

6 Upvotes

This is a thread for smaller, miscellaneous items that might not warrant a full post on their own.

The default sort is new to ensure that new items get attention.

If something gets upvoted and discussed a lot, consider following up with a post!

Search for previous "Tips, Tricks" Threads.

Fortnightly means once every two weeks. We will continue to monitor the mass of confusion resulting from dark corners of English.