Timothy D Beach

How My Links Got Their Pictures

Wed, 10 Jun 2026 00:00:00 +0000

Paste a link to this site into LinkedIn, or Slack, or a text message, and a little card unfurls: a title, a sentence, and a picture. That card is doing a lot of quiet work — it's the difference between a friend tapping your link and a friend scrolling past a naked blue URL.

For a long time, every link to this site unfurled with the same picture — a generic photo of me that had nothing to do with whatever article I was actually sharing. This is the story of the protocol that fixes that, and the three traps I fell into making it work on a site like mine.

🔗 The protocol nobody told you about

The technology is called the Open Graph protocol, and you've been looking at its output for years without knowing its name. Facebook published it in 2010 so that a shared link could carry a title, a description, and an image into the news feed. It caught on, and now essentially every platform that renders a "link preview" — LinkedIn, X, Slack, Discord, iMessage, WhatsApp, Signal — reads the same tags.

The tags live in the of your HTML, and they're almost insultingly simple:

That's it. og:title, og:description, and og:image are the three that matter; the others are polish. There is no JavaScript, no API, no SDK. You write five lines of HTML and the entire internet's worth of chat apps suddenly know how to show your link off.

🐦 Twitter wanted to be different

X — Twitter, when this all started — decided it needed its own parallel set of tags, prefixed twitter: instead of og::

The one that does real work is twitter:card. Set it to summary_large_image and you get the big edge-to-edge picture instead of a cramped thumbnail. The good news is that Twitter falls back to your Open Graph tags for anything it can't find a twitter: version of — so in practice you write the og: tags, add twitter:card on top, and you're covered everywhere. I emit both on every page, belt and suspenders.

One quirk worth knowing: since around 2023, X often renders link cards as just the image with the domain stamped on it, dropping the title and description text that LinkedIn shows. That's a display choice on their end, not a mistake in your tags. Your picture still shows up large.

🤖 The crawler doesn't run your code

Here is the single most important fact about Open Graph, and the one that caused all my grief: the thing reading your tags is a dumb robot, not a browser.

When you paste a link, the platform sends out a crawler — LinkedIn's is called LinkedInBot, Twitter's is Twitterbot — to fetch your page. That crawler downloads the raw HTML and reads the meta tags. It does not run your JavaScript. It does not wait for your single-page app to boot, fetch data, and render. It reads what the server hands it, on the first byte, and leaves.

For a normal website with real HTML pages, this is fine. For my site, it was a disaster, and to explain why I have to admit how this site is built.

🪤 Trap one: the fragment that never arrives

timbeach.com is a single-page app. Every article lives at a URL like timbeach.com/#/article/how-tmux-works. That # is a hash fragment, and the site's router watches it to decide which article to show — all in the browser, all in JavaScript.

Here's the problem, and it's baked into the web itself: the part of a URL after the # is never sent to the server. It's a client-side-only construct, by design, going back to the original purpose of fragments as "jump to this anchor on the page." So when LinkedIn's crawler fetches timbeach.com/#/article/how-tmux-works, the server only ever sees a request for timbeach.com/. The crawler gets my homepage, reads the homepage's generic OG tags, and shows that same generic photo of me — no matter which article the link pointed to.

Two strikes, both fatal: the crawler can't run the JavaScript that would pick the right article, and it can't even see which article was requested. There is no clever tag I could add to fix this. The hash URL is a dead end at the protocol level.

The fix is to stop asking a hash URL to do a server's job. At deploy time, a script now walks every article and writes a real, honest HTML file at a real path — a/how-tmux-works/index.html — with that article's own Open Graph tags baked in. That's a page the crawler can actually fetch and read. A human who clicks it gets a one-line redirect into the usual single-page reader, so the experience is unchanged; only the URL you share is different. Crawlers read the static tags; people land in the app. Everybody gets what they came for.

🌫️ Trap two: the blur

I shipped the share pages, pasted a link, and there it was — the right article's image, finally. Except it was blurry.

The culprit was aspect ratio. Open Graph images want to be 1200×630 pixels — a specific, slightly-wider-than-2:1 rectangle. The image I'd handed it was a 1536×1024 screenshot. When the crawler gets an image that isn't the right shape, it crops and resamples it to fit, then re-encodes the result as a compressed JPEG. For a screenshot full of small text, that round of squashing and recompression turns crisp pixels to mush.

Worse, a couple of my images were smaller than 1200 pixels wide, and platforms will quietly demote an undersized image — showing it as a tiny thumbnail off to the side instead of the big card. Same tags, completely different result, purely because of pixel dimensions.

The fix was to stop handing crawlers raw images and start handing them finished cards. Now the publish pipeline composites every article's image onto an exact 1200×630 canvas — the whole image, scaled to fit, centered on a dark background that matches the site, downsampled once with a good filter. The crawler receives something already the precise shape and size it wants, so it has nothing left to crop or resample. The blur is gone, and a square diagram or an undersized photo gets the same clean treatment as a perfect screenshot.

♻️ Trap three: the cache that never forgets

This one is the cruelest, because everything was working when it bit me.

I'd been iterating — first a plain text card, then the real image, then the sharp composited version — and each time I redeployed and re-checked the preview. At one point the preview reverted to showing an old version I thought I'd deleted two iterations ago. The file on my server was unambiguously the new one; I checked the bytes by hand. And yet LinkedIn kept showing the stale one.

Platforms cache Open Graph images aggressively, and they cache them by URL. My image had lived at the same URL the whole time — .../og.png — while its contents changed underneath. LinkedIn had fetched that URL early, stored the bytes, and from then on it served its copy without ever asking my server whether the image had changed. Re-scraping the page refreshed the tags but not the cached image. The URL was the cache key, the URL never changed, so the cache never expired.

The fix is a trick as old as web development: put a fingerprint of the contents into the filename. The card is now named after a hash of its own bytes — og-de50d8b938.png — so the moment the image changes, its filename changes, and therefore its URL changes, and therefore every cache on earth treats it as a brand-new image it's never seen. When nothing changes, the name stays put and the cache stays valid. You only bust the cache exactly when you mean to.

🌟 The whole trick, in one breath

Open Graph is a beautiful little protocol: five lines of HTML buy you a polished presence in every chat app and feed on the internet. But it rests on one assumption — that a crawler can fetch a real page and read real tags — and the moment your site bends that assumption, you find out exactly how much was riding on it.

If you take three things from my bruises:

Crawlers don't run JavaScript. If your content only exists after your app boots, the crawler will never see it. Serve real HTML with real tags at a real URL.
Hand over a finished 1200×630 image, not a raw one. Let the crawler do as little as possible, and it can't make your picture worse.
Fingerprint the filename so the URL changes when — and only when — the image does. Otherwise some cache, somewhere, will haunt you with a picture you killed days ago.

I added a read-aloud voice to this blog last month and learned that two parsers will always eventually disagree. This month I learned that a crawler is just a very literal reader who refuses to run your code, resizes your art without asking, and never throws anything away. Build for that reader, and your links will finally look like they mean something.

Still Really Simple: A Short History of RSS (and How This Site Uses It)

Sun, 07 Jun 2026 00:00:00 +0000

There's a small orange icon you don't see much anymore. For about a decade it lived in the corner of every browser's address bar, and then one day it quietly vanished. The technology behind it never did — you're using it right now if you listen to podcasts, and you can use it to read this site. No account, no app, no algorithm deciding what you get to see.

That technology is RSS. This is what it is, where it came from, and exactly how the feed for this website gets built.

What RSS actually is

RSS is a plain-text file that a website publishes and keeps up to date. It lists the site's recent content — each entry with a title, a link, a short description, and a date — in a structured format that software can read. That's the whole idea.

You point a program called a feed reader at the file's address. The reader checks the file every so often, notices when new entries appear, and shows them to you in a tidy, chronological list. Subscribe to a dozen sites and your reader becomes a single inbox for everything you care about — in the order it was published, with nothing injected and nothing hidden.

The crucial part is who's in charge. There's no middleman. The site publishes the file; your reader fetches it directly. No company sits between you and the writer deciding what's worth your attention. You subscribed, so you get everything.

A short, contentious history

RSS was born at Netscape in 1999 as a way to fill the "channels" on the My Netscape portal. The acronym has meant three different things over the years, which tells you something about how its history went: it started as RDF Site Summary, was softened to Rich Site Summary, and finally settled — thanks largely to Dave Winer of UserLand Software — as Really Simple Syndication.

That naming muddle was a symptom. Through the early 2000s, development splintered between camps with different technical philosophies, and the versions multiplied: 0.90, 0.91, 0.92, 1.0, and eventually RSS 2.0 in 2002, which froze the format and is what most feeds — including this one — still use today. The friction got bad enough that a rival format, Atom, was created in 2005 to do the same job more cleanly. Both still exist, readers support both, and the war is a museum piece now.

Then came the golden age. Google Reader launched in 2005 and, for a while, RSS was simply how the technical web read the technical web. And then, in 2013, Google shut Reader down. The headlines wrote themselves: RSS is dead.

It wasn't. It just got quiet. Every podcast on earth is distributed as an RSS feed — that's what a podcast is, underneath. Newsletters, news sites, and blogs still publish feeds. A healthy ecosystem of independent readers survived Reader's death and arguably got better for it. RSS didn't lose; it just stopped being fashionable, which on today's web is nearly a compliment.

Why it's still worth using

The pitch is the same as it was in 2005, only more so now that the alternative is so much worse:

No algorithm. You see every post from everyone you subscribed to, newest first. Nothing is boosted, throttled, or reordered to keep you scrolling.
No account, no tracking. Your reader fetches a file. The site doesn't know who subscribed, and there's no login standing between you and the words.
It's yours and it's portable. Your subscription list lives in your reader and exports as a small file (called OPML) you can carry to any other reader. Nobody can lock you in.
It's calm. No infinite scroll, no notifications begging for your time. You read what's new and you're done.

For a personal site like this one, RSS is the honest way to say "here's how to follow along" without asking anyone to make an account or trust a platform.

How the feed works on this site

Here's the part specific to this site. It is fully static — no database, no backend — so the feed is generated ahead of time and served as a plain file at:

https://timbeach.com/feed.xml

Everything here, including the feed, is built from a single source of truth: a file called articles.json that lists every article with its title, date, tags, and a one-sentence summary. The homepage reads it to draw the article cards. A small Python script named build_feed.py reads the very same file to build the feed.

When the script runs, it sorts every article by date, newest first, and writes one entry per article — each carrying the title, the publish date, a permanent link, and the summary as its description. Then it does something many feeds don't: it embeds the full text of each article, not just an excerpt, so a reader can show you the whole piece without ever visiting the site.

That last point matters. Many feeds give you a teaser and make you click through. This one hands over the complete article, rendered from the same markdown the website itself uses.

The build runs automatically as part of deploying the site. The deploy script validates everything, regenerates the feed from the current articles.json, and ships it alongside the rest of the static files. There's no live server assembling the feed on request — by the time you fetch it, it's already a finished document sitting on disk. Fast, cacheable, and impossible to break at read time.

So when I publish something new, the feed updates itself as a side effect of the same command that updates the site. No separate step, nothing to forget. The orange icon may be gone from your browser, but the file it pointed to is still here, still really simple, and still the best way to follow along.

Paste this into any feed reader:

https://timbeach.com/feed.xml

That's the whole setup. No account to make, nothing to install beyond a reader you like. Welcome to the quiet web.

Why Claude Code Keeps Asking for Permission (and How to Make It Stop)

Sat, 06 Jun 2026 00:00:00 +0000

Disclaimer: never do this. It's too dangerous, and I accept no responsibility for explaining how this works here 😉 — but for real, don't do this. This article is purely for academic interest.

If you run Claude Code with --dangerously-skip-permissions every single launch, and you've noticed that resumed sessions are the worst offenders for nagging you to approve things — this one's for you. The behavior isn't a bug. It's a consequence of how permission mode works, and once you understand it the fix is one line of config.

The core idea: mode is set at startup, not per-turn

Claude Code has a few permission modes. The strongest is bypassPermissions — the true "no guardrails, never ask" mode. The critical thing to understand:

A session's permission mode is locked in when the session starts. It is runtime state, not a setting that gets re-read on every action.

There are exactly two ways a session enters bypassPermissions:

You launch with the --dangerously-skip-permissions flag, or
You set permissions.defaultMode to bypassPermissions in your settings, which is read at startup.

That word startup is the whole story.

Why resumed sessions are the worst

Here's the pattern that drives people up the wall:

Fresh session with the flag → bypass mode → blissful silence.
Leave it open for hours → it asks less and less, because every "yes, and don't ask again" you click gets appended to your allow-list. The session is learning.
Exit, then claude --resume or claude -c → the mode resets to default, and unless you re-type the flag, you're back to approving everything from scratch.

So the sessions that feel the most annoying — the ones you're returning to from yesterday — are exactly the ones where the flag from the original launch no longer applies. You didn't do anything wrong. The flag just never persisted.

The fix: make bypass your default

Add this to ~/.claude/settings.json:

{
  "permissions": {
    "defaultMode": "bypassPermissions"
  }
}

Now every session — fresh, resumed, or background — starts in bypass mode with no flag required. You can stop typing --dangerously-skip-permissions entirely.

One related setting worth knowing: skipDangerousModePermissionPrompt: true only suppresses the scary red "are you sure you want bypass mode?" warning dialog. It does not put you in bypass mode. People conflate the two and wonder why they're still being asked. Different knob.

The Shift+Tab trap

Here's where a lot of people (myself included) waste five minutes: Shift+Tab does not cycle to bypass.

Tap Shift+Tab at the prompt and you'll cycle through:

normal — prompts on everything
accept edits on — auto-approves file edits, still prompts on shell commands
plan mode on — read-only, proposes a plan first
auto mode on — a smart classifier that auto-approves anything it judges safe and only stops for genuinely destructive or irreversible actions

Notice what's missing: bypassPermissions. It is deliberately excluded from the interactive cycle. It's the one mode with zero guardrails, so the designers made it reachable only via the launch flag or the startup setting — never a keystroke. If you're hammering Shift+Tab in a running session waiting for "bypass permissions" to show up, it never will. That's the safety boundary working as intended, not a broken session.

What to do with sessions that are already running

Because mode is fixed at startup, editing your settings does not retroactively flip a session that's already live. For those:

Want the most relief without restarting? Shift+Tab until it reads auto mode on. It kills the vast majority of prompts — auto-approving routine work and only pausing on the genuinely dangerous stuff (drops, wipes, rm -rf). For most workflows you won't feel the difference from bypass.
Want true zero-prompt bypass? Exit and bring the session back with claude -c or claude --resume. On relaunch it reads your new defaultMode and comes back in real bypass mode, with your full context intact.

One honest caveat

bypassPermissions means zero prompts, including for genuinely destructive actions. If your day involves sudo, disk partitioning, or live database work, a fat-fingered command goes through with no "are you sure?" If you want a safer middle ground, set defaultMode to acceptEdits (auto-approves edits, still pauses on shell commands) or lean on auto mode, which is smart enough to auto-approve the safe 95% and stop on the scary 5%.

Seriously, though: do it in a sandbox

The permission prompt is a safety net, and turning it off entirely means you've removed the one thing standing between an agent and your real filesystem, your real credentials, your real production database. So if you're going to run with no guardrails, put a different set of guardrails around the whole thing: run it in a sandbox.

That can mean a few things, in rough order of effort:

Claude Code's own sandbox. There's a sandbox block in settings that confines tool execution — filesystem write-jails, network allow/deny lists, the works. Bypassing prompts while still sandboxing execution is a genuinely reasonable combo: no nagging, but a fat-fingered rm -rf / can't escape the box.
A container or VM. Run the whole session inside Docker, a throwaway VM, or a dev container with only the project mounted and nothing sensitive in reach. If it all goes sideways, you docker rm the blast radius.
A scratch user / scratch machine. No prod creds in the environment, no SSH keys to your real infrastructure, nothing in ~ you'd cry over.

The principle: never combine "no prompts" with "full access to things you care about." Remove one or the other. Bypass mode is a lot less scary when the worst it can reach is a disposable container.

But if you've already been launching with --dangerously-skip-permissions every time, setting defaultMode: bypassPermissions isn't new risk. It just makes your existing habit the default — and finally fixes the resumed-session nagging for good.

Claude /tips: The Complete List

Thu, 04 Jun 2026 00:00:00 +0000

TL;DR

You know those little italic tips that flicker at the bottom of Claude Code while it thinks — "Double-tap esc to rewind," "Hit Shift+Tab to cycle modes"? There's no docs page that lists them, because they're compiled into the Claude Code binary itself. So I pointed Claude at its own executable and had it read them out.

The result: all 58 tips that Claude Code 2.1.162 ships with, below. You'll never see them all in normal use — each one is gated to a relevant context and put on cooldown after it shows, so the rotation is different for every project and every user. The complete list is right here, followed by a bonus round of keyboard shortcuts that aren't in the rotation, and — if you're curious — the story of how I extracted them at the end.

The Complete List

Every tip Claude Code 2.1.162 can show you, grouped by theme. (Two are fully dynamic — a server-supplied "feature of the week" and a team-artifacts summary — so they have no fixed text and are omitted.)

Keyboard & input

Press Shift+Enter (Option+Enter on Apple Terminal) to send a multi-line message
Hit Shift+Tab to cycle between default mode, auto-accept edit mode, and plan mode
Double-tap esc to rewind the conversation to a previous point in time
Double-tap esc to rewind the code and/or conversation to a previous point in time
Hit Enter to queue additional messages while Claude is working
Send messages to Claude while it works to steer it in real-time
Did you know you can drag and drop image files into your terminal?
Paste images into Claude Code using Ctrl+V (not Cmd+V!)

Slash commands & config

Use /memory to view and manage Claude memory
Use /theme to change the color theme
Use /statusline to set up a custom status line beneath the input box
Use /permissions to pre-approve and pre-deny bash, edit, and MCP tools
Use /voice to enable push-to-talk dictation
Use /feedback to help improve Claude Code
Name your conversations with /rename to find them easily in /resume later
Running multiple sessions? Use /color and /rename to tell them apart at a glance
Try smoother rendering, lower memory, mouse support, and better copy formatting — /tui fullscreen
New to Claude Code? Run /powerup for a quick interactive tutorial
Run /terminal-setup to enable Shift+Enter (or Option+Enter) for new lines and more

Agents, skills & workflows

Create skills by adding .md files to .claude/skills/ in your project, or ~/.claude/skills/ for skills that work everywhere
Use /agents to optimize specific tasks — e.g. Software Architect, Code Writer, Code Reviewer
Use --agent to start a conversation directly with a subagent
Say "fan out subagents" and Claude sends a team — each one digs deep so nothing gets missed
/loop runs any prompt on a recurring schedule — great for monitoring deploys, babysitting PRs, or polling status
Set an objective with /goal — Claude keeps working until it's met
Use Plan Mode to prepare for a complex request before making changes — Shift+Tab twice to enable
Ask Claude to create a todo list when working on complex tasks to track progress and stay on track
Use git worktrees to run multiple Claude sessions in parallel
/ultrareview runs a deep, multi-agent review of your changes
Start with small features or bug fixes, tell Claude to propose a plan, and verify its suggested edits

IDE & app integrations

