cb341 Blog

How the Homebrew Multi-User Rabbit Hole Bricked My Mac

Mon, 27 Apr 2026 00:00:00 +0000

I work part-time at Renuo as a software engineer and study Computer Science part-time at ZHAW. Most weeks mix client codebases, coursework, and personal projects on the same laptop, with the same tools: Neovim with lazygit and delta, iTerm2, Raycast, Setapp, hotkeys, window management. The setup should feel the same regardless of which one I am working on.

I also want clean separation. Slack should not interrupt a study session. Personal email should not show up in client meetings. The git identity loaded should match the project I am in, without me having to think about it.

Why not one user?

The friction was constant but small enough that I lived with it for quite some time now. The Slack icon lit up during ZHAW deadlines. The dock mixed work apps with personal ones. The clipboard remembered things from the wrong context. Mail surfaced three accounts in one inbox, and switching between them was manual.

Switching contexts meant manual cleanup. Killing apps I did not want open at school, opening the ones I did. Same in reverse every evening. A few minutes per transition.

On quiet evenings, the Slack icon was right there in the menu bar. I would open it "to check one thing" and lose half an hour.

The bigger issue was that client projects sat one cd away from personal ones. Same shell history, same git config, same SSH keys loaded. The boundary between client and personal work was mental, not enforced.

I tried Apple's Focus modes first. Focus only hides things.

A second laptop would solve all of this but is overkill, expensive, and twice the hardware to maintain.

Two macOS user accounts handle every point above with no clever software. macOS already isolates them. If I really need to move a file across, I can do it via sudo from ~dani to ~cb341 (or vice versa).

The setup landed at two admin users on one machine:

cb341 (personal): ZHAW, personal projects, iCloud Keychain
dani (work): Renuo projects, Google Drive, Slack, Renuo Google account, Renuo 1Password, NCLT

Each app and account lives on exactly one side. ZHAW modules like Low Level Programming and Communication & Technology run in their own Linux VMs and Docker contexts on the personal side, kept separate from the work user's containers. Mail runs on both, but with different accounts.

This is not full isolation. Both users share the same hardware, the same network, the same macOS install. Anything installed system-wide (Wireshark, kernel extensions, daemons) is visible from both sides. An admin user can sudo into the other's home directory if they really want to. Real isolation would mean separate machines, or at least separate VMs. Two users is not a security boundary. It is a context boundary. Different login, different state, different mental mode. That is enough for the problems I actually have.

The Homebrew rabbit hole

Once I had committed to two users, the next question was how to share Homebrew between them. I love Homebrew. It is not pacman, but for macOS it is the closest thing. Most of the CLIs and many GUI apps I use are one brew install away.

The trouble is that Homebrew is fundamentally designed for one non-root user to own a single install. There are not many ways to bend that, and the three I describe below are not exhaustive. They are the most viable ones I found, and the ones the community keeps recommending. I tried all three before giving up.

Approach 1: shared group permissions

This is the top Stack Overflow answer for any "Homebrew multi-user" search. You will find variants of it in countless gists and Medium posts. Run something like:

sudo chgrp -R admin /opt/homebrew
sudo chmod -R g+w /opt/homebrew

Both users in the admin group can now read and write the Homebrew prefix. In theory. In practice it falls apart immediately.

The root cause is that Homebrew's default umask does not preserve group-write permissions on newly-created files. As soon as one user installs anything, the new files land owned by that user with no group-write bit. The prefix is back to being half-broken for the other user. The symptoms cascade through the layers I rely on: my shell (zsh, the macOS default since Catalina) and the polyglot version manager Renuo uses (mise, like nvm or rvm but for any language).

zsh autocompletion silently stops working because completion files in /opt/homebrew/share/zsh/site-functions are not readable across users. zsh refuses to load them entirely with zsh compinit: insecure directories warnings.
Plugin managers (antigen, oh-my-zsh) fail to update because their cached state lives under the brew prefix or the user's home but references files the other user wrote.
mise has a trust system for .tool-versions and mise.toml files. Files written by one user fail the trust check when the other user reads them. You get prompted to re-trust on every shell.
Ownership drifts fast. I spent two days on this approach. By the end, brew doctor was a wall of warnings, formulae refused to update, and parts of my setup had silently broken. None of it resolved cleanly. The fix is to reinstall the prefix.

The usual workarounds pile up. Re-run the chmod hack after every install. Set a custom umask globally. Or, and this is real (codejam.info calls it out), drop a chmod -R g+w into your ~/.zshrc so the prefix is force-corrected every time you open a terminal. A recursive filesystem operation on every shell launch, just to keep the previous workaround working. At which point you are not really using Homebrew anymore. You are maintaining a wrapper around it.

Approach 2: separate per-user installs

The "clean" alternative is to install Homebrew under each user's home directory. Say, ~/.homebrew. Each user owns their own copy. This sounds reasonable on paper. In practice it breaks. Homebrew's prebuilt bottles are compiled for the default prefix (/opt/homebrew on Apple Silicon, /usr/local on Intel). Install anywhere else and you lose the bottles entirely. Some formulae then fail to build at all. Others compile but link against paths that do not exist on the new prefix, so they break at runtime in unpredictable ways. The official docs say it directly: "Some things may not build when installed elsewhere." That is not a warning to weigh against the benefits. It is a description of what happens.

Approach 3: shared install + sudo

This is what the Homebrew FAQ actually recommends when pressed. It is buried in a section explaining why Homebrew "refuses to work using sudo". It took me longer to find than I would like to admit. Create a dedicated user just for Homebrew (call it brew-admin), install Homebrew under that account, then from your actual user run brew via sudo:

# in ~/.zshrc on each real user
export PATH="/opt/homebrew/bin:/opt/homebrew/sbin:$PATH"
alias brew='sudo -Hu brew-admin brew'

The -H flag points HOME at the impersonated user so Homebrew's cache and state stay consistent. Charles Loder's writeup walks through this for Apple Silicon specifically. It works. It is also where Homebrew's single-user assumption becomes visible. You are now maintaining a third user account whose only job is to own the package manager. Tools that shell out to brew internally (think nvm, version managers, install scripts) do not know about your alias and break.

By the time I had cycled through all three I realized I had been fighting the tool to do something it was not built for. That is when I started looking at MacPorts. Before I got there, I bricked the laptop.

How I bricked it

I cannot prove Homebrew alone caused this. The system had its own accumulated junk before I started: years of half-uninstalled tools, framework drift, the kind of rot every long-lived install collects. But the Homebrew permission mess is what pushed everything past the point of recovery.

Honestly, I cannot reconstruct the exact sequence. I followed guides, tried random fixes, reverted some of them, deleted directories I probably should not have. Homebrew's paths reach further into the system than I realized, and somewhere along the way I took system files with them when I only meant to remove brew. By the time I noticed how bad it was, the damage was past clean repair.

The chain went roughly like this. Permission state on /opt/homebrew got into a configuration neither user could fully repair. The macOS update via System Settings refused to apply. Manual installation of the "Update to macOS Tahoe" .pkg failed too. Xcode CLI tools would not install. Then Xcode itself would not install. Then the App Store stopped loading. I could not erase the disk through the normal recovery flow. Eventually I broke the GNU tools (make, git) badly enough that recovery scripts failed.

For reference, here is what a normal macOS update flow looks like. None of it worked for me. Even the softwareupdate --fetch-full-installer command-line escape hatch failed:

$ softwareupdate --fetch-full-installer --full-installer-version 26.4.1
Scanning for 26.4.1 installer
Install failed with error: Installation failed
Error Domain=PKDownloadError Code=8 "(null)"
  ... NSLocalizedDescription=The request timed out.
  ... https://swcdn.apple.com/.../InstallAssistant.pkg

Time for a clean reset.

Homebrew → MacPorts (reluctantly)

