How many reactions per second can Speechwave handle?

A user recently sent us this question:

How many reactions can the audience send at once before the emoji display slows down or drops some of them?

It’s a fair question to ask before you put an app in front of a few hundred people at a conference. We haven’t had a reported issue yet, but I realized I had never actually measured it. So I did, and here are the results.

If you haven’t seen it, Speechwave is a live emoji reaction app for talks. The audience taps emoji on their phones, and a Chrome extension floats them over the speaker’s slides. The speaker gets analytics afterward.

Great expectations

I already knew from developing the code that each audience member is limited to one reaction every 3 seconds. So the most any room can send is the number of people divided by 3, per second. A 300-person room tops out at 100 reactions per second, and only if everyone taps the instant their button comes back, and that’s if you get 100% room participation.

That gives us our theoretical maximum, but tells us nothing about what the server does at 100 reactions per second.

What about SQLite?

I next guessed that SQLite could be a weak spot. Every accepted reaction is saved to the database, and SQLite has a reputation for being a single-writer database. However, it turns out SQLite can write far more than a few hundred rows a second.

Measuring it inside the same container used for the rest of the test, it did about 7,500 inserts per second. It didn’t seem like the database was going to be out limiting factor.

Testing methods

Wanting the test to look like production, I built the production Docker image and ran it locally with the same limits as my Fly machine: one CPU, 512 MB of memory, and a database pool of 2. Then I wrote a small Node script that simulates an audience. Each fake person loads the talk page, joins the LiveView over a websocket, and taps on a timer. A second connection plays the Chrome extension and times how long a reaction takes to arrive.

There were two gotchas.

First, Docker’s --cpus=1 limits how much CPU time a container gets, but the Erlang VM still looked at my laptop and started eight schedulers. On Fly it would see one. When I pinned the container to a single core, the numbers got a worse, but a lot more realistic.

Second, the load generator was the bottleneck. Every reaction is sent to every audience phone, so with 800 fake people one Node process had to read about 200,000 messages per second. It couldn’t, and that backed things up on the server in a way real phones wouldn’t. I split the generator across several processes and made it count messages without parsing them.

Results

I held the audience at a fixed size and raised the total number of reactions per second until something gave.

Of course, the answer depends on how many people are in the room. With 400 people, things slow down at about 100 reactions per second and start dropping soon after. With 800 people, the same thing happens at about 45.

Showing everybody everything

Here’s the part I hadn’t initially thought about. The audience page also shows the floating emoji, so that people can see their reaction appear. That means every reaction is pushed to every connected phone, not only to the speaker’s laptop.

Here’s the handler from the audience LiveView:

def handle_info(
      %Phoenix.Socket.Broadcast{event: "new_reaction", payload: %{emoji: emoji}},
      socket
    ) do
  {:noreply, push_event(socket, "new_reaction", %{emoji: emoji})}
end

Every audience member runs that for every reaction. So the work per second is the number of people times the number of reactions per second, which grows with the square of the room. In my runs one core topped out at about 35,000 to 40,000 of those pushes per second, and both of my break points were right there:

• 400 people × 100 reactions/s = 40,000
• 800 people × 45 reactions/s = 36,000

That gives us a rule of thumb: total reactions per second should stay under about 35,000 divided by the number of people. A room of 1,000 can handle about 35 reactions per second. A room of 200 can handle about 175, though it can’t reach that, because the 3-second limit caps it at about 67.

Real audiences don’t tap constantly. If each person reacts about once every 30 seconds, 800 people send 27 reactions per second, and that ran fine at 55% CPU. Raise it to 1,200 people at the same pace and the core saturates. Obviously, we could handle higher loads if we assume less than 100% participation.

What failure mode looks like

We want things to degrade gracefully. When the core is saturated, the database insert inside someone’s LiveView waits too long for a pool connection and raises. That crashes the process, so the reaction is lost, and the phone has to reconnect. While it’s not ideal, the audience is unlikely to notice a few lost reactions. However…

Memory was the other ceiling. Each connected person costs about 0.23 MB on top of a baseline around 160 MB. A 3,200-person run was killed for running out of memory. That’s not something we’ve seen in production yet, but it wouldn’t be great.

How we can make it even better

The obvious fixes are to batch the pushes to audience phones (one message every quarter second instead of one per reaction), to batch the database writes, and to catch an insert failure so one timeout doesn’t take a page down with it. The first one attacks the primary issue. Of course, if we need to, we can always scale our servers at Fly as well.

Caveats: These were single runs, so the edges are fuzzy: one 800-person run lost 5% of its reactions at a rate where a harder run lost none, so there’s some variance here. Fly’s shared CPU can be throttled harder than a pinned core on my laptop, so the real limits may be lower. Also, I only measured the server. Whether the emoji on the speaker’s screen keep up at these rates is a separate test. For really large talks we may need to throttle/summarize the reaction stream going to the speaker’s broswer extension.

So in summary…

For a typical talk with a few hundred participants, life should be good. For a thousand active particpants (congratulations!), reactions might start to drop above roughly 35 reactions per second across the whole audience, which is what you’d see if everyone tapped about once every 30 seconds and then something exciting happened in the talk. That’s a good problem to have, and now we know where the edge is. Even better, we know how to push the edge out futher if we need to.

Why I built Speechwave in Elixir (as a Rails developer)

I’ve been developing with Ruby on Rails for a long time. If you had asked me to bet on what I’d build my next web app with, I would have bet on Rails.

Then I started building Speechwave, a live emoji reaction app for conference talks, and I wrote it in Elixir instead

This isn’t a “Rails is dead” post. It’s still a great choice for lots of things. This is about what this particular app needed, why Elixir turned out to a great choice, and why the hosting bill is about as small as a bill can get. If you’re an Elixir developer, some of this may be familiar.

What Speechwave does

Attendees scan a QR code at a talk and are sent to a page of emoji buttons. They tap one. A Chrome extension on the speaker’s laptop receives that reaction and floats the emoji over the speaker’s Google Slides in real time. After the talk, the speaker can see which slides got which reactions.

Look at that from a server’s point of view. It’s a lot of small, short-lived, simultaneous things:

• Dozens (or hundreds) of phones holding open WebSocket connections
• Each tap needs to be rate limited, optionally saved, and fanned out to everyone who cares
• The speaker’s extension holds one more long-lived connection, and it isn’t even a web page
• The whole thing is quiet for days, then very busy for 45 minutes

That last point will matter quite a bit when we get to the hosting section.

Why it works: the three things I would have had to do in Rails

I don’t want to oversell this. Rails can do real-time. Action Cable exists, and Rails keeps improving. But in Rails I would have been assembling pieces. In Phoenix, the pieces come in the box and they were designed together.

1. A message bus that doesn’t care who’s listening

Phoenix PubSub lets any process broadcast to a topic and any other process subscribe to it. The attendee’s LiveView doesn’t know the Chrome extension exists. After the rate limit check (and saving the reaction, if a session is recording), it just broadcasts. Here’s the handler from talk_live.ex, with the persistence code trimmed out:

def handle_event("react", %{"emoji" => emoji}, socket) do
  if RateLimiter.allow?(socket.assigns.session_id) do
    # ...save the reaction if a session is recording...

    SpeechwaveWeb.Endpoint.broadcast!(
      "reactions:#{socket.assigns.talk.slug}",
      "new_reaction",
      %{emoji: emoji}
    )
  end

  {:noreply, socket}
