In the last few weeks, I’ve revisited it and had a lot more success.

The Core Problems

The main problems that kept me from adopting Linux day to day were:

• Inability to set keyboard shortcuts for apps to provide a Mac-like experience (namely, using Meta or Alt instead of Ctrl so I could have the same common shortcuts everywhere).
• Clipboard Managers didn’t seem to really work.
• Lack of a Dash-like API lookup tool.

There were some papercuts, too. These were the most painful:

• Inability to configure the Framework 13’s trackpad scrolling speed.
• Global text replacement/text expansion doesn’t work
• PWA support with Firefox
• 1Password reliability and compatibility with Firefox

I’ve found solutions for some of these and set expectations about others, and have a decent working setup. It’s not perfect, but it’s usable.

xremap Solves Keyboard Shortcuts

xremap seems to inject itself at the right layer of the OS to allow remapping keyboard shortcuts. The best example of what was throwing me off was Firefox’s use of Ctrl as the modifier (and zero ability to change this setting). My fingers are used to using the Cmd key on mac, and used to consistent shortcuts across apps (for example, Ctrl-C isn’t “copy” in terminal apps, since that sends a control sequence).

xremap solves this, once I figured out the magic strings required to make it work and found a way to run it on login. At a high level, you create a YAML file like so:

- name: Firefox
  application:
    only: "firefox"
  remap:
    Alt-q: C-q
    Alt-c: C-c
    Alt-v: C-v
    Alt-t: C-t

Figuring out Magic Strings is Hard

The string given to only: is surprisingly hard to figure out. Even now, the only way I know to figure it out is to run xremap with debugging and observe the log with what it outputs when you interact with a window (I’m running Wayland-only, and most of the internet searches for debugging this problem only work with X11).

But, the remap: section is where you set things up: when I type Alt-c, it sends Ctrl-c. You can set this up for any app and it seems to work pretty consistently (in fact, this is probably the most consistent behavior of any piece of software on the Linux desktop). You can even have it match wildcards, so here is how I apply all these settings to all Firefox PWAs:

- name: FirefoxPWA
  application:
    only: /^FFPWA/
  remap:
    Alt-q: C-q
    Alt-c: C-c
    Alt-v: C-v
    Alt-t: C-t

At this point, the main annoyance is having to set up a mapping for new apps I install or use. But basically, if you are logging xremap’s output, you can click on an app, try to use a keyboard shortcut, and it will usually output that app’s name, which you can then use in this file.

For example, the file browser’s name is org.gnome.Nautilus, which I would never figured out in a million years.

Getting Things to Run at Login is Hard

It also helps to run xremap with --watch so it will pick up changes without having to be manually restarted.

I will say that getting this to run on login was amazingly difficult to do. I have no idea if what I came up with is the best way to do it, but it was the last of many attempts to get it working. I had to make a wrapper script and much with /etc/udev/rules.d/input.rules.

Here is the script for setting it up that I used. Oof.

Clipboard Management Doesn’t Really Work

I tried a lot of clipboard managers, and ended up using GPaste. I wouldn’t say it works, but it seems to provide the easiest way to access previously-copied snippets.

How Clipboard Management should work: Focus a text field in any app (including vim), invoke a keyboard shortcut to show a menu of available snippets on the clipoboard, select one, it is inserted into the text field. This is how all clipboard management works on the Mac.

How Clipboard Management works on Linux: Focus a text field in any app, but you can’t have a global keyboard shortcut for whatever reason, so using the mouse invoke the app and using the mouse select the snippet to paste, then use the mouse to focus the text field again, then paste. This sucks, but is workable.

From what I can tell, global keyboard shortcuts are difficult or impossible to configure. It also seems like there is not a universal text input system in Linux, so the idea that an app can appear, be interacted with, go away, and leave you back at the text input you started with is not possible to do consistently.

I tried a lot of clipboard managers and a lot of different ways to invoke them. None of them truly worked, so I’ve settled for the workflow above. It’s not great, but it works and is less friction than I would’ve thought.

Lack of API Lookup App

To see the workflow for API lookups on the Mac, check out my original post. It’s awesome to go from either Alfred (launcher) or vim to looking at API docs.

This just doesn’t seem possible on Linux. I tried two solutions:

• Zeal is an attempt to build Dash for Linux, but a) it is missing almost all documentation I would want, like various RubyGems, and b) there is no way to programmatically invoke a search such that it performs the search and focuses/activates the window. This means you have to use the mouse to interact with it.
• DevDocs is a website that can be installed as a PWA. You can programmatically perform a search and have it focus/activate by properly and carefully configuring the PWA setup in Firefox. Unfortunately, a) DevDocs has almost none of the documentation I want to look up (RubyGems), b) it’s extremely flaky, often showing no results or just hanging, and c) it remembers the scroll position when loading new pages, meaning each new search requires grabbing the mouse and scrolling back up to the top of the page. Linux requires a lot of mousing.

For now I’m using DevDocs and back to web searches for everything else. This really does suck, but I think I could live with it.

Do Not Use Snap or, through inaction, allow Snap to be used.