Since I was rebuilding from scratch I revisited the package manager question. To be clear: I would rather have stayed on Homebrew. It is the macOS package manager I actually enjoy using. The formula coverage is unmatched. But the previous three sections are why I could not. Homebrew is fundamentally a single-user tool. No amount of group-permission hacks or sudo aliases makes it not so.

MacPorts has been around longer than Homebrew and predates it as the de facto BSD-style ports system for macOS. ETH has a decent writeup that nudged me to actually try it.

The honest tradeoffs:

MacPorts wins on

Clean Unix permissions. sudo users administer packages, regular users just use them. Multi-user is the default, not an afterthought.
Predictable install locations (/opt/local).

Homebrew wins on

Bigger ecosystem. OrbStack, delta, and a lot of casks I rely on are first-class on Homebrew, less so on MacPorts.
No sudo needed for day-to-day installs. macOS as a platform leans away from sudo for user-space work, partly because System Integrity Protection already blocks writes to /System and /usr regardless of root, and partly because Apple's pattern is "drag to /Applications" rather than "elevate to install". When something does need privileged access, macOS prefers authorization dialogs and entitlements over sudo. Even our Renuo laptop setup guide flags it: "On a Mac, you should seldom be required to use sudo." Homebrew respects that convention. MacPorts does not.

So when does each one win? One disclaimer first: I am only comparing on the multi-user dimension. Formula coverage, build determinism, update frequency, dependency handling, and tap ecosystems all matter for picking a package manager, and other articles cover them well. None of those tipped my decision. The multi-user model did.

Use Homebrew when one human owns the Mac. Bigger ecosystem, less friction, fits the macOS "seldom sudo" norm. Most setups land here. If you are the only person who logs in, there is no reason to pick anything else.

Use MacPorts when multiple humans share the Mac. This is where Homebrew's single-user model breaks down, and no permission hack fixes it cleanly. MacPorts treats installs as a privileged operation, which means all users share the same stack without one of them owning the prefix. You trade ecosystem size for sanity. The "seldom sudo" norm goes out the window, but that norm only worked because Homebrew gave one user write access to a system path. Multi-user breaks the trick. Pretending otherwise is what got me into the mess in the first place.

For my setup, MacPorts was the only sane choice. I still miss brew install --cask orbstack. The smaller cask selection hurts, and I fill the gaps with manual .dmg installs for the few apps that are not there.

The rebuild

There was an upside to the wipe. A long-lived macOS install collects a lot of state: background services from apps I had not opened in months, config files in ~/Library/Application Support for tools I tried once and abandoned, login items from installers without proper uninstall scripts, kernel extensions from drivers I no longer needed. All of it went with the reset. Login is faster, idle CPU is lower, and the menu bar is no longer full of icons from things I do not use.

For the Renuo side I followed our internal laptop setup guide. It gave me a known-good baseline: a Ruby/Rails toolchain via mise, Postgres and Redis as background services, git + git-flow, GPG, the Heroku CLI, and mas for App Store updates from the command line. Before wiping the old install I ran brew bundle dump to spit out a Brewfile of everything I had. That became my checklist for the new machine. The guide is written assuming Homebrew throughout. Every step is a brew install something. On the MacPorts side I mentally translated each line into sudo port install something (or the equivalent), and looked up the small handful of packages where the names differ. brew services start postgresql becomes a launchd plist that MacPorts wires up automatically when you install the postgresql17-server port. Same outcome, slightly different vocabulary.

On top of that baseline, the core stack on both users:

Editor and git: LazyVim on Neovim, lazygit, delta
Terminal: iTerm2 with Caskaydia Cove, Caps Lock remapped to Escape
Window management and launching: Rectangle and Raycast
Setapp tools: Dash, CleanShot, TextSniper, Timing, Paste
Apple defaults kept: Notes, Mail, Messages

Neovim config gets manually synced between the two users. Not ideal, but it is a small price. Everything else is just installed twice.

What made the migration bearable

A few things saved real hours. The Samsung T7 Shield 4TB over Thunderbolt was fast enough that copying selectively onto it and pulling back from it was painless. iTerm2, Raycast, and Timing all support exporting settings to a file (iTerm2 prefs, Raycast settings export). Importing on the fresh install took seconds rather than an evening of clicking through preference panes. My dotfiles repo covered the rest of the editor and terminal experience: Neovim config, lazygit, shell setup, all in one git clone. Running ncdu before backup let me clean out node_modules, Rust target/ directories, and vendor/ folders that did not need to make the trip. Easily 100 GB saved.

For now: the laptop boots, both users have what they need, and I have not bricked anything in days. That counts as a win.

Compressed Language

Mon, 30 Mar 2026 00:00:00 +0000

I communicate with AI in broken English and it works perfectly. I drop vowels, ignore spelling, skip grammar, and the meaning arrives intact. Why?

"I have made this longer than usual because I have not had time to make it shorter." * Blaise Pascal

Building on "Map-Reducing Myself" * if we compressed 21MB of data into 15 words of identity, what does that say about the language we used for the other 20.99MB?

Thesis

There is a spectrum from natural language to formal notation, and human-AI communication is carving out a new point on it.

\[E_{\text{comm}} = f(N_{\text{tok}}, \text{ambiguity}, |V|, C_{\text{decode}})\]

Every example in this article is a tradeoff between these four variables. The key constraint: density scales with shared context. Compression only works because both sides share the same context.

Hieroglyphs as framing

Hieroglyphs were logographic: one symbol encoded an entire concept. We decomposed that into alphabets (phonetic atoms), gained universal composability but lost density. Now we are circling back: $\bowtie$, $\pi$, $\rightarrow$, emojis * reinventing hieroglyphs for specific domains.

hieroglyphs -> alphabets -> formal notation -> emoji/symbols -> compressed protocols

We started with symbols, detoured through words, and the optimal path forward might look more like where we began.

The language of the universe

Math notation as the purest compressed language. Evolved over centuries toward maximum information density.

Math symbols are not faster to write (typing integral, sum, join is awkward) but massively faster to read. A trained eye parses $\sum_i x_i^2$ instantly; "the sum of the squares of each element x sub i" requires linear reading. Optimized for output bandwidth, not input.

Upfront learning cost amortized over every future read. Same tradeoff as any compressed protocol.

Linear algebra as extreme case

A single matrix multiplication $AB$ encodes potentially millions of operations. Two characters, behind them a thousand nested loops. No natural language comes close to that compression ratio. This is not just compression * it is delegation to a shared semantic model. $AB$ only works because both sides agree on what matrix multiplication means. Compression requires a shared decoding function.

And it is the backbone of the AI we are communicating with. The compressed language (linear algebra) built the system (neural nets) that now lets you use another compressed language (your protocol) to talk to it.

Relational algebra vs SQL

\[\pi_{\text{name, email}}(R \bowtie S)\]

SELECT DISTINCT R.name, R.email FROM R INNER JOIN S ON R.id = S.id;

16 symbols vs 67. The algebra implies distinctness (set-based by definition), so DISTINCT is redundancy the formal notation never needed. SQL trades density for explicitness and practical execution semantics: bag semantics, execution hints, readability for broader audiences. The verbosity is not accidental. But for expressing the pure relational operation, the algebra is unmatched.

Programming languages: Ruby vs Java

names = users.select(&:active?).map(&:name)

List<String> names = users.stream()
    .filter(User::isActive)
    .map(User::getName)
    .collect(Collectors.toList());

Same logic. Java makes you declare List<String>, wrap in .stream(), unwrap with .collect(Collectors.toList()). The type system demands you narrate what Ruby lets the reader infer from context. names already tells you it is a list of strings * the type annotation is redundant to anyone reading the code.

Java encodes constraints and guarantees. Ruby encodes intent and convention. Both work. One trusts context, the other spells it out.