Connect Claude to your IDE — /ide
In VS Code, open the Command Palette (Cmd+Shift+P) and run "Shell Command: Install 'code' command in PATH" to enable IDE integration
Run /install-github-app to tag @claude right from your GitHub issues and PRs
Run /install-slack-app to use Claude in Slack
Run Claude Code locally or remotely using the Claude desktop app — clau.de/desktop
Run tasks in the cloud while you keep coding locally — clau.de/web
Continue your session in Claude Code Desktop with /desktop
Working on UI? Claude Code Desktop has live preview and inline images — clau.de/desktop
Control this session remotely — run /remote-control
Get pinged on your phone when long tasks finish — enable push notifications in /config
Build your AI product with Claude API — run /claude-api to get started

Environment & plugin nudges

Working with HTML/CSS? Install the frontend-design plugin
Working with Vercel? Install the vercel plugin
Working with Stripe? Install the stripe plugin
Run claude --continue or claude --resume to resume a conversation
Try setting COLORTERM=truecolor for richer colors
Set CLAUDE_CODE_USE_POWERSHELL_TOOL=1 to enable the PowerShell tool (preview)
Your default model is Opus Plan Mode — press Shift+Tab twice to plan with Claude Opus

Sharing & growth

Share Claude Code and earn usage credits — /passes
Run /team-onboarding to turn your Claude usage into a shareable onboarding guide

Bonus: shortcuts that aren't in the rotation

Honestly, these are more valuable day-to-day than half the tips above — the keyboard shortcuts and input sigils pulled from the same binary's keybinding map. They mostly don't surface as tips, but they're the difference between poking at Claude and actually driving it.

The three input sigils — type these as the first character of your message:

! runs the rest of the line as a shell command in your session, dropping the output right into the conversation. Perfect for an interactive login or a quick git status without leaving the chat.
@ mentions a file or directory — Claude pulls it into context. Start typing a path and it autocompletes.
# saves what follows as a memory, so Claude remembers it in future sessions.

Keyboard shortcuts (defaults — all rebindable in ~/.claude/keybindings.json):

Shift+Tab — cycle through default / auto-accept-edits / plan mode
Esc — interrupt Claude mid-task
Esc Esc (double-tap) — rewind the conversation (and optionally code) to an earlier point
Ctrl+G — pop your draft open in your $EDITOR for long or multi-line prompts
Ctrl+L — clear the screen
Ctrl+V — paste an image from your clipboard (note: not Cmd+V on Mac)
Ctrl+S — stash your current input
Alt+P — open the model picker
Alt+T — toggle extended thinking
Alt+O — toggle fast mode
Alt+W — toggle workflow-keyword detection
Ctrl+B — background a running tool call so you can keep working
Ctrl+X Ctrl+K — kill running agents

Slash commands worth knowing beyond the ones the tips mention: /resume and /clear to manage history, /compact to summarize and free up context, /export to save a transcript, /cost for session spend, /model to switch models, /vim for modal editing, and /init to generate a CLAUDE.md for a fresh project.

How I got this list: Claude reading itself

Here's the fun part. There's no documentation page for the tips, they aren't in a config file you can cat, and they aren't fetched from a server. They're baked into the Claude Code executable — a single 233 MB binary sitting at ~/.local/share/claude/versions/2.1.162 on my machine.

But even compiled binaries are full of readable strings — the literal text of every message a program can print is sitting right there in the file. So the investigation was just a matter of knowing where to look.

First, find where the tips live. Tips fire an analytics event when shown, so I grepped the binary's strings for anything tip-shaped:

strings -n 6 claude-binary | grep -oiE "tengu_[a-z_]*tip[a-z_]*"
# tengu_tip_shown
# tipId
# tipsHistory

That tengu_tip_shown event, with its tipId field, was the thread to pull. Each tip turned out to be a JavaScript object baked into the bundle, shaped like this:

{
  id: "double-esc",
  content: async () => "Double-tap esc to rewind the conversation to a previous point in time",
  cooldownSessions: 3,
  isRelevant: async () => true
}

Find one, find the array. A grep for the content:async signature surfaced all of them, and a small Python parser walked each object to recover its text — including the ones whose content is built dynamically from keybinding helpers and the current terminal type.

The whole thing took about four tool calls. No decompiler, no reverse-engineering, no guessing — just Claude reading the strings table of the program it is. There's something pleasingly recursive about asking an AI assistant to introspect its own source and report back what advice it's been quietly trying to give you.

Why you never see them all

Those two fields on each tip object — isRelevant() and cooldownSessions — explain the whole experience.

isRelevant() is a context check. The IDE-integration tip only fires when you're in an external terminal. The Stripe-plugin nudge only appears when your project actually depends on Stripe. The "Opus Plan Mode" reminder only shows if that's your configured default. Most tips are gated to a situation where they'd genuinely help.
cooldownSessions is a repeat suppressor, typically 3. Once you've seen a tip, it won't come back for at least that many sessions.

So the tip at the bottom of your screen is the result of: of all the tips whose context currently applies, which ones aren't on cooldown — pick one. That's why a fresh project surfaces different advice than a long-running one, and why power users and first-timers see different rotations.

The advice was never hidden, just compiled. If you want to re-extract these after your next update, the recipe is simple: strings the binary at ~/.local/share/claude/versions/ and grep for content:async near cooldownSessions. The tips evolve with each release — but now you know where they live.

Future Me Has Receipts: Building circleback

Tue, 26 May 2026 00:00:00 +0000

🧶 Future Me Has Receipts: Building `circleback`

Here's what a normal week looks like for me:

A Claude Code session debugging an LTI enrollment query at work (Postgres, SQL diffs, 70-message thread)
Another one prepping state-test contractor diffs (Python, xlsx files, waiting on partners to deliver data)
A third one building a Rust CLI for personal use (totally different stack, totally different brain mode)
A fourth one mid-audit, with a half-written message to a coworker that I haven't sent yet
A fifth one I started three weeks ago and forgot existed

These sessions are wildly unrelated. They live in different directories, touch different languages, follow different work streams. None of them know about each other. And they're all long-running — Claude Code holds context across days or weeks, which is amazing until you have a dozen of them and can't remember which is which.

The single hardest thing about working this way isn't building the stuff. It's finding my way back to each of these threads after a few hours away. After a reboot. After a long meeting. After two days on a completely different project. After (sometimes) the laptop dying mid-thought when its battery decides it's done for the afternoon.

So I built a thing. A small thing. Let me show you what it is, and along the way I'll point out some of the Linux/Unix gears that make it tick, because they're cool and you should know them.

🎯 What problem does it actually solve?

Claude Code already lets you claude --resume to jump back into a session. Cool. But:

The session IDs are UUIDs — those 36-character monstrosities like fc8b09ad-e13b-42e7-b04b-fad59f47c97c. Try memorizing five of those at once.
Each session is scoped to its launch directory. You have to cd to exactly the right place before resume works. Not the parent dir. Not a sibling. The exact dir.
The sessions live in ~/.claude/projects//.jsonl, which is great for Claude Code internally but unreadable as a top-down view of "what am I working on."
If you don't write down what you were doing in each thread, future-you has no idea which session is which.

For a while I had a hand-curated markdown file at ~/CIRCLE_BACKS/CIRCLE-BACKS.md where I'd dump notes like:

Resume this session with:
claude --resume fc8b09ad-e13b-42e7-b04b-fad59f47c97c
/home/trashh_panda/code/STRIDE/3_SQL/.../STATE_TEST_PREP
State Test Prep is in wait-and-diff mode...

This was a start, but only sort of. To resume one I had to:

Open the file
Scan with my eyes
Copy the UUID
cd to the right path
Paste the resume command

And — equally important — I had to remember to write the entry in the first place. If I got pulled into something else and didn't park the thread, that whole working context dissolved when I switched away. Same outcome if the laptop powered off before I wrote the note. The capture step depended on me being disciplined, every single time, which is not a thing humans are good at.

🔧 The three new pieces

Here's what I just built, in plain English:

circleback — type that in any terminal, get a fuzzy-search picker over all your saved sessions, hit Enter, and you're back. Hit Ctrl-D to archive ones you're done with.
A "SessionStart" hook — the millisecond a Claude session opens, a stub entry gets written. No more "oh wait, I forgot to log this thread." Every session shows up in the list automatically, and if the laptop dies before I can write a proper closing note, at least the entry is there, with a timestamp, telling future-me where to look.
A "SessionEnd" hook — when the session closes cleanly, the hook reads what was last said and replaces the stub's "(in progress)" placeholder with an actual closing thought.

Three pieces, ~500 lines of bash total, zero new dependencies. Let me walk through the technologies.

✨ fzf: the hero of every good terminal workflow

If you don't know fzf yet, stop reading and sudo pacman -S fzf right now. I'll wait.

fzf is a fuzzy finder. You pipe it a list of strings, it pops up an interactive picker with type-ahead matching:

echo -e "alpha\nbeta\ngamma" | fzf

That's it. Three lines, a beautiful TUI picker. fzf is the most-loved kind of Unix tool: it does one thing, it accepts text on stdin, and it composes with literally anything.

For circleback, I:

Parse the markdown file into one display line per entry
Pipe those lines to fzf with --multi (so I can mark several at once with Tab)
Bind Ctrl-D to "archive marked", Ctrl-E to "open in $EDITOR"
On Enter, the script exec claude --resume s from the entry's directory

That exec is doing real work — it replaces the shell process with claude, so when you exit Claude you're back at your original prompt, no nested shell. The Unix way.

🪝 Hooks: how Claude Code hands off control

Claude Code (the CLI) has a thing called hooks. You can wire little scripts to fire at lifecycle events like SessionStart, SessionEnd, PreCompact, PreToolUse. You configure them in ~/.claude/settings.json:

"hooks": {
  "SessionStart": [
    { "hooks": [{ "type": "command", "command": "$HOME/.claude/hooks/circleback-session-start.sh" }] }
  ],
  "SessionEnd": [
    { "hooks": [{ "type": "command", "command": "$HOME/.claude/hooks/circleback-session-finish.sh" }] }
  ],
  "PreCompact": [
    { "hooks": [{ "type": "command", "command": "$HOME/.claude/hooks/circleback-session-finish.sh" }] }
  ]
}

When the event fires, Claude Code pipes a small JSON payload to your script's standard input:

{"session_id":"70cbfbb4-c59e-40d0-a5c2-85b3764b405b","source":"startup"}

So in my hook, the first line is:

sid=$(jq -r '.session_id // empty')

The // empty is jq-speak for "if the field is missing, give me an empty string instead of null". Defensive coding.

🛠️ awk, sed, jq: the old reliable trio

Big chunks of this codebase are awk pipelines. Why? Because the entries in CIRCLE-BACKS.md are structured text — four lines per entry, blank lines as separators — and awk is built for exactly this.

Here's the heart of the parser (simplified):

/^## .+\/$/ { section = $0; sub(/^## /,"",section); sub(/\/$/,"",section); next }
/^[[:space:]]*$/ {
  if (acc_n == 4 && acc[1] == "Resume this session with:") {
    # Emit a TSV record
    printf "%s\t%s\t%s\t%s\t%d\t%d\n", section, sid, cwd, thought, start, end
  }
  acc_n = 0; next
}
{ if (acc_n == 0) start = NR; acc_n++; acc[acc_n] = $0 }

awk processes one line at a time. When it sees a blank line, it checks whether the four-line accumulator looks like a valid entry and emits a tab-separated record if so. When it sees a section header like ## WORK/, it captures whatever name follows ## — the parser doesn't hardcode any section names, which is what lets you define your own.

The output is one line per entry, fields separated by tabs:

WORKaaaaaaaa-.../paththought36

That's the internal format of the picker. Why TSV? Because tabs basically never appear in your prose, so they make a perfect delimiter that bash can IFS=$'\t' read -r directly.

jq does the same job for JSON — it's the awk of structured data. And sed shows up for surgical text edits, like deleting exactly lines 3-6 from a file:

sed -i "3,6d" file.md

🧪 TDD caught real bugs