end

The extension’s channel is subscribed to the same topic, so it gets the message. If it add a third kind of listener tomorrow, say a live dashboard, nothing in that function changes.

2. LiveView for the attendee page

The attendee page is a LiveView, so we got WebSocket-backed interactivity without building a single-page app and without maintaining a separate JavaScript frontend. The UI is a function of server state, and Phoenix handles keeping the browser in sync. For an app where nearly every interesting event is “something happened on the server, tell the clients,” that model is a very good match.

3. Cheap, isolated processes for everything else

The rate limiter is a GenServer that owns an ETS table (an in-memory key/value store built into the runtime). Reads don’t queue behind the GenServer, so a room full of people tapping at once doesn’t turn into a traffic jam. It’s a few dozen lines and there is no Redis anywhere.

Presence, which tracks how many extensions are connected to a talk so we can enforce plan limits, is also built in. So is the supervision tree that restarts any piece that crashes without taking down the rest. Here’s the top level of the tree from application.ex, trimmed a bit for space:

children =
  [
    Speechwave.Repo,
    {Phoenix.PubSub, name: Speechwave.PubSub},
    Speechwave.RateLimiter,
    Speechwave.AuthThrottle,
    # ...a few more throttles and reapers...
    SpeechwaveWeb.Endpoint,
    SpeechwaveWeb.Presence
  ] ++ backup_children()

opts = [strategy: :one_for_one, name: Speechwave.Supervisor]
Supervisor.start_link(children, opts)

I wrote down what happens when each child crashes (the rate limiter loses its cooldown state, Presence resets its count, and so on) and for this app every answer is “acceptable, by design.” Thinking about failure that explicitly is something the platform nudges you toward. In a Rails apps, I mostly find out what a crash does when it happens.

The hosting bill

This is the part I was the most excited about, and why I’m writing this post in the first place.

Speechwave runs on Fly.io, and here are the essential bits configuration:

[[vm]]
  memory = '512mb'
  cpu_kind = 'shared'
  cpus = 1

[http_service]
  auto_stop_machines = 'suspend'
  auto_start_machines = true
  min_machines_running = 0

That’s one shared CPU and 512 MB of memory. When nobody is using the app, the machine suspends. When someone scans a QR code, it wakes up.

Three things make that work, and Elixir is part of each of them.

The runtime is frugal. Because the BEAM runs lightweight processes instead of OS threads, one small machine can hold a lot of open connections. I’ve configured the app to allow up to 1,000 concurrent connections on that single 512 MB box. For context, my realistic target is a few conference rooms, not a stadium.

One process serves everything. The reaction fan-out, the LiveView pages, the Channel for the extension, the rate limiter, the presence tracking, and the scheduled backups all run inside a single Elixir application. I don’t need a separate Redis for pub/sub, a separate worker process for background jobs, or a separate WebSocket server. Fewer moving parts means fewer things to pay for and fewer things to keep alive.

SQLite is enough. The first version of this app used Fly’s managed Postgres. I’ve since moved to SQLite on a Fly volume, with Ecto’s SQLite adapter and a pool size of 2. Reactions are small writes, the data volume is tiny, and a few talk-shaped workloads doesn’t need a database server.

That does mean I own backups. A GenServer takes a snapshot every hour using SQLite’s VACUUM INTO (which gives a consistent copy of a live database, unlike copying the file) and uploads it to an S3-compatible object storage. It’s about a hundred lines of Elixir, it’s supervised like everything else, and a failed backup logs an error instead of crashing anything. If you want the details, the codebase explainer walks through it.

Put those together and the cost is tiny. Fly waives invoices under $5, and only last month did my bill creep above that to $5.49, just a little over the line. Usage of the S3 object store at Tigris has stayed within its free allowances.

I want to be careful about what I’m claiming. That number reflects low traffic on a young app. I haven’t load tested a 5,000-person keynote, and I’m not claiming this configuration handles one. What I can say is that the floor is very low, and the architecture doesn’t force me to pay for a fleet of services before I’ve earned a paying user.

Could I have done this in Rails?

Probably, yes. Rails 8 made SQLite a first-class citizen, and Solid Cable removes the Redis requirement for Action Cable. I’m not going to pretend that Rails can’t get to a similar place. A fair comparison, though, is about how much I had to assemble and tune to get there, and about how comfortable the result is at idle and at peak.

For this specific shape of app, many long-lived connections, constant broadcast, tiny writes, spiky traffic, Phoenix gave me the right design without much negotiation. In Rails I would have been making deliberate choices to approximate it.

I’ll also say what I did not get for free. Rails has an enormous ecosystem of gems that solve the boring parts of an app. In Elixir I wrote more of the glue myself. Authentication is a good example: magic links and OAuth took more work (Phoenix’s generator got me started, and a library called Assent handles the OAuth side). If this had been a plain CRUD app with admin screens, Rails may have been faster to build, and I may have shipped it sooner.

What learning Elixir was like for a Ruby developer

Easier than I expected, honestly. The syntax is friendly to Rubyists, the tooling (mix, iex, ExUnit) feels familiar, and the community writes really good documentation. The adjustments that took some effort were more conceptual:

• Data is immutable, so you transform values instead of mutating objects.
• Pattern matching shows up everywhere, and it replaces a surprising amount of if and case logic.
• You think in processes, which is a new mental model, but a pleasant one once it clicks.

If you’ve used Ruby 3’s case/in, pattern matching won’t be a brand new idea. You can destructure hashes and arrays, bind variables, and pin values with ^:

case response
in {status: 200, body:}
  render(body)
in {status: 404}
  not_found
end

The difference is how deep it goes. In Ruby, pattern matching is a feature you opt into with case/in, and most Ruby code still uses if, case/when, and guard clauses. In Elixir it’s foundational. Even = is a match operator, not just assignment. Most importantly, you can match right in a function’s arguments, so each clause of a function handles one shape of input. Speechwave’s Channel has two join functions, for example (from reaction_channel.ex, with the first one’s body trimmed):

def join("reactions:" <> slug, %{"api_key" => api_key}, socket) do
  # ...check the talk, the user, and the plan limits...
end

def join("reactions:" <> _slug, _params, _socket) do
  {:error, %{reason: "unauthorized"}}
end

The first clause only matches when the topic starts with "reactions:" and the params include an api_key. Anything else falls through to the second clause, which rejects it. No if required.

Ruby methods have one body, so you branch inside it. Elixir functions can have many clauses, and the branching happens before your code even runs. That’s the part that changed how code was structured, and it’s why pattern matching feels more like a way of working than a convenient syntax.

Here’s an example. The Channel join for the Chrome extension is a chain of four checks, and each failure has its own reason. This is the body of that first join clause, minus a couple of setup lines inside the do block:

with {:talk, %Talks.Talk{} = talk} <- {:talk, Talks.get_talk_by_slug(slug)},
     {:user, %Accounts.User{} = user} <- {:user, Accounts.get_user_by_api_key(api_key)},
     {:owner, true} <- {:owner, talk.user_id == user.id},
     {:capacity, :ok} <-
       {:capacity,
        Plans.check(
          :max_participants,
          user.plan,
          Presence.list("reactions:#{slug}") |> map_size()
        )} do
  # ...subscribe to disconnect events, schedule presence tracking...
  {:ok, join_payload(user), assign(socket, talk: talk, user: user)}