I was banging my head against a wall for hours because I had installed Firefox and 1Password via Snap as that is what the OS was telling me to do. In this setup, Firefox and 1Password do not work together. 1Password barely works at all, and Firefox PWAs do not work, period.

Unwinding this was not easy, despite using snap to uninstall them. I had to first install these tools via apt, which was a huge amount of code and setup. Then I was seeing snap just re-install these apps anyway. So I had to do further munging in some configuration to try to prevent that. I’m not sure if I have succeeded, but once I stopped using Snap, applications started working.

And, given how often Linux requires rebooting and logout/login, it seems to have stuck to the Firefox/1Password versions I installed.

Update While Writing This Post: Snap re-installed Firefox, even though I had set the priority for it to not do that! What a great fucking system!

I’m not sure what the point of Snap is, but my official policy is I hate it.

PWAs Sorta Work!

Progressive Web Apps AKA PWAs AKA running websites as if they were native apps are a really cool concept. They really would be a sweet solution if they were properly supported by browsers and operating systems. Chrome/Chromium/Edge appear to offer good support, but in practice, their PWAs don’t work - they are just windows of Chromium and not their own apps. I think the reason has to do with something something Gnome something Wayland, but I have no idea. I tried a lot of configurations and Chrome-derived browsers. None worked property.

Ultimately, I was able to use the Progressive Web Apps for Firefox extension, which provides the best support I could find. The main issue with it is that it doesn’t really respect or support a lot of metadata and behavior for PWAs, so you have to muck in about:config to get things working well.

I was able to script this almost entirely, so the process of installing a PWA is as painless as I could make it. But it still sucks.

The reason PWAs matter is that most services don’t make apps for Linux, but with a modicum of server-side configuration, and support from a browser/OS, a website can be made to act like an app.

I also created pwa.support to try to document how PWAs work across browsers and operating systems, plus details on how to use the PWA for Firefox extension effectively.

Things I have Yet To Solve

The Trackpad Sucks

The trackpad on the Framework 13 is absolute garbage for a lot of reasons, and two things make it hard to use that I couldn’t fix:

• Clicking moves the mouse cursor so you get a lot of clicks in the wrong place. Macs must have some way to counter this. The trackpad seems designed for a Windows world where you only ever click on the lower left part of the trackpad. Macs haven’t worked like that for over a decade and I cannot believe PC trackpads are still the same as they were 10 or even 20 years ago.
• Scrolling is hard-coded to the speed of light and not configurable that I could tell. I think it has something to do with Wayland, but it’s just mind-boggling. The scroll speed of my mouse is also not configurable, but it seems set at something usable.

While I prefer a trackpad, and my Magic Trackpad does work, the scroll speed makes them both unusable, so I try to use the mouse whenever I can’t use the keyboard. Desktop Linux requires a ton of mousing, but it’s generally fine.

Fingerprint Doesn’t Really Work

Using the Framework’s fingerprint to login pretty much doesn’t work. About 50% of the time, I open my laptop to a message that it’s timed out. The remainder of the time, if I don’t succeed on my first attempt it won’t try again. I set the PAM configuration to try more than once, but it just won’t.

For sudo and 1Password unlocking it works more reliably, but also does not try more than once. I did try to set up multiple fingerprints, but the UX is so bad. It took me 10 minutes of tapping my finger to get the first one set up. The UI provides no real feedback about what’s happening or what to do.

Text Expansion Not Really Possible

I don’t use a lot of text expansions, but I do have a few. I set up espanso and in some text fields in some apps when Mercury is in retrograde, it works. All other times it doesn’t. I think this is related to why clipboard management doesn’t work: there is no way to make a truly global keyboard shortcut and no API to interact with all text entry mechanisms in the OS. Oh well.

Installation Hell

There are many ways to install software and they all require a lot of nonsense. I’ve settled on using apt if possible, even if it requires sudo cat whatever to /etc/whatever. I mean, look at this nonsense required to install Terraform! WTF is any of that? The only reason I trust it is because it’s from their website¹.

Finding install instructions for software was not easy. My general strategy was to ask an AI, then use what it told me to find the actual instructions from the vendor or developer’s website. The AI was usually accurate, but given that I have no fucking idea what gpg --dearmor does, I wasn’t about to trust it outright.

I realize that each distro having at least one, if not three, package managers makes this problem difficult for maintainers and vendors. I also think creating yet more package managers is not a solution. Ideally, there could be some repository of “here’s how to install this software on this distro” metadata that maintainers could provide, but that’s not how things work.

Notifications are Cursed

No app seems able to consistently maintain its own state and the state of its notifications, nor do they respond to clicks consistently.

For example, Ghostty allows apps to send notifications. When this happens, I click the notification and…nothing happens. Sometimes the notification is removed from the notification center, sometimes not. But clicking it never activates Ghostty. Another example is Fastmail - it shows a badge and a notification for some number of unread messages. Sometimes that number is the exact number of unread messages! Frequently, it is not.

However notifications work under the hood, it’s either broken by design, or so complicated that no apps can figure out how to use it properly. I would honestly prefer if apps just ran xmessage (not that you can programmatically activate and raise an app reliably [ and yes, I have the Gnome extension that claims to do that and it sometimes works! ])