I wrote this whole thing test-first. ~110 tests, plain bash, no framework. (I considered bats-core but it would've required sudo, and the surface area is small enough that hand-rolled assertions are fine.)

Two real bugs the tests caught:

Bug 1: `sort -r` quietly doesn't reverse

In my archive function I needed to delete multiple line ranges from the file, processing them bottom-up so earlier deletions don't shift later line numbers. I wrote:

sort -k1,1n -r

Reading that, you'd think: "sort by column 1, numeric, reversed." Nope. The -r flag wasn't being applied because of how it interacts with -k. The correct form is:

sort -k1,1nr

Bake the r into the key spec. The test for "archive multiple ranges" failed loudly and I caught it before shipping.

Bug 2: the missing blank line

When the SessionStart hook inserted the very first BEACH entry into a freshly-skeletoned file, the result looked like this:

## BEACH/
Resume this session with:    ← no blank line between header and entry
claude --resume ...

The awk script was eating the blank line that should have lived between the section header and the first entry. Fixed by always emitting one — regardless of whether the section was previously empty.

The point: TDD is not about ceremony, it's about catching the dumb stuff before your hooks start running on your real workflow at 9am Monday.

🏷️ Friendly names, stable UUIDs

You can rename a Claude session (/rename my-cool-name), and circleback picks that up automatically: the picker shows the friendly name as the row label instead of a UUID like c31187ad-…. It reads the name live from the session log every time you open the picker, so it's always current.

Under the hood, though, the entry in my notes file still stores the UUID, not the name — on purpose:

The UUID is globally unique and never changes: a rock-solid anchor for resuming.
Reading the name live means a re-rename just shows up next launch. Nothing to keep in sync, nothing to drift or corrupt.
Two sessions could end up sharing a name; a collision can never break resume, because the file always holds the unique UUID underneath.

Friendly name on the surface, stable ID underneath.

(Confession: I first convinced myself Claude Code didn't persist session names at all, and built a lesser version around that wrong assumption. It does — the name lands in the session log the instant you /rename. Filed under "a grep that comes up empty is a fact about your search, not about reality.")

🎬 What it looks like in action

$ circleback

[STRIDE] …/STATE_TEST_PREP — wait-and-diff mode, LM xlsx incoming
[STRIDE] ~/code/STRIDE/1_APPS — SBOP-7011 audit re-run done, draft to Ernie
[STRIDE] …/2026-05-12_Tue — arcade-db-query skill round-tripped
[auto][BEACH] /tmp — Goodbye.

Arrow keys to scroll. Right pane shows full preview (session ID, cwd, status, summary, full closing thought). Enter resumes. Tab marks. Ctrl-D archives. Esc quits.

Test it yourself:

# Start a throwaway session
cd /tmp && claude
# Type "say goodbye"
# /exit
# Check the file
cat ~/CIRCLE_BACKS/CIRCLE-BACKS.md
# Run the picker
circleback

The /tmp entry should be there as [auto][BEACH] /tmp — Goodbye. Mark it with Tab, Ctrl-D, type y, and it gets archived to CIRCLE-BACKS-ARCHIVE.md.

📅 The daily rollup

Once every session was getting captured automatically, a second use fell out almost for free: what did I actually do today, across all these unrelated projects?

So circleback now keeps a per-day file — ~/CIRCLE_BACKS/daily/2026-05-27_SUMMARY.md — with two regions that never step on each other:

## Sessions (auto) — one line per session that ran that day, written by the very same SessionEnd/PreCompact hook that fills in closing thoughts. Section tag, directory, closing thought, and the resume command. Zero effort; it's just there by evening.
## Digest — prose, written only when I ask for it. I say "update the daily summary" and a small skill reads the day's session lines (and each session's own STATUS doc) and writes a skimmable, cross-project what-mattered-today. Standup notes, or the seed of an article like this one.

The hook owns the mechanical spine; the skill owns the prose. They share a file but not a region, so neither clobbers the other.

There's also a no-Claude accessor, so I never type the dated path:

circleback daily              # open today's summary in $EDITOR
circleback daily 2026-05-26   # a specific day
circleback daily --list       # which days have summaries
circleback daily --rebuild    # regenerate today's auto spine from the master list

--rebuild is the safety net: the auto region is derived data, so if it ever drifts, you regenerate it from CIRCLE-BACKS.md — without touching your prose digest.

🪧 The nudge that made me write this

Here's the part that closed the loop. I added one more hook — separate from circleback, living in my ~/.claude — on Claude Code's UserPromptSubmit event (it fires on every prompt and can inject context into that turn). After the fourth prompt of a session (so quick lookups are spared), exactly once, it plants a standing instruction: at the next natural stopping point, ask whether this work is worth showing people publicly.

Three answers: draft it now (→ my publish-article skill), park it (→ circle-back), or skip. It's a habit enforced by a turn counter and a marker file, not by willpower. Resume the session later and it won't re-ask — the marker is keyed by session id.

This article is what "draft it now" looks like.

🧠 The meta-point

This whole thing is bash, awk, sed, jq, fzf, and one config-file edit. No new language, no framework, no daemon, nothing to compile. The total install footprint is:

One executable script (~/.local/bin/circleback)
Two hook scripts (~/.claude/hooks/circleback-session-*.sh)
A few helper libraries (lib/parse.sh, lib/config.sh, lib/enrich.sh, lib/archive.sh, lib/daily.sh)
One small config file (~/.config/circleback/config)
One additive edit to ~/.claude/settings.json

That's it. The whole thing is composable, debuggable, scriptable, and small enough to read top-to-bottom in an afternoon.

Linux gives you a stupid number of tiny, sharp tools. The trick is recognizing when you can compose them into something useful instead of reaching for a heavy framework. Every shell pipeline you write is a tiny essay in this style.

I've got a dozen Claude Code threads running across as many projects right now, and for the first time it feels like that's a feature instead of a liability. Future-me has receipts.

📬 Want to try it?

circleback is built to be installed by anyone — config-driven sections, an install.sh that checks your dependencies, walks you through your sections (work / personal / research / whatever, or one flat list), symlinks the binary, and wires the Claude Code hooks into your settings.json (backing it up first, safe to re-run). uninstall.sh reverses all of it and leaves your data alone.

The repo's private for now — the installer touches your ~/.claude/settings.json, so I want it boringly reliable on a few machines that aren't mine before I point the whole internet at it. If you'd like early access to kick the tires, email me at beachtimothyd@gmail.com and I'll add you. It's Linux-first (built on Aegix) and wants bash, fzf, jq, and the claude CLI.

When it goes public I'll update this article with the link.

Built alongside Claude itself, using its superpowers brainstorm → spec → plan → TDD workflow — ~110 passing bash tests at last count. Email me if you want early access. Future me has receipts.

The OSI Model, Explained from a Whiteboard

Sat, 02 May 2026 00:00:00 +0000

Sometimes the best way to lock in a concept is to grab a marker and start scribbling. I sketched out the OSI model recently — seven layers stacked top to bottom, with a few mnemonic hints squeezed into the margins. Here's the walk-through.

What the OSI Model Actually Is

The Open Systems Interconnection model is a conceptual framework that breaks network communication into seven distinct layers. It was published by ISO back in the 1980s, and while the modern internet runs on the looser TCP/IP model, OSI is still the lingua franca for talking about networking. When somebody says "that's a Layer 7 problem" or "Layer 2 broadcast storm," they're speaking OSI.

Each layer has one job. Each layer talks to the layer above and the layer below — and in theory, only those. Data flows down the stack on the sending side, crosses the wire (or air), and flows back up the stack on the receiving side, getting unwrapped at each step.

Layer 7: Application

HTTP, SMTP, DNS, SSH

This is the layer closest to the user. Your browser, your email client, your terminal — they all live here. When you type a URL and hit enter, you're generating an HTTP request that originates at Layer 7.

Worth noting: "Application Layer" doesn't mean "the app itself." It means the protocols apps use to talk to the network. Chrome isn't Layer 7. The HTTP protocol Chrome speaks is.

Layer 6: Presentation

Encryption, compression, character encoding

This is the translator. It takes data from Layer 7 and reformats it for transmission — encrypting it (TLS lives here, conceptually), compressing it, converting between character sets like UTF-8 and ASCII.

In the real-world TCP/IP stack, this layer often gets folded into Layer 7 or handled inline by libraries. But conceptually, it's the "make this data ready to send" step.

Layer 5: Session

Conversation between two nodes — volleyball

The volleyball metaphor is the clearest one I've found. A session is a back-and-forth rally between two endpoints. Layer 5 sets up the volley, keeps it going, and ends it cleanly when the point is over.

Think SSH login sessions, RPC calls, anything where state persists across multiple message exchanges. The session layer opens, maintains, and closes those conversations.

Layer 4: Transport

Segmentation, acknowledgment, multiplexing — reliable

Now we're into the plumbing. Layer 4 is where TCP and UDP live. Its job is to break data into segments, deliver them, and — in TCP's case — make sure they actually arrived.

Segmentation: Break the message into chunks small enough to send.
Acknowledgment: TCP's "did you get that?" handshake.
Multiplexing: Multiple conversations sharing one connection, sorted by port number.

When someone talks about "port 443" or "port 22," that's a Layer 4 concept.

Layer 3: Network

Packet / datagram — routing and addressing

This is IP. Layer 3 is responsible for getting a packet from Network A to Network B, possibly across a dozen routers along the way. It assigns logical addresses (IP addresses) and figures out the path.

If Layer 4 says "deliver this reliably," Layer 3 says "deliver this to that house, in that city, in that country." Routers operate at this layer.

Layer 2: Data Link

Data frames — two nodes physically connected

Layer 2 handles communication between two devices on the same physical network segment. Ethernet and Wi-Fi are Layer 2 protocols. MAC addresses are Layer 2 addresses.

Where Layer 3 worries about routing a packet across the internet, Layer 2 worries about getting a frame across a single hop — your laptop to your router, your router to the cable modem. Switches operate here.

Layer 1: Physical

Let's get physical — raw bitstreams

The wire. The radio wave. The fiber optic pulse. Layer 1 is the actual electrical, optical, or radio signal carrying ones and zeros.

No addressing here, no framing, no protocol logic — just voltage, frequency, and timing. Cables, connectors, hubs, repeaters, and the spec of "what does a 1 look like on this medium?" all live at Layer 1.

Memorizing the Stack

The classic mnemonics:

Top down: All People Seem To Need Data Processing.
Bottom up: Please Do Not Throw Sausage Pizza Away.

Pick whichever sticks. Personally, I find the pizza one harder to forget — and the bottom-up direction matches the way data actually arrives at your machine: photons and voltages first, application semantics last.

Why It Still Matters

Most production debugging is OSI-flavored, even when nobody calls it that. "DNS isn't resolving" is Layer 7. "TLS handshake failing" straddles 6 and 7. "Connection refused" is 4. "No route to host" is 3. "Link is down" is 1 or 2. Knowing which layer to investigate first is half the job.

The OSI model isn't a precise description of how networks actually work — TCP/IP collapses some of these layers and ignores others. It's a thinking tool. A way to decompose a fundamentally messy problem into manageable slices. Once it clicks, you start seeing it everywhere.

From ~/.local/src to the AUR

Fri, 01 May 2026 00:00:00 +0000

If you run Aegix — or you're an Arch / Artix tinkerer who likes the suckless stack — you can now yay -S dwm-aegix-git (or st-aegix-git, dmenu-aegix-git, dwmblocks-aegix-git) and pull down the exact builds I run on my own machine. This post is the short story of how that pipeline got built, and a couple of small gotchas worth knowing if you publish your own.

The problem

I edit my suckless tools the obvious way: in ~/.local/src/{dwm,st,dmenu,dwmblocks}, then sudo make clean install. That's the source of truth on this machine. Two things needed solving:

Reflect those edits into the AEGIX monorepo so the project's submodule pins stay current — without needing me to remember.
Publish them to the AUR so anyone running Arch or Artix can install Aegix's flavor without cloning, patching, and make-ing four repos.

Different problems, same starting point.

Half one: the local sync

The reflection part is a single post-commit hook in each ~/.local/src/ repo. When I commit, the hook fast-forwards the corresponding submodule in ~/code/PROJECTS/AEGIX/ to the new SHA and stages the submodule pointer bump in the parent. That's it.

It does not push anywhere. I tried an earlier design that auto-pushed to GitHub, and it bit me the first time my local was behind the remote — the hook happily force-shoved stale state over newer commits. The lesson:

Live on this machine is truth. The network is a manual gesture.

So now there's exactly one place automation touches: my local filesystem. git push stays in my fingers, where it belongs. The whole sync is ~150 lines of bash with a 28-assert test harness. Boring on purpose.

Half two: the AUR side

The four packages are all -git flavor, which means the PKGBUILD doesn't need editing when I tweak config.h. The pkgver() function auto-resolves against GitHub HEAD on every build:

pkgver() {
  cd "$_pkgname"
  printf "r%s.%s" "$(git rev-list --count HEAD)" "$(git rev-parse --short HEAD)"
}

So my normal flow is now exactly two manual operations:

# 1. Edit + test live
vim ~/.local/src/dwm/config.h
cd ~/.local/src/dwm && sudo make clean install

# 2. Commit (hook reflects to AEGIX automatically)
git commit -am "feat: new keybinding"

# 3. When ready, publish
git push origin master

Next time anyone runs yay -Syu, AUR resolves the new HEAD and they get the rebuild. The PKGBUILD itself only needs touching for real packaging changes (new dep, license fix, build-system tweak).

The flow

  ~/.local/src//          ← edit + build + test
           │
           │ git commit
           ▼
  post-commit hook (local, no network)
           │
           └─► ~/code/PROJECTS/AEGIX//   ← submodule advances
           
           │ git push            ← only manual network action
           ▼
  github.com/aegixlinux/
           │
           │ pkgver() resolves on yay -Syu
           ▼
  AUR users get fresh builds  ✨

Two manual git operations, four published packages.

Two gotchas worth sharing

1. AUR work-trees inside a parent repo. I wanted aur//PKGBUILD to be tracked by the outer monorepo and by the AUR's own remote. Nested .git directories make Git refuse to track the inner files in the outer repo. The fix: hold each AUR package's .git outside its work-tree, in a sibling aur/.aur-git// dir, and run AUR-side git through a tiny wrapper:

#!/usr/bin/env bash
PKG="$1"; shift
export GIT_DIR="$HOME/AEGIX_AGENTIC/aur/.aur-git/$PKG"
export GIT_WORK_TREE="$HOME/AEGIX_AGENTIC/aur/$PKG"
exec git "$@"

Now aur-git dwm-aegix-git push does the right thing without confusing the parent repo.

2. st's tic runs at install time. The stock st Makefile calls tic -sx st.info during make install, which writes to /usr/share/terminfo — fine on a real install, but inside makepkg's fakeroot it tries to write to the real filesystem and fails. The fix is a one-line prepare() step in the PKGBUILD:

prepare() {
  cd "$_pkgname"
  sed -i 's|tic -sx st.info|tic -sx -o "$(DESTDIR)/usr/share/terminfo" st.info|' Makefile
}

Both of these took longer to diagnose than to fix, which is the usual ratio.

Why bother

Honestly? Mostly so I stop accidentally diverging between "the dwm I actually use" and "the dwm I publish." When the publishing is one git push away from the editor, there's no excuse for them to drift. And as a side effect, anyone curious about Aegix's stack can try a piece of it without committing to the whole distro.

If you want to peek: the four packages are on the AUR under dwm-aegix-git, st-aegix-git, dmenu-aegix-git, dwmblocks-aegix-git. The build pipeline lives at github.com/aegixlinux.

Pipeline vs Harness

Wed, 29 Apr 2026 00:00:00 +0000

Two words that sound similar, get used loosely, and actually mean different things. Short version up top, then the nuance.

TL;DR

Pipeline = work moves through stages. The thing being processed flows; the stages are fixed.
Harness = the system stays put; the harness wraps it to run/test/drive it. The wrapper is active, the wrapped thing is acted upon.

A pipeline is a conveyor belt. A harness is a jig (or a horse's harness — same root metaphor).

Pipeline

Colloquial sense

A series of stages where the output of one step is the input of the next. Linear, directional, often automated. Borrowed from oil/water pipelines: stuff goes in one end, comes out the other, transformed along the way.

Technical instances we actually use

CI/CD pipeline — lint → build → test → deploy. GitHub Actions, Jenkins, GitLab CI.
Data pipeline / ETL — extract → transform → load. Airflow, dbt, Dagster.
Unix pipes — cat foo | grep bar | sort | uniq -c. The original.
ML training pipeline — ingest → featurize → train → evaluate → register.
Compiler pipeline — lex → parse → typecheck → optimize → codegen.
Render pipeline — vertex shader → fragment shader → framebuffer.

Defining traits

Directional flow — work moves forward through ordered stages.
Stage isolation — each stage has a clear input contract and output contract.
Transformation-centric — the thing (data, code, artifacts) is what changes.
Often parallel-fan-out / fan-in — but still graph-shaped, not loopy.
Stateless-ish stages — re-runnable, cacheable, idempotent when done well.

When someone says "the pipeline broke," they mean a stage failed and the artifact didn't make it to the next stage.

Harness

Colloquial sense

A thing that wraps around another thing to control it, hold it in place, or drive it. Horse harness, climbing harness, wiring harness. The harness doesn't become the horse — it constrains and directs the horse.

Technical instances we actually use

Test harness — the scaffolding that sets up fixtures, invokes the code under test, captures output, asserts. JUnit, pytest, RSpec. The harness is what makes a function testable in isolation.
Agent / LLM harness — the loop and machinery around a language model: prompt assembly, tool dispatch, context management, retries, hooks. Claude Code is a harness around Claude. The model is the engine; the harness is the chassis.
Hardware test harness — physical bench rig that powers a board, drives its inputs, measures its outputs.
Wiring harness — bundled cables that connect a system together (cars, aircraft).
Fuzzing harness — LLVMFuzzerTestOneInput(...) — a thin wrapper that hands fuzzer-generated bytes to the code being fuzzed.
Benchmark harness — JMH, criterion.rs. Wraps the code, runs it many times under measured conditions.

Defining traits

Wraps a system under operation — the wrapped thing (function, model, board, binary) is the subject; the harness is the apparatus.
Control loop / driver — usually has its own event loop, timing, or invocation logic.
Instrumentation — captures, observes, asserts, measures.
Lifecycle ownership — sets up, tears down, isolates the system under test/run.
Often stateful — maintains context across invocations of the wrapped thing.

When someone says "the harness is flaky," they mean the wrapper itself (setup, teardown, env) is broken — not the code being exercised.

The overlap zone (where people mix them up)

Term you'll hear	Which is it really?
"Test pipeline"	A pipeline of stages (lint → unit → integration → e2e). Each stage may use a test harness.
"Test harness"	The framework that runs an individual test — fixtures, asserts, mocks.
"Inference pipeline"	Data flows: input → preprocess → model → postprocess → output.
"Agent harness"	Loop wrapping an LLM with tools and context. Not a pipeline — has cycles, branching, persistent state.
"Build pipeline"	Stages: compile → link → package → sign → publish.
"Build harness"	Less common; would mean the rig that invokes the build (e.g., a meta-builder driving many sub-builds).

Rule of thumb

If you can draw it as a DAG of stages with artifacts moving left-to-right → pipeline.
If you can draw it as a box wrapping another box, with a control loop and instrumentation → harness.
They compose: a CI pipeline runs a stage that invokes a test harness to exercise the code.

Why the distinction matters for our work

Debugging triage — "the pipeline failed at the test stage" vs "the test harness is hanging" point at very different failure modes. One is an artifact problem (build broken, deps missing), the other is an environmental/wrapper problem (fixture setup, teardown leaking).
Design choices — when building automation, ask: am I moving artifacts through stages (pipeline) or driving a system to observe its behavior (harness)? The shapes are different. Pipelines want orchestrators (Airflow, GHA). Harnesses want runners and drivers (pytest, custom loops).
LLM-era specifically — "agent" work is overwhelmingly harness work. Claude Code, Cursor, the Claude Agent SDK — they are all harnesses around a model. Calling them pipelines obscures that the central thing is a loop with state and tool dispatch, not a feed-forward flow.

One-line mnemonic

A pipeline transforms what flows through it. A harness controls what sits inside it.

How My Blog Got a Voice

Sun, 26 Apr 2026 00:00:00 +0000

Click ▶ read aloud at the top of this article. A British man named Lewis is going to read it to you. He works for me now.

This is a story about how I got there, and about all the wrong turns I took along the way. If you're considering adding text-to-speech to your site, please learn from my mistakes — there are at least four of them.

🎤 The first attempt: Web Speech

The Web Speech API has been built into browsers for over a decade. You hand speechSynthesis.speak() a string, the browser figures out a voice and reads it aloud. No download, no library, no API key. It is the easiest possible way to add TTS to a webpage.

I wired it up in maybe twenty lines. It worked beautifully on macOS. It worked on Windows. It worked on Android. Then I opened my own site in my own browser — Brave, on Aegix Linux — and the voice list came back empty. No audio. No error. Just silence.

It turns out that on Linux, the browser's "speech synthesis" is a thin wrapper around a system service called speech-dispatcher, which in turn shells out to espeak-ng (or Festival, if you're feeling vintage). If you don't have those installed — which most desktop Linux distros don't, by default — your browser knows zero voices, and the API politely returns nothing.

This was annoying for me personally, because I am the entire Linux audience for my own blog, and I was apparently locked out of my own read-aloud feature. But it would have been annoying for any of my visitors on Linux too, and I wasn't about to ship "install these three packages first" as a UX.

🐌 The second attempt: WASM in the browser

Fine, I thought. If the browser's native TTS can't be relied upon, I'll bring my own. Kokoro is a lovely open-source neural TTS model — small (82 million parameters), fast for its size, and there's a JavaScript port that runs entirely in the browser via WebAssembly. No system dependencies. Works in any browser anywhere.

The download is ~80 MB. That's a lot. But it's a one-time hit, cached in IndexedDB. Once you've heard one article, the rest are free. I added a button that said HQ · ~80MB, made the model load with a progress bar, and shipped it.

It was sublime. For about thirty seconds.

The first paragraph rendered fine. The model loaded, made some confident claims about what Lewis sounded like, and started reading. Then, somewhere in the middle of the second paragraph, Brave threw up a dialog that said "This page is not responding." The model was synthesizing the next paragraph in the background — on the same thread the browser uses to fire audio events and repaint the screen — and the synthesis was taking long enough that the watchdog assumed the tab had hung.

I moved the synthesis into a Web Worker. The unresponsive dialog went away. But now there were multi-second gaps between paragraphs, because synthesizing each new paragraph took about as long as the previous paragraph's audio took to play. The "look-ahead" pipeline that was supposed to prepare the next paragraph in advance couldn't get ahead. It was a real-time-factor problem: my laptop is fast, but it isn't that fast, and other people's laptops are often slower than mine.

I sat with this for an evening, and eventually said it out loud: I am asking every reader's CPU to do work that I should be doing once, on my own machine.

📼 The pivot: render once, ship the bytes

The realization is dumb in retrospect. Audio doesn't have to be live. I publish articles by hand, one at a time, on my own laptop. There is exactly one moment per article when I need TTS — at publish time — and exactly one machine that needs to do the work — mine.

So now, when I publish an article, a Python script splits the markdown into paragraphs and feeds each one through Kokoro running locally. The samples get concatenated, encoded as Opus at 64 kbps mono, and saved as audio/.ogg. Alongside it, a tiny audio/.timings.json records the start and end timestamp of every paragraph. Both files get rsynced to the server with the rest of the site.

The browser then does almost nothing. It sees the audio path in the article metadata, attaches a native element, and plays. As currentTime advances, a timeupdate listener finds which paragraph the playhead is in and adds a tts-reading class to its DOM element. That's how the highlighted line glows as Lewis reads it. There are no models, no workers, no WebAssembly. Just a 3 MB Opus file and a 13 KB JSON sidecar.

It works on every browser on every operating system. No 80 MB download. No "page not responding." The highlight is exact, because the timestamps were measured at synthesis time — not estimated client-side.

The whole TTS-related code in the page is about 130 lines. The thing it replaced was almost 700.

🪤 The traps the parsers hid

Two bugs hit me on the way to shipping, and I want to flag them because they're shaped the same way: two different markdown parsers disagreeing about what counts as a paragraph.

The site has a custom JavaScript markdown parser, and the Python render pipeline uses markdown-it-py. They're supposed to produce the same paragraph structure for the same input, because the highlight needs paragraphs[idx] on the server side to refer to the same DOM element on the client side. They didn't always agree.

Trap one. My JS parser maps # Title to

, not
. (I have no idea why past-me thought this was a good idea. Past-me is not available for comment.) `markdown-it-py`, being CommonMark-compliant, maps `#` to
. So the article title was counted as a paragraph on the client and skipped on the server. One element off, every time. The fix was to make the client's TTS selector skip
, mirroring the server skipping
— which works because in this codebase,
is always the article title.

Trap two. When I wrote the dream notes article, I used a verse-style format with one short sentence per line, separated by single newlines. CommonMark treats those lines as one paragraph with soft breaks. My JS parser treats every line as its own paragraph. So Python saw 52 paragraphs and the browser saw 110, the runtime sanity check fired, and the read-aloud button silently refused to open. The fix was to rewrite the article using `\n\n` between every line. Both parsers now agree.

The deeper lesson: when two systems both parse the same input, you eventually find out they parse it differently. I added a `--validate` mode to the render tool that flags timings vs. markdown drift, and a gate in `deploy.sh` that aborts if any article's audio is stale. That catches "I edited an article and forgot to re-render," which is the most common future failure mode. It does not catch parser-disagreement bugs of the kind I just described — for that, you'd need to run both parsers from the same harness and diff their output. I'm leaving that as a future project.

🌟 Why this is actually better

I started out trying to give my Linux readers parity with my macOS readers. What I ended up with is something better than either.

Every reader gets the same voice. Every paragraph highlights at exactly the right moment. The audio loads progressively from a static file, which the browser is excellent at. There's no compute on the reader's device, no model to download, no system service to install. The whole feature degrades gracefully — articles that don't have audio (because I haven't re-rendered them, or because rendering failed) simply don't show the read-aloud button.

And the voice is good. `bm_lewis` is a British-accented neural TTS voice that takes itself seriously. It sounds like the audiobook narrator for a book on, say, Jungian dream interpretation. Which is convenient, because I just wrote one of those.

🐉 What I'd do differently

Less, mostly.

The Web Speech experiment took a few hours. The WASM-in-browser experiment took several days, including an entire branch of work — engine abstractions, look-ahead queues, IndexedDB caching, jsDelivr fallbacks, `_pendingResumeIdx`, `_keepAlive` intervals to work around a Chrome bug — that I deleted in a single commit when I switched to pre-rendering. I built a sophisticated solution to the wrong problem. The correct realization — that I publish articles by hand and could just render them by hand too — was sitting there the whole time.

The hard part wasn't the engineering. It was noticing that a constraint I'd accepted (TTS has to be live in the browser) was self-imposed. Once I let go of it, the implementation got smaller, faster, and more reliable in the same edit.

If you're building something where you find yourself defending a complicated piece of infrastructure on someone else's behalf — every reader's CPU should run inference so that... — try the version where you do that work once, on your own machine, and ship the bytes. You will probably be surprised how often it's enough.

Now press play, and let Lewis take it from here.

Jungian Dream Notes

Thu, 23 Apr 2026 00:00:00 +0000

Dream notes from the night of Earth Day 2026. This one hit different.

The House That Burns Before It Burns

I find myself returned to a life that is no longer mine. I walk within it as though it still holds me. The rooms are familiar, but they do not agree with memory. They are like recollection seen through water, true in essence, false in form.

I knew I had come from a later time, and I had not come without purpose. The house stood whole, but it was already ash. I understood the past is not a fixed place, but a living chamber within the soul, which may be re-entered when inner knowledge ripens or expands.

The Vehicle of Borrowed Motion

I move through the night in a great vehicle, large and serviceable, yet I know it is not truly mine. It carries me forward with the weight of duty, and I accept its offices.

Within myself I heard: This is how I once lived, borne along by structures I did not question, fulfilling roles that preceded me. I saw what we call “our life” is often a vessel inherited, and only later do we ask whether we were its driver or its cargo.

The Gathering of the Dogs

On the dark roadside I find animals waiting. Some I know, and others I do not, yet all come willingly with the turn of my head. They enter the vehicle and lay in quiet trust.

I knew them to be companions of instinct, the faithful movements of the soul that bind themselves to us long before we understand them. I saw what is loyal in us does not ask whether it is recognized, but only whether it is received.

The Transformation into the Living Beast

Then the great vehicle dissolves, and in its place stands a creature of strength and patience, not unlike a yak. I mount it, and it bears me without resistance. I marvel, for I do not command it with force, yet it obeys.

Then I understood that which was once mechanical in me had become alive. For when a man ceases to be carried by structure, he must learn to ride what lives within him, and if he is fortunate, it will not throw him.

The Crossing Between Worlds

I pass from place to place without passage. Familiar roads give way to distant lands, and yet no journey seems to occur.

Then I saw the soul does not travel as the body travels. It moves by association, by memory, by likeness. And thus it binds together what the waking mind keeps apart. What we call distance is only the refusal to see continuity.

The House of Quiet Knowing

I come upon a place of stillness, where an old man tends a shop of subtle things. He speaks little, yet much was conveyed. I linger here, though I cannot say why.

Then I knew this was the place within where knowledge gathers before it becomes speech. The old man was not other than myself, but the part of me that does not hurry, for wisdom does not announce itself loudly, but waits until the noise has passed.

The Knowledge of Fire

Then it is given to me to know: The houses would burn. Not one, but many. And though they stand intact, their destruction is already present, yet I do not panic. Instead, I feel the weight of what must be spoken.

I saw, to know what is coming is not the same as to prevent it, and foresight does not grant dominion, only responsibility.

The Return to the House

I enter the house that was both past and present. Those within it move as though the day were ordinary. And I speak: “Fire is coming. You must prepare.” Some hear me. Others do not. And I repeat myself, calmly, as though repetition might bridge the gap between knowing and not knowing.

Then I understood, truth does not enter all ears equally, and there are moments when one must speak even while knowing one will not be fully believed.

The Children of Uneven Time

Among those present are the young. One receives my words and holds them. Another can not yet grasp them.

And I saw clearly within us are many ages. One part sees. Another part feels. Another part cannot yet know. And no argument will hasten what must ripen and expand. I learned, Patience is owed not only to others, but to the undeveloped regions of one’s own soul.

The Crowd and Their Doubt

I speak again and again. Some begin to act, though uncertainty clings to them. They move as those who half-believe.

And I knew, when when truth is heard, it is often received in fragments. To accept fully what is coming is to surrender the comfort of what is, and few surrender quickly.

The Fire Already Begun

I step outside and behold the street. Flames are already taking hold in the distance. Voices rise. Vehicles gather. The event I have come to warn against is already unfolding.

Then I saw awareness arrives within time, but events do not wait for awareness, and we are often late to what has long been in motion.

The Market of Letting Go

In the yard, people exchange their possessions. They barter lightly, as though the day were still ordinary. And I marvel, for the fire advances even as they trade.

Then I understood we begin to release our lives before we admit they are ending, and what appears as casual exchange is often the first movement of dissolution.

The Relinquishing of Control

Then a knowing comes upon me: It is not mine to save them. It is not mine to compel belief. It is mine only to speak. And having spoken, to depart.

I learned there is a boundary to responsibility. Beyond it lies illusion, the belief that one can govern what belongs to all.

The Return

I withdraw from that place. The path reverses, though no steps are retraced. The living beast gives way again to the vessel, and I find myself returned.

I saw the past may be entered, but not inhabited, and one who lingers too long forgets which time is his own.

The Release of What Was Carried

I return the animals to their place. They do not resist. And I keep nothing for myself.

Then I understood, that which accompanies us for a time is not therefore ours to keep, and care does not require possession.

The Token of Knowing

I am given a small object, a thing of no practical use. Yet I valued it. For it stood as proof, not to others, but to myself, that I had seen truly.

I saw the soul does not trade in evidence, but in symbols. And what it gives is not for display, but for remembrance.

Final Word

And so I came away with this: That a man may come to know what is unfolding, yet he cannot hasten others into that knowing. He may speak truth, but he cannot command its reception. He may see the fire, but he does not own the flame.

And if he is wise, he will do what is his to do, and leave the rest to what is greater than himself.

How to Configure Obsidian the Agentic Way

Tue, 21 Apr 2026 00:00:00 +0000

Step 1: Ask Claude.

Step 2: There is no step 2.

OK fine, here's the long version.

Obsidian, like most modern apps, keeps its settings in a pile of JSON files tucked away inside your vault (.obsidian/). You could go clicking through Settings panels, memorizing the difference between "Editor → Display" and "Editor → Behavior," hunting for the one toggle that turns off that specific thing you hate. Or you could just say what you want out loud.

The other day I got tired of the squiggly red underlines treating every third word as a typo. So I asked:

how do we turn off spell check red underlining in obsidian? if you can find the config and update it directly, go ahead

Claude found .obsidian/app.json, flipped "spellcheck": true to "spellcheck": false, and told me to reload the vault. Total time: maybe six seconds, most of which was me typing the question.

No scavenger hunts through preference panels. No StackExchange threads from 2019 describing menus that no longer exist. No sed incantations with escaped quotes.

You just describe the vibe you want, and a piece of software rearranges the other piece of software to match. The future is weird.

Then teach it to do this forever

One-off wins are nice. But if you're going to do this kind of thing a lot, the next move is to codify the trick into a skill. So I followed up with:

thank you.. that was brilliant.. now let's take this one step further.. spin up subagents to look through .obsidian and one to go online and look at obsidian documentation.. then write a guide for future agents to understand how to interact with obsidian programmatically to change settings via claude code in natural language rather than clicking around in the interface.. if this goes well, also create a skill for this.. go into planning mode first if you need to

Two parallel subagents went digging: one cataloged .obsidian/ file by file, the other scraped help.obsidian.md, the forum, and vetted GitHub examples. They reported back, and Claude shipped ~/.claude/skills/configuring-obsidian/SKILL.md.

The skill now knows the safety rules (close Obsidian first; workspace.json and graph.json are off-limits — Obsidian rewrites them constantly), the file map of which JSON controls what, and the cookbook recipes: toggling booleans in app.json, changing theme and font in appearance.json, enabling or disabling plugins, overriding hotkeys with "Mod" instead of "Ctrl" for portability, and reloading without a restart via the Command Palette.

Next time I — or any future session — asks anything about Obsidian settings, the skill loads automatically and Claude already knows where to look.

So the real loop is:

Ask Claude to do the thing.
Ask Claude to write down how it did the thing.
Never think about the thing again.

Dependency Hell: Why Software Breaks When Everything Works

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

You changed nothing. You tested it yesterday. You watched it pass. And now, on deployment day, everything is on fire.

If you've spent any time building software, you've probably been dragged into a special kind of chaos that the industry has lovingly named dependency hell. It's the place where your code is fine, everyone else's code is fine, but the combination of all of it together is decidedly not fine.

Let's talk about what it is, why it keeps happening, and what — if anything — you can do about it.

🧱 The Analogy

Imagine you're building a house. You need bricks, and each brick requires a specific mortar. Fine — you pick the right mortar. But the mortar requires a specific sand, and the sand is only compatible with a certain type of foundation aggregate. The foundation aggregate was updated last week and now requires a thinner mortar. But your bricks crack with thin mortar.

Nobody changed your blueprint. Nobody touched your bricks. But the house won't stand because three levels deep in your supply chain, someone "improved" their sand.

That's dependency hell. Your software depends on other software, which depends on other software, and somewhere in that chain, something shifted in a way that breaks the thing you're building — even though you didn't change a line of code.

🔥 The Taxonomy of Suffering

Not all dependency hell is the same. It comes in distinct flavors, each with its own special brand of misery.

The Diamond Dependency Problem

This is the classic. Your project depends on Library A and Library B. Both A and B depend on Library C — but they each require a different version of C. You can't install both versions simultaneously, so you're stuck. Your dependency graph forms a diamond shape, and at the bottom of that diamond is a conflict with no clean resolution.

Your Project needs Lib A and Lib B. Lib A needs Lib C version 1. Lib B needs Lib C version 2. You can only install one version of Lib C. Deadlock.

In some ecosystems, this is an unsolvable puzzle. In others, the tooling can deduplicate or isolate — but it's always a source of pain.

Transitive Dependency Sprawl

You install one package. That package pulls in 12 dependencies. Those 12 pull in 80 more. Before you know it, your node_modules directory weighs more than the application itself, and you're relying on code written by hundreds of strangers, any one of whom might push a breaking change, abandon their project, or delete their package entirely.

The real problem isn't the count — it's that you didn't choose any of those transitive dependencies. You don't know what they do. You don't know who maintains them. But your software can't run without them.

Circular Dependencies

Package A depends on B. Package B depends on A. Now nothing can be built first because everything needs the other thing to already exist. It's a chicken-and-egg problem that confuses build systems, package managers, and humans alike.

Circular dependencies are usually a design smell — they signal that two packages should either be merged or restructured — but they crop up in large codebases with organic growth.

System-Level Shared Library Hell

This is where things get truly nasty, especially on Linux.

When you install a program on a Linux system, it typically links against shared libraries — .so files that live in /usr/lib or similar paths. Multiple programs share the same library to save memory and disk space. Beautiful in theory. In practice, it means that upgrading one library can break every program that depends on it.

On Windows, this was historically called DLL Hell — the same fundamental problem with .dll files. On Linux, it manifests when a system update pulls in a new version of libssl, glibc, or some other foundational library, and suddenly half your installed software segfaults or refuses to start.

Package managers like apt and pacman try to manage this with dependency metadata, but they can only protect you from conflicts they know about. If you've installed anything from source, compiled against a specific library version, or mixed repositories — you're on your own.

The ABI (Application Binary Interface) is the invisible contract here. Source code might be "compatible," but if the compiled binary layout changes — struct sizes, function signatures at the machine level — everything breaks silently and catastrophically.

The Vendoring Dilemma

One natural response to shared dependency chaos is vendoring — bundling your own copy of every dependency directly into your project. This gives you total control. Nothing changes unless you change it.

The tradeoff? You're now responsible for updating everything yourself. Security patches don't flow downstream automatically. Your project bloats. And if everyone vendors everything, you end up with twelve different versions of OpenSSL running on the same machine, each with its own set of known vulnerabilities.

Vendoring trades one kind of hell for another. It's a valid choice, but it's not a free lunch.

💀 War Stories

Theory is nice. Let's talk about the times dependency hell actually set things on fire.

"It Worked Yesterday" — A Laravel Deployment Nightmare

I've lived through many of these wars, including this one. We had an application deployment that was tested and verified the day before launch. Everything passed. Every check was green. Ship it tomorrow.

Tomorrow came. The deployment broke.

What happened? Overnight, a transitive dependency in the Composer ecosystem had updated. Laravel's dependency constraints were strict enough to notice the change but not strict enough to prevent it from being pulled in. The package that resolved perfectly at 4 PM was unresolvable by 8 AM because something three levels deep had pushed a new minor version that conflicted with another constraint.

Nothing in our code changed. Nothing in Laravel's code changed. But the dependency graph that Composer had to solve was now different, and the solver couldn't find a valid resolution. Deployment day became debugging day.

This is the insidious nature of dependency hell — it can be time-dependent. The same composer install can produce different results on different days if you aren't locking your dependencies aggressively. And even when you do lock them, the moment you need to update anything, you're re-entering the negotiation.

`left-pad` and the Disappearing Package (npm, 2016)

In March 2016, a developer named Azer Koçulu unpublished a package called left-pad from npm. It was 11 lines of code. It padded strings with spaces on the left side. Trivial functionality.

The problem was that thousands of packages depended on it, including heavy-hitters in the React ecosystem. When it vanished, builds broke worldwide. CI pipelines failed. Production deployments stalled. Thousands of developers scrambled to figure out why their code — which they hadn't touched — suddenly wouldn't build.

left-pad exposed a deeper truth: when an ecosystem incentivizes tiny, single-purpose packages, the web of transitive dependencies becomes so vast that removing any single thread can unravel the whole thing. Your project didn't depend on left-pad. But your project depended on something that depended on something that depended on left-pad. And that was enough.

Python's `pip` and the Resolver That Couldn't

For years, pip didn't have a proper dependency resolver. It installed packages in order, and if two packages needed conflicting versions of a shared dependency, pip would simply install whichever one it encountered last — silently overwriting the other. Your install would "succeed," but your application would crash at runtime because it had the wrong version of something.

In 2020, pip finally shipped a real resolver. The good news: it catches conflicts. The bad news: it catches conflicts. Upgrades that previously "worked" (by silently being broken) now fail loudly with resolution errors. The Python ecosystem is still working through the aftershocks.

Linux Shared Libraries: The `glibc` Trap

On Linux, glibc — the GNU C Library — is the foundation that almost everything is built on. It provides the basic system calls, memory allocation, string handling, and threading that virtually every compiled program relies on.

Upgrading glibc can break programs compiled against an older version. Downgrading it can break your entire system. It's the one dependency where "just update it" and "just don't update it" are both dangerous advice.

Rolling-release distributions like Arch (and its derivatives, including Artix and Aegix) feel this more acutely than point-release distros like Debian. When your entire system updates continuously, the window for ABI-breaking changes is always open. You gain cutting-edge software at the cost of living permanently on the frontier of compatibility.

🤔 Why This Keeps Happening

Dependency hell isn't a bug in any particular tool. It's an emergent property of how software is built.

Semantic Versioning Is a Social Contract, Not a Technical Guarantee

Semver says: bump the major version for breaking changes, the minor version for features, the patch version for fixes. In practice, people get it wrong constantly. A "patch" release introduces a subtle behavior change. A "minor" release deprecates something your code relies on. Semver only works if every maintainer in your entire dependency tree follows it perfectly, and they don't.

Ecosystems Incentivize Small Packages

npm's culture of micro-packages means your dependency tree is wide and shallow — lots of packages, each doing one tiny thing. Python's culture is more "batteries included," leading to fewer but larger dependencies. Neither approach is immune. Wide trees have more points of failure; deep trees have more severe failures when they break.

Nobody Owns the Whole Stack

Your application sits on top of frameworks, which sit on top of libraries, which sit on top of system packages, which sit on top of a kernel. Each layer is maintained by different people with different priorities, release schedules, and opinions about backward compatibility. There's no central authority ensuring that the whole stack works together at any given point in time.

Time Is a Dimension of Your Dependency Graph

The same dependency resolution can produce different results on different days. Packages get published, yanked, deprecated. Registries have outages. Mirrors fall behind. Your build on Monday and your build on Friday might resolve to different dependency trees, even with the same input.

🛠️ Mitigation Strategies

You can't eliminate dependency hell, but you can build bunkers.

Lock Your Dependencies

Every modern package manager has a lockfile: package-lock.json, Cargo.lock, poetry.lock, composer.lock. Commit them. A lockfile records the exact versions that were resolved at a specific point in time. It turns your build from "whatever resolves today" into "exactly what resolved when we last explicitly updated."

If I had to give one piece of advice from this entire article, it would be this: use lockfiles and treat them as first-class artifacts.

Pin Transitives When It Matters

Sometimes the lockfile isn't enough. If you're deploying to production, consider pinning your transitive dependencies explicitly. Tools like pip-compile (Python), npm shrinkwrap (Node), and cargo lock (Rust) give you varying degrees of control over the full dependency tree.

Reproducible Builds and Nix

The most rigorous approach to dependency management is Nix. Nix treats every package — including its exact dependencies, build flags, and compiler version — as a unique, content-addressed entity. Two builds with the same inputs will always produce the same outputs. There is no shared mutable state.

Nix is powerful and philosophically sound. It's also a steep learning curve and a different way of thinking about your system. But if reproducibility is critical to you, nothing else comes close.

Containers: The Blunt Instrument

Docker and its kin solve dependency hell by side-stepping it entirely. Bundle everything — your app, your dependencies, your runtime, your system libraries — into a container image. Ship the whole thing. It works because it literally ships the machine.

The tradeoff is that you're vendoring at the OS level. Every container image carries its own copies of system libraries, and keeping those updated for security is now your problem. You've traded system-level dependency conflicts for image-level maintenance burden.

It works. It's pragmatic. It's not elegant.

Static Linking

Instead of relying on shared libraries at runtime, you can statically link everything at compile time. The resulting binary contains all its dependencies and runs anywhere (on the same OS/architecture) without caring what's installed on the system.

Go does this by default, and it's one of the reasons Go binaries are praised for their deployment simplicity. Rust makes it straightforward with musl targets. C and C++ can do it, but it's more manual and sometimes legally complex (LGPL licensing requires dynamic linking in certain cases).

The cost: larger binaries, no shared security updates across programs, and potential license headaches. But for deployment reliability, it's hard to beat.

🪢 The Fundamental Tension

At its core, dependency hell exists because of an unresolvable tension in software engineering: code reuse and independence are at odds with each other.

Every dependency you take on is a bet that someone else's code will continue to work the way you need it to, for as long as you need it to, without requiring changes on your end. Sometimes that bet pays off for years. Sometimes it blows up overnight.

The industry keeps building better tools — smarter resolvers, content-addressed stores, hermetic builds — and they genuinely help. But the fundamental problem won't go away because it's not a tooling problem. It's a coordination problem among millions of independent developers who don't know each other, don't share priorities, and can't predict the future.

The best you can do is understand the landscape, pick your tradeoffs deliberately, and always — always — check that lockfile.

How to Write a Custom Claude Code Skill

Thu, 19 Mar 2026 00:00:00 +0000

Claude Code can do a lot out of the box, but it doesn't know your workflows. It doesn't know that publishing an article to your website means copying a markdown file to a specific directory, adding an entry to a JSON registry, previewing locally, rsyncing to a VPS, and committing to git. Every time you ask, it has to explore your repo, discover the structure, and figure it out from scratch.

Skills fix this. A skill is a markdown file that teaches Claude a procedure it can follow with the tools it already has. No plugins, no scripts, no MCP servers — just instructions.

Where Skills Live

Claude Code discovers skills from two locations:

Global (personal): ~/.claude/skills//SKILL.md — available in every session
Project-scoped: .claude/skills//SKILL.md — available only in that project

Each skill is a directory containing a SKILL.md file. The directory name becomes the slash command. So ~/.claude/skills/publish-article/SKILL.md gives you /publish-article.

~/.claude/skills/
  publish-article/
    SKILL.md              # Required entrypoint
    template.md           # Optional supporting files

Anatomy of a SKILL.md

A skill file has two parts: YAML frontmatter for discovery, and markdown content for instructions.

Frontmatter

---
name: publish-article
description: Use when publishing a markdown article to timbeach.com, adding content to the personal website, or when the user says "publish article"
---

Two fields:

name — letters, numbers, hyphens only. This is what shows up in the skills list.
description — tells Claude when to use this skill. Start with "Use when..." and describe triggering conditions. Don't summarize what the skill does — just describe when it applies.

The description matters more than you'd think. Claude reads it to decide whether to load your skill for a given task. If the description says "Use when publishing articles" and you say "add this post to my website," Claude connects the dots.

Content

The rest of the file is the procedure Claude follows. Write it like you're explaining the workflow to a competent colleague who's never seen your project before. Be specific about paths, file formats, and the order of operations.

A Real Example: publish-article

Here's a skill I built for publishing markdown articles to my personal website. The site is a vanilla SPA — no build step, no framework. Articles are markdown files in an articles/ directory with metadata in a single articles.json file. Deployment is an rsync to a VPS.

Without this skill, Claude would need to explore the repo every time: read the index.html to understand the rendering pipeline, examine the JSON format, figure out where images go, discover the deploy script. With the skill, it just follows the recipe.

The Full Skill

---
name: publish-article
description: Use when publishing a markdown article to timbeach.com, adding content to the personal website, or when the user says "publish article" or references timbeach.com articles
---

# Publish Article to timbeach.com

Publish a markdown article to timbeach.com from any working directory.
Accepts a file path or inline content.

**Repo:** `~/code/PROJECTS/VULTR_0/sites/timbeach.com`

## Procedure

### 1. Acquire Content

- **File path provided:** Read and validate it has at least one # heading.
- **No file path:** Ask the user for content. Write it to a temp file.

### 2. Handle Images

Scan for ![alt](path) references in the markdown.

For each image found:
1. Resolve path relative to the source file's directory
2. Check if file exists — warn and skip if not
3. Check for name collision in pix/ — ask user: overwrite, rename, or skip
4. Copy image to pix/
5. Rewrite the markdown path to pix/filename.ext

Then ask: "Is there an additional image you'd like to include?"

### 3. Propose Metadata

Infer all fields and present as one block for approval:

  "kebab-case-title.md": {
    "title": "Inferred from first heading",
    "date": "2026-03-18",
    "tags": ["suggested", "from", "content"],
    "emoji": "suggested-emoji"
  }

User approves or tweaks in one shot.

### 4. Write Files

1. Copy markdown (with rewritten image paths) to articles/{filename}.md
2. Update articles/articles.json:
   - Read and parse as JSON
   - Verify filename key doesn't already exist
   - Add new entry
   - Write back with 2-space indentation

### 5. Local Preview

Start python3 -m http.server 8000 from the repo directory.
Tell the user to preview. Wait for approval.

### 6. Deploy

Run ./deploy.sh from the repo root. Report output.
If deploy fails, don't proceed to git commit.

### 7. Git Commit + Push

Stage only the specific changed files. Commit and push.

Why This Works

Notice what the skill does and doesn't do:

It gives Claude facts it can't derive quickly. The repo path, the JSON schema, the image path convention, the deploy script's CWD requirement — these are things Claude would have to discover by reading the codebase. The skill front-loads that knowledge.

It sequences the workflow. Preview before deploy. Deploy before commit. Don't commit if deploy fails. This ordering encodes your actual process, not something Claude would guess.

It specifies interaction points. Propose metadata and wait. Preview and wait. These aren't things Claude would naturally pause for — it would just barrel through. The skill makes the human checkpoints explicit.

It doesn't over-specify. The skill doesn't tell Claude how to read a file or how to run a bash command. It already knows how to do that. The skill only teaches what's specific to your workflow.

Writing Your Own

Pick a workflow you repeat. Something where you find yourself explaining the same sequence of steps to Claude across sessions. That's a skill waiting to be written.

Step 1: Map the procedure

Write out every step you'd take manually. Include the file paths, the exact commands, the order. Don't abstract — be concrete. If you cd to a specific directory before running a script because the script uses $PWD, write that down.

Step 2: Identify what Claude can't infer

Separate the steps into two buckets:

Things Claude could figure out by reading your codebase (how your JSON is structured, what framework you use)
Things Claude can't easily derive (your preferred workflow order, which fields to propose for approval, where to deploy)

Your skill should focus on the second bucket. Include enough of the first bucket to save Claude the exploration time, but don't document your entire codebase.

Step 3: Define the interaction points

Where should Claude pause and ask you? Metadata approval, preview confirmation, deploy authorization — these are places where your judgment matters and Claude shouldn't just proceed.

Step 4: Write the SKILL.md

Put the frontmatter at the top with a good description. Write the procedure as numbered steps. Be specific about paths and commands. Include error handling for things that actually go wrong (port already in use, file already exists, deploy fails).

Step 5: Test it

Start a new Claude Code session. Run /your-skill-name and see if Claude follows the procedure correctly. If it misses a step or makes wrong assumptions, update the skill and restart.

Tips

Keep it under 500 words if you can. The skill gets loaded into Claude's context. Long skills burn tokens. Write what's necessary, skip what's obvious.

Description is for when, not what. "Use when deploying to production after tests pass" is better than "Runs the deploy pipeline with blue-green switching." Claude needs to know when to reach for the skill, not what it does — that's what the content is for.

Hardcode paths. Skills are your personal tools. Don't parameterize things that never change. If your repo is always at ~/code/myproject, write that path directly.

Include error handling for real failures. Port conflicts, existing files, failed deploys — these actually happen. "Parse error in JSON? Warn and stop" is more useful than pretending everything always works.

Global vs. project-scoped. If the skill only makes sense in one repo, put it in .claude/skills/ in that repo. If you'd use it from anywhere (like publishing articles from whatever directory you're working in), put it in ~/.claude/skills/.