else
  {:talk, nil} -> {:error, %{reason: "not_found"}}
  {:user, nil} -> {:error, %{reason: "unauthorized"}}
  {:owner, false} -> {:error, %{reason: "unauthorized"}}
  {:capacity, {:error, :limit_reached}} -> {:error, %{reason: "capacity_reached"}}
end

I might have written that as a pile of guard clauses in Ruby. This version reads top to bottom as a list of requirements, and the else block is a table of what goes wrong.

As an aid to learning I had AI help me write a short course for Ruby developers, drawing the examples from the Speechwave codebase. If you’re coming from the Rails side, that’s an interesting place to start.

What I’d tell another Rails developer

If your app is mostly forms, tables, and background jobs, stay with Rails. You’ll move faster and you’ll have more gems to lean on.

If your app is mostly “lots of people connected at once, and something happening to all of them in real time,” look hard at Phoenix. The runtime and the framework were built for exactly that, and you may find, as I did, that the infrastructure shrinks down to a single small machine.

And if you’re already an Elixir developer: I’d love your feedback on the codebase. It’s open, it’s about 6,800 lines of application code, and I’m sure there are idioms I’m still getting wrong.

• Try Speechwave: speechwave.live
• Read the code: github.com/speechwave-live/speechwave
• Tour the internals: codebase explainer
• Peek at the AI-assisted short course for Ruby developers

Not long ago I wrote about my search for a process (as in daemons) management tool to manage webservers, build watch processes, etc. across many different projects. I was still undecided at that point, but have since landed on Pitchfork. It does a bit more than I need and it is well-maintained. See that previous post for a discussion of that and other options that I considered.

Having settled on Pitchfork for process management, I next needed to choose a task runner. The contenders were: make, just, mise, and go-task/task. I’m not going to do a detailed breakdown, but here’s a post from another site that does. It turns out I came to the same decision they did, for mostly the same reasons. The winner was Mise.

You may notice that both tools, Pitchfork and Mise, come from the same developer. This is a bit of a risk. If the developer (Jeff Dickey) decides they’re no longer interested in maintaining these projects, then I’m suddenly looking for two tool replacements instead of one. But right now, looking at Jeff’s bio, income from his sponsors, support from his employer, etc., I’m really not too concerned.

I picked the top 19 most active repos that I have and migrated all of them to Pitchfork and Mise. Having that consistency across repos has made context switching much easier. It’s been great so far.

Around the same time, I also began using a few new skills. In addition to Pitchfork and Mise skills, I added a markdown formatter and my own writing skill. The writing skill comes with an LLM cliche linter tool as well. During the same migration, I ran the markdown formatter over all my READMEs, so now they’re easier for me to scan and find things in too.

I’ll add just a bit of brutal honesty here at the end in case you made it this far. Whenever I have a little extra time, or I’m just procrastinating on something, I tend to either a) tidy up, or b) try to improve the process. That was exactly the inspiration for this migration. Cheers!

I love RSS feeds. I have a reader on my phone (Feeder) and one on my laptop (NetNewsWire). I find it the perfect way to keep up with my blogroll reading list. Imagine my horror, then, when I discovered that my own blog had the RSS feed turned off. 😱 It took a while to get the feed icon and the inline images to show up properly, but with the help of my AI sidekick we eventually figured it out.

My own feeds

My site doesn’t surface the feed variety very well yet, so here’s the list:

Feeds I follow

In case you’re wondering what my feed looks like, here it is:

You may not care for those site designs, but that’s not the point. The point is that they don’t look like so many other generated sites and impeccable did achieve the looks I was after.

From Impeccable.stlye:

Impeccable strips the slop from AI-generated interfaces, gives you precise commands to steer, and iterates visual variants live in your product. Then the dice: pushed out of distribution, your model designs ambitious visual worlds it could never reach alone.

Recommended.

The inertia problem

When I start working on a project, I open a terminal and start a few processes. The web server. A background job worker. The asset watcher that recompiles my JavaScript. Maybe a locally-running database service. Each one might get its own terminal tab, and each tab has a command I have to remember, or dig out of a README, or other docs.

Since I work across multiple projects in different languages, with different stacks, this gets expensive fast. Not expensive in terms of CPU or memory, but in terms of mental overhead. Every project has its own conventions: make dev, ./bin/dev, docker compose up, or something else entirely. You spend more time than you’d like just overcoming the inertia to get back to a running state every time you switch projects.

A process manager gives you a single command to start everything your project needs. And if you can standardize on one tool across all your projects (🤞), you eliminate that context-switching tax entirely: cd project && [tool] start works everywhere, every time.

That’s the goal, so let’s look at the options. (Or just scroll down to the comparison table and the verdict if you want to skip the narrative.)

But before I dive in, it’s worth being clear about what I’m trying to solve for here. Most frameworks give you ways to run individual commands natively: npm run dev, mix phx.server, bundle exec rails server. Those are great and you should use them. Your Procfile entries will often call them directly. A process manager sits on top of those commands and coordinates them, starting all your services at once and multiplexing their output into a single view. The two approaches are complementary, not competing.

There’s also a related but separate problem. Task runners like Make, Rake, Just, and npm scripts handle short-lived commands like running database migrations, executing tests, or triggering builds. You will still reach for those tools for that kind of work, and there’s a whole separate conversation to be had about achieving consistency there across projects. This post is focused specifically on the process management side: starting and keeping multiple long-lived development services running together.

It all started with a Procfile

In 2011, David Dollar released Foreman, a Ruby gem for managing multiple processes during development. The central idea was the Procfile: a plain text file that declares your process types, one per line.

web: bin/rails server
worker: bundle exec sidekiq
assets: npm run watch

Heroku adopted the format and popularized it. Today it’s the closest thing the development world has to a standard for declaring process types. Ports of Foreman exist for Python (Honcho), Go (goreman, forego), and more. Those ports largely replicate the original feature set, so I won’t review them separately, but the ecosystem shows how durable the Procfile idea has been.

What followed were tools that kept the Procfile format but went well beyond what Foreman originally offered. Here’s where things stand today.

The tools

Foreman

Foreman is where it all started for me, and it still does its job. Install the gem, drop a Procfile in your project, and run foreman start. It multiplexes the output of all your processes into a single stream, prefixed with the process name and a timestamp.

gem install foreman
foreman start

One unique feature is that Foreman can export your Procfile to init system formats like systemd, upstart, launchd, and runit. If you want to manage production processes the same way you manage development ones, that export path is a nice convenience. None of the other tools in this review offer it.

Pros: Mature and battle-tested. Dead simple to adopt. Procfile export to init systems is unique among these tools. Wide adoption means good documentation and community support.

Cons: It’s a Ruby gem, which adds a runtime dependency for non-Ruby projects. The bigger issue is how it handles process output. Processes detect they are not writing to a real terminal and suppress their colored output. If you’ve ever run rails server through Foreman and wondered why the logs look flat and grey, that’s why.

Hivemind

Hivemind was built by the team at Evil Martians to fix exactly that problem. It uses a PTY (pseudo-terminal) to capture process output, which means processes think they are writing to a real terminal. So colors work and log output behaves the way you’d expect.

It’s a standalone Go binary with no runtime dependencies beyond the binary itself. Install it with Homebrew or download the binary directly.

brew install hivemind
hivemind