Java -> Ruby -> math notation -> compressed protocol

Typoglycaemia / redundancy

Shannon entropy tells us that natural language carries far more bits per symbol than the minimum needed to convey meaning. If we can read jumbled words and sentences with missing vowels, are they really necessary? The Cambridge meme (first/last letter preservation) proves English carries enough redundancy that large chunks can be dropped without losing meaning.

xkcd 1133: Up Goer Five

Randall Munroe describes the Saturn V rocket using only the 1000 most common English words. The results:

"The kind of air that once burned a big sky bag and people died" * hydrogen
"This is full of that stuff they burned in lights before houses had power" * kerosene
"Things holding that kind of air that makes your voice funny" * helium
"Part that falls off first" / "Part that falls off second" / "Part that falls off third" * rocket stages

27 annotations, averaging ~12 words each, to describe what an engineer conveys in 1-2 words per part. Roughly a 10x expansion.

But there is a real tradeoff here. The Up Goer Five approach has advantages:

No upfront vocabulary to learn. Anyone who speaks English can read it.
Smaller token set. You reuse the same 1000 common words, so the vocabulary overhead is near zero.
Zero onboarding. A child can follow along.

The cost: you need far more tokens per concept. "Hydrogen" is 1 word. "The kind of air that once burned a big sky bag and people died" is 14 words, and it is less precise * which sky bag? The Hindenburg, but you would never know.

This is the fundamental tradeoff: vocabulary size vs token count. A large specialized vocabulary compresses each concept into fewer tokens but demands learning. A small vocabulary reuses tokens but requires more of them per concept. The optimal point depends on how many times you will reuse the vocabulary. For a one-time explanation: Up Goer Five wins. For daily communication: learn the word "hydrogen."

Same tradeoff as the CLAUDE.md protocol. The upfront cost of agreeing on ->, x, ? is tiny. But it only pays off because we reuse those symbols hundreds of times.

The CLAUDE.md protocol as proof

The CLAUDE.md communication protocol:

Symbols: done | -> next | x blocker | ? clarify
Flow: short intent -> act -> checkpoint -> brief result -> loop

Communicating with Claude, spelling is irrelevant, vowels optional, grammar ignored * and precision is maintained. This proves English carries massive redundancy that can be stripped when both parties share enough context.

Live example from this conversation:

"wt f w gt mr i dtl f xkcd"

Decoded: "want/wait for * we get more in detail for/of xkcd" * a request to go deeper into the xkcd comic's actual content rather than just summarizing the concept.

8 consonant-skeleton "words", no vowels, no grammar, fully understood. The message is 30 characters; the English version is 53. ~43% compression with low perceived loss under shared context.

Why I prefer talking to an LLM over humans

LLMs optimize for throughput. Humans optimize for alignment. LLMs are denser, more responsive, and work easier with loss. I can drop vowels, skip grammar, misspell everything, and the model still gets it. Humans need me to slow down, spell things out, repeat myself. The LLM meets me at my speed and my level of compression. It does not ask me to expand what I already said clearly enough. The bandwidth match is better.

This is not a social preference. It is a communication efficiency preference. I already optimize across languages in daily life: my sister and I both speak fluent Czech, but we write to each other in English. It is more token efficient. Simpler. No need to differentiate i/y. No carets, no accents. Shorter words. I do the same with classmates who are native German speakers * we default to English because it is faster. You can rush more, compress more, and still land the meaning. For Software Engineering I enrolled in the English group so that the language stays as close to the technical side as possible. Having to live-translate an English class diagram into German for a presentation is overhead I want to minimize. Every translation is a lossy operation. The LLM just takes that one step further.

Same pattern in what I enjoy studying at ZHAW. I like Analysis 1, Analysis 2, Linear Algebra, Information Theory. These are not ambiguous. They are precise. There is one correct answer. I do not like Databases or Communication modules. Those are imprecise, ambiguous, require more context. Domain modeling is not a precise task * it depends on interpretation, convention, stakeholder opinions. The modules I gravitate toward are the ones where the language is already compressed and unambiguous. The part of Software Engineering I do like is UML. It allows me to express myself very compactly. First you define the communication protocol * the notation itself. Then you can communicate concepts in a very efficient manner. The upfront cost of agreeing on the symbols pays off in every diagram after. Consider composition vs aggregation in UML: a filled diamond explains lifetime-dependency in a single glyph. No sentence needed. Same principle as math notation, same principle as the CLAUDE.md protocol. The same message that takes 8 consonant skeletons with Claude would need a full paragraph with a person, plus clarification, plus context setting. The protocol overhead of human communication is massive.

Same reason I use Neovim. It is the same principle applied to editing. In VS Code, reformatting a paragraph is: mouse select paragraph, open command palette, type "reflow", select the command. In Vim it is gqap * four keystrokes, no menu, no search. Select a word and uppercase it: gUiw. Delete everything inside quotes: di". The grammar is composable: once you learn the verbs (d, c, gU, gq) and the nouns (iw, ap, i"), you can combine them without ever having seen the specific combination before. It is a compressed language for text manipulation. The upfront cost is steep, the long-term throughput unmatched.

The cost of ambiguity (personal)

I struggle with emails. Every sentence carries the risk of misinterpretation. I do not want to sound hostile. I do not want to sound pushy. I do not want to be ambiguous. But English makes all three possible with the same words depending on how the reader feels that day. It is overwhelming. Same when talking to people * finding the right words, worrying about how they interpret me. Human language is lossy in the wrong direction: it does not lose redundancy, it loses intent. With an LLM I do not carry that weight. It does not read tone where there is none.

Ambiguity as the variable

Formal notations compress because they strip ambiguity. English preserves ambiguity because human communication needs it. Human-AI communication needs less ambiguity than human-to-human but more than pure formal notation. The compressed protocol sits in that gap.

Rhythm and repetition

CGP Grey leans heavily into poetic structure in his narration. "Hexagons are the bestagons." It is not just a joke. Rhyme and rhythm improve memorization and flow. He repeats core concepts throughout a video, each time adding a layer, building cohesion. The repetition is not redundancy * it is reinforcement. The same phrase compressed into a catchphrase becomes a handle for the entire idea.

This is a different kind of compression. Not fewer tokens, but more memorable tokens. Poetry, slogans, mnemonics * they optimize for retrieval, not transmission. The best compressed language might need both: dense notation for writing, rhythmic structure for remembering.

Additional ideas/thoughts

Markdown/LaTeX/UML as prior art for structured text: pros/cons of each
Goethe excerpt: find a passage that illustrates verbosity vs density
GEMTEX markup as inspiration
Emojis and symbols as expression
New way to structure text beyond paragraphs
Consistent pronunciation, consonant focus, capitalization for emphasis only
Multiplicities, borrowing concepts from programming (;, =, *, *, .)
What if we communicate with LLMs via UML?

Claude the writer, me the editor

Every section in this article started as a compressed prompt and went through multiple rounds of editing. Claude drafted, I rejected, corrected, restructured, added context only I had. "wt f w gt mr i dtl f xkcd" became the Up Goer Five analysis. "mntn mth symbols mb not faster write but mch faster read" became the information density argument. The ideas and the direction were mine. The expansion was collaborative. The process was the proof.

Sources

Map-Reducing Myself

Sat, 28 Mar 2026 00:00:00 +0000

I talk to Claude every day. It writes code with me, reviews my PRs, debugs my specs, validates my homework. At 3am it is the thing I talk to when I am still awake and thinking about something I cannot put into words yet. Over six months that added up to 312 conversations and 21MB of JSON.

Claude Code has a /insights command that analyzes your usage. It told me I am a "persistent, correction-driven iterator" who steers Claude through "frequent wrong approaches with direct feedback." 98 sessions, 198 hours. Accurate. Shallow.