Software Delivery and Deployment SOP

Wed, 18 Mar 2026 00:00:00 +0000

Co-authored with Mason U Borchard

A practical standard operating procedure for teams managing branching, releases, SQL changes, and deployments in a corporate software environment.

Philosophy: Every Feature is a "Gift"

Sometimes changing the language can change our perception. Imagine if a feature branch was called a gift. This idea comes from Ernie Gray.

A common challenge in software development is the gravity of the development environment. Engineers spend hours completing code that works locally, submit a PR, check that it works on the dev environment, and then feel the rest of the process is beyond their control.

Escaping the gravity of the development environment into outer orbits requires more energy.

A great team ensures their code is a polished, deployable package — a gift to the team working together toward a great release. These SOPs define what "polished and deployable" looks like.

1. Story/Feature-Level Definition of Done

Quality parts make quality systems. A consistent definition of done at the story level prevents incomplete or undocumented code from entering the pipeline.

A story is not done until all of the following are true:

[ ] Code Review: Pull request is reviewed and approved by a teammate
[ ] Static Analysis: Developer has reviewed the scan and addressed all issues
[ ] SQL Archival: All required SQL is committed to the release folder in the repository and linked in the Release Manifest (see Section 5)
[ ] Ticket Linking: The ticket contains a comment with the direct URL to any SQL files
[ ] Feature Toggle: If the feature is high-risk, a configuration flag is implemented for instant deactivation
[ ] Test Case: A test case is drafted in comments or the test suite, including named test users in the QA environment
[ ] Release Manifest: The story/feature is added to the Release Manifest
[ ] Communication: All decisions and context are documented on the ticket — not in chat threads or verbal conversations