Hivemind is deliberately minimal. It reads your Procfile, starts your processes, and gets out of the way. The README itself will tell you: if you want more features, check out Overmind.

Pros: Standalone binary with no language runtime required. Fixes the color output problem. Extremely easy to adopt, with the same Procfile format and simpler installation than Foreman for non-Ruby projects.

Cons: No interactive process management. If a process crashes, the whole group goes down. There’s no way to restart a single process without restarting everything.

Overmind

Overmind is Hivemind’s more capable sibling, also from Evil Martians. The key difference is that Overmind runs your processes inside a tmux session, which gives it capabilities no other Procfile tool matches.

You can connect directly to any process and interact with it:

overmind connect web

You can restart a single process without touching the others:

overmind restart sidekiq

You can tell Overmind that certain processes are allowed to exit without bringing everything else down, which is useful for one-time setup tasks like database migrations. Auto-restart on crash is configurable per process, and port assignment is automatic and consistent so you can reference one process’s port from another’s configuration.

The tmux integration turns out to be more than a dependency. If you’ve ever wanted to connect to a running Rails process to use the console, or poke at a webpack dev server that’s behaving strangely, overmind connect gets you there without restarting anything.

Pros: Full PTY support, so colors work. Individual process control without affecting the group. Auto-restart on crash. Port management per process. Highly configurable via environment variables so your preferences apply globally across every project.

Cons: Requires tmux. If tmux isn’t already part of your workflow, this is a real dependency, not just a binary download. Nested tmux sessions are manageable if you’re already inside tmux, but worth knowing about upfront.

Overitall

Overitall (oit) takes a different angle entirely. Where the previous tools focus on running processes and multiplexing their output, Overitall treats logs as a first-class concern. It’s a TUI (terminal user interface) that combines process management with what amounts to a built-in log viewer.

You still use a Procfile for defining processes, but a .overitall.toml config file can also point at standalone log files rather than just process output. This is useful for services that write to a file instead of stdout, or for situations where you want to correlate a running process’s output with a framework’s own log file.

The TUI gives you real-time search (regex-capable), per-process visibility toggles, time-based navigation (:goto -5m), and trace detection that can spot correlation IDs and UUIDs in your logs and filter to a specific trace. For log-heavy development workflows, this is a meaningful upgrade over watching interleaved output scroll by.

There’s also an AI integration story: run oit skill install and Overitall installs a skill into .claude/skills/oit/ (or the Cursor equivalent) that teaches your AI assistant how to control the running TUI from the command line. You can then ask Claude to check recent errors, restart a process, or search the logs without leaving your editor.

Pros: Log management as a first-class feature. Regex filtering, time navigation, and trace detection. Interactive TUI with per-process visibility control. AI skill for Claude Code and Cursor. Available on both macOS and Linux.

Cons: Requires an additional .overitall.toml config file alongside the Procfile. The TUI has a learning curve compared to a simple process runner. It’s a newer project and still maturing.

Pitchfork

Pitchfork is the most ambitious tool in this list, and also the most different. Where everything else runs your processes in the foreground and stops them when you close the terminal, Pitchfork manages daemons: background processes that keep running after you walk away. A supervisor process handles them, and you interact with it via a CLI.

The configuration is a pitchfork.toml file:

[daemons.redis]
run = "redis-server --port 6379"
auto = ["start", "stop"]

[daemons.api]
run = "npm run dev"
auto = ["start", "stop"]
depends = ["redis"]
ready_http = "http://localhost:3000/health"

The auto = ["start", "stop"] setting is the most interesting feature for the cross-project consistency goal. With shell hooks activated, Pitchfork starts those daemons automatically when you cd into the project directory and stops them when you leave. You never have to remember to start your services. You just navigate to your project and they’re there.

The feature list goes further: dependency ordering (so Redis starts before the API that needs it), ready checks (so Pitchfork waits until a health endpoint actually responds before declaring a service up), file watching for auto-restart, cron scheduling, resource limits, and a web UI. Pitchfork also ships a built-in MCP server. One JSON config block in your Claude Desktop or Cursor settings wires your AI assistant directly into daemon management.

Color output is available but requires opting in with pty = true per daemon. Since processes run in the background by default, PTY is not on automatically, but enabling it is a one-line change per daemon.

Pros: The most powerful feature set in this review by a wide margin. Auto-start and auto-stop via shell hooks directly address the cross-project consistency problem. Built-in MCP server for AI integration. Dependency ordering, ready checks, and cron scheduling included. Language-agnostic standalone binary.

Cons: Steeper learning curve and a new configuration format to learn. The daemon model is a different mental model than a foreground process runner. You check on services rather than watching them scroll past. Color output requires explicit opt-in per daemon. Actively developed and not yet at 1.0.

Feature comparison

Which tool is right for you?

Choose Foreman if your project is already Ruby-based and you want the simplest possible setup. The gem installs alongside your other dependencies, and the ecosystem familiarity is hard to beat. It’s also the right call if you need to export process definitions to init system formats for production use, since no other tool here does that.

Choose Hivemind if you want a no-frills Procfile runner that works for any project in any language, with proper color output. It’s an easy, zero-cost, drop-in replacement for Foreman for those that don’t need individual process control.

Choose Overmind if you live in tmux and want the ability to connect to, inspect, and restart individual processes without tearing down your whole stack. Once you’ve used overmind connect to drop into a running process’s window, it’s probably hard to let that go.

Choose Overitall if log management is a first-class concern in your workflow. Noisy logs from multiple services, distributed traces to chase, correlation IDs to filter on: this is where oit’s search, filtering, and time navigation start to pay off. I can see this being really useful in a more complex $work environment. The AI skill integration is also a practical bonus if you use Claude Code or Cursor heavily.

Choose Pitchfork if you want services that follow you between projects and start automatically without any deliberate action on your part. The daemon model requires a mental shift, but it has a nice TUI (and Web UI) and it’s the most direct answer to the cross-project consistency problem in this roundup.

The verdict

If you’re looking for a single tool to carry across every project regardless of language or stack, the choice comes down to how much you want to invest in configuration upfront versus how much friction you want to eliminate long-term.

For a lightweight universal runner, Hivemind is the pragmatic choice. Single binary, no runtime dependencies, correct color output, zero learning curve. Drop a Procfile in a project and you’re running. The limitation of no individual process control rarely matters until it suddenly does, and when it does, you know where to go next.

If you are already a tmux user, Overmind is the easy upgrade over Hivemind. Same binary story, same Procfile format, but you gain individual process control and the ability to interact directly with any running process. The additional capability costs almost nothing if tmux is already in your toolkit.

The most interesting answer for the cross-project consistency problem, though, is Pitchfork. Shell hooks that auto-start and auto-stop services as you move between directories solve the problem at a deeper level than any foreground runner can. You stop managing process startup entirely, and your services are just there when you need them. That comes with more upfront configuration and a different operational model, but if you work across many projects and that investment appeals to you, Pitchfork is the tool that most ambitiously reframes what a development process manager can be.

For myself, I’m honestly not sure where I’ll land quite yet. I have a soft spot for the simplicity of Hivemind, I’m not a frequent tmux user so Overmind’s advantages are less compelling, and Pitchfork’s daemon model is intriguing but requires extra work for me and my AI integration.

