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

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.

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

Building a presentation thingy.

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.