I wanted to go deeper. So I built a pipeline to summarize all 312 conversations into a profile of myself.

The pipeline

The raw export is noisy: metadata, UUIDs, timestamps, tool calls, thinking blocks, and the actual text buried inside. The first step is stripping everything that is not what I said or what Claude said.

21MB raw JSON -> 4MB normalized -> 2.9MB plain text

Most of the file was structure, not content. The actual conversations compress to 2.9MB.

Next, chunking. Each chunk needs to fit in a context window, so I targeted 80K tokens per chunk, roughly 320KB of text:

TARGET_BYTES = 320_000

for conv in data:
    conv_size = sum(len(m.get('text', '')) for m in conv['messages'])
    if current_size + conv_size > TARGET_BYTES and current_chunk:
        chunks.append(current_chunk)
        current_chunk, current_size = [], 0
    current_chunk.append(conv)
    current_size += conv_size

That gives 10 chunks. Each gets fed to Claude Sonnet with a prompt asking for everything the conversations reveal about me: identity, preferences, code style, communication style, personality, interests, struggles, projects. Each observation labeled [stated], [demonstrated], or [inferred]. The 10 summaries then merge into one profile. Five parallel workers, a couple of minutes, $3.31 via the API.

10 chunks -> Sonnet -> 10 summaries (~28K tokens) -> Sonnet -> 1 profile

What it found

The profile was accurate. Renuo, ZHAW, Neovim, Ruby, Rust, it/its pronouns, strong opinions about naming, many typos, rejects em-dashes and emojis in technical contexts. It noted that I ask for 20 naming options, then 50, then "more generic," and called this "an intellectual interest, not thoroughness." It catalogued my projects, my coursework, my side interests. All correct. And shallow.

It described what I do. Not why.

What it missed

The profile found that I write inline asserts in my numerical methods code. Pre/postcondition checks inside the functions, not in a test file. It noted this as "inline verification" and moved on.

The asserts are not checking the math. I understand the math. They are checking the transcription. I type fast and produce "everutjing" when I mean "everything." The asserts exist because I do not trust that what I typed is what I meant. The mind is precise. The hands are not. Everything I build sits in that gap.

Claude could not find this. It sees patterns but not the thing that connects them. During the conversation that followed the pipeline, we kept pulling on that thread, and it turned out to be the thread that tied everything together. The typos, the naming obsession, the formatting rules, the inline asserts, the pronouns. All the same gap. None of that was in the data. It came out of the conversation.

The compression

After the pipeline produced the profile, I spent the better part of a day in conversation with Claude, questioning it, correcting it, adding context the data did not contain. Claude read my blog posts and gallery captions on cb341.dev to understand how I write. It asked me things the data could not answer. Then we started compressing.

21MB    raw JSON
 4MB    normalized
2.9MB   plain text
 28K    tokens of summaries
  6K    tokens of merged profile
  200   words of dense description

At each stage, something is lost. The metadata, the structure, the individual conversations, the contradictions, the context. But at each stage, what survives is more essential than what was removed.

There is a concept in information theory called Kolmogorov complexity: the length of the shortest program that produces a given output. It is uncomputable in general, but the idea is useful. The 200-word profile described me accurately. But so did the 6K-token version, and so did the 28K-token version. Each was shorter, none was minimal. Still describing, not yet true.

200 words felt close. Not close enough. So we kept compressing.

15 words

Back and forth, rejecting drafts, cutting what was description and keeping what was true, until there was nothing left to remove.

dani understands and cannot express. so it builds until it can. and gives it away.

21 megabytes to 15 words.

Still figuring things out

I went into this thinking I could automate self-knowledge. I could not. Claude could not ask "when was the last time someone took care of you." Some things only surface when someone asks the right question.

But the automated profile was accurate enough to see myself in and say "yes, but also this." Claude was the first draft. The conversation was the edit.

Claude drafted the words. I shaped them until they were mine. The code and the result are MIT licensed.

My Editor Journey

Sat, 25 Oct 2025 00:00:00 +0000

I have bounced around quite a bit over the years. Started with Atom back when it was the hot new thing, then migrated to VSCode like everyone else when Atom started showing its age.

Eventually moved to JetBrains (specifically RubyMine) for the superior refactoring tools and language intelligence. Somewhere along the way I discovered Vim keybindings and could not go back, so I added IdeaVim to RubyMine.

The JetBrains suite felt too heavy after a while, so I returned to VSCode but this time with Vim emulation. That is when I got curious about actual Vim and tried NVChad for a while. It was close, but I ended up back in VSCode for the ecosystem.

I have dabbled with Sublime Text here and there (I do not really like it), and recently tried Zed when it launched (impressive speed, but too minimal for my needs). I even spent some time with vanilla Vim to understand the fundamentals.

Eventually I built my own custom Neovim setup, which worked great until maintenance became a chore. Tried Cursor when AI coding assistants became a thing, used it a lot for the agentic mode and tab completion features. But I do not really like VSCode as a base, and it made me pretty sad during the time I was using it. Ended up back in my custom Neovim setup because I missed my configurations.

Finally landed on LazyVim, the sweet spot between a pre-configured distro and the flexibility to customize without maintaining everything myself.

Why Neovim

I genuinely enjoy Neovim as a hobby. The community is fantastic, it is intuitive to use once you get the hang of it, and there is no big tech corp jargon or anyone pushing AI down my throat. If I do not like a plugin anymore, I can just uninstall it or write my own replacement.

Building software is a lot about writing programs, text. You need a text editor. I do not think that you necessarily need an IDE as long as you know what you are doing. Many times I am faster searching for things using grep than waiting for ruby_lsp to feed me references. I like using the terminal, I switch very much between terminal and editor, pipe output of shell commands into the editor.

Neovim is not just a text editor. It is FAST, the fastest editing experience I have had. It is incredibly feature rich, yet keyboard oriented for efficient, sophisticated workflows. The modal editing paradigm takes time to learn, but once you understand even a subset of the key command set, it becomes a superpower.

Neovim integrates incredibly well with my terminal setup: zellij, autojump, ripgrep, lazygit. Everything works together seamlessly.

This is the way.

Why LazyVim

DHH promotes it, which caught my attention. Omakub ships with LazyVim as its complete Neovim setup, showcasing what is possible out of the box without having to write a single line of configuration. It is a distribution of Neovim plugins and configurations that has been lovingly tuned.

I was already using lazy.nvim and Lazygit, so the naming consistency appealed to me. LazyVim has sensible default keybindings, excellent support for Ruby out of the box, a great "extras" system for optional features, and makes it trivial to deactivate plugins I do not want. The documentation is solid, which makes troubleshooting and customization straightforward.

The large community is another huge plus. I am much more likely to find solutions to my problems when others have already encountered and solved them.

On AI Coding Tools

AI autocomplete saves me time looking through docs, reading through code, coming up with sensible names. Agents are good for refactoring, as long as they do not touch tests. I do not trust AI generated tests.

It is more about shaping than building line by line. It gives me a lot of flexibility. Let's do two classes, no wait let's merge into one, let's move this, rename that, use this convention, let's use imperative approach, no let's use an ERB template. Let's try this API, no let's try that one. Let's move this into shared context, let's DRYify this, let's translate, let's extract partials.

Agents are great when they work. They produce code very quickly, but debugging can be quite a nightmare. The other day I spent time debugging an ERB file that was causing the linter to fail, only to realize the agent had used Windows line endings for some reason.

I am constantly catching agents silently ignoring errors, adding rescue nil statements, removing unit tests after they have been failing for too long, and straight up LYING about what they have done. I also hate the marketing jargon and the never ending "You're absolutely correct".

I do not really like AI, but I do not want to fall behind the competition either. I want to learn the boundaries of what AI can and cannot do. I do not want to run on autopilot, blindly accepting all suggestions and producing functional but not craftsmanlike, mediocre software. I want to build good software, have fun doing it, and actually understand what I am building. I am making many mistakes and I hope that I'll learn from them eventually, Simon.