Stuff I Still Need a Mac For

I still use my Mac for a few things:

• Apple Ecosystem stuff like iPhotos. These can be read from Linux via the iCloud website, but my iPhone photos go here.
• Right-click in Finder to scan documents from my Phone. OMG this is so useful, especially during the US’s tax season!
• iMessage - having to use my phone only for text messaging my friends sucks.
• Pixelmator and Omnigraffle are great apps. I don’t use them often, but they work well.

Where I go From Here

Because of xremap it’s in good enough shape that I can use this laptop without losing my mind and wreaking havoc with learned keyboard shortcuts. I disabled a lot of pre-existing shortcuts and generally have a setup that isn’t hard to use.

As I mentioned in a previous post, I’m using AI code generators to understand how they work and how to use them, and doing this on a Linux box means the blast radius is contained. There’s nothing on this laptop’s hard drive that matters.

But even beyond that, I am enjoying using it. I realize there are other distros and other window managers and all that. I think for this second attempt, since I wrote down everything I had to do to set stuff up, I’m more confident in trying another window manager or distro². You can see my setup scripts in all their glory if you want to see what I’ve done.

For now, Desktop Linux is working well as a dev machine, despite my many complaints above.

I’ve been revisiting desktop Linux since my last attempt, and it involved setting up a lot of websites as Progressive Web Apps. The state of platform and browser support for the “sweet solution” is extremely mediocre. There’s pretty much no combination of operating system and browser that provides a truly app-like experience (except maybe Chromebooks).

I’ve captured it all on pwa.support. The content there is 100% written by me, after trying out various PWAs across Linux, macOS, Windows, and iOS (please get in touch if you can check this stuff on Android). The site’s code, however, was “vibe coded”¹. I did this to try to understand how AI code generation tools work (see my post, “The Death of a Software Craftsman” for a breakdown of where I see things). I’m not “all-in” (per my post) on these tools, but felt it was important to understand how they work on something real.

I find “golly gee whiz guys, Claude Code did a thingy” posts extremely tedious. I will not bore you with my specific thoughts and feelings. They are captured on pwa.support if you want to read them, but I’m not linking nor promoting it. I’m really tired of reading posts about how “amazing” these tools are. I’m no longer amazed and so should you.

I do want to re-iterate, the content and opinions on pwa.support are 100% from me, based on me opening up websites on a bunch of laptops. Believe me, if I could never touch a Windows laptop again, I would. But I had to see what the experience was like directly. Sweet solution, it was not.

The death of a software craftsman
Well, it happens a lot ‘round here
You think quality is a common goal
That goes to show how little you know

Developers work hard over the years to cultivate tools and techniques to improve the quality of the construction of their software. These tools and techniques are slowly becoming even more useless than they may already be. We must adapt by either going all-in, totally opting-out, or finding a middle ground by tracking the AI code-generation craze to fill the gap as a hand-coding artisan.

Software Quality Problems are People Problems

All techniques for improving the quality of software construction attempt to solve one problem: allow a person to understand the system they are changing so they can safely and correctly make a change to it. Techniques either prevent certain classes of bugs (e.g. static typing, code review, web frameworks), or make it easier to manage complexity (e.g. object-orientation, microservices, function currying)¹.

Although we debate and discuss various techniques amongst ourselves, no non-programmer cares about them. They can’t even conceptualize how software is made, so they have no way to know what quality construction is, how to value it, or even how to identify it. They just care about outcomes.

We tell ourselves that it's these skills that deliver those desired outcomes

Despite all that, we tell ourselves that these skills are critical in delivering those desired outcomes. I myself have a very particular set of skills. Skills I’ve acquired over a very long career. I write about them, I use them, and I am truly convinced that careful construction of software is the best way to reliably create systems that can be easily changed over their lifetimes. Even if no one knows or cares.

However.

Best Block No Be There

I may relish the solutions to building quality software, but the best solution to any problem is to eliminate the problem. Don’t bet against Mr Miyagai’s wisdom.

Let’s imagine a hypothetical tool that could take, as input, any software system and a description of a change. The tool produces, as output, an updated system with that change incorporated. This hypothetical system would not rely on any particular software construction technique—it works with any system you give it.

If software was created this way, would anyone know what, say, dependency injection was? Would anyone go to a conference to learn about the latest features of Ruby on Rails? Would anyone buy a book about carefully designing database schemas?

They would not. There would be no reason to. It literally would not matter what the code was like. Our hypothetical system could handle whatever it’s given and produce the requested changes. Sure, a small few would need to understand how code works, but the group would be quite small.

This hypothetical tool isn’t intended to be magic. Like any tool, there would be a skill to it, perhaps a difficult-to-master skill. And while there might be some overlap with the skills we use today to create quality software, most of those skills would become obsolete.

This system is not so hypothetical.

We know that in at least some cases, they do exactly what I described above.

We’ve seen what AI code generation systems are capable of. We know that in at least some cases, they do exactly what I described above. In some cases, they can take an existing system, a description of a change, and produce a system with that change. And they seem to be improving quickly, handling more and more cases.

And yet.

Soylent Green is People