2. Source Control and Branching Strategy

2.1 Multi-Tier Branching Model

Teams should follow a multi-tier branching model to isolate development, testing, and release preparation.

feature/PROJ-XXXX ──► development ──► integration ──► release/REL-XXXX ──► main
       │                  │                │                │                │
  Individual work     DEV env          QA testing      CI/CD builds     Always = PROD
                                       on QA env       & deploys to
                                                       PROD (pristine)

Branch	Purpose	Deploy Target
`feature//PROJ-XXXX-desc`	Individual work	Local / DEV
`development`	Automated builds, early integration testing	DEV
`integration`	Formal QA testing of combined features	QA
`release/REL-XXXX`	Pristine release candidate — only QA-approved code. CI/CD builds and deploys artifacts from this branch.	PROD (+ staging/perf)
`main`	Stable, production-ready code. Source of truth. Always reflects PROD.	—

Important: Production artifacts are only built and deployed from release branches. The development branch deploys to DEV for early testing but is not a source for production artifacts.

2.2 Branch Naming

All branches must include the ticket identifier from your project tracker.

Feature branches: feature//PROJ-XXXX-short-description Release branches: release/REL-XXXX (sequential numbering)

2.3 Creating Branches

All new branches must be created from main.

git checkout main
git pull origin main
git checkout -b feature//PROJ-XXXX-short-description

Why: Creating branches from main ensures that a release branch can be rebuilt easily from the sum of the individual branches included in the release.

2.4 Release Lifecycle

A new release branch is created from main using the release naming convention
Feature branches and bug fixes for that release are merged into the release branch via pull requests
CI/CD builds and deploys artifacts from the release branch
QA testing is performed against the deployed build; fixes go back into the same release branch
Once the release passes QA, the release branch is merged into main
A new release branch is created from main for the next cycle

Creating a new release branch:

git checkout main
git pull origin main
git checkout -b release/REL-XXXX
git push -u origin release/REL-XXXX

Merging a completed release back to main:

git checkout main
git pull origin main
git merge --no-ff release/REL-XXXX
git push origin main

Tip: Use --no-ff (no fast-forward) merges to preserve release branch history in the git log. This makes it easy to trace which commits belonged to which release.

2.5 Branch Ownership

Branch management is owned by the developer. Each developer is responsible for:

Creating branches from main
Keeping branches up to date
Resolving merge conflicts
Cleaning up stale branches after merge

2.6 Do's and Don'ts

Do	Don't
Branch from `main`	Commit directly to `main` — all changes reach `main` through a release branch merge
Follow naming conventions exactly	Build or deploy production artifacts from `development` — it is for integration testing only
Complete the current release merge into `main` before creating the next release branch	Run parallel release branches — only one should be active at a time
Use `--no-ff` merges when merging release branches back to `main`	Force push to `main`
Use pull requests for all merges to shared branches	Merge unapproved features into the release branch

3. Pull Requests

3.1 PRs to Development

Developers can PR to the development branch at will
Merging to development triggers automated build and deploy to the DEV environment
PRs to development do not require approval but are still required (no direct pushes)

3.2 PRs to Integration

When a feature is ready for formal QA, the developer merges it into the integration branch via PR
The integration branch is what the QA team deploys to the QA environment
PRs to integration require review

3.3 PRs to Release

Only features fully signed off by QA in the integration branch are merged into the release branch
The release branch is cut from main and must remain pristine — no rejected or unapproved code
PRs to release branches require review and approval

3.4 General PR Guidelines

PR title should include the ticket identifier
PR description should summarize what changed and why
Link the PR to the relevant ticket

4. The Release Manifest

A wonderful side-effect of the agentic AI trend is context as code in natural language. Scientific processes are good at "breaking things into pieces" at the expense of a holistic context. Version control and project trackers tend to atomize and disarticulate. Context is easy to lose sight of.

The Release Manifest is a living document that provides a collaborative, holistic, human-readable context of the work candidates for a given release. A human (or agent) should be able to understand intent and build your software using this document.

4.1 Lifecycle

At the outset of a sprint (or following a release), a Release Manifest is created and cross-linked with the release ticket
Deferred features from the previous manifest are copied forward
The document is updated incrementally as features emerge from the sprint
At standup, the team briefly reviews the Release Manifest
At release assembly time, all features are either Approved or Deferred, and contents are transposed into the release ticket

Important: Release tickets should not be cloned from the previous deployment. Use a clean template to avoid stale information.

4.2 Manifest Sections

Section	Meaning
Proposed	Code complete and merged to integration branch
Approved	Approved by QA, static analysis reviewed, merged to release branch
Deferred	Not ready yet — wait until next release

4.3 For Each Feature, Include:

A meaningful title with the ticket key (e.g., "PROJ-1144 - Temperature Configuration")
A short context explaining:
- What it is
- How it works
- How it's deployed (including any infrastructure components)
Links to:
- The tracker tickets
- The feature branch
- Associated SQL files

5. SQL Management Protocol

Many organizations formally request all SQL processing via DBA tickets above the development environment. Well-organized SQL etiquette reinforces good habits and gives the acting DBA clear execution paths.

All SQL changes are version-controlled in the repository. The SQL folder serves as the source of truth, organized by release ticket ID.

5.1 Directory Structure

/releases/REL-XXXX/
├── 001_PROJ-101_DDL_CreateUserTable.sql
├── 002_PROJ-101_DML_InsertDefaults.sql
├── 003_PROJ-205_DDL_AddPrefsColumn.sql
├── rollback/
│   ├── 001_PROJ-101_UNDO_DropUserTable.sql
│   ├── 002_PROJ-101_UNDO_DeleteDefaults.sql
│   └── 003_PROJ-205_UNDO_RemovePrefsColumn.sql
└── deferred/
    └── (scripts moved here if feature is rejected by QA)

5.2 Naming Convention

Forward scripts: SequenceNumber_TicketCode_Action_Description.sql Rollback scripts: SequenceNumber_TicketCode_UNDO_Description.sql

5.3 Each SQL Script Must Include

The primary DDL/DML
A verification query (e.g., SELECT count(*)) to confirm success
A corresponding rollback script
Clear comments explaining what the script does

5.4 Ticket Linking

The ticket must contain a comment with the direct URL to the SQL files in the repository.

A feature is not considered complete if scripts only exist in a local environment or the development database.

6. Deployment Strategy

6.1 Developer Ownership

Deployment strategy is owned by the developer. Each developer is responsible for:

Linking their story to the release ticket used for tracking the deployment
Adding their feature to the Release Manifest
Stories are not linked to the release ticket until the release branch is completed

6.2 Release Checklist

Before submitting the release for deployment approval:

[ ] Build Artifact: Specific CI/CD artifact ID is listed (built from the release branch)
[ ] Branch Integrity: The release branch contains only the features listed in the release ticket
[ ] DBA Execution Order: A table lists every SQL script in exact order of execution
[ ] QA Sign-off: Formal statement or checkbox from QA confirming the release candidate is stable
[ ] Pre-Deployment Steps: Documented
[ ] Post-Deployment Steps: Documented
[ ] Static Analysis: Release branch is scanned and results are linked

7. Handling Rejections and Rollbacks

7.1 Rejection Protocol

If a feature fails QA in the integration branch:

Perform a git revert on the merge commit (preserves branch history)
Move corresponding SQL scripts to the /deferred/ subfolder to prevent DBA execution
Update the Release Manifest — move the feature to Deferred

7.2 Rollback Protocol

Every deployment plan must include a "Point of No Return" assessment.

If a failure occurs post-deployment:

Operations redeploys the previous stable artifact ID
DBA executes scripts in the /rollback/ folder in reverse sequence number order

This restores the environment to its exact previous state without guesswork.

8. Responsibilities and Timing

Action	Responsible Party	Timing
Commit SQL + rollback scripts	Developer	During feature development
Update Release Manifest	Developer	As features are completed
Update release ticket	Developer	Upon merge to release candidate
Verify artifact ID and scripts	Lead / Scrum Master	24 hours before submission
Execute deployment and SQL	Operations / DBA	Scheduled release window

Quick Reference

What	Rule
Branch source	Always branch from `main`
Branch naming	Must include project ticket ID
Post-release	Merge release branch back to `main` with `--no-ff`
Branching model	`feature` → `development` → `integration` → `release` → `main`
Parallel releases	No — only one active release branch at a time
Direct commits to main	Never — all changes reach `main` through release branch merge
Production artifacts	Built only from release branches
PRs to development	Required, no approval needed
PRs to integration	Required, reviewed — this is what QA tests
PRs to release	Required, approval needed — only QA-approved code
SQL changes	In repository `/releases/REL-XXXX/` with rollback scripts
Release Manifest	Living document, updated by each developer, reviewed at standup
Release tickets	Fresh template, not cloned — assembled from Release Manifest
Definition of Done	Code review + static analysis + SQL archived + test case + manifest updated
Communication	On the ticket
Branch management	Developer-owned
Deployment strategy	Developer-owned

Claude Code Agent Teams: Put Your AI Coworkers in tmux Panes

Sat, 21 Feb 2026 00:00:00 +0000

You're staring at a feature that touches the API, the frontend, and the test suite. Three separate concerns, three separate contexts, and one of you. You could work through them sequentially — endpoint first, then component, then tests — context-switching each time, holding the whole architecture in your head at once. Or you could do what any reasonable engineering manager would do: delegate. Tell three specialists to work in parallel, coordinate through a shared task list, and synthesize the results when they're done.

Claude Code agent teams let you do exactly that. You spawn multiple Claude instances — each in its own tmux pane, each with its own context window, each working on a discrete piece of the problem. They message each other, share a task board, and report back to you. It's pair programming scaled sideways.

This guide walks you through setup, first launch, architecture, practical patterns, and the safety model. By the end, you'll have a one-word alias that turns a single Claude session into a coordinated team.

Prerequisites

You need three things:

Claude Code installed and working (claude command available in your shell)
tmux installed (tmux -V to check — any recent version works)
Two settings in your Claude configuration file

Add the following to ~/.claude/settings.json (create the file if it doesn't exist):

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "skipDangerousModePermissionPrompt": true
}

If the file already exists with other settings, merge these in. The env block enables the experimental teams feature. The skipDangerousModePermissionPrompt setting suppresses the confirmation dialog that appears each time you launch Claude with --dangerously-skip-permissions — without it, you'd have to click through a warning on every team session start. We'll discuss the safety implications of that flag at the end.

The Alias

The full launch command is verbose. Let's fix that. Add this alias to your shell configuration (e.g., ~/.bashrc, ~/.zshrc, or wherever you keep aliases):

alias teamz="claude --dangerously-skip-permissions --teammate-mode tmux"

Two flags, each doing something specific:

--dangerously-skip-permissions — bypasses all permission prompts. Teammates inherit this, which means they can run commands, edit files, and take actions without asking you first. This is what makes autonomous parallel work possible.
--teammate-mode tmux — tells Claude to spawn each teammate as a separate process in its own tmux pane, rather than running them all in a single process.

Reload your shell config (source ~/.bashrc or open a new terminal), and you're ready.

Quick Start

1. Get into tmux

Teammates spawn as tmux panes, so you need to be inside a tmux session first:

tmux new -s work

Then navigate to your project:

cd ~/code/my-project
teamz

What if you're not in tmux? Claude falls back to in-process mode — all teammates run inside your single terminal. You can cycle through them with Shift+Down and toggle the task list with Ctrl+T. It works, but you lose the visual parallel layout that makes teams powerful.

2. Describe what you want

Once Claude is running, just tell it what you need in plain language:

Create an agent team with 3 teammates:
- backend-dev: implement the REST API endpoints
- frontend-dev: build the React components
- tester: write integration tests for both

Have them coordinate through the task list. Require plan approval before implementation.

Claude — now acting as team lead — will:

Create the team with a config file at ~/.claude/teams/{team-name}/config.json
Create a shared task list at ~/.claude/tasks/{team-name}/
Spawn each teammate in its own tmux pane
Assign initial tasks and begin coordinating

Within seconds, your terminal splits into panes. Each teammate starts working.

3. Watch, navigate, intervene

Standard tmux navigation applies:

Action	Keys
Move between panes	`Ctrl+B`, then arrow keys
Zoom one pane full-screen	`Ctrl+B`, then `z` (toggle)
Resize panes	`Ctrl+B`, then `Alt+arrow`
Click into a pane	Just click (if mouse mode is on)

You can read any teammate's output, and if you click into their pane, you can type messages directly to them. The team lead pane (your original session) is where you issue high-level instructions.

How It Works

Architecture

Team Lead (your main Claude session)
  ├── Teammate 1 (tmux pane) ──┐
  ├── Teammate 2 (tmux pane) ──┼── Shared Task List (~/.claude/tasks/)
  └── Teammate 3 (tmux pane) ──┘
              ↕ messaging ↕

Four moving parts:

Team lead — your original Claude session. It creates the team, defines tasks, spawns teammates, and synthesizes results. This is the only session you interact with directly (unless you click into a teammate's pane).
Teammates — independent Claude processes, each with its own context window. They don't share memory with the lead or with each other — they communicate through messages and the task list.
Task list — JSON files on disk at ~/.claude/tasks/{team-name}/. Every agent can read and write to it. Tasks have statuses (pending, in_progress, completed), owners, dependencies, and descriptions. This is the coordination backbone.
Messaging — agents send direct messages to each other by name. No polling, no shared state beyond the task list. The lead gets notified when teammates finish tasks or need help.

What teammates inherit (and what they don't)

Each teammate automatically receives:

Your project's CLAUDE.md instructions
Configured MCP servers
Available skills and plugins
The spawn prompt from the lead (their specific assignment)

What they do not get: the lead's conversation history. If context matters for a task, the lead needs to include it in the spawn prompt or in a message. This is by design — it keeps each teammate's context window focused on their specific job rather than polluted with unrelated conversation.

Common Patterns

Parallel feature development

The most natural use case. You have a feature that spans multiple concerns:

Build the notification system:
- API teammate: design the notification service and REST endpoints
- UI teammate: build the notification bell component and dropdown
- DB teammate: create the migration and notification model

Have them agree on the notification schema before implementing.

The key phrase is "agree on the schema before implementing." Teammates can message each other directly — the lead doesn't have to relay everything. The DB teammate can share the schema with the API and UI teammates, and they can coordinate without you in the loop.

Parallel debugging

Four eyes are better than two. Twenty are better still:

Users report the app crashes on login. Spawn 4 teammates to investigate:
- One checks the auth middleware
- One examines recent database migrations
- One reviews the session handling code
- One searches error logs and stack traces

Have them share findings and narrow down the root cause together.

Each investigator works a different angle simultaneously. When one finds something relevant, they message the others. The lead synthesizes the findings into a diagnosis.

Multi-angle code review

A single reviewer catches bugs. Multiple reviewers with different mandates catch categories of bugs:

Review PR #42 from three angles:
- Security reviewer: check for injection, auth bypass, data exposure
- Performance reviewer: check for N+1 queries, unnecessary re-renders, missing indexes
- Test reviewer: verify coverage, edge cases, and assertion quality

Synthesize their findings into a single review.

Research and design exploration

Not all teamwork is about code. Sometimes you need perspectives:

I'm designing a CLI tool for managing environment variables across projects.
Create a team to explore this:
- UX researcher: how do developers actually manage env vars today? What's painful?
- Architect: propose the data model, storage format, and CLI interface
- Devil's advocate: find the edge cases, challenge assumptions, identify where this breaks

Controlling the Team

Message a specific teammate

Message the backend-dev teammate: "Prioritize the auth endpoints — the frontend needs them first."

Assign or reassign tasks

Assign the caching task to the backend-dev teammate.

Tasks can also have dependencies — "don't start the integration tests until the API endpoints are done" — which the lead manages through the task list.

Require plan approval

For high-stakes work, you can put teammates in plan mode. They research and propose a plan, then wait for your explicit approval before writing any code:

Spawn an architect teammate to refactor the auth module. Require plan approval before any changes.

The teammate will explore the codebase, write up a plan, and send it to you. You review it, approve or reject with feedback, and only then do they start implementing. This gives you architectural control without micromanaging the implementation.

Shut down teammates

When work is done:

Ask the tester teammate to shut down.

Or wind down everything:

Shut down the team and clean up.

This removes the team config and task list files. The tmux panes close.

Choose models for teammates

Not every task needs the most capable (and expensive) model. You can specify:

Create a team with 3 teammates using Sonnet for cost efficiency.

Use Opus for complex architectural work, Sonnet for straightforward implementation, Haiku for simple lookups and formatting. The lead can mix models across teammates.

Tips and Troubleshooting

Getting the granularity right

Task size is the single biggest factor in team effectiveness. Too small and you drown in coordination overhead — agents spend more time messaging than working. Too large and teammates go dark for long stretches, potentially duplicating effort or heading in the wrong direction.

The sweet spot: self-contained units of work. A module. A test file. An API endpoint with its route, controller, and validation. Aim for roughly 5–6 tasks per teammate per session. Each task should be something a teammate can complete without needing to ask three clarifying questions.

Token economics

Each teammate gets its own context window. Three teammates means roughly 3x the token usage of a single session — there's no sharing or deduplication of context across agents. Factor this into your planning, especially for long sessions.

Things to know

Teammates can DM each other. The lead sees a summary of peer messages but doesn't have to relay everything.
One team per session. You can't nest teams or have a teammate lead its own sub-team.
Sessions don't resume teammates. If you use /resume or /rewind, in-process teammates won't be restored. The team lead session resumes, but you'd need to re-spawn teammates.
Orphaned tmux sessions happen if something crashes. Clean up with tmux ls and tmux kill-session -t .

Common issues

Problem	Solution
No tmux panes appearing	You probably ran `teamz` outside a tmux session. Start tmux first.
Teammate seems stuck	Message them directly — sometimes they need a nudge or clarification.
Panes too small to read	`Ctrl+B, z` zooms a single pane full-screen. Toggle it again to return.
Want to kill a specific pane	`Ctrl+B`, then `x` confirms killing the active pane.

In-process fallback keys

If you're not using tmux, teammates run in-process. Navigation:

Key	Action
`Shift+Down`	Cycle through teammates
`Escape`	Interrupt current teammate's turn
`Ctrl+T`	Toggle task list view

A Note on Safety

The --dangerously-skip-permissions flag means what it says. Every agent in the team — lead and teammates alike — can execute arbitrary shell commands, edit any file in the project, and make destructive changes without asking permission. There is no confirmation step, no sandbox, no undo beyond what git provides.

This is the tradeoff that makes autonomous parallel work possible. If every teammate had to ask before running npm test or editing a file, the coordination overhead would make teams impractical.

Mitigate the risk:

Work in git-tracked directories with clean commit history. If a teammate breaks something, git diff shows what changed and git checkout reverts it.
Don't run teams in directories with sensitive files (credentials, production configs, private keys) unless you trust the prompts you're giving.
Start small. Try a two-agent team on a low-stakes task before orchestrating six agents on your production codebase.

For finer-grained control without the nuclear option, configure permissions in ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git commit *)",
      "Read",
      "Edit(src/**)"
    ],
    "deny": [
      "Bash(git push *)",
      "Bash(rm -rf *)"
    ]
  }
}

This lets you allow specific operations (running tests, committing, reading files, editing source) while blocking dangerous ones (force pushes, recursive deletes). It's more work to configure, but it lets you use teams without the global permission bypass.

File Reference

What	Location
Team configuration	`~/.claude/teams/{team-name}/config.json`
Shared task list	`~/.claude/tasks/{team-name}/`
Claude settings	`~/.claude/settings.json`

One alias, one tmux session, one sentence describing what you want built. The agents handle the rest — splitting work, coordinating, reporting back. It won't replace thinking about architecture, but it will replace the tedium of context-switching between three files that all need to change at once.

True Random Number Generators: From Quantum Physics to Silicon

Fri, 20 Feb 2026 00:00:00 +0000

How do you get a genuinely unpredictable bit? Not a bit that looks random, not a bit computed from a seed, but a bit that did not exist in the universe until the moment you measured it. This article traces the answer from the foundations of quantum mechanics through circuit design, post-processing, standards, attacks, and the open philosophical questions that remain.

Why Randomness Matters

Cryptography, simulation, lotteries, statistical sampling, and security protocols all depend on unpredictable numbers. If an adversary can predict your random numbers, they can predict your encryption keys, forge your signatures, and break your protocols. The entire security of modern digital infrastructure rests on the assumption that certain numbers are genuinely unknowable in advance.

A pseudorandom number generator (PRNG) produces numbers that look random but are entirely determined by an initial seed. Know the seed, know the sequence. A true random number generator (TRNG) produces numbers from a physical process where the outcome is not determined by any prior state of the universe. The distinction is not academic — it is the difference between security that holds against any adversary and security that holds only against adversaries who lack a specific piece of information.

What Is "True" Randomness?

The Quantum Foundation

Classical physics is deterministic. Given the position and velocity of every particle, Newton's laws determine the entire future. In this framework, "randomness" is just a word for ignorance — we call a coin flip random because we can't track the air molecules, not because the outcome is undetermined.

Quantum mechanics broke this picture. In 1926, Max Born proposed that the wave function describes not a trajectory but a probability amplitude. The probability of finding a particle in a particular state is the squared magnitude of its wave function: P(x) = |ψ(x)|². This is not a statement about incomplete knowledge. Before measurement, a quantum system does not have a definite value for the measured property — it exists in a superposition of possibilities. The measurement outcome is intrinsically probabilistic. No hidden information, no deeper theory, no additional computation can predict it.

The Heisenberg Uncertainty Principle

Heisenberg's principle formalizes this. A particle cannot simultaneously have a precise position and a precise momentum: Δx · Δp ≥ ℏ/2. This is not an instrument limitation — the universe itself does not contain that information. In electronic circuits, this means electrons at finite temperature exhibit random fluctuations that cannot be eliminated even in principle.

Bell's Theorem: The Nail in the Coffin of Hidden Variables

The strongest argument for genuine randomness comes from John Bell's 1964 theorem.

The challenge (Einstein, 1935): Maybe quantum particles carry predetermined values we can't see — "hidden variables" — and the apparent randomness is just our ignorance.

Bell's answer: He derived a mathematical inequality that any hidden variable theory must satisfy. Quantum mechanics predicts correlations that violate this inequality.

The experiments: Starting with Alain Aspect (1982) and culminating in loophole-free Bell tests (Hensen et al. 2015, Giustina et al. 2015, Shalm et al. 2015), experiments consistently confirm quantum mechanics and violate Bell's inequality.

What this means: The randomness in quantum measurements is not due to hidden variables we've failed to discover. When a photon hits a beam splitter and is either reflected or transmitted, that outcome is genuinely undetermined before it occurs. This is the deepest foundation for TRNGs.

Quantum Indeterminacy vs Classical Chaos

Classical Chaos is deterministic but sensitive to initial conditions. It is unpredictable in practice — think weather, turbulence, dice. With perfect information, it would be perfectly predictable.

Quantum Indeterminacy is fundamentally probabilistic. It is unpredictable in principle — think photon beam splitters, radioactive decay. Even with perfect information, the outcome remains unpredictable.

TRNGs based on quantum phenomena tap into fundamental indeterminacy. Sources like atmospheric noise or lava lamp convection rely on classical chaos amplifying quantum-level noise — practically unpredictable, but not provably so in the same rigorous sense.

Physical Entropy Sources

Ordered from most rigorously quantum-random to most dependent on classical chaos.

Photon Beam Splitter QRNGs

The conceptually simplest TRNG: a single photon hits a 50/50 beam splitter. Quantum mechanics dictates exactly 50% probability of reflection vs transmission, and no property of the photon before the beam splitter determines which path it takes.

One photon in, one genuinely random bit out. Bell's theorem guarantees no hidden variable determines the outcome. Modern implementations achieve Mbit/s to Gbit/s rates. ID Quantique (Geneva) pioneered commercial devices using this architecture.

Vacuum Fluctuation QRNGs

Even in a perfect vacuum, electromagnetic fields fluctuate — vacuum fluctuations are a direct consequence of the Heisenberg uncertainty principle applied to the EM field. A homodyne detection scheme combines a laser with a vacuum input on a beam splitter, and the difference signal between two photodetectors is dominated by quantum vacuum noise.

No classical analog exists — this noise is purely quantum. The Australian National University (ANU) operates a public vacuum QRNG at qrng.anu.edu.au achieving 5.7 Gbit/s. It can be sampled at high frequencies since homodyne detection is continuous.

Radioactive Decay

A radioactive atom has a probability of decaying per unit time, but the exact moment is completely unpredictable. The nucleus exists in a superposition of "decayed" and "not decayed" states — the transition is genuinely stochastic.

Why it's the philosophical gold standard: No hidden variables (Bell's theorem applies). It is immune to environmental conditions — temperature, pressure, EM fields don't affect nuclear decay rates. Each decay is independent (Poisson process). John Walker's HotBits project (1996) used Cesium-137 plus a Geiger counter.

Practical limitations: Regulatory issues, low bit rates, source activity decreases over time, not suitable for consumer electronics.

Avalanche Noise (Zener Diodes)

When a p-n junction diode is reverse-biased near its breakdown voltage, two quantum phenomena generate noise. Zener breakdown (below 5V) involves electrons quantum-tunneling through the depletion region, where individual tunneling events are quantum mechanically random. Avalanche breakdown (above 5V) involves accelerated carriers ionizing lattice atoms, creating cascading secondary carriers where the multiplication factor per carrier is stochastic — quantum scattering processes determine when and where impact ionization occurs.

The noise can be millivolts to volts — much larger than thermal noise — making these circuits practical and popular. Diodes in the 5-7V breakdown range are preferred because they operate primarily via avalanche multiplication.

Design note: Why avalanche over thermal noise? The signal is 1000x larger, requiring far less amplification and reducing the risk that amplifier noise dominates the entropy source.

Shot Noise

Walter Schottky described shot noise in 1918. When current flows across a potential barrier (p-n junction, tunnel junction), it's not a smooth flow — it's discrete electrons crossing at random, independent times. The power spectral density is S_I = 2qI where q is the electron charge and I is DC current. This gives white noise (flat across all frequencies). Each electron's barrier crossing is governed by quantum tunneling probabilities — fundamentally stochastic.

Thermal Noise (Johnson-Nyquist)

Every resistor above absolute zero generates random voltage fluctuations from the thermal motion of charge carriers. At room temperature across a 10kΩ resistor with 10kHz bandwidth, this amounts to about 1.3 μV RMS. Tiny, but measurable.

The quantum connection: At the deepest level, the thermal motion is governed by quantum statistical mechanics (Fermi-Dirac distribution). At very high frequencies or very low temperatures, the classical formula breaks down and Planck's quantum noise formula takes over.

Engineering reality: You need 60-80 dB of amplification to work with these signals, and your amplifier's own noise floor must be well below the signal level — a significant design challenge.

Ring Oscillator Jitter and Metastable Flip-Flops

A ring oscillator (an odd number of inverters in a loop) has propagation delays that fluctuate due to thermal noise, shot noise, and flicker noise in the transistors. This jitter accumulates over time, making the oscillator's phase drift in a random walk.

Why this matters enormously: Ring oscillator TRNGs require no special components — only standard digital logic gates. They work in any CMOS process, including FPGAs and ASICs. This is why they dominate in system-on-chip designs.

Metastable flip-flops: A flip-flop driven into metastability (input arrives exactly at the clock edge) must resolve to 0 or 1, with thermal noise determining which. Intel's RDRAND uses this principle — pairs of cross-coupled inverters are periodically forced to their metastable point.

Design note: Why ring oscillators for on-chip TRNGs? No analog components, no special fabrication steps, portable across process nodes. The tradeoff: susceptibility to electromagnetic injection locking (an external signal can lock the oscillators, destroying randomness).

Atmospheric Noise and Lava Lamps

About 2,000 thunderstorms are active at any moment, producing roughly 50 lightning flashes per second. A radio receiver tuned to an unused frequency picks up a chaotic superposition of these emissions. random.org has served over a billion random bits per day using this approach since 1998.

Cloudflare's LavaRand: A wall of about 100 lava lamps filmed by a camera. The Rayleigh-Bénard convection creates complex, never-repeating patterns driven by chaotic fluid dynamics with thermal noise at boundaries. Pixel data is hashed to extract entropy. Other Cloudflare offices use chaotic pendulum mobiles (London) and radioactive decay (Singapore).

Design note: Why lava lamps? Defense in depth. Even if an attacker could solve the intractable fluid dynamics, the entropy is mixed with other sources. The lava lamps are one layer, not the only layer.

From Analog Noise to Digital Bits

The Amplification Problem

The central engineering challenge: raw entropy signals are typically microvolts in amplitude, while the noise floor of the measurement circuitry can be comparable or larger. If your entropy source produces 10 μV of genuine random noise but your amplifier's input noise is 15 μV, you're measuring the amplifier, not the entropy source.

A typical signal chain: First, a low-noise preamplifier — JFET-input op-amps with roughly 1 nV/√Hz input noise and 40-60 dB gain. Second, a bandpass filter — high-pass (1-10 kHz) removes DC drift and 1/f noise while low-pass (100 kHz to several MHz) limits bandwidth to Nyquist frequency and attenuates interference. Third, a second amplification stage bringing total gain to 60-80 dB. Finally, an anti-aliasing filter — a steep low-pass immediately before digitization.

AC coupling between stages (via capacitors) is essential — without it, DC offset accumulates through the high-gain chain and saturates the amplifiers at the supply rails, producing a very deterministic output.

Digitization

Comparator-based (1-bit): Amplified noise compared against a threshold. Above = 1, below = 0. Simple but the sampling rate must be much lower than the noise bandwidth to ensure independence between samples.

ADC-based (multi-bit): An ADC captures multiple bits per sample, but only the least significant bits carry genuine entropy (MSBs carry the deterministic signal shape). An 8-bit ADC might yield 2-4 bits of entropy per sample.

Design note: Why comparators over ADCs in many designs? Simplicity, low power, easy on-chip integration. The throughput penalty is accepted because conditioning and CSPRNG expansion provide the needed volume.

Sampling Rate

This is critical. If the noise bandwidth is B Hz, the autocorrelation time is roughly 1/(2B). Sampling faster than this produces correlated (non-independent) bits. Practical designs sample at B/5 to B/10 for good independence, accepting the throughput cost.

Conditioning Raw Entropy

Why Raw Bits Aren't Uniform

No physical entropy source produces perfectly uniform, independent bits. The raw output suffers from bias — comparator offset, amplifier asymmetry, or DC leakage means P(1) ≠ 0.5. Even 1 mV of comparator offset against 100 mV noise RMS gives P(1) ≈ 0.496. It also suffers from autocorrelation — sampling too fast relative to noise bandwidth means successive bits are correlated. Non-stationarity means temperature, voltage, and aging shift the statistical properties over time. And deterministic components — clock signals, power supply switching noise, and nearby digital circuits — inject periodic patterns.