Custom Figma Design Challenges

Tue, 12 Aug 2025 00:00:00 +0000

While building the hackts.ch site, I encountered layout issues that I did not anticipate. The design came from a highly customised Figma file with precise alignments, irregular shapes and spacing patterns.

I chose Rails with custom Sass stylesheets because of the abundance of unique styling across the page. Bootstrap felt difficult to adapt to the design, and Tailwind's utility classes were not flexible enough for the level of customisation required.

The Design Gap

As you can see in the box model view, the layout contains many irregular spacings, varying element sizes, and non-uniform alignments. These characteristics made it difficult to implement using flexbox or grid with simple gaps, margins, and paddings, and required precise, element by element positioning.

A draft of the hackts.ch page with box model inspection, showing the irregular spacing and alignment requirements.

I also experimented with Figma to code tools such as Builder.io's Figma plugin but the results were disappointing. The generated markup was verbose and composed of inline styles, with font styling defined multiple times instead of integrating with the existing font definitions. There was no clear component structure or hierarchy, which made the output unpleasant to read.

Retrospective Approaches

Looking back, several methods might have eased the process:

Rendering sections as images with defined clickable areas using <area> elements
Using background images with text overlays
Exporting directly from Figma as SVGs to keep both vector shapes and text, applying CSS classes to SVG elements for consistent styling (MDN: Styling SVG with CSS)
Adding overlays for pixel accurate alignment adjustments

While using images and clickable areas may allow for faster development, it compromises accessibility, responsiveness, and maintainability, ultimately leading to a poorer user experience and not aligning with best practices in web development.

A Possible Solution

A more efficient solution could be to build a GUI editor in Rails for placing visual components. Such an editor could work similarly to JavaFX Scene Builder or other drag and drop UI layout tools. Developers could place images, text, and overlays directly in the browser, adjusting positions interactively instead of editing CSS values and refreshing the page.

The implementation could store element coordinates and properties in the database, with position: relative containers handling placement in the final rendering. This would allow pixel accurate adjustments without touching the stylesheets for every change.

An approach could borrow concepts from Herb LSP, which proposes a language server for HTML and embedded Ruby, but adapt them to support live visual positioning of components. As David Heinemeier Hansson has noted, there is value in keeping the development process grounded in simple, direct editing environments. A GUI editor should complement text based workflows, not replace them, allowing developers to maintain clean and maintainable code while benefiting from faster layout adjustments.

Conclusion

Highly customised designs often make standard frameworks and layout approaches less effective. Even with Sass for flexibility, aligning to the Figma design became a slow and manual process. A GUI editor for Rails, inspired by tools like Scene Builder, could provide an efficient and interactive way to place and adjust components, reducing the need for repetitive code edits while keeping the underlying code approachable.

Local zsh

Fri, 08 Aug 2025 00:00:00 +0000

Different projects often have different setups. Some are started with bun, others with bin/dev or bin/start. Some rely entirely on Docker Compose.

Defining global aliases for commands such as rspec or rubocop can quickly cause conflicts between projects:

alias rubocop='docker compose exec app bundle exec rubocop -a'

Creating complex Bash functions to detect the correct environment is possible, but usually not worth the time.

A Very Simple Solution

Let each project define its own aliases and functions in a small local_zsh file. Then, have your shell source it when you are in that project.

Example structure:

project_1/
  local_zsh
project_2/
  local_zsh

In your .zshrc:

[[ -f local_zsh ]] && source local_zsh

Whenever you switch to a project, sourcing .zshrc loads the correct aliases for that project.

Example local_zsh:

alias bash='docker compose exec app bash'
alias rc='docker compose exec app rails c'
alias rspec='docker compose exec app bundle exec rspec'
alias rubocop='docker compose exec app bundle exec rubocop -a'
alias erb_lint='docker compose exec app bundle exec erb_lint -a'

A small file per project is all that is needed for a more productive setup.

Exploring Rust as a Rubyist

Fri, 28 Feb 2025 00:00:00 +0000

At Renuo, we love Ruby. It's simple, elegant, and powerful. But let's be honest, Ruby isn't the fastest language out there.

Over the last couple of months, I've been exploring low-level programming, hoping to bridge the gap between the high-level world of Ruby and the lower-level world of systems programming. To do this, I started working on my first Rust project: a blazingly fast voxel "game" called rsmc. It features a terrain generator, meshing, a scalable client-server architecture, and custom serialized messages for high-speed communication. This project has been my playground for learning Rust, and in this post, I'll share some of the lessons I've learned along the way.

Early RSMC development with the Renet visualiser showing simultaneous client/server connections

Why Rust?

Rust is one of the most appreciated programming languages, as highlighted in the GitHub Octoverse Survey. It offers memory safety, high performance, and strong tooling, making it a solid choice for both small utilities and large-scale applications. Many of the tools I use daily, like Alacritty and 1Password, benefit from Rust's speed and reliability.

Key Benefits

Performance: Comparable to C and C++, but with safety mechanisms that prevent common errors.
Memory safety: Eliminates null pointer dereferences, segmentation faults, and data races.
Modern syntax: Readable and expressive, making it accessible despite its low-level capabilities.
Powerful tooling: Cargo simplifies dependency management, builds, and testing.

For my voxel game, Rust's speed and safety make it an excellent choice for terrain generation, networking, and real-time interactions. Unlike dynamically typed languages such as Ruby, Rust catches entire categories of bugs at compile time, improving maintainability.

Beyond CLI tools, Rust powers game engines, operating systems, simulations, and even web browsers, proving its adaptability across different domains.

Bevy: Game Development Made Fun

Since my project is built with Bevy, understanding its core concepts was very important. Bevy's entity-component-system (ECS) architecture makes game development modular and efficient, allowing for highly decoupled systems.

Some of my favorite takeaways:

Systems: Keep them small and focused on one task. This way they are easier to test and extend.
Plugins: Encapsulate resources, systems, and components into distinguishable modules.
Events: Use events to the fullest extent to decouple systems and keep code modular.
States: Run systems only when they are relevant (e.g., Menu, Playing). This helps with UI and logic separation. In particular this PR: #32

Bevy makes structuring a game engine intuitive, and its Rust-first approach ensures safety and performance while keeping things flexible. If you're interested in learning more about the ECS approach to game development, I wrote a blog article about planning an ECS: Multiplayer in Rust Using Renet and Bevy.

Feature Flags: Shipping Less in Production

Feature flags allow enabling or disabling specific functionality at compile time, making it easy to toggle features based on configuration.

In my voxel game, feature flags help manage debugging tools like wireframe rendering and debug UI. What's neat about these feature flags is that debug code doesn't get shipped in production, reducing binary size and keeping the release build clean.

In Cargo.toml, you can define feature flags like this:

[features]
egui_layer = []
terrain_visualizer = ["egui_layer"]
renet_visualizer = ["egui_layer"]

And then use them in your code:

#[cfg(feature = "egui_layer")] {
use bevy_inspector_egui::bevy_egui::EguiPlugin;
	app.add_plugins(DefaultPlugins);
	app.add_plugins(EguiPlugin);
}

The downside is that testing all possible feature combinations is a challenge. With just five features, you already have 32 different configurations to check. But that's the price of flexibility.

Cargo Watch: Automating Workflows

During the development of rsmc, I often needed to recompile code, and manually restarting my binary after every change quickly became tedious. I really wish I had discovered cargo-watch earlier.

Just install it and let the watcher do its thing:

cargo watch -x 'run --bin client'

Composition Over Inheritance

Coming from Ruby, where inheritance is common, Rust's approach felt different. Rust doesn't have classes. It uses structs and traits. This forced me to use composition over inheritance and think differently about code structure.