My visceral reaction to these tools has been a combination of disgust and boredom. Here are the things I have told myself about why this technology can or should be ignored:

• It was created unethically.
• It consumes an unreasonable amount of resources (such as electricity and hard drives).
• It is owned and sold by some of the worst people in the world.
• Its true cost is hidden by investor money. Once its pricing is set in line with its true cost, no one could afford it.
• Being non-deterministic, it can never be as a good as a person.
• There’s no way to hold anyone accountable for its output.
• A real programmer will still need to go into the code. Practices around software construction will always matter.
• It’s shit at anything that’s not a popular technology applied to a common use case.

As of this writing, these are all true. But are they intrinsic problems? Must they be true, always?

AI code generation's problems aren't actually as intrinsic as they may seem

Unlike crypto, which is literally made of intrinsic problems preventing it from widespread adoption (please don’t email me), AI code generation’s problems aren’t actually as intrinsic as they may seem.

• AI models could be created ethically. There could be (and perhaps are?) systems created that comply with the licenses of their training materials.
• Systems that use AI models could be done with less power and resources. DeepSeek demonstrated that even minimal performance tweaking can give real benefits. Not enough to fully ameliorate the issues, but enough that I cannot say with certainty that these resource problems are unsolvable.
• AI code generation tools could be required to operate within a system of accountability. We’ve all seen that CEOs will comply with the government when threatened. And someday, we all might live under a functioning government that works for its people.
• Their price may be bearable when investor money runs out. Uber still exists as a going concern, despite being more expensive than ever.
• People are non-deterministic, too, so it’s not clear me that AI coding agents are necessarily worse than people at producing results. Coding agents are already better at programming than the vast majority of the population. I can’t say with certainty that every living programmer is the embodiment of John Henry.
• While AI coding agents may never be able to handle every imaginable task, it’s not clear to me that there is a limit on what they can do or that any given limit is unreasonable. Most of us are putting spreadsheets in a web browser or wrapping a database in a front-end, so if all that work is automated, that doesn’t seem necessarily bad to me.

In other words, all the problems of this technology could be addressed. I’m not saying they will be, or that it will happen on any particular timeline. But, it seems entirely possible to have a tool that produces software by taking in an existing system and written request as input, all without producing the externalities they currently do.

Not inevitable, but possible.

This means it’s worth considering a world where AI code generation is commonplace. In fact, professional software developers must consider such a world, and think deeply about their place in it.

As a thought experiment, imagine if all the issues above were addressed. We have AI code generation tools are ethical, use appropriate resources, etc. Who wouldn’t use these systems to produce software? At least in the context where the quality of the output was sufficient (a low bar if we are being honest), why would anyone not use these tools?

As much as I love coding, it would be really nice to produce results without fretting over variable names, modularity, OO purity, monads, or any of that stuff. Having a system produce reliable code just seems better. And it’s not like these tools are the first examples of code generation—we use code generation all the time.

Almost everyone in the orbit of software development only cares about outcomes

Remember, almost everyone in the orbit of software development only cares about outcomes and results, not the process by which they were achieved. It doesn’t mean you are wrong to care, but most people don’t.

So what’s a lonely programmer to do?

Ce n’est Pas un Griefpost

I’ve been a professional software developer for 30 years, and these AI code generation tools basically obviates a big chunk the skills I’ve developed. But I like using those skills. I like writing code. I like the process of building software. How do I navigate a world that no longer values that?

I’m results-oriented and am good at communicating with non-programmers. I can manage teams and projects, and keep people focused on business outcomes. These are all skills you need no matter how code is written. But my least happy professional eras were when I wasn’t involved with code.

Up until now, the never-ending need for programmers has given me a nice career where I can balance all of this stuff. Thankfully, I’m on the tail end of that career. But I’m not retired yet.

I see three paths in front of me: Hard Pass, All In, and Embrace Tradition.

Hard Pass

The problems I listed above are real. And while they could be solved, there’s no guarantee they will be solved in any given timeframe, or even at all. The problems compound and create what many believe to be an easy choice: don’t support unethical systems created by terrible people that quickly exhaust our resources.

This is how I felt initially. It’s just easy to write this entire thing off as awful, useless, evil, of poor quality, and not something I want to be involved with (like crypto!). Unlike ignoring crypto, the Hard Pass has consequences to the career of a software professional.

In the short term, it’s still possible to be gainfully employed in software while abstaining from AI. There’ll be fewer and fewer such jobs as time goes by, but there should be at least a few years of generally available jobs writing code by hand.

But these positions will become fewer and far between. Choosing AI abstinence means ultimately exiting professional software development, at least at some point.

Choosing AI abstinence means exiting professional software development

This might seem extreme, but be honest: these tools will become far more prolific over the short term. Not enough people are going to come around on the ethical issues to slow or stop their adoption. The country I live in is 350+ million people who tolerate the sexual exploitation and murder of children (as just one example). I say this not to encourage you to give in or sell out, but just to understand that the world of software development as you know it is going to become very small very fast.

This is the consequence of the moral dilemma. You can opt-out. Almost every job that ever was or ever will be is something other than writing software. Most people make a living without writing software. But if you want to give AI a Hard Pass, you will eventually be giving your career as a programmer a hard pass, too (though please stick around for option three, below).