AI lets you ship faster than ever. That’s great. But six months later, you’re staring at your own codebase wondering who wrote this. Why is this service doing that? Why did you pick this library over the obvious one? What were you thinking?

The problem usually isn’t the code. It’s that AI accelerates the building without capturing the thinking. You evaluate options, make tradeoffs, reject approaches, and move on. The decision happens in a chat window and then it’s gone. What’s left is code without context, and that debt (a form of cognitive debt) compounds quietly until it becomes a real problem.

Though it might help, the best fix isn’t to slow down. It’s to build a few lightweight documentation habits that will hold up in an AI-assisted workflow.

The new documentation problem

Traditional documentation advice assumes you understand everything you’re writing. You wrote the code, you know why it works the way it does, you just need to write it down. AI-assisted development changes that assumption in a couple of ways.

First, you move faster. When you’re evaluating three AI-generated implementations in ten minutes instead of writing one over an hour, there’s almost no natural pause where documentation feels like the obvious next step. The decision-making is compressed, and so is the documentation.

Second, git history gets less useful. It still tells you what changed, but it doesn’t tell you that you picked this background job library because the other one had a deployment constraint you needed to avoid. It doesn’t tell you which of four Stripe webhook implementations the AI suggested, or why you picked that one. It doesn’t tell you that you almost went a completely different direction.

The gap is context. And that’s exactly what these habits are designed to capture.

Document decisions, not implementations

The highest-leverage documentation habit is writing down why, not what. Code already shows what. What it can’t show is the thinking that produced it.

Keep a docs/decisions.md file. No formal template required. No ADR ceremony. Just a running list of decisions, what options you considered, what you ruled out and why, and what you landed on. A few sentences per decision is enough.

Some examples of the kind of thing worth capturing:

• Why you chose Sidekiq over Solid Queue (maybe it was a deployment constraint, maybe it was familiarity, maybe you tried Solid Queue and hit a weird edge case)
• Which Stripe webhook implementation you kept after the AI suggested three different approaches
• Why the data model is shaped the way it is instead of the more obvious structure you considered first

This is especially useful in AI-assisted work because the evaluation often happens fast. You look at a few options, pick one, and move on. Without a quick note somewhere, that reasoning is gone the moment you close the chat.

The daily scratchpad

A scratchpad is not a journal. It’s not a changelog. It’s a place to think out loud while you’re working.

Drop a file at tmp/scratch.md (some people call it journal.md or dev-journal.md) and use it to capture rationale in the moment. What did you try? What didn’t work? How did you arrive at this solution? What were you unsure about?

It doesn’t need to be clean. It doesn’t need to be organized. It just needs to exist.

Git history will tell future you that something changed on a Tuesday in March. The scratchpad will tell future you that you were choosing between two approaches, that one of them had a subtle concurrency problem you figured out mid-afternoon, and that the solution you landed on was a compromise you felt okay about. That’s the stuff that can really help when you return to a project three months later and can’t quite remember what you were even trying to do.

Let AI explain what it built

Sometimes you ship code you don’t fully understand yet. That’s not a great position to be in, but it’s a real one, especially when you’re learning a new language or framework alongside building something.

When that happens, ask the AI to explain what it just built.

Recently I was building a new SaaS product in Elixir while still actively learning the language. The initial architecture involved OTP supervision trees, GenServers, and some patterns that weren’t immediately obvious (to me). Rather than hoping the understanding would come later, asking the AI to write an explainer.md for the architecture made the whole thing legible. Later, an explainer.html with diagrams and a walkthrough made it even better.

You can do the same thing with an existing codebase you’re jumping into for the first time. Drop the relevant files into context and ask for an explainer. It’s faster than reverse-engineering the code yourself, and it gives you something you can update and refer back to as your understanding deepens.

My explainers live in docs/explainers/. They’re not precious documents. They can be rough, they can be wrong in places, and they should be updated as you learn more. But having them at all is the difference between a codebase that feels like yours and one that always feels a little foreign.

Keep your README human

AI tooling has introduced a temptation to stuff READMEs with prompts, agent instructions, and notes about which parts were AI-generated. Resist it.

The README is for humans. What is this project? How do I get it running? Where is the rest of the documentation? How do I contribute?

AI-specific context belongs elsewhere. Agent instructions and project rules for your AI assistant go in AGENTS.md (if you use Claude, a CLAUDE.md symlink pointing to it is handy). Plans and specs go in docs/plans/ and docs/specs/. Decisions go in docs/decisions.md. Explainers go in docs/explainers/.

The README is the front door. Keep it welcoming and keep it human.

Own the code, all of it

You don’t need to mark which lines an AI wrote.

I know that might feel counterintuitive. There’s a reasonable instinct to be transparent about your process. But there’s a difference between transparency and hedging. Marking code as AI-generated is a subtle way of distancing yourself from it, as if to say: if this breaks, that’s not entirely on me. But that’s not how accountability works.

You are responsible for every line of code you ship, regardless of how it was produced. If you don’t understand the code, you shouldn’t ship it. If you’re not sure you understand it, that’s what explainers are for.

The middle ground is being transparent about your development process at a high level. It’s no secret that most developers use AI assistance now, and saying so in your docs or your README is great. That’s transparency. What’s different is using it as a hedge. The tool you used to write the code doesn’t change your responsibility for the result.

The loop

Good documentation helps you understand your codebase. Understanding your codebase means you can give the AI better context when you’re building something new. Better context (human and AI) produces code that really fits the existing architecture. Code that fits is easier to explain and document. Round and round.

None of these habits are heavy. A few sentences in decisions.md. A rough note in scratch.md. An explainer file when you’re in unfamiliar territory. A README that stays focused on humans.

The payoff is that six months from now, when you come back to this project, it feels like yours. You remember what you were thinking. You know why things are the way they are. And you can keep building without spending the first week just figuring out what past-you was up to.

Bonus: automate it with a post-merge hook

All of these habits share a common enemy: you have to remember to do them. Remembering is fine when you’re focused, but documentation is usually the thing that slips when you’re rushing to ship.

Here’s a way to take the remembering out of it. A git post-merge hook fires automatically after every merge. You can use it to shell out to Claude Code in non-interactive mode and ask it to review and update your docs in light of what just changed.

The hook grabs the merge diff, hands it to Claude along with a focused prompt, and lets Claude update README.md, docs/decisions.md, any relevant explainers, and product docs. Changes are left unstaged so you can review them before committing. Nothing gets force-pushed. Nothing gets auto-committed. You stay in control.

Here’s the script:

#!/usr/bin/env bash
#
# .git/hooks/post-merge
#
# After merging to main, asks Claude Code to review and update documentation.
# Changes are left unstaged for your review.
#
# Setup:
#   cp post-merge .git/hooks/post-merge
#   chmod +x .git/hooks/post-merge
#
# Requires Claude Code CLI to be installed and authenticated.

set -euo pipefail

# Only run on main branch
CURRENT_BRANCH=$(git symbolic-ref --short HEAD)
if [ "$CURRENT_BRANCH" != "main" ]; then
  exit 0
fi

echo "📝 Checking documentation after merge to main..."

# Capture what changed in the merge so Claude has context
DIFF=$(git diff ORIG_HEAD..HEAD --stat)

# Build the prompt
PROMPT="A feature branch was just merged to main. Here is a summary of what changed:

$DIFF

Please review the following documentation and update anything that is out of date
or missing given the changes above:

- README.md
- docs/decisions.md (add an entry if a significant architectural decision was made)
- Any relevant files in docs/explainers/
- Any relevant product documentation in docs/

Do not modify AGENTS.md or any files in docs/plans/ or docs/specs/.

After making changes, print a brief summary of what you updated and why.
If nothing needed updating, say so."

# Run Claude Code in non-interactive mode with read/write permissions only
claude -p "$PROMPT" \
  --allowedTools "Read" "Write" "Glob" "Grep" \
  --max-turns 10

# Show which files were changed (if any)
DOC_CHANGES=$(git diff --name-only -- README.md 'docs/**' 2>/dev/null || true)

if [ -n "$DOC_CHANGES" ]; then
  echo ""
  echo "✅ Documentation updated. Review changes before committing:"
  echo "$DOC_CHANGES" | sed 's/^/   /'
  echo ""
  echo "   Run 'git diff' to review, then 'git add' and 'git commit' when ready."
else
  echo "✅ No documentation changes were necessary."
fi

Download here: post-merge

To install it, copy the script to .git/hooks/post-merge and make it executable with chmod +x .git/hooks/post-merge. Since .git/ isn’t tracked by git, you might want to keep the canonical copy in a hooks/ directory in your repo and add a setup step to your README.

A few things worth noting about the script:

The --allowedTools flag scopes Claude to read and write only. It can’t run arbitrary bash commands, can’t touch your git history, and can’t do anything outside the files you’ve pointed it at. Keeping the tool surface small is good hygiene for any automated Claude Code invocation.

The --max-turns 10 flag is a circuit breaker. It caps how many agentic turns Claude can take so a single post-merge hook can’t spin forever if something unexpected happens.

The prompt explicitly excludes AGENTS.md, docs/plans/, and docs/specs/. You don’t want a merge hook rewriting your agent instructions or your design plans. Keep the scope tight.

The --max-turns flag is a circuit breaker, but may need to be tuned based on how much the amount of work that needs to be done. If the circuit breaker is hit, the hook will exit with an error and leave the finished changes unstaged for manual review.

This is a starting point, not a finished product. Your project’s doc structure will differ, and you’ll want to tune the prompt to match. But the pattern holds: capture the diff, give Claude focused scope, leave changes unstaged, and let the human decide what to commit.

Creating a gem that writes your missing tests

No new project survives contact with the real world unscathed. We built TestGenAI, ran it on itself, and it worked well. Then we ran it on another codebase, and two things broke immediately. The fixes turned out to just as interesting as the original build.

This is a walkthrough of how the tool works and what we learned when we took it outside the greenhouse.

The code here is from TestGenAI, a working Ruby CLI gem you can install and run against your own codebase.

The pipeline

The pipeline has five stages:

1. Scan your codebase to find classes and methods without test coverage
2. Build context for each untested method
3. Generate tests using an LLM with the mechanically curated context
4. Validate that the generated tests run and pass
5. Collect the results

Each stage needs to be reliable enough that you can walk away and trust the process to complete. That means handling errors gracefully, providing clear output about what happened, and making it easy to pick up where things left off if something breaks.

Finding untested code

Before you can generate tests, you need to know what needs testing. The right approach depends on whether SimpleCov is available in the project.

If SimpleCov is set up, TestGenAI runs your test suite with COVERAGE=true, reads the resulting coverage/.resultset.json, and uses AST parsing to find methods where every executable line has zero hits. This scanner handles partially-tested files correctly. It reports individual methods that were never exercised, even if other methods in the same file have full coverage.

If SimpleCov isn’t available, the scanner falls back to checking whether a spec or test file exists for each source file. This approach is less accurate. A file tested only through integration tests or through specs for its subclasses will appear fully untested even if its methods are exercised constantly. The SimpleCov scanner is worth setting up.

Both scanners share the same underlying logic for locating methods in source files, which brings up something worth explaining.

Walking the AST

To locate methods, TestGenAI parses each Ruby source file into an abstract syntax tree and walks it recursively. The walker looks for :def and :defs nodes (instance and class methods), tracks the current class/module namespace, and records each method’s file, class, name, and line range.

That line range matters. The SimpleCov scanner uses it to check whether any executable lines in the method had zero hits. A nil in SimpleCov’s coverage array means a line isn’t executable, like a blank line, a comment, or an end. The scanner filters those out before checking for zeros, so it only flags methods where runnable code was never touched.

The parser compatibility problem

To parse Ruby, the gem relies on the parser gem. In older versions, you’d call Parser::CurrentRuby.parse(source) and get back an AST. This worked fine until Ruby 3.4, which switched its internal default parser to prism. Using Parser::CurrentRuby with Ruby 3.4 produces warnings, and in some configurations it fails entirely.

The prism project ships a compatibility shim, Prism::Translation::ParserCurrent, that produces the same AST node types as the old parser gem. The AST-walking code works unchanged. The only question is which one to load.

The solution is a small file that runs at load time and sets a constant:

module Testgenai
  if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("3.4")
    require "prism"
    CurrentParser = Prism::Translation::ParserCurrent
  else
    require "parser/current"
    CurrentParser = Parser::CurrentRuby
  end
end

The rest of the codebase calls CurrentParser.parse(source) and never thinks about which parser is underneath. The pattern of version check at load time, constant as the abstraction is a clean way to handle the same kind of compatibility gap you’ll run into whenever Ruby ships a significant internal change.

Context, generation, and validation

When you ask an LLM to write tests for a method, you can’t just paste in the method body. It needs the full class, the dependencies that file requires, examples of how the method is called elsewhere in the codebase, and existing test files it can match in style. Context quality is where quick-and-dirty AI test generators fall apart, too little and the tests don’t compile, too much and you hit token limits.

The generator builds a prompt from all of that, sends it to the LLM via the ruby_llm gem (which keeps the generator code provider-agnostic), and strips any markdown fences from the response before passing it to the validator.

The validator writes the code to a temp file, runs bundle exec rspec or the Minitest equivalent, and distinguishes between three outcomes: the file failed to load (syntax errors, undefined constants), the tests ran but failed, or the tests passed. Each outcome needs different handling. A file that doesn’t load gets deleted immediately because it’s useless. A file that runs but fails gets its error output fed back to the LLM for a retry.

The pipeline retries up to three times, passing failure details back each time. LLMs are reasonably good at fixing specific errors when told what went wrong. Undefined constants and wrong require paths almost always resolve in one retry. More complex failures, like incorrect behavior assumptions, may not, and those end up in a failed bucket for manual review.

Then we ran it on a real project

The first external test run revealed two problems, both on the same day.

The first: generated tests were syntactically valid, ran, and passed — but they looked nothing like the rest of the project’s test suite. Wrong authentication setup, wrong factory usage, helpers that weren’t available. Tests that technically pass but violate project conventions create a maintenance burden.

The second: the tool was silently destroying existing tests. When a spec file already existed at the output path, the pipeline would overwrite it with the newly generated content. Any tests already in that file were gone.

Both problems make complete sense in retrospect. The tool had only ever run on its own codebase, where it was always generating new files and where the conventions were deeply familiar to the model from the context it was seeing. A different project broke both assumptions.

Fixing the conventions gap

The core problem is that the LLM knows what your method does, but it doesn’t know how your team writes tests. It doesn’t know that you authenticate in before blocks a certain way, or that you have specific factory traits available, or that you’re not using rails-controller-testing so assigns isn’t an option.

