Transparent Software is software the user can “see through”. It’s clear what the software is doing. It does something that might be slow to do manually, but contains no magic.

Hugo and other static site generators are an example. Hugo takes some HTML templates, your words in Markdown format, and outputs the HTML files. If you’re a programmer, you can probably picture yourself replacing it, right? Sure there will be edge cases, several kinds of templates, different amounts of customization, but nothing you can’t handle. I use Hugo to publish this blog. If Hugo went away tomorrow I could replace enough of it to keep blogging in a few days, maybe a week. I have all the important content, my posts, in a bunch of Markdown files.

The opposite of Hugo is Wordpress, which I used here before Hugo. Wordpress is opaque. It was very difficult for me to replace it. Migrating this blog to Hugo was a serious effort. I don’t have a mental model of what Wordpress does. My content was spread over various tables in its database.

Why Transparent Software?

For the last 15 years I have been managing my passwords with kip (the first ten years in Python, the last five in Rust). I didn’t want to use a commercial manager precisely because they are not transparent. Passwords are very important!

I wanted my passwords to be a folder of GPG (now AGE) encrypted files. That’s it. The name of the website is the name of the file. The contents of the file are username, password, and some notes. The tool, kip, just makes it easy to manage those files. kip <site> finds the file, uses a command line from the config file to decrypt it, and puts the password in my paste buffer; which it does by calling a command line defined in the config file.

That means I can replace the tool anytime. I control the data and I understand what it does.

It builds trust with users. If anyone else uses kip, they are not beholden to me.

And it is easy to debug and hack. I can run the gpg command manually. I can tweak it and I can change things:

• Switching from GPG to AGE didn’t involve any code changes, just a config file example in the README.
• Switching the copy-to-buffer tool likewise was a README update, and a one liner to make it the default.

Transparent software will often be modular, clear, composable, simple, parsimonious, and extendable, almost as a side-effect.

Transparent all the way down: calum.nvim + llm + HTTP

Stacked transparent software can be a joy to use.

As an example, I wrote a neovim plugin to easily talk to Large Language Models (“AI”) while I am coding - calum.nvim.

All that does is shell to the wonderful llm. The command lines are in the config file. This line is how I get AI to review my code:

  review_cmd = 'llm -m {MODEL} -o temperature 0.2 -s \'You are a code review tool. You will be given snippets of code which you will review. You first identify the language of the snippet, then you provide helpful precise comments and suggestions for improvements. For each suggestion provide a recommended code change, if approriate. Be concise.\'',

And llm itself is transparent. What it does it make HTTP requests. If you set LLM_OPENAI_SHOW_RESPONSES=1 it prints those out.

That gives me a lot of confidence that everything is working correctly. It means that I’m not worried about depending on calum.nvim or llm. I can replace either.

Not a new idea - Eric S. Raymond and The Art of UNIX Programming

The idea of writing a GUI as a wrapper over a command line tool has been a UNIX staple for a very long time. Writing a GUI is hard. Writing software that does something useful is hard. Separating the two hard things makes each better.

Twenty years ago, Eric S. Raymond in his essential The Art of UNIX Programming (the online version is a little ugly, so Amazon link) dedicates all of Chapter 6 to transparency, as well as several other sections.

Aside: If you take nothing else away from this post remember that book. It took me forever to read because every few pages I would have an epiphany and go re-write some things.

Go forth and be transparent

I have been trying to write this post for years. The principle seems very important and I wanted to do it justice, so of course I wrote nothing.

This will have to do.