If this is you, start figuring out how you’re going to make a living otherwise.

Or, you could go all-in.

All In

Going all-in is to accept that the profession is changing so radically that you’ll need to retrain yourself. You’ll leverage your experience and incorporate these new tools in the same way as you would any other advance in the field. Except you may leave a lot of your existing skills behind.

It's hard to live a life free of compromise

It’s hard to live a life free of compromise. Going All In is to compromise. It means you must tolerate the downsides of this technology (assuming you believe there are at least some downsides). Of course, tolerance is not the same thing as support. Every one, every where, every day must weigh their needs against what their conscience can bear.

If your priority is to stay working in software development, especially if you have a long career ahead of you, going All In is the safest, simplest, most practical option. You just have to be able to live with yourself.

There are two reasons I find this option depressing, beyond having to tolerate the ethical problems.

One is as I mentioned above: I like coding. I like writing code and everything about it. I like the control it gives me, and I do not enjoy “coding” by writing Markdown and feeding it to a compiler that sometimes works and sometimes doesn’t until I ask it nicely to do what I need.

Two is related to the “common technology” problem. These tools produce code using the popular frameworks, techniques, and libraries. While it’s possible I won’t have to review or modify the code these tools produce some day, today is not that day. And I just really, really don’t want to write React or Tailwind. I don’t really want to learn Python. And the creator of Rails can go fuck himself.

But that’s me. If I were younger, smarter, and less concerned with the ethical issues, I’d embrace this new world, and not worry so much about what code was being produced. The whole point is that it won’t matter in the end.

All this being said, flat-pack furniture made of fiberboard did not eliminate the skill of putting a chisel to hard wood. The time of the software craftsman could be coming.

Reject Modernity, Embrace Tradition

I always thought the “software craftsman” movement was dumb. Uncle Bob is a terrible person with bad ideas, and Agile Thought Leaders seem more focused on their billable rate than improving outcomes for users. Their collective disrepsect for anyone not a programmer is galling. But most of all, it just seemed like navel-gazing. Results and outcomes really do matter!

But what is a craftsman, really? Someone with deep skills honed over many years, who can produce amazing results using a process that’s almost as engaging to observe as the results themselves. There are certain outcomes that only a highly trained human hand can deliver.

There are still craftsmen being trained and employed to this day, across a wide variety of industries. Although few people have hand-made furniture, you can still commission it. And don’t forget that even uninspiring chain restaurants like The Cheesecake Factory still make almost all their food from scratch.

Thus, it’s not unreasonable to think that such an industry will exist for writing software. In the short term, there’s still a ton that AI coding agents simply can’t do very well. And in the long term, there will be at least some demand for software written to a higher standard than what AI is producing. Of course, there will always be the need to pay a high price to have real programmer pop the hood on your vibe-coded mess to figure out what’s actually wrong.

However, to live in this world as a Software Crafter² is to understand AI code generation…at least until it plateaus in capabilities. To be marketable and make a living, you have to know what gap you are filling. And that gap is changing often. Thus, you cannot abstain entirely from AI if this is the way you go. You may not use it to produce your results, but you will need to use it—not just read about it—to understand it.

We don’t get to live our lives free of compromise.

Maybe in the next world.

If you want to know about more about why Brut exists or its philisophical underpinnings, check it out!

What is a Sub-Command CLI?

At first glance, OptionParser doesn’t seem to support a sub-command CLI, like so (I’ll explain what each part is below):

> bin/test --verbose audit --type Component specs/front_end

Yes, you could configure --verbose and --type TYPE, then figure out that the first thing left over in ARGV was a command, but it gets very cumbersome when things get beyond trivial, especially when you want to show help.

Fortunately, OptionParser's lesser-known (and oddly-named) method order! parses the command-line up to the first argument it doesn’t understand. How does this help?

Consider the command above. It’s made up of five parts: the app name (bin/test), the globally-applicable options (--verbose), the sub command (audit), command-scoped options (--type Component) and the arguments (specs/front_end):

> bin/test --verbose audit --type Component specs/front_end
   ---+--     ---+-- --+--   ----------+---  ----+------
      |          |     |               |         |
App---+          |     |               |         |
Global Options---+     |               |         |
Sub Command------------+               |         |
Command Options------------------------+         |
Arguments----------------------------------------+

You’d design a CLI like this if the various sub-commands had shared code or behavior. It also helps to avoid having a zillion different scripts and provides a namespace, especially if you can provide good help. Fortunately, OptionParse does provide good help and can parse this.

Two Option Parsers Divide Up the Work

The key is to use two OptionParsers:

• The first parses the global options. It uses order! (instead of parse!) so that it only parses options up to the first argument it doesn’t understand (audit) in our case.
• The second uses parse!, which consumes the entire rest of the command line, leaving ARGV with whatever wasn’t parsed.

Here’s a basic sketch. First, we’ll create the global OptionParser:

require "optparse"

global_parser = OptionParser.new do |opts|
  opts.banner = "bin/test [global options] command [command options] [command args...]"
  opts.on("--verbose", "Show additional logging/debug information")