A raw TRNG bit might carry only 0.7-0.99 bits of min-entropy rather than the ideal 1.0 bit. Conditioning transforms a stream with imperfect entropy density into a shorter stream with full entropy density.

Von Neumann Debiasing (1951)

Examine raw bits in pairs: (0, 1) outputs 0. (1, 0) outputs 1. (0, 0) or (1, 1) are discarded.

Why it works: If each bit independently has probability p of being 1, then P(0,1) = (1-p)·p = P(1,0). Equal regardless of p. The matched pairs are discarded because their probabilities do depend on p.

The cost: At best, 75% of input bits are wasted (only 25% of pairs are usable). With heavy bias (p=0.9), efficiency drops to about 9%. Output rate is variable, complicating downstream clocking.

Limitation: Assumes independence. If successive bits are correlated (which they are in practice), bias leaks through.

XOR Folding

XOR N consecutive bits to produce one output bit. For bias p, XOR of two bits has P(1) = 2p(1-p) — closer to 0.5. XORing more bits reduces bias exponentially. Simple but doesn't handle autocorrelation, and throughput drops N:1.

Cryptographic Conditioning

Modern TRNG designs use cryptographic hash functions as entropy condensers. This is what NIST SP 800-90B mandates.

Von Neumann uses pair comparison, gives at most 25% throughput, and removes first-order bias only. XOR folding uses N-to-1 XOR, gives 1/N throughput, and reduces bias but doesn't fix correlation. LFSR uses a linear hash over GF(2), gives roughly 100% throughput, but is not cryptographic and is vulnerable to algebraic attacks. SHA-256 hashes 512 raw bits down to 256 output bits, giving roughly 50% throughput with full entropy if min-entropy rate exceeds 0.5. AES-CBC-MAC uses block cipher conditioning, gives variable throughput, and produces 128-bit conditioned output per block. HMAC-DRBG uses HMAC in a feedback construction, gives variable throughput, and is NIST SP 800-90A compliant.

Design note: Why hash-based conditioning over von Neumann? The hash function's avalanche property destroys any bias or correlation in the input. It provides a fixed output rate regardless of input statistics, and has a security proof under standard cryptographic assumptions.

Health Monitoring

Why It's Critical

A TRNG is a physical device, and physical devices fail. When a TRNG fails, it may produce deterministic or predictable output — a catastrophic security failure invisible to software unless actively detected.

Failure modes include diode aging, amplifier rail saturation (stuck at all 0s or all 1s), EM frequency injection into ring oscillators, temperature extremes reducing thermal noise, and manufacturing defects producing biased output.

NIST SP 800-90B Mandatory Tests

Repetition Count Test: Counts consecutive identical outputs. If the count exceeds a threshold C, declare failure. For 0.85 bits/sample min-entropy, C = 25 consecutive identical samples triggers the alarm.

Adaptive Proportion Test: Within a window of 1024 samples (binary), counts how many match the first sample. If the count exceeds a threshold, declare failure. This catches bias shifts the repetition test would miss.

Startup vs Continuous

Startup tests run before any output is provided — collect and test a large initial sample (for example, 4096 samples). No output until tests pass. Continuous tests run on every sample during operation and must be lightweight (a counter and a comparison per sample).

When Tests Fail