The fix is a conventions system with two parts.

ConventionsExtractor scans your existing test files and pulls out mechanical facts: the most common authentication setup pattern, available factory traits from your factories directory, frequently stubbed objects, whether transactional fixtures are disabled and how cleanup is handled, and whether specific helpers are unavailable based on what’s in your Gemfile. These aren’t judgments, they’re observations extracted directly from the code.

ConventionsSynthesizer takes those raw facts and sends them to the LLM with a prompt asking it to write a concise conventions guide explaining the rule behind each pattern. The result is plain prose. Something like “authentication is handled in before blocks using session[:user_id] = rather than Devise helpers; use this pattern consistently.” That text gets prepended to every generation prompt.

The synthesized guide is cached to spec/conventions.md and invalidated automatically when spec files or Gemfiles change. Regenerating it costs one LLM call.

Enable it with the --conventions flag:

testgenai generate --provider anthropic --model claude-opus-4-7 --conventions

Add spec/conventions.md to your .gitignore. It’s a derived artifact and probably not something to check in.

Fixing the overwrite problem

The overwrite bug was straightforward to diagnose and subtle to fix correctly.

The naive fix would be to skip generation if a spec file already exists. That’s less than ideal. The point is to add tests for untested methods, and partially-tested files are the most common case.

Better behavior is to inject the generated tests into the existing file. The pipeline now reads existing content before doing anything else. It combines existing content with the newly generated code and validates the combined file. If it passes, the combined content is written to the spec file.

If it fails, the pipeline restores the original file exactly as it was and writes the generated-only code to a fallback path. A method in lib/payments/processor.rb that already has a spec/payments/processor_spec.rb would get its fallback at spec/payments/processor_context_spec.rb (using the method name to scope the filename). The failure output tells you where to find it:

  ✗ Payments::Processor#context failed after 3 attempt(s)
    → Generated tests saved to spec/payments/processor_context_spec.rb for manual review

You end up with your original tests intact and the generated attempt sitting somewhere you can look at it and decide what to do.

Running it

Install the gem and point it at your project:

gem install testgenai
cd your_project
testgenai generate --provider anthropic --model claude-opus-4-7

Or add it to your Gemfile in the development group and use bundle exec. Configuration can also come from environment variables:

export TESTGENAI_PROVIDER=anthropic
export TESTGENAI_MODEL=claude-opus-4-7
export ANTHROPIC_API_KEY=your_api_key
testgenai generate --conventions

Three diagnostic commands are available before you commit to a full run:

testgenai scan      # find untested methods without making any API calls
testgenai context   # show what context would be sent to the LLM for each method

scan gives you a picture of your coverage gaps. context is useful for understanding what the LLM will see before spending API credits.

The goal isn’t to replace the developer who understands the code and makes decisions about testing. It’s to handle the mechanical work: setting up describe blocks, wiring test data, writing happy-path coverage. Then you can spend your time on the parts that actually need your judgment. The second project taught us that “mechanical” is more context-dependent than it looks.

A few days ago I built a tool called JoyConf: a real-time audience feedback system that lets speakers see emoji reactions floating up in the corner of their presentation while they’re talking. It was a fun, simple idea and I was pretty excited about it.

I built it in Elixir and Phoenix LiveView, which was a deliberate choice. I mostly write Ruby these days, but this project felt like a good excuse to dig into Elixir and LiveView. Learn something new, build something useful. Two birds, one stone.

I drove the overall design and implementation planning, did active code review, and contributed everywhere I could. But for the Elixir and LiveView specifics, I leaned heavily on Claude. The syntax, architecture decisions, and debugging were Claude’s domain, because I simply didn’t know enough yet to own them. The tool worked and it seemed to work well. But when I got to the end and looked at the codebase, I realized I didn’t really understand the parts Claude had built. I had reviewed the code as carefully as I could, but reviewing code in a language you don’t know, implementing an unfamiliar architecture, only gets you so far. The understanding of those pieces had mostly stayed with Claude.

That’s cognitive debt. And LLMs are very good at generating it.

What cognitive debt actually is

Cognitive debt accumulates when you defer the thinking that should happen now. It’s different from technical debt, which is about the code itself (shortcuts taken, tests skipped, abstractions that didn’t quite work out). Cognitive debt is about the reasoning that never happened. The mental model that never got built. The decision that got made without being understood.

Like financial debt, it doesn’t feel like much at first. You’re moving fast, things are working, you’re shipping. The bill comes later, when you need to debug something you can’t reason about, extend a system you don’t understand, or explain a decision you never actually made. And to be clear, cognitive debt has been around long before LLMs, LLMs just magnify the problem.

LLMs make this disturbingly easy

LLM-generated code is mostly right. That’s what makes it dangerous.

If the code were obviously wrong, you’d catch it. You’d dig in, figure out what went wrong, learn something in the process. But LLM output is usually plausible, often correct, and just coherent enough that it passes the vibe check. You run the tests. They pass. You move on. The mental model of how it works never gets built, because you never needed it… until you do.

There’s a specific failure mode worth naming here. Using an LLM to move faster on things you understand is leverage. Using it to skip understanding altogether is debt. Those feel identical in the short term. Both result in code getting written. One leaves you with understanding you can build on; the other leaves you with output you’re stuck with.

And it catches everyone. Junior developers accept LLM output because they don’t know enough to question it. Senior developers accept it because they had a hundred PRs today and the code looks fine, so they assume it is fine. Both skip the reasoning step. The result is a codebase full of decisions nobody on the team can actually defend.

Back to JoyConf

When I realized I’d built something I didn’t fully understand, I asked Claude to write me an explainer document. Not a summary, but an actual explanation of the architecture, the key concepts, why certain decisions were made, how the pieces fit together. Something I could read, learn from, and come back to later.

It wasn’t a magic pill. I was starting from near zero with Elixir and LiveView, so one document didn’t make me an expert. But it meaningfully closed the gap. I understood the code better than I did before. I had something to refer back to. And I started to feel like the codebase was actually mine.

That experience shaped how I think about using LLMs for coding. The tool works fine. How you engage with it makes all the difference.

Practical ways to keep the debt in check

Ask for explanations before you accept the code. Don’t just run it. Ask the LLM to walk you through what it did and why. This takes an extra minute and catches a surprising number of cases where the code is technically correct but built on assumptions you don’t share.

Ask for an explainer document for bigger decisions. Architecture choices, non-obvious patterns, anything you’re going to need to live with for a while: ask the LLM to write it up in plain language. Keep it in the repo. Future you will thank present you.

Use Simon Willison’s “showboat” approach to document what was built. The showboat tool “creates executable demo documents that show and prove an agent’s work.” (kind of like a Jupyter notebook, but just markdown). The LLM walks through its output with explanation and context. It’s a great way to produce living documentation that captures not just what the code does, but why it was written that way. It’s a great tool, but not suitable for every use case.

Read the LLM’s thinking, especially when debugging. Many LLMs can expose their reasoning process. When you’re stuck on a bug or trying to understand a decision, asking the LLM to think out loud before answering is one of the fastest ways to build genuine understanding rather than just getting an answer.

Write the tests yourself. Even if you let the LLM write the implementation, writing the tests forces you to reason about the behavior you actually want. It’s one of the best ways to make sure the mental model gets built. Of course, it takes more time and it’s not always possible, like with JoyConf where I didn’t know enough about the Elixir environment to write effective tests. But when you can, it’s a great way to stay in the driver’s seat.