end

Next, we’ll need the second OptionParser for the audit subcommand. You’d need one OptionParser for each subcommand you want to support.

commands = {}
commands["audit"] = OptionParser.new do |opts|
  opts.on("--type TYPE", "Set the type of test to audit. Omit to audit all types")
end
# Add more OptionParsers for more commands as needed

Now, when the app runs, we parse the global options first using order!. This means that ARGV[0] (i.e. the first part of the command line that didn’t match anything in the global OptionParsers) is the command name. We use that to locate the OptionParser to use, then call parse! on that.

global_options  = {}
command_options = {}

global_parser.order!(into: global_options)
command = ARGV[0]
command_parser = commands[command]
command_parser.parse!(into: command_options)

# Now, based on the value of command, do whatever needs doing

What OptionParser doesn’t give you is a way to manage the code to run for the e.g. audit command, but you have all the object-oriented facilities of Ruby available to do that. In Brut, the way I did this was to create a class with an execute method that maps to its name and exposes it’s OptionParser. Roughly:

class AuditCommand

  def self.option_parser
    OptionParser.new do |opts|
      opts.on("--type TYPE", "Set the type of test to audit. Omit to audit all types")
    end
  end

  def initialize(command_options:, args:)
    @command_options = command_options
    @args            = args
  end

  def execute
    # whatever
  end
end

commands["audit"] = AuditCommand

# ...
command = ARGV[0]
command_klass = commands[command]
command_parser = command_klass.option_parser
command_parser.parse!(into: command_options)
command_klass.new(command_options:, args: ARGV).execute

OptionParser also provides sophisticated type coercion via accept. Many built-in conversions are available and you can create your own.

This code gets more complex when you want to show help or handle errors

Showing Help and Handling Errors

OptionParser can produce a decent help message:

puts global_parser
# or
puts command_parser

You can do much fancier stuff if needed by using summarize.

For handling errors, OptionParser will raise an error if options were provided that aren’t valid, and you can check whatever you need and call exit.

Now, there is a lot of “do whatever you want” here, as well as potentially verbose code. Why not use a gem that does this for you?

Don’t Use Gems if Your Needs are Typical

Code that relies only on the standard library is stable code. The standard library rarely breaks things and is maintained. OptionParser is designed to parse a UNIX-like command line, which is usually what you want.

Even though OptionParser is a bit verbose, you likely aren’t writing command-line code frequently, so the verbosity—and reliance on the standard library—is a bonus. DSLs, at least in my experience, tend to have a half-life and can be hard to pickup, so you re-learn them over and over, unless you are working in them every day.

I built GLI to make this easier, but in practice, it’s a somewhat wide DSL that you have to re-learn when editing your CLI.

Thor is very popular, included with Rails, and mostly supports this kind of UI, but it is an even denser DSL that I don’t think rewards you for learning it. And, because it does not use OptionParser, it’s very sensitive to command and argument ordering in a way that seasoned UNIX people would find surprising and annoying. It also includes a ton of other code you likely don’t need, such as the ability copy files and templates around.

Rake is part of the standard library, but the CLIs it produces are not very ergonomic. You must use a sequence of square brackets and quotes to pass arguments, and there is no facility for options like --verbose. Rake is designed as a dependency manager, e.g. build my favicon.ico whenever my favicon.png changes. It’s not a general-purpose way to make command line apps.

So, embrace the standard library, and embrace OptionParser!

There’s also a tutorial that does the same thing or, if you are super pressed for time:

<form>
  <brut-confirm-submit message="Are you sure?">
    <button>Save</button>
  </brut-confirm-submit>
</form>

<brut-confirmation-dialog>
  <dialog>
    <h1></h1>
    <button value="ok"></button>
    <button value="cancel">Nevermind</button>
  </dialog>
</brut-confirmation-dialog>

Progressive enhancement, and no magic attributes on existing elements.

• <brut-confirm-submit> docs
• <brut-confirmation-dialog> docs

Rails popularized “convention over configuration”, but it often fails to help when conventions aren’t aligned, often silently failing with no help for debugging. This cultural norm has proliferated to many Ruby tools, like Shopify’s ruby-lsp, and pretty much all of Apple’s software design.

• I asked my editor to jump to a definition and the LSP didn’t do it and there is no error message.
• I took a picture on my phone, it’s connected to WiFi, as is my computer, and it’s not synced to my photos. There is no “sync” button, nor any sort of logging telling me if it tried to sync and failed or didn’t try and why not.
• I’m creating my dev and test databases and it doesn’t create my dev database, but creates my test database twice. (I hope this poor guy figured it out…it’s been seven years!)

We all experience these failures where we get an error message that’s not helpful and then no real way to get more information about the problem.

Creating a debuggable system is critical for managing software, especially now that more and more code is not written by a real person. To create such a system, it must provide two capabilities:

• Helpful and descriptive error messages
• The ability to ask the system for much more detailed information

Both of these capabilities must be pre-built into the system. They cannot be provided only in some interactive debugging session or only in a development environment. You want these capabilities in your production system.

Write Helpful and Descriptive Error Messages