The options range from most to least conservative: suppress output immediately, alarm and retry (wait, re-run startup tests), fall back to stored entropy on a time-limited basis, or degrade gracefully with notification — continue from a previously-seeded CSPRNG but flag that live entropy is unavailable (this is Linux's approach).

Intel's RDRAND sets the carry flag (CF) to indicate success. CF=0 means the DRNG failed health tests — software must check this.

Statistical Test Suites

Used during design validation and certification, not online. NIST SP 800-22 runs 15 tests (monobit, runs, FFT, matrix rank, etc.) on 1M-bit sequences. Diehard (Marsaglia, 1995) offers 18 tests including birthday spacings, parking lot, and squeeze. TestU01 (L'Ecuyer) is the gold standard — SmallCrush (10 tests), Crush (96), BigCrush (160). NIST SP 800-90B entropy estimation uses 10 different min-entropy estimators; the final assessment is the minimum across all (conservative bound).

Real-World Implementations

Intel RDRAND/RDSEED (Ivy Bridge, 2012+)

A three-stage pipeline. First, the entropy source: pairs of cross-coupled inverters forced to metastability, where thermal noise determines resolution. Raw output is roughly 3 Gbps with about 0.5 bits min-entropy per raw bit, including continuous health testing. Second, the conditioner: AES-CBC-MAC compresses roughly 512 raw bits into a 256-bit seed with full entropy. Third, the CSPRNG: AES-CTR-DRBG (SP 800-90A compliant) generates up to 512 values per seed.

RDRAND returns CSPRNG output (roughly 500 MB/s). RDSEED returns conditioned entropy directly (slower, can fail if entropy is consumed faster than generated).

Linux /dev/random and /dev/urandom

Historical architecture (pre-5.17): An entropy pool accumulated entropy from interrupt timing, input devices, disk I/O, and RDRAND. SHA-1 mixing. /dev/random blocked when the entropy estimate hit zero; /dev/urandom never blocked.

Modern architecture (5.17+, Jason Donenfeld's overhaul): ChaCha20-based CSPRNG replaced the entropy pool. /dev/random and /dev/urandom are now functionally identical after initial seeding. blake2s is used for input mixing. Jitter entropy serves as backup. RDRAND/RDSEED are XORed in (never trusted alone). The getrandom() syscall is the preferred interface — blocks only until initial seeding, then never.

Design note: Why unify /dev/random and /dev/urandom? The blocking was based on a misconception that a CSPRNG "uses up" entropy. Once seeded with 256 bits, ChaCha20's output is computationally indistinguishable from random. Blocking caused real-world harm (GnuPG stalling, users installing dubious entropy daemons) with zero security benefit.

Hardware Security Modules (HSMs)

The highest-assurance implementations. Dedicated analog noise sources (thermal or shot noise) in tamper-responsive enclosures. If physical tampering is detected, all keys and entropy are zeroized. FIPS 140-3 Level 3/4 certified. Vendors include Thales Luna, Entrust nShield, and Utimaco.

Quantum RNG Chips

ID Quantique Quantis: Photon beam-splitter architecture, 4-16 Mbps (chip), up to 240 Mbps (PCIe). Available as chip-scale modules for smartphones and IoT. Quside (Spain): Phase-diffusion QRNG, over 100 Gbps demonstrated in research.

Cloudflare LavaRand

Camera feeds a lava lamp wall, pixel data seeds the CSPRNG. One entropy source among several. London office uses chaotic pendulum mobiles. Singapore uses radioactive decay. Defense in depth.

The Hybrid Architecture: TRNG + CSPRNG

Why This Dominates

Virtually every modern system uses the same pattern:

TRNG (slow, genuine entropy)
    ↓ seed (128-512 bits)
CSPRNG (fast, computationally indistinguishable from random)
    ↓ output (GB/s)
    ↑ periodic reseed from TRNG

Throughput: CSPRNG runs at CPU speed (AES-NI: over 10 GB/s). No physical entropy source matches this. Unpredictability: TRNG seeding means even state compromise is temporary — the next reseed restores security. Resilience: If the TRNG temporarily fails, the CSPRNG continues securely from its current state.

Entropy Pools and Fortuna

An entropy pool accumulates entropy from multiple sources via a cryptographic mixing function.

Fortuna (Schneier and Ferguson) uses 32 separate pools. Each entropy source distributes input round-robin. Pool P0 is used at every reseed, P1 every 2nd, P2 every 4th, and so on. This guarantees recovery from state compromise within 2^31 reseeds, even if an attacker monitors some sources. Fortuna is used in FreeBSD and influenced Windows' CryptGenRandom.

The PRNG-to-TRNG Spectrum

At the weakest end sits a deterministic PRNG like Mersenne Twister — predictable with state knowledge and the fastest option. Next is a CSPRNG like AES-CTR or ChaCha20 — computationally hard to predict and very fast. Then a hybrid (TRNG+CSPRNG) like Linux RNG or Intel RDRAND — non-deterministic seed plus computational speed. Above that, a TRNG with conditioning (PTG.2 device) where every bit depends on fresh entropy at moderate speed. Then a raw TRNG (PTG.3 device) with information-theoretic security but slow. At the very top, a device-independent QRNG using Bell-test certification — provably unpredictable but very slow.

Standards and Certification

NIST SP 800-90 Series (US)

90A specifies DRBGs — Hash_DRBG, HMAC_DRBG, CTR_DRBG. (Dual_EC_DRBG was removed after the NSA backdoor scandal.) 90B covers entropy sources — min-entropy estimation (10 different estimators, take the minimum), mandatory health tests, IID vs non-IID tracks. 90C (draft) describes how to combine 90A + 90B into a complete random bit generator.

AIS 31 (German BSI)

A fundamentally different philosophy from NIST. NIST SP 800-90B is empirical and statistical — "show me the output looks random." Its core requirement is statistical tests on collected samples. This is low-barrier and allows novel sources to be evaluated, but it can't detect a deterministic source that passes all tests.

AIS 31 (BSI) is model-based and physical — "explain to me WHY it's random." Its core requirement is a stochastic model of the entropy source. This provides deeper assurance and catches sources that pass tests but aren't truly random, but it can only certify well-understood sources.

AIS 31 classes: PTG.1 is a deterministic RNG (essentially a CSPRNG) that passes statistical tests, seeded from PTG.2+. PTG.2 is a physical TRNG with conditioning that requires a stochastic model plus statistical tests — most hardware TRNGs certify here. PTG.3 is a physical TRNG without conditioning — raw output must pass all tests. Extremely difficult, essentially requiring a quantum source with near-perfect uniformity.

FIPS 140-2/3

Security requirements for cryptographic modules. Level 1-2 requires basic statistical testing. Level 3 adds identity-based authentication and tamper-evident enclosures. Level 4 adds environmental failure protection — the module zeroizes if temperature, voltage, or EM excursions are detected.

FIPS 140-3 validation typically takes 12-24 months and costs $50K-$200K+.

Attacks and Security

The Dual_EC_DRBG Scandal

The most consequential cryptographic scandal of the 21st century. The algorithm uses two elliptic curve points P and Q. If you know the discrete log relationship between them (Q = eP), you can recover the internal state from a single output block and predict all future output.

In 2007, Shumow and Ferguson publicly noted this backdoor possibility. In 2013, Snowden documents confirmed the NSA had paid RSA Security $10M to make Dual_EC_DRBG the default in BSAFE. NIST removed it from SP 800-90A in 2014.

Lasting impact: Fundamental loss of trust in NIST-recommended algorithms (which NIST has worked to restore through more transparent processes). Motivated "nothing up my sleeve" number requirements in cryptographic designs.

The RDRAND Controversy

Intel's RDRAND is a black box on the CPU die. You cannot inspect the implementation, cannot access raw entropy, and external testing can only evaluate CSPRNG output (which passes all statistical tests regardless of entropy source quality, because AES-CTR-DRBG is strong).

Theodore Ts'o (Linux kernel RNG maintainer): "I am so glad I resisted pressure from Intel engineers to let /dev/random rely only on the RDRAND instruction."

The 2019 AMD bug: Certain AMD processors had RDRAND always return 0xFFFFFFFF — a complete, silent failure demonstrating why you never trust a single source.

Current consensus: RDRAND is one input to an entropy pool, never the sole source. Linux XORs it with other sources — even a backdoored RDRAND cannot weaken the final output (XOR with an independent source can only help).

Environmental Manipulation

Temperature: Cooling a chip to -40°C can reduce thermal noise entropy to near zero. Voltage: Lowering supply voltage reduces noise margins; voltage glitches can force deterministic behavior. EM injection: A focused EM field can lock ring oscillators in phase, eliminating jitter entirely. Bayon et al. (CHES 2014) reduced ring oscillator TRNG entropy to essentially zero from centimeters away.

Side-Channel Attacks

Electromagnetic emanation: EM probes near the chip can observe jitter patterns and infer generated bits. Markettos and Moore (2009) extracted internal state from several commercial TRNGs. Power analysis: SPA/DPA on the TRNG's power consumption can reveal which bits were generated. Timing: If output rate is data-dependent (for example, von Neumann debiasing), timing reveals information about raw source values.

Supply Chain Attacks

A hardware Trojan inserted during fabrication can subtly weaken a TRNG — reducing noise bandwidth, adding a deterministic component to oscillators, or inserting a kill switch. Such trojans may involve changes to only a few transistors in a billion-transistor chip and pass all functional and statistical testing.

Never Trust a Single Source

This is the most important practical lesson. Hardware can fail silently (AMD RDRAND bug). Manufacturing variations mean your test chip is not your production chip. Environmental conditions differ between lab and deployment. Backdoors exist (Dual_EC_DRBG proved this). XOR with independent sources can only help, never hurt — mixing multiple sources means compromising the output requires compromising ALL sources simultaneously.

Historical Timeline

~3000 BCE — Mesopotamian dice (sheep ankle bones). 1655 — Roulette wheel attributed to Pascal. 1918 — Schottky describes shot noise. 1926 — Born proposes probabilistic interpretation of QM; Johnson observes thermal noise. 1927 — Heisenberg uncertainty principle; Tippett publishes first random number tables. 1928 — Nyquist derives thermal noise formula. 1940s — Monte Carlo methods (Ulam, von Neumann, Metropolis) at Los Alamos. 1951 — Von Neumann publishes debiasing technique. 1955 — RAND Corporation publishes "A Million Random Digits." 1957 — ERNIE 1 — neon tube discharge noise selects UK Premium Bond winners (built by Tommy Flowers' team). 1964 — Bell's theorem. 1982 — Aspect's Bell test experiments. 1996 — HotBits (radioactive decay RNG); SGI patents LavaRand. 1998 — random.org (atmospheric noise). 1999 — Intel i810 — first consumer CPU with on-chip TRNG. 2007 — Dual_EC_DRBG backdoor publicly noted. 2012 — Intel RDRAND/RDSEED (Ivy Bridge). 2013 — Snowden confirms NSA backdoor in Dual_EC_DRBG. 2015 — Loophole-free Bell tests (Delft, Vienna, NIST). 2018 — NIST SP 800-90B published; cosmic Bell test using quasar light. 2019 — ERNIE 5 (quantum RNG); AMD RDRAND bug discovered. 2022 — Linux 5.17 unifies /dev/random and /dev/urandom. 2020s — Chip-scale QRNGs commercially available for smartphones and IoT.

Frontiers

Device-Independent Quantum RNGs

The theoretical gold standard. Two entangled particles are measured by spatially separated devices. If the CHSH Bell inequality is violated (S > 2), the outputs must contain genuine randomness — regardless of device trust. Even if every component was manufactured by an adversary, Bell violation certifies randomness.

Current limitations: requires over 82.8% detector efficiency (to close the detection loophole), cryogenic detectors, low throughput (bits/second). Active research is pushing toward practical rates.

Randomness Expansion and Amplification

Expansion: A short seed of n perfect random bits can generate 2^(poly(n)) certified random bits via Bell test protocols. Proven possible by Vazirani and Vidick (2012).

Amplification: Starting from weak randomness (each bit has bounded bias ε < 1/2), you can arrive at perfect randomness. This is impossible classically (Santha-Vazirani, 1986) but possible quantumly (Colbeck-Renner, 2012). The profound implication: if any unpredictability exists in the universe, perfect randomness follows.

NIST Randomness Beacon and League of Entropy

NIST Beacon: Publishes signed, chained 512-bit random values every 60 seconds from two independent quantum sources. Public, verifiable, unpredictable. Used for lotteries, audits, timestamping.

drand (League of Entropy): Cloudflare, Protocol Labs, and others operate a distributed beacon using threshold cryptography — no single participant can predict or bias output. More robust than any single-operator beacon.

Exotic Sources

Cosmic microwave background: Quantum vacuum fluctuations from cosmic inflation, frozen 13.8 billion years ago. The 2018 "cosmic Bell test" used quasar photons (billions of light-years away) to choose measurement settings, closing the freedom-of-choice loophole. Brownian motion: Nanoparticle tracking gives well-characterized stochastic signals. Neural noise: Neurons fire with inherent stochasticity due to random ion channel behavior — speculative but theoretically sound.

Philosophy: The Deepest Questions

What Does "Random" Actually Mean?

Kolmogorov complexity: A string is random if it's incompressible — the shortest program that outputs it is approximately as long as the string itself. A PRNG output, no matter how long, has low Kolmogorov complexity (the algorithm plus seed is short). A truly random string of n bits has complexity roughly n. The fundamental problem: Kolmogorov complexity is uncomputable (halting problem), so you can never prove a specific finite string is random.

Martin-Löf randomness: An infinite sequence is random if no computable betting strategy can make unbounded money on it. Equivalent to saying no computable adversary can distinguish it from uniform.

Information-theoretic view: A TRNG produces genuine information in Shannon's sense. Each bit is irreducible — it didn't exist in the universe before measurement. A PRNG produces no new information; it merely stretches the information in its seed.

Can We Prove Randomness?

For finite strings: No. It could have been generated by an unknown deterministic process. All statistical tests have finite power. AES-CTR output passes every known test but is entirely deterministic.

For processes: Conditionally yes. If you accept quantum mechanics (and reject superdeterminism), Bell inequality violations prove the outputs contain genuine randomness. This is the strongest known certification.

The Interpretations Problem

Copenhagen: Measurement outcomes are fundamentally stochastic. TRNG randomness is real. Many-Worlds (Everett): All outcomes occur in different branches. No collapse, no randomness at the universal level. QRNGs produce different bits in different branches. Bohmian mechanics: Deterministic pilot wave guides particles. Randomness is epistemic (quantum equilibrium), like classical chaos but with stronger unpredictability. Superdeterminism: Everything was predetermined by initial conditions, including "free" measurement choices. Bell violations don't imply randomness.

The Practical Resolution

For engineering purposes, the debate is irrelevant. Quantum processes are the best known source of unpredictability. No known technology can predict quantum measurement outcomes. Bell tests can certify that outputs are at least as random as QM predicts. Whether the universe is "really" deterministic at some deeper level doesn't affect practical security — no adversary has access to that deeper level.

The hierarchy for practical security: Weakest — Algorithmic (PRNG), predictable with state knowledge. Moderate — Classical physical (thermal noise, chaos), unpredictable in practice, deterministic in principle. Strongest — Quantum mechanical, unpredictable even in principle, certifiable via Bell tests.

Key Takeaways

Quantum mechanics provides the foundation. Bell's theorem and its experimental confirmation establish that certain physical events are fundamentally undetermined. TRNGs exploit this.

No raw source is perfect. Every physical entropy source has bias, correlation, and non-stationarity. Conditioning is not optional.

The hybrid architecture won. TRNG seeds CSPRNG. You get genuine entropy for the seed and computational speed for bulk output. This is Linux, Windows, Intel, ARM — everyone.

Never trust a single source. The AMD RDRAND bug, Dual_EC_DRBG, and environmental manipulation attacks all prove this. Mix sources. XOR can only help.

Statistical tests cannot prove randomness. They detect non-randomness. Passing all tests is necessary but not sufficient. AES-CTR output passes everything but is deterministic.

Standards disagree on philosophy. NIST says "show me it looks random." BSI says "explain to me why it's random." Best practice: satisfy both.

The deepest randomness is certifiable. Device-independent QRNGs use Bell violations to prove randomness without trusting the device. This is the theoretical endpoint of the field.

Further reading: NIST SP 800-90A/B/C, BSI AIS 31, Killmann and Schindler "A Proposal for Functionality Classes for Random Number Generators" (2011), Herrero-Collantes and Garcia-Escartin "Quantum Random Number Generators" (Rev. Mod. Phys. 2017), Ma et al. "Quantum Random Number Generation" (npj Quantum Information 2016)

Deploy a Website

Sun, 28 Sep 2025 00:00:00 +0000

This document outlines the complete process used to deploy Mason Borchard's personal website from development to production on the internet.

Overview

This guide covers deploying a static HTML website using a VPS (Virtual Private Server), custom domain, and nginx web server. The process involves server setup, domain configuration, DNS management, web server configuration, and security considerations.

Step 1: VPS Setup

Choosing a VPS Provider

Provider: Vultr (vultr.com)
Plan: Basic/entry-level VPS instance
Specifications:
- 1 vCPU
- 1GB RAM
- 25GB SSD storage
- 1TB bandwidth
Operating System: Debian 12 (recommended for stability)
Cost: ~$5-6/month
Add ssh keys to vultr and attach to instance before deploying it so you can connect easily later

Step 2: Domain Registration and DNS Configuration

Domain Registration

Registrar: Any reputable domain registrar (epik.com)
Domain: masonborchard.com
Cost: ~$10-15/year for .com domain

DNS Record Configuration

Configure the following DNS records in your domain registrar's control panel:

Type    Name    Value                   TTL
A       @       YOUR_VPS_IPV4_ADDRESS   30
A       www     YOUR_VPS_IPV4_ADDRESS   30
AAAA    @       YOUR_VPS_IPV6_ADDRESS   30
AAAA    www     YOUR_VPS_IPV6_ADDRESS   30

Notes:

@ represents the root domain (masonborchard.com) -> the @ you can leave out as blank works with Epik
www creates the www subdomain (www.masonborchard.com)
A records point to IPv4 addresses
AAAA records point to IPv6 addresses
TTL of 30 seconds allows for quick DNS updates during setup

Step 3: Web Server Installation and Configuration

Install nginx

# Install nginx web server
sudo apt install nginx -y

# Start and enable nginx
sudo systemctl start nginx
sudo systemctl enable nginx

# Verify nginx is running
sudo systemctl status nginx

Create Website Directory Structure

# Create directory for the website
sudo mkdir -p /var/www/masonborchard.com

# Set appropriate permissions
sudo chmod -R 755 /var/www/masonborchard.com

Upload Website Files

# Copy your index.html to the web directory via rsync or w/e
# Or create a quick "hello world" index.html
vim /var/www/masonborchard.com/index.html

Configure nginx Virtual Host

Create nginx configuration file:

sudo vim /etc/nginx/sites-available/masonborchard.com

Add the following configuration:

server {
    listen 80;
    listen [::]:80;

    server_name masonborchard.com www.masonborchard.com;

    root /var/www/masonborchard.com;
    index index.html index.htm;

    location / {
        try_files $uri $uri/ =404;
    }

    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header Referrer-Policy "no-referrer-when-downgrade" always;

    # Cache static assets
    location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

Enable the site:

# Create symbolic link to enable site
sudo ln -s /etc/nginx/sites-available/masonborchard.com /etc/nginx/sites-enabled/

# Remove default nginx site
sudo rm /etc/nginx/sites-enabled/default

# Test nginx configuration
sudo nginx -t

# Reload nginx
sudo systemctl reload nginx

Step 4: Firewall Configuration

Configure UFW (Uncomplicated Firewall)

# Install UFW if not already installed
sudo apt install ufw -y

# Set default policies
sudo ufw default deny incoming
sudo ufw default allow outgoing

# Allow SSH (important - don't lock yourself out!)
sudo ufw allow ssh

# Allow HTTP and HTTPS traffic
sudo ufw allow 'Nginx Full'

# Enable firewall
sudo ufw enable

# Check firewall status
sudo ufw status verbose

Step 5: SSL Certificate Setup (Optional but Recommended)

Install Certbot for Let's Encrypt SSL

# Install certbot with nginx plugin via apt
sudo apt install certbot python3-certbot-nginx -y

# Obtain SSL certificate (make sure your domain is already pointing to your server)
sudo certbot --nginx -d masonborchard.com -d www.masonborchard.com

# Test automatic renewal
sudo certbot renew --dry-run

Important Prerequisites for Certbot:

DNS must be working: Your domain must already be pointing to your server and resolving correctly
HTTP must be accessible: Your nginx site must be working on port 80 before running certbot
Firewall must allow HTTP/HTTPS: Ensure ports 80 and 443 are open

How Certbot Works:

Certbot creates temporary files in your web directory to verify domain ownership
Let's Encrypt servers access these files via HTTP to confirm you control the domain
Once verified, certbot downloads the SSL certificates
The --nginx flag automatically updates your nginx configuration to use HTTPS
Certbot sets up automatic renewal via systemd timer

If Certbot Fails:

Verify domain resolution: dig masonborchard.com should return your server IP
Test HTTP access: curl -I http://masonborchard.com should return a 200 response
Check nginx logs: sudo tail /var/log/nginx/error.log
Ensure no other services are using port 80

This will automatically:

Obtain SSL certificates from Let's Encrypt
Update nginx configuration to use HTTPS and redirect HTTP to HTTPS
Set up automatic certificate renewal (certificates expire every 90 days)

Step 6: Verification and Testing

Test Website Accessibility

DNS Propagation: Use tools like dig or online DNS checkers
```
dig masonborchard.com
dig www.masonborchard.com
```

HTTP Response: Test with curl

curl -I http://masonborchard.com
curl -I https://masonborchard.com  # if SSL configured

Browser Testing: Visit the domain in multiple browsers

Performance and Security Testing

GTmetrix or PageSpeed Insights: Test loading performance
SSL Labs: Test SSL configuration (if HTTPS enabled)
Security Headers: Check security header implementation

Step 7: Ongoing Maintenance

Regular Tasks

System Updates: sudo apt update && sudo apt upgrade
Log Monitoring: Check nginx logs in /var/log/nginx/
SSL Renewal: Automated via certbot, but monitor for issues
Backup: Regular backups of website files and server configuration

Monitoring

# Check nginx status
sudo systemctl status nginx

# View nginx access logs
sudo tail -f /var/log/nginx/access.log

# View nginx error logs
sudo tail -f /var/log/nginx/error.log

# Check server resources
htop
df -h

Cost Breakdown

VPS: ~$5-6/month
Domain: ~$10-15/year
SSL Certificate: Free (Let's Encrypt)
Total Annual Cost: ~$75-90/year

Troubleshooting Common Issues

DNS Not Resolving

Check DNS record configuration in registrar panel
Wait for DNS propagation (up to 48 hours) but it usually only takes a few minutes
Use DNS checker tools online

Website Not Loading

Verify nginx is running: sudo systemctl status nginx
Check nginx configuration: sudo nginx -t
Review nginx error logs: sudo tail /var/log/nginx/error.log

SSL Certificate Issues

Ensure domain points to server before running certbot
Check firewall allows HTTP/HTTPS traffic
Verify nginx configuration is correct

This deployment process provides a robust, scalable foundation for hosting static websites with professional-grade infrastructure and security.

Install Signal Desktop on Aegix Linux

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

yay -S signal-desktop --noconfirm

Launch the app in a terminal with:

signal-desktop

Or use Mod + d and start typing signal-desktop to launch it via dmenu.

Notice the QR code.

Go to the Signal app on your phone and find Settings.

Tap "Linked devices"

Tap "Link a new device"

This will open up your camera.

Scan the QR code to link your device.

😘

How tmux Works

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

🧠 How tmux Works

tmux is a terminal multiplexer — it lets you:

Start a terminal session that stays alive even if you disconnect (like over SSH)
Split your terminal into multiple panes and windows
Switch between tasks or commands without opening new terminals
Reattach to sessions later

⚙️ Basic Concepts

Session: A named (or unnamed) workspace. Think of it like a virtual terminal container.
Window: Like a tab in a terminal, inside a session.
Pane: A split view within a window (horizontal/vertical).

🚀 Using `tmux` with Explicit Session Names

✅ Start a session with a name

tmux new-session -s timothason

This creates a new tmux session named mysession and attaches you to it.

🔄 Attach to a named session

tmux attach-session -t timothason 
# or tmux a -t timothason

📋 List all sessions

tmux ls

🧯 Kill a session

tmux kill-session -t mysession

⌨️ Inside tmux: Common Controls

All shortcuts use the prefix key, which is Ctrl+b by default

| Action             | Key sequence             |
| ------------------ | ------------------------ |
| New window         | `Ctrl+b`, then `c`       |
| Next window        | `Ctrl+b`, then `n`       |
| Split vertically   | `Ctrl+b`, then `"`       |
| Split horizontally | `Ctrl+b`, then `%`       |
| Move between panes | `Ctrl+b`, then arrow key |
| Detach             | `Ctrl+b`, then `d`       |

You can detach from a session and leave it running, then reattach later.

✅ Tips

Use one session per project or task (e.g. tmux new -s rails).
You can script tmux to auto-start with custom panes/windows.
Tmux works great with remote servers to avoid losing work if disconnected.

Adding a Second Aegix User

Wed, 30 Jul 2025 00:00:00 +0000

Let's say we want to create a secondary user on an Aegix Linux system. For this example the user we created during the installation process is called borchard and the secondary user we want to create will be called timothy.

1. First, check what groups "borchard" belongs to:

groups borchard

id borchard

2. Create the timothy user with home directory and zsh shell:

sudo useradd -m -s /bin/zsh timothy

3. Add timothy to the wheel group (most important for sudo access):

sudo usermod -aG wheel timothy

4. Set a password for timothy:

sudo passwd timothy

5. Copy the group memberships from borchard to timothy:

You can do this automatically with:

sudo usermod -G $(id -Gn borchard | tr ' ' ',') timothy

6. Create the essential directories that Aegix expects:

sudo -u timothy mkdir -p /home/timothy/{Downloads,Documents,Pictures,Music,Videos/obs,code,ss,Applications/vs-code-insider}
sudo -u timothy mkdir -p /home/timothy/.cache/zsh/
sudo -u timothy mkdir -p /home/timothy/.config/{abook,mpd/playlists}
sudo -u timothy mkdir -p /home/timothy/.local/src

7. Copy the Aegix dotfiles configuration:

Since Aegix uses the "gohan" dotfiles, you'll want to copy the configuration:

sudo cp -r /home/borchard/.config /home/timothy/
sudo cp -r /home/borchard/.local /home/timothy/
sudo cp /home/borchard/.* /home/timothy/ 2>/dev/null || true
sudo chown -R timothy:wheel /home/timothy

8. Set up vim/neovim plugins for timothy:

sudo -u timothy mkdir -p /home/timothy/.config/nvim/autoload
sudo -u timothy curl -Ls "https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim" > /home/timothy/.config/nvim/autoload/plug.vim
sudo -u timothy nvim -c "PlugInstall|q|q"

9. Verify the setup:

# Check groups
groups timothy

# Check home directory
ls -la /home/timothy

# Test switching to the user
su - timothy

The new timothy user should now have:

A home directory with the standard Aegix directory structure
The same group memberships as borchard (including wheel for sudo access)
The Aegix dotfiles and configurations
zsh as the default shell
Neovim with plugins installed

You can now log in as timothy or switch to that user with su - timothy.

Parsimony and Aegix Linux

Tue, 29 Jul 2025 00:00:00 +0000

Parsimony refers to simplicity or frugality in design—favoring the fewest necessary components or complexities. In software engineering, it embodies minimalism, efficiency, and clarity, where complexity is deliberately avoided unless justified by necessity.

Aegix Linux exemplifies parsimony by employing a streamlined approach to its architecture and user experience. Built upon Artix Linux and utilizing the lightweight Runit init system instead of the more complex systemd, Aegix emphasizes performance, simplicity, and user control. By reducing dependencies, avoiding unnecessary layers, and adhering to straightforward POSIX-compliant scripting, Aegix Linux provides users with a clean, efficient operating environment that embodies the very principle of parsimony.

How to Add New Articles to timbeach.com

Tue, 29 Jul 2025 00:00:00 +0000

This site uses a custom, lightweight article system that makes it easy to add new content without any complex build processes or databases.

Use This System for Your Own Site

Want to build your own website with this article system? The complete source code is available on GitHub at https://github.com/timbeach/timbeach.com. You can fork the repository and customize it for your own content while keeping the parsimonious design philosophy intact.

How It Works

The system consists of two simple components:

Markdown files - Your actual article content
JSON metadata - Article information like title, date, and tags

Adding a New Article

Step 1: Create the Markdown File

Create a new markdown file in the articles/ directory:

# Example: articles/my-new-article.md
echo "# My New Article" > articles/my-new-article.md

Write your article content using standard markdown syntax:

# My New Article

This is my new article content.

Features

Code blocks work perfectly
Bold and italic text
Links to external sites

Code Example

# This is a comment
echo "Hello, World!"

The system supports all standard markdown features!

Step 2: Add Metadata to JSON

Add an entry to articles/articles.json:

{
  "my-new-article.md": {
    "title": "My New Article",
    "date": "2025-07-29",
    "tags": ["tutorial", "example", "markdown"]
  }
}

Step 3: That's It!

The article will automatically appear in the articles list. No build process, no database, no complex CMS - just files and JSON.

System Features

Automatic Loading

Articles load from markdown files when available
Falls back to built-in content if files aren't accessible
No server-side processing required

Markdown Support

Full markdown syntax support
Code blocks with language highlighting
Links, images, and formatting
Lists, tables, and more

Simple Maintenance

Version control friendly (just text files)
Easy to backup and restore
No database migrations or complex deployments

File Structure

timbeach.com/
├── articles/
│   ├── articles.json          # Article metadata
│   ├── my-article.md          # Article content
│   └── another-article.md     # More articles...
└── index.html                 # The main site

Benefits of This Approach

Simplicity - Just markdown and JSON
Performance - Static files load fast
Reliability - No database dependencies
Portability - Easy to move or backup
Version Control - Text files work great with git

Advanced Features

Terminal Integration

The site features a terminal-style navigation system with commands:

ls - List articles and directories
cd articles - Navigate to articles directory
cat filename.md - Display article content
tree - Show directory structure with articles sorted by date
help - Show all available commands

Dynamic Loading System

The JavaScript implementation includes:

Graceful fallback - If external files fail to load, built-in content is displayed
Cache busting - Timestamp parameters prevent browser caching issues
Smooth transitions - Content fades in/out during navigation
Direct linking - URLs like #articles/filename.md work for sharing specific articles

Markdown Parser

The custom markdown parser handles:

Headers (H1, H2, H3)
Code blocks with language highlighting
Inline code formatting
Bold and italic text
Links with target="_blank"
Paragraph wrapping
Preserves formatting within code blocks

Search Functionality

When viewing the articles directory:

Real-time search by title or filename
Case-insensitive matching
Instant filtering of article list

Technical Implementation Details

Data Flow

Page Load: JavaScript fetches articles/articles.json
Article Request: When user clicks an article, JavaScript fetches the .md file
Parsing: Custom markdown parser converts content to HTML
Display: Content appears with terminal-style navigation

Error Handling

Network failures: Falls back to built-in article content
Missing files: Shows "Article Not Found" message with error details
JSON parse errors: Gracefully handles malformed metadata

Performance Optimizations

Lazy loading: Articles only load when requested
Minimal dependencies: No external JavaScript libraries
Efficient caching: Browser caches static files naturally
Small footprint: Entire site is a single HTML file + articles

File Naming Conventions

Use lowercase with hyphens for readability:

✅ my-article-title.md
✅ linux-tutorial.md
❌ MyArticleTitle.md
❌ my_article_title.md

Deployment

The deployment is equally simple:

./deploy.sh

This rsync script pushes all changes to the production server, excluding .git/, archive/, and .well-known/ directories.

This system proves that you don't need complex tools to create a beautiful, functional website. Sometimes the simplest solution is the best solution - and this custom article system exemplifies the philosophy of parsimony in web development.

Simplicity in Software Engineering

Fri, 10 Jan 2025 00:00:00 +0000

Simplicity is the cornerstone of effective software engineering. It leads to code that is easier to understand, maintain, and debug. By embracing straightforward logic, reducing unnecessary complexity, and adhering to well-defined standards, developers create software that's resilient and adaptable.

At its heart, simplicity respects the user's and developer's time and attention, focusing efforts on clarity and essential functionality. Whether through minimal dependencies, clear documentation, or intuitive design, prioritizing simplicity results in robust, elegant software solutions that endure.

Timothy D Beach

How My Links Got Their Pictures

🔗 The protocol nobody told you about

🐦 Twitter wanted to be different

🤖 The crawler doesn't run your code

🪤 Trap one: the fragment that never arrives

🌫️ Trap two: the blur

♻️ Trap three: the cache that never forgets

🌟 The whole trick, in one breath

Still Really Simple: A Short History of RSS (and How This Site Uses It)

What RSS actually is

A short, contentious history

Why it's still worth using

How the feed works on this site

Subscribe

Why Claude Code Keeps Asking for Permission (and How to Make It Stop)

The core idea: mode is set at startup, not per-turn

Why resumed sessions are the worst

The fix: make bypass your default

The Shift+Tab trap

What to do with sessions that are already running

One honest caveat

Seriously, though: do it in a sandbox

Claude /tips: The Complete List

TL;DR

The Complete List

Keyboard & input

Slash commands & config

Agents, skills & workflows

IDE & app integrations

Environment & plugin nudges

Sharing & growth

Bonus: shortcuts that aren't in the rotation

How I got this list: Claude reading itself

Why you never see them all

Future Me Has Receipts: Building circleback

🧶 Future Me Has Receipts: Building circleback

🎯 What problem does it actually solve?

🔧 The three new pieces

✨ fzf: the hero of every good terminal workflow

🪝 Hooks: how Claude Code hands off control

🛠️ awk, sed, jq: the old reliable trio

🧪 TDD caught real bugs

Bug 1: sort -r quietly doesn't reverse

Bug 2: the missing blank line

🏷️ Friendly names, stable UUIDs

🎬 What it looks like in action

📅 The daily rollup

🪧 The nudge that made me write this

🧠 The meta-point

📬 Want to try it?

The OSI Model, Explained from a Whiteboard

What the OSI Model Actually Is

Layer 7: Application

Layer 6: Presentation

Layer 5: Session

Layer 4: Transport

Layer 3: Network

Layer 2: Data Link

Layer 1: Physical

Memorizing the Stack

Why It Still Matters

From ~/.local/src to the AUR

The problem

Half one: the local sync

Half two: the AUR side

The flow

Two gotchas worth sharing

Why bother

Pipeline vs Harness

TL;DR

Pipeline

Colloquial sense

Technical instances we actually use

Defining traits

Harness

Colloquial sense

Technical instances we actually use

Defining traits

The overlap zone (where people mix them up)

🧶 Future Me Has Receipts: Building `circleback`

Bug 1: `sort -r` quietly doesn't reverse

`left-pad` and the Disappearing Package (npm, 2016)

Python's `pip` and the Resolver That Couldn't

Linux Shared Libraries: The `glibc` Trap