Here's an example from my terrain generator:

pub struct NoiseFunctionParams {
  pub octaves: u32,
  pub height: f64,
  // ...
}

pub struct HeightParams {
  pub noise: NoiseFunctionParams, // Composition!
  pub splines: Vec<Vec2>
}

Instead of inheriting from a base class, HeightParams contains a NoiseFunctionParams struct. This keeps the code flexible and avoids deep inheritance hierarchies.

Macros: Code That Writes Code

Rust's macros are like Ruby's metaprogramming but more structured and powerful. They help eliminate boilerplate while maintaining type safety.

Here's a macro I used to define blocks in my project:

macro_rules! add_block {
    ($block_id:expr, $is_solid:expr) => {
        Block {
            id: $block_id,
            is_solid: $is_solid,
        }
    };
}

pub static BLOCKS: [Block; 14] = [
    add_block!(BlockId::Air, false),
    add_block!(BlockId::Grass, true),
    // ...
];

Macros don't affect runtime performance. They are a zero-cost abstraction, a great feature of Rust.

Rust's Learning Curve: Worth the Effort?

Rust isn't the easiest language to pick up. The borrow checker takes time to understand, and coming from Ruby, its verbosity stands out. Ruby achieves more with fewer symbols. While Rust's explicitness helps with maintainability and reducing hidden behaviors, it also means writing more boilerplate.

One of the biggest disadvantages to me is compile times. They can be frustrating since Rust enforces strict checks, but this reduces runtime errors. There's even an XKCD comic about it.

XKCD 303 the Rust compile time experience

From my experience, Rust has its trade-offs. Catching many errors at compile time reduces debugging effort, but the strict rules and verbosity make writing new code slower compared to Ruby. That said, Rust's language servers provide excellent refactoring support, which makes working with larger projects easier.

For quick prototyping and iteration, scripting languages such as Ruby are still the better choice. However, when stability, performance, and long-term maintainability matters, Rust seems to be the better pick.

Conclusion

Rust isn't just another language. It changes how you think about programming. It makes you more aware of memory, safety, and performance. The learning curve is steep, but if you stick with it, the rewards are worth it.

I hope you enjoyed this journey into Rust! If you're a Ruby developer who has also tried Rust, what challenges have you faced? I'd love to hear your thoughts!

Hotwire Outside of Rails

Sat, 03 Aug 2024 00:00:00 +0000

A live Turbo Streams chat demo built with BunJS

This blog article is inspired by a Hotwire Turbo streams tutorial for Sinatra.

When you search for Hotwire tutorials on Google, you'll find that most of the results are related to Ruby on Rails. Even the Hotwire guides predominantly use Ruby on Rails as an example for implementing Turbo Streams.

This does not really come as a surprise, as the framework has been created by the same company behind the Ruby on Rails framework.

However, it's important to recognize that Hotwire is not exclusively a Rails framework. In this blog article, I aim to convince you that Hotwire can be used beyond the Rails context, especially Turbo, its core feature.

Goals

In this blog article, I will explain:

Setting up a BunJS Application
Implementing client and server-side Web Sockets
Using turbo streams to update the UI
Creating a stimulus controller attached to the DOM

Step 1: Set up a BunJS Application

Initially, I considered using Java Spring for this blog, but I encountered challenges with Web Sockets. Instead, I opted for a much simpler TypeScript application.

Let's start by initializing a new BunJS application:

mkdir bunjs-turbo-demo
cd bunjs-turbo-demo
bun init

Now, let's run the application:

bun run index.ts
Hello via Bun!

Step 2: Implement a Simple Web Socket / HTTP Server with BunJS

Web Sockets serve as the backbone for real-time communication in our project. In this step, we'll create a basic Web socket HTTP server using Bun. Web Sockets are essential for enabling bidirectional communication between clients (such as web browsers) and the server.

The Multiple Publisher - Multiple Subscriber Pattern

Our approach involves implementing the multiple publisher - multiple subscriber pattern. Here's how it works:

Client Interaction:
- Clients (users' web browsers) initiate actions, such as sending chat messages or requesting updates.
- These interactions trigger Web Socket connections to the server.
Server Processing:
- The server receives messages from multiple clients.
- It processes these messages and prepares appropriate responses.
Broadcasting Updates:
- When a client sends a message (e.g., a new chat message), the server broadcasts it to all connected clients.
- This ensures that everyone receives the latest updates in real time.
Seamless Communication:
- Web Sockets allow seamless, low-latency communication.
- Clients can instantly receive updates without the need for manual page refreshes.

Here is a simple sequence diagram showing the core idea of this project:

Multiple publisher / multiple subscriber pattern over WebSockets

Implement the server

For brevity, I've omitted the code for view helpers such as layoutHTML and chatRoomHTML. These helpers handle rendering HTML components and chat room layouts. While important, their details won't significantly impact the core concepts discussed in this blog.

const topic = "chatroom";

Bun.serve({
  port: 8080,
  fetch(req, server) {
    const url = new URL(req.url);

    if (url.pathname === "/")
      return new Response(layoutHTML("Chatroom", chatRoomHTML()), {
        headers: {
          "Content-Type": "text/html",
        },
      });

    if (url.pathname === "/subscribe") {
      if (server.upgrade(req)) {
        return;
      }
      return new Response("Couldn't upgrade to a WebSocket connection");
    }

    return new Response("404!");
  },
  websocket: {
    open(ws) {
      console.log("Websocket opened");
      ws.subscribe(topic);
      ws.publishText(topic, messageHTML("Someone joined the chat"));
    },
    message(ws, message) {
      console.log("Websocket received: ", message);
      ws.publishText(topic, messageHTML(`Anonymous: ${message}`));
    },
    close(ws) {
      console.log("Websocket closed");
      ws.publishText(topic, messageHTML("Someone left the chat"));
    },
    publishToSelf: true,
  },
});

Implement the client

The application is incomplete without the client, which connects to the Web Socket server. Following the Web Socket server connection documentation, connecting to the backend is straightforward:

const client = new WebSocket("ws://localhost:8080/subscribe");
const form = document.getElementById("chat-form");
const chatFeed = document.getElementById("chat-feed");

client.addEventListener("message", (event) => {
  chatFeed.innerHTML += event.data;
});

form.addEventListener("submit", (event) => {
  event.preventDefault();
  const formData = new FormData(form);
  const message = formData.get("message");
  client.send(message);
  form.reset();
});

Don't forget to add the route for the JavaScript file to the backend and include it inside your view using a module script tag. Also, make sure to implement the backend response.

The problem

As you can see here, every change in UI needs to be manually implemented. At the moment, we are listening to a single event and updating one single element. When the application grows in complexity, the JavaScript code grows, too. What if I told you that we can "almost" completely eliminate the client code by introducing Turbo streams?

Step 3: Implement Turbo streams

Turbo is a vital part of the Hotwire Framework. It enables you to dramatically reduce the amount of custom JavaScript you need to write.

The most relevant feature for this application are the turbo streams. They enable us to deliver page changes in the form of HTML over the wire.

Importing Turbo is as simple as including this snippet of code inside our layout file:

<script type="module">
  import hotwiredTurbo from "https://cdn.jsdelivr.net/npm/@hotwired/turbo@8.0.3/+esm";
</script>

In order to use Web Sockets for Turbo streams in the frontend, we can use the following snippet from the stream documentation:

<turbo-stream-source src="ws://localhost:8080/subscribe" />

In order to update the UI when a message is sent, we broadcast the following HTML through Web Sockets:

<turbo-stream action="append" target="chat-feed">
  <template>
    <p class="notice">Anonymous: Hello World!</p>
  </template>
</turbo-stream>

This method of HTML updates stands out for its transparency and simplicity. Firstly, we select an element with the #chat-feed selector and then append to it the contents of the broadcasted template. In this case, a paragraph containing the user message. This also eliminates almost all the client-side JavaScript needed for page update.

Step 4: Implement Form Controller

Before introducing turbo, we added a simple event listener to reset the Form after the data has been sent to the server. We now need to bring the functionality back, but without reusing the old code. We could use a turbo-stream to reset the form or even a turbo-frame, but rather than using that, I decided to use another library of the Hotwire framework, namely Stimulus:

Stimulus is a JavaScript framework with modest ambitions. It doesn't seek to take over your entire front-end -- in fact, it's not concerned with rendering HTML at all. Instead, it's designed to augment your HTML with just enough behavior to make it shine.

https://stimulus.hotwired.dev/

This is a simple code snippet for the Form Stimulus controller:

import {
  Application,
  Controller,
} from "https://cdn.jsdelivr.net/npm/stimulus@3.2.2/+esm";

class FormController extends Controller {
  clear() {
    this.element.reset();
  }
}

const application = Application.start();
application.register("form", FormController);

This is what the form HTML looks like, with data attributes used to attach the controller to the DOM and hook the events up to the corresponding controller methods:

<form
  id="chat-form"
  action="/submit"
  method="post"
  data-controller="form"
  data-action="turbo:submit-end->form#clear"
>
  <label for="message-input">Message:</label>
  <input name="message" data-form-target="input" required />
  <input type="hidden" name="clientId" value="${clientId}" />
  <input type="submit" value="Send" />
</form>

The event that works best for form submission in that case is turbo:submit-end. Following the documentation of Stimulus descriptors, we can call the #clear() method after the form submission event. We are not using the submit event because this would clear the form prematurely.

Conclusion

Hotwire is a JavaScript framework that helps us make applications more interactive while keeping the JavaScript code to a minimum. While the framework has been created by the authors of Ruby on Rails, the framework itself is backend agnostic.
Turbo streams enable us to update client user interfaces asynchronously without the need for any (in some cases, just very little) frontend code.
Stimulus enables us to add simple JavaScript behavior to our HTML with the use of Stimulus Controllers and data-attributes.

Where can I find the source?

You can find the complete chatting application with additional features such as:

Client identification via Query Parameters
Random username generation
Real-time user list

The GitHub Repository for this project can be found here: https://github.com/cb341/bunjs-turbo-demo

Supercharge Your Tmux Setup

Sun, 14 Apr 2024 00:00:00 +0000

Tmux is a terminal multiplexer. It is a tool for managing multiple shells inside a single terminal window. It is integrated into most modern terminal emulators like Iterm2 or Warp. In this blog article, I will show you two simple configurations that drastically improved my tmux experience.

Autoresizing panes

The main problem I had with tmux when starting out was that panes were not automatically resized as I was used from Warp:

Panes without auto-resize, manually spreading with <PREFIX> + E

Don't get confused by the remapped tmux prefix. The main thing to notice here is that I am using <PREFIX> + E to spread the panes out evenly.

What we now need is:

The command to resize the windows
The hook(s) for executing the command
Update the tmux configuration with the hook and the command.

Part1: Finding the command

According to the manual entry for tmux:

select-layout [-Enop] [-t target-pane] [layout-name]
							 (alias: selectl)
				 Choose a specific layout for a window.  If layout-name is not given, the last preset layout used (if any) is
				 reapplied.  -n and -p are equivalent to the next-layout and previous-layout commands.  -o applies the last
				 set layout if possible (undoes the most recent layout change).  -E spreads the current pane and any panes
				 next to it out evenly.

We can use the select-layout -E command to spread the panes evenly.

Part2: Finding the hooks

The first part is done. Now we need the hooks.

Unsurprisingly, this can also be found in the manual entry:

%window-pane-changed window-id pane-id
	 The active pane in the window with ID window-id changed to the pane with ID pane-id.

...

window-resized          Run when a window is resized.  This may be after the client-resized hook is run.

Part3: Updating the configuration file

If you haven't moved the .tmux.conf to .config, you can find the default configuration file for MacOS at ~/.tmux.conf.

To execute the command on the resize and pane changed hooks, we can add these lines to the tmux configuration:

# .tmux.conf
...
set-hook -g window-pane-changed 'select-layout -E'
set-hook -g client-resized 'select-layout -E'
...

This is how the panes behave after adjusting the configuration:

Panes automatically spreading after adding the select-layout -E hooks

According to the manual entry, we can also shorten the command to the following:

set-hook -g window-pane-changed 'selectl -E'
set-hook -g client-resized 'selectl -E'

Dimming Inactive Panes

Next to automatically resizing windows, we can also automatically dim panes that aren't active by using the following configuration:

set-hook -g pane-focus-out 'select-pane -P bg=colour233,fg=colour10'
set-hook -g pane-focus-in 'select-pane -P bg=default,fg=default'

Inactive panes dimmed using focus hooks

Now, this is a much nicer alternative than the active border color. If you are wondering how I got rid of it, I used this configuration:

set -g pane-active-border-style "bg=#000000,fg=white"
set -g pane-border-style "bg=#000000,fg=white"

Remember that black and #000000 are not the same thing when configuring your terminal, as the color names are defined by your color scheme.

Conclusion

While tmux isn't as usable/powerful out of the box as the integrated tmux in Iterm or Warp, with some simple configuration, it can be significantly improved. The manual page for tmux is the go to source for looking up commands and events and will save a lot of time googling.

Tools and Sources

Screen recorder: CleanShotX
Keystroke recorder: KeyCastr
Terminal Emulator: Alacritty
Other configuration: My Dotfiles

Multiplayer with Bevy and Renet

Thu, 07 Mar 2024 00:00:00 +0000

Here at Renuo, we specialize in web technologies such as Ruby on Rails, React, Angular, and Spring. One of our core company values is continuous learning: we love exploring new technologies even beyond our usual scope of expertise.

Inspired by Michael's Unity Powerday, I decided to delve into how multiplayer games operate. As a team, we held a competition to implement FPS (First-Person Shooter) games using C# boilerplate. Initially, the sheer amount of boilerplate required felt overwhelming. Beyond that, I wanted to understand client/server data synchronization at a lower level of abstraction.

My recent experiences with Rust and Bevy convinced me to write this blog article to share my newfound learnings of game development.

Why Choose Rust

Advantages

Rust is a statically typed, memory-safe, multi-paradigm programming language that matches the performance of C. Due to its safety, concurrency features, and modern syntax, it has gained popularity among developers in recent years.

Some notable software written in Rust includes:

Rapier3d: A performant physics engine often used with ThreeJS.
Ripgrep: A performant command line search tool.
Alacritty: A performant, minimalistic cross-platform terminal emulator.
Warp: A performant, modern terminal IDE.
Tauri: A performant and lightweight alternative to ElectronJS.
Amethyst: A performant tiling window manager for MacOS.
Condorium Blockchain: A performant and secure blockchain technology.

"I mean, there is no such thing as a perfect programming language. Rust is merely a statically type low-level multi-paradigm perfect programming language."

YouTube interview by Programmers Are Also Human,

Ferris, the unofficial Rust mascot

Picking a game engine

"There are currently 5 games written in Rust. And 50 game engines."

Interview with a Senior Rust Developer - 2:52

There are too many game engines available for Rust. An excellent resource is Are We Game Yet. I also recommend this article by GeeksforGeeks, which makes picking the optimal engine easier.

The Difference Between Bevy and Other Engines

While big game engines like Godot, Unity, and Unreal Engine come with graphical editors, Bevy focuses on providing a simple yet powerful, multithreaded system to manage game state with minimal code.

Understanding ECS

The ECS (Entity Component System) is a software pattern that emphasizes a modular design. It is commonly utilized in game and game engine development. This approach separates the data and behaviour of game entities into components, making it easier to manage and organize complex systems.

Components of ECS

Entities: Unique identifiers of a group of components (A u32 wrapper in bevy).
Components: Modular data pieces that represent specific Entity attributes. (A struct that derives the Component macro in bevy)
System: Logic that operates on entities and their components. (A struct that derives the Resource macro in bevy)

Systems in Bevy

Systems in Bevy are functions that take various parameters such as queries, EventReaders, assets, and resources and apply logic to them.

One powerful feature of Bevy systems is the Query interface. It allows you to fetch specific data for entities in your project. For instance, if no entity is found, the single_mut() function will raise an error. Multiple queries are possible as long as entities do not overlap.

Below is an example where the MyPlayer component doesn't contain any data but is used to denote that the entity belongs to the client player.

pub fn update_player_movement_system(
    mut keyboard_events: EventReader<KeyboardInput>,
    mut query: Query<(&mut Transform, &MyPlayer)>,
) {
    let (mut transform, _) = query.single_mut();

    for event in keyboard_events.read() {
        let mut delta_position = Vec3::new(0.0, 0.0, 0.0);

        match event.key_code {
            KeyCode::KeyW => delta_position.z += 0.1,
            KeyCode::KeyS => delta_position.z -= 0.1,
            KeyCode::KeyA => delta_position.x -= 0.1,
            KeyCode::KeyD => delta_position.x += 0.1,
            _ => {}
        }

        let new_position = transform.translation + delta_position;
        transform.translation = new_position;
    }
}

The example above has a flaw: the player position update has a fixed step. Instead of using a fixed-step update, consider using the time passed since the last step. This will ensure a consistent movement speed regardless of the frame rate.

Picking Networking Libraries

We need to decide on networking libraries after choosing Bevy as our game engine. Here are a few options:

Matchbox
Naia
Renet
Bootleg_networking
Spicy_networking

I chose Renet because of its popularity and my good experiences with its boilerplate. Additionally, I included Serde for efficient binary message encoding.

Sketching the scene

Before coding, let's sketch a simple scene:

Camera: Renders the scene.
Plane: Represents the floor.
Green Cube: Represents the player.
Red Cubes: Represent other players.

Attributes to synchronize:

Position: Vec3

Input method:

Keyboard (WASD): Used to translate the player.

Handling Player inputs

There are three main ways to handle player inputs:

Client-side: The client handles inputs, moves the player, and sends the position to the server.
Server-side: The client sends input data to the server, and the server responds with the position.
Hybrid: The client handles inputs and shares them with the server, which then responds with position synchronization.

The client-side approach can reduce latency, but is less secure. The server-side approach is more secure but adds server load. The hybrid approach offers a balance, but is more complex.

Planning

Client

Type	Name	Description
Component	PlayerEntity(ClientId)	Represents an enemy player entity.
Component	MyPlayer	Marks the current player entity.
Event	PlayerSpawnEvent(ClientId)	Emitted when a player joins. Adds a player object to the scene.
Event	PlayerDespawnEvent(ClientId)	Emitted when a player leaves. Removes a player object from the scene.
Event	PlayerMoveEvent(ClientId, Vec3)	Emitted by the player controller when a player moves.
Event	LobbySyncEvent(HashMap<ClientId, PlayerAttributes>)	Emitted when the client receives sync messages from the server. Updates other player positions using their ID and position.
System	send_message_system	Shares MyPlayer position data with the server.
System	receive_message_system	Processes messages received from the server.
System	update_player_movement_system	Updates player position from keyboard input.
System	setup_system	Sets up the scene with a camera, a ground plane, and a mesh for the current player.
System	handle_player_spawn_event_system	Adds enemy players to the scene once they join in.
System	handle_lobby_sync_event_system	Updates enemy player positions and potentially spawns missed players into the scene.

Server

Type	Name	Description
Resource	PlayerLobby(HashMap<ClientId, PlayerAttributes>)	Holds attributes of all players currently in the game. Used to synchronize these attributes with the clients.
System	send_message_system	Broadcasts player positions to keep enemy player positions in clients up-to-date.
System	receive_message_system	Updates player lobby position based on messages received from the RenetClient.
System	handle_events_system	Handles events such as ClientConnected and ClientDisconnected from the Bevy Renet plugin.

Deciding on a project structure

I separated the ECS components into specific modules to structure the Bevy project and used two entry points: one for the client and one for the server. Shared code, such as structures for Client-Server communication, can be placed in a global lib module.

src
src/
  client/
    components.rs
    events.rs
    main.rs
    resources.rs
    systems.rs
  lib.rs
  server/
    main.rs
    resources.rs
    systems.rs

Defining various entry points is as simple as adding this to the Cargo.toml file:

[[bin]]
name = "server"
path = "src/server/main.rs"

[[bin]]
name = "client"
path = "src/client/main.rs"

Afterwards, the binaries can be run with the --bin argument:

cargo run --bin server
cargo run --bin client

Setting up Boilerplate

To integrate bevy_renet into the bevy project, I followed the Bevy Renet documentation. In my setup, I used these two default channels:

Unreliable: Used for sending and receiving messages for player attribute synchronization. (We don't care about every state change, we can pick the last one)
ReliableOrdered: Used for sending and receiving messages for player actions such as joining and leaving.

Synchronising player positions

Here's an example of sending player attributes from the client to the server:

pub fn send_message_system(mut client: ResMut<RenetClient>, query: Query<(&MyPlayer, &Transform)>) {
    let (_, transform) = query.single();
    let player_sync = PlayerAttributes {
        position: transform.translation.into(),
    };
    let message = bincode::serialize(&player_sync).unwrap();
    client.send_message(DefaultChannel::Unreliable, message);
}

Handling messages from the client on the server:

pub fn receive_message_system(mut server: ResMut<RenetServer>, mut player_lobby: ResMut<PlayerLobby>) {
    for client_id in server.clients_id() {
        let message = server.receive_message(client_id, DefaultChannel::Unreliable);
        if let Some(message) = message {
            let player: PlayerAttributes = bincode::deserialize(&message).unwrap();
            player_lobby.0.insert(client_id, player);
        }
    }
}

Sending attributes of all players back to the client:

pub fn send_message_system(mut server: ResMut<RenetServer>, player_lobby: Res<PlayerLobby>) {
    let chanel = DefaultChannel::Unreliable;
    let lobby = player_lobby.0.clone();
    let event = multiplayer_demo::ServerMessage::LobbySync(lobby);
    let message = bincode::serialize(&event).unwrap();
    print_lobby(&player_lobby);
    server.broadcast_message(chanel, message);
}

Synchronizing the client scene with the player attributes from the server:

pub fn handle_lobby_sync_event_system(
    mut spawn_events: EventWriter<PlayerSpawnEvent>,
    mut sync_events: EventReader<LobbySyncEvent>,
    mut query: Query<(&PlayerEntity, &mut Transform)>,
    my_clinet_id: Res<MyClientId>,
) {
    let event_option = sync_events.read().last();
    if event_option.is_none() {
        return;
    }
    let event = event_option.unwrap();

    for (client_id, player_sync) in event.0.iter() {
        if *client_id == my_clinet_id.0 {
            continue;
        }

        let mut found = false;
        for (player_entity, mut transform) in query.iter_mut() {
            if *client_id == player_entity.0 {
                let new_position = player_sync.position;
                transform.translation = new_position.into();
                found = true;
            }
        }

        if !found {
            info!("Spawning player {}: {:?}", client_id, player_sync.position);
            spawn_events.send(PlayerSpawnEvent(*client_id));
        }
    }
}

Conclusion

The multiplayer demo project demonstrates the intricate planning and attention to detail needed to synchronize player attributes between the client and server. This showcases the complexity of creating a seamless multiplayer experience at a lower level.

For more detailed code, visit the MIT-Licensed GitHub repository.