There is always a tension between an error message that is so full of information as to be useless and one so vacant that it, too, is useless. Designers never want users to see error messages. The security team never wants to allow error messages to provide hackers with information. And programmers often write errors in their own language, which no one else understands.

Ideally, each error message the system produces is both unique and is written in a way you can reference more detailed information about what to do.

Consider what happens when using NeoVim and Shopify’s ruby-lsp is asked to go to the definition of a Ruby class and, for whatever reason, it can’t:

No Location Found

This absolutely sucks:

• It doesn’t explain what went wrong
• It doesn’t provide any pointers for further investigation
• It’s not clear what is producing this message: ruby-lsp, the Neovim plugin, or Neovim itself
• It doesn’t even say what operation it was trying to perform!

Here are some better options:

• “Could not find definition of ‘FooComponent’”
• “Could not find definition of ‘FooComponent’, ruby-lsp returned empty array”
• “Could not find definition of ‘FooComponent’, restart ruby-lsp server with --debug to debug”
• “Could not find definition of ‘FooComponent’, see NeoVim’s log at ~/cache/logs/neovim.log for details”
• “Could not find definition of ‘FooComponent’, searched 1,234 defined classes from 564 folders”

These messages each have attributes of a useful error:

• The operation that caused the issue (“Could not find definition”)
• The specific inputs to that operation (FooComponent)
• Observed behavior of dependent systems (“ruby-lsp returned empty array”)
• Options to get more information (“restart ruby-lsp…” and “see NeoVim’s log”)
• Metadata about the request (“searched 1,234 classes…”)

These can all help you try to figure out the problem. Even if you can’t provide all diagnostics, you should always consider including in your error message:

• What operation you tried to perform
• What result you got (summarized, not analyzed)
• What systems are involved:
  • attach your system’s name to messages you create
  • attach the subsystem’s name to message you receive and pass along

Aside from this, creating a way to get more information is also extremely helpful.

Create a Debug or Diagnostic Mode

The volume of information required to fully debug a problem can be quite large. It can be costly to produce and difficult to analyze. This can be a worthwhile tradeoff if something isn’t working and you don’t have any other options. This means your system needds a debug or diagnostic mode.

A diagnostic mode should produce the inputs and outputs as well as intermediate values relevant to producing the outputs. Let’s imagine how finding the definition of a class in Ruby works in the ruby-lsp.

At a high level, the inputs are the symbol being looked-up and the outputs are a list of files and locations where that sybmol is defined. LSP is more low level, however, as it will actually accept as input a line/column of a file where a symbol is referenced, and expect a list similar locations in return.

This means there are a few ways this can fail:

• The file doesn’t exist
• There is no symbol at the location of the file
• The symbol’s definition can’t be found
• The symbol was found, but the file isn’t accessible to the caller

The most common case is a symbol being correctly identified in the file, but not found. This is where intermediate values can help.

Presumably, a bunch of files were searched for the symbol that can’t be found. Knowing those files would be useful! But, presumably, those files were found by searching some list of folders for Ruby files. That list of folders would be nice to know as well!

This is obviously a massive amount of information for a single-line error message, however the information could be stored. The entire operation could be given a unique ID, which is then included in the error message and included in a log file that produces all of this information. Given the volume of information, you’d probably want the LSP to only produce this when asked, either with a per-request flag or a flag at startup (e.g. --diagnostic or --debug).

Making all this avaiable requires extra effort on the part of the programmer. Sometimes, it could be quite a bit of effort! For example, there may not be an easy way to generate a unique ID and ensure it’s available to everywhere in the code with access to the diagnostic information. And, of course, all this diagnostic code can itself fail, creating more intermediate values needed to diagnose problems. We’ve probably all written something like this before:

begin
  some_operation
rescue => ex
  begin
    report_error(ex)
  rescue => ex2
    $stderr.puts "Encountered #{ex2} while reporting error #{ex} - something is seriously wrong"
  end
end

In addition to just culling the data, you have to log it, or not. Ruby’s Logger provides a decent solution using blocks:

logger.debug {
  # expensive calculation
}

The block only executes if the logger is set to debug level. Of course, you may not like the all-or-nothing approach. The venerable log4j used in almost every Java app allows you to configure the log level per class and even dynamically change it at runtime. You can do this in Ruby with SemanticLogger:

require "semantic_logger"

SemanticLogger.appenders << SemanticLogger::Appender::IO.new(STDOUT)

class Foo
  include SemanticLogger::Loggable
  def doit
    logger.debug("FOO!")
  end
end

class Bar
  include SemanticLogger::Loggable
  def doit
    logger.debug("BAR!")
  end
end

foo = Foo.new
bar = Bar.new

foo.debug # => nothing
bar.debug # => nothing
Foo.logger.level = :debug
foo.debug # => 2025-08-06 18:35:59.138433 D [2082290:54184] Foo -- FOO!
bar.debug # => nothing

While SemanticLogger only allows runtime changes of the global log level, you could likely write something yourself to change it per class.

Please Create Debuggable Systems

While you could consider everything above as a part of observability, to me this is distinct. Debuggable systems don’t have to have OTel or other fancy stuff—they can write logs or write to standard output. Debuggable systems show useful error messages that explain (or lead to an explanation of) the problem, and can be configured to produce diagnostic information that tells you what they are doing and why.