Slow down at decision points. LLMs are fast. That’s the point. But speed can accelerate debt. When you hit a fork in the road (an architectural choice, a tradeoff, a “there are a few ways to do this” moment) pause and do the reasoning yourself, even if you use the LLM to help you think it through.

The goal isn’t to use LLMs less

LLMs are genuinely useful and I don’t plan to stop using them. The goal is to stay in the driver’s seat mentally, using them for leverage rather than as a substitute for thinking.

A healthy LLM workflow and a debt-generating one can look identical from the outside. The difference shows up later, when you need to understand, maintain, or extend what you built. If you finish each session understanding what you built and why, you’re using the tool well. If you don’t, you’re taking out a loan.

And like financial debt, cognitive debt is a lot easier to avoid than to pay off.

References

• MIT study on cognitive debt
• Simon Willison’s showboat tool
• JoyConf repo
• JoyConf story

I built a live emoji reaction app for my upcoming talk

I have a talk coming up in a few weeks. It got rescheduled once, which gave me extra time to prepare. The presentation itself is finished, so I used that time to build an application that I think will make the talk more fun and engaging for the audience.

I wanted to add some live audience interaction. The usual options, Slido, Mentimeter, Poll Everywhere, are fine, but they’re designed around Q&A and polls. What I actually wanted was simpler and more visual: live emoji reactions that float up as an overlay on my slides while I’m presenting. None of the existing tools seem to do that. So I built my own, and I called it JoyConf.

It also gave me a reason to finally learn some Elixir.

What it does

The flow is simple:

1. You create a talk in the admin panel and get a QR code
2. You put the QR code on your title slide
3. Attendees scan it and land on a page with pre-defined set emoji buttons: ❤️ 😂 🙋🏻 👏 🤯, etc.
4. They tap a button, and the emoji floats up on their screen in real time
5. A Chrome extension running on your laptop picks up the same broadcast and overlays the emoji directly in the lower right corner of your Google Slides presentation

That’s it. No accounts for attendees, no app to install, no configuration to fiddle with. Scan, tap, react.

Why Elixir and Phoenix

I write Ruby day to day, so the syntax was familiar enough. But Elixir runs on the BEAM, the Erlang virtual machine, which was built for soft real-time systems with lots of concurrent connections. Phoenix LiveView lets you build interactive, server-rendered UIs over WebSockets without writing much JavaScript. And Phoenix PubSub gives you a message bus that lets any process broadcast to any other, regardless of what type of process it is.

All three of those things are important for a system where dozens of phones are sending events to a server that needs to fan them out to a slide presentation and all the phones (for their own consolidated live view) in under a second.

LiveView is pretty magical, by the way. You define your UI as a function of state, and Phoenix handles keeping the browser in sync. You get WebSocket-backed interactivity without writing a single-page app.

How it works under the hood

There are three clients talking to one Phoenix server.

Attendee phones connect via Phoenix LiveView, which manages the WebSocket lifecycle automatically. When an attendee taps an emoji, it fires a phx-click event to the server. The server checks a rate limiter (one reaction per session every 3 seconds) and, if allowed, broadcasts the event to a PubSub topic keyed by the talk slug: "reactions:my-talk".

The Chrome extension connects via a Phoenix Channel, a lower-level WebSocket primitive. The extension can’t use LiveView because it’s not a web page; it just needs to receive events. The ReactionChannel is subscribed to the same PubSub topic, so when the attendee’s broadcast lands, it gets forwarded to the extension automatically.

The admin browser is a standard LiveView protected by HTTP Basic Auth. You create a talk, the server generates a slug from the title, and you get a QR code pointing at the attendee URL.

The PubSub layer is what makes the architecture clean. TalkLive doesn’t need to know the Chrome extension exists. It just broadcasts on the topic, and PubSub delivers it to everyone subscribed, whether that’s a LiveView process, a Channel process, or both.

Here’s the entire broadcast path in code:

def handle_event("react", %{"emoji" => emoji}, socket) do
  if RateLimiter.allow?(socket.id) do
    Endpoint.broadcast!("reactions:#{socket.assigns.talk.slug}", "new_reaction", %{emoji: emoji})
  end
  {:noreply, socket}
end

That’s the whole thing. Five lines. PubSub does the fan-out.

Rate limiting with ETS

The rate limiter is a GenServer that owns an ETS table. ETS is an in-memory key/value store built into the BEAM runtime. It’s extremely fast and, crucially, you can configure it for concurrent reads without going through the GenServer process. This matters because with many attendees tapping at once, you don’t want all those requests queuing up behind a single process.

The table stores {session_id, last_reaction_at}. The allow?/1 function looks up the session, checks if enough time has passed, and updates the timestamp atomically. No database round-trip, no lock contention.

There’s also a client-side rate limit in JavaScript: buttons are disabled for 3 seconds with a visible countdown timer. That’s just UX, the real enforcement is on the server.

The Chrome extension

The extension has two parts: a popup where you enter the talk slug once, and a content script injected into Google Slides pages that handles the actual connection and overlay.

The content script connects a Phoenix WebSocket client to the server, joins the reactions:${slug} channel, and listens for new_reaction messages. When one arrives, it spawns a floating <span> element with a CSS animation that drifts up and fades out.

It never works on the first try

Double emojis on slides. Early on, every reaction appeared twice on the speaker’s screen. The bug was that the Chrome extension was subscribing to PubSub directly as well as receiving the Channel push. Two subscriptions, two deliveries. The fix was removing the redundant subscription and letting the Channel handle delivery exclusively.

Fullscreen mode swallows the overlay. When you go fullscreen in Google Slides, the browser creates a new stacking context. Any position: fixed element on <body> becomes invisible. The fix was listening for fullscreenchange events and re-parenting the overlay <div> into document.fullscreenElement when it fires:

document.addEventListener("fullscreenchange", () => {
  const overlay = document.getElementById("joyconf-overlay");
  if (document.fullscreenElement) {
    document.fullscreenElement.appendChild(overlay);
  } else {
    document.body.appendChild(overlay);
  }
});

Not obvious, but straightforward once you know it.

Button clicks were being swallowed. The initial implementation disabled the emoji buttons immediately on click. That blocked the phx-click handler from firing, so the server never received the event. The fix was deferring the button disable to a setTimeout(..., 0), which lets the click event propagate before the buttons get disabled.

The Chrome extension’s origin. Chrome extensions run from a chrome-extension:// origin, which Phoenix’s check_origin protection rejects by default. One line in endpoint.ex fixes it:

socket "/socket", JoyconfWeb.UserSocket,
  websocket: [check_origin: false]

The tech stack, briefly

The database has one table: talks. Reactions are ephemeral and never persisted. If the server restarts, in-flight reactions are lost, which is fine.

What’s next

JoyConf is an MVP. It does one thing and it’s ready for me to use at my talk. It’s not productized, it’s not super-polished, and it’s likely not easy for the average non-technical user to deploy.

Things that might be nice to add in the future:

• Ease of deployment for less technical users.
• Reaction analytics tied to slides so you can see which parts of your talk landed
• Support for other presentation tools beyond Google Slides

For now, I’m just going to go use it.

The source code is on GitHub. If you want to run your own instance, the README should have everything you need.