You can get started by creating better error messages in your tests! Instead of writing assert list.include?("value"), try this:

assert list.include?("value"),
       "Checking list '#{list}' for 'value'"

Try to make sure when any test fails, the messaging you get is everything you need to understand the problem. Then proliferate this to the rest of your system.

This is a whirlwind tour of the basics of Brut, where I build a blog from scratch in a bit over 15 minutes. The app is fully tested and even has basic observability as a bonus. The only software you need to install is Docker.

• Watch on YouTube, if PeerTube isn’t working for you for some reason
• Check out the source code, if you don’t want to watch a video

Brut aims to be a simple, yet fully-featured web framework for Ruby. It's different than other Ruby web frameworks. Brut has no controllers, verbs, or resources. You build pages, forms, and single-action handlers. You write HTML, which is generated on the server. You can write all the JavaScript and CSS you want.

Here’s a web page that tells you what time it is:

class TimePage < AppPage
  def initialize(clock:)
    @clock = clock
  end

  def page_template
    header do
      h1 { "Welcome to the Time Page!" }
      TimeTag(timestamp: @clock.now)
    end
  end

end

Brut is built around low-abstraction and low-ceremony, but is not low-level like Sinatra. It’s a web framework. Your Brut apps have builtin OpenTelemetry-based instrumentation, a Sequel-powered data access layer, and developer automation based on OptionParser-powered command-line apps.

Brut can be installed right now, and you can build and run an app in minutes. You don’t even have to install Ruby.

> docker run \
        -v "$PWD":"$PWD" \
        -w "$PWD" \
        -it \
        thirdtank/mkbrut \
        mkbrut my-new-app
> cd my-new-app
> dx/build && dx/start
> dx/exec bin/setup
> dx/exec bin/dev
# => localhost:6502 is waiting

There’s a full-fledged example app called ADRs.cloud you can run right now and see how it works.

What You Get

Brut has extensive documentation, however these are some highlights:

Brut’s core design is around classes that are instantiated into objects, upon which methods are called.

• No excessive include calls to create a massive blob of functions.
• No Hashes of Whatever. Your session, flash, and form parameters are all actual classes and defined data types.
• Minimal reliance of dynamically-defined methods or method_missing. Almost every method has documentation.

Brut leverages the modern Web Platform.

• Client-side and server-side form validation is unified into one user experience.
• BrutJS is an ever-evolving library of autonomous custom elements AKA web components to progressively enhance your HTML.
• With esbuild, you can write regular CSS and have it instantly packaged, minified, and hashed. No PostCSS, No SASS.

Brut sets up good practices by default.

• Your app will have a reasonable content security policy.
• Your database columns aren’t null by default.
• Your foreign keys will a) exist, b) be indexed, and c) not be nullable by default.
• Time, available through Brut’s Clock, is always timezone-aware.
• Localization is there and is as easy as we can make it. We hope to make it easier.

Brut uses awesome Ruby gems

• RSpec is how you write your tests. Brut includes custom matchers to make it easier to focus on what your code should do.
• Faker and FactoryBot will set up your test and dev data
• Phlex generates your HTML. No, we won’t be supporting HAML.

Brut doesn’t recreate configuration with YAML.

• I18n uses the i18n gem, with translations in a Ruby Hash. No YAML.
• Dynamic configuration is in the environment, managed in dev and test by the dotenv gem. No YAML.
• OK, the dev environment’s docker-compose.dx.yml is YAML. But that’s it.
• YAML, not even oncetwice.

Brut doesn’t create abstractions where none were needed.

• Is this the index action of the widgets resource or the show action of the widget-list resource? is a question you will never have to ask yourself or your team. The widgets page is called WidgetsPage and available at /widgets.
• My Widgets class accesses the WIDGETS table, but it also has all the domain logic of a widget! No it doesn’t. DB::Widget gets your data. You can make Widget do whatever you want. Heck, make a WidgetService for all we care!
• What if our HTML had controllers but they were not the same as the controllers in our back-end? There aren’t any controllers. You don’t want them, you don’t have to make them.
• What about monads or algebraic data types or currying or maybe having everything be a Proc because call?! You don’t have to understand any part of that question. But if you want your business logic to use functors, go for it. We won’t stop you.

WHY?!?!?!

I know, we can vibe away all the boilerplate required for Rails apps. But how much fun is that? How much do you enjoy setting up RSpec, again, in your new Rails app? How tired are you of changing the “front end solution” every few years? And aren’t you just tired of debating where your business logic goes or if it’s OK to use HTTP DELETE (tunneled over a _method param in a POST) to archive a widget?

I know I am.

I want to have fun building web apps, which means I want write Ruby, use HTML, and leverage the browser. Do you know how awesome browsers are now? Also, Ruby 3.4 is pretty great as well. I’d like to use it.

What I don’t want is endless flexibility, constant architectural decision-making, or pointless debates about stuff that doesn’t matter.

I just want to have fun building web apps.

Next Steps

I will continue working toward a 1.0 of Brut, building web apps and enjoying the process. I hope you will, too!