DEV Community: Athreya aka Maneshwar

How We Got an LLM to Draw Charts Without Ever Touching a Pixel

Athreya aka Maneshwar — Sun, 16 Aug 2026 12:41:39 +0000

Let's get something out of the way first.

Having data is good. Having a database full of reviews, commits, and org activity sitting there quietly, untouched, unread, never once glanced at by a human being with a coffee and an opinion? That's not "having data." That's a very expensive data graveyard.

At LiveReview, we build what we call a Blast-Radius Aware AI Code Review for Business-Critical Systems.

Which is a fancy way of saying: we review your code, we figure out how bad it would be if a change goes wrong, and we don't shut up about it until someone fixes it.

Along the way we accumulate a review data: who reviewed, how much, how fast, how often, which repos are on fire.

And for a while, that pile just sat there.

Engineering leaders would ask "is adoption increasing?" and get back a vibe, not an answer.

So we built Livi, a chat bot that answers real questions about that data with real charts, not paragraphs of hedging.

This post technically about how Livi draws those charts.

Specifically: why we never let the LLM touch a pixel, how the same chart definition ends up as both a live interactive graph in your browser and a flat PNG in a Slack thread, and why teaching a language model to pick the right chart shape is a surprisingly deep rabbit hole.

The core decision: don't ask the LLM to draw, ask it to describe

The tempting, wrong idea is: "let's have the LLM generate an image." Please don't.

Image-generating models are a different beast entirely, and even if you got one to draw a bar chart, you'd have no way to verify the numbers on it are real.

You'd be trusting a model that hallucinates plausible-sounding review counts to also render them faithfully into pixels.

That's not a chart, that's chart-shaped fan fiction.

The actually good idea, and the one every serious LLM-charting integration eventually converges on, is: the LLM writes Vega-Lite, a JSON grammar for describing charts declaratively.

You don't say "draw a blue bar going up." You say:

{
  "mark": "bar",
  "encoding": {
    "x": { "field": "month", "type": "temporal" },
    "y": { "field": "review_count", "type": "quantitative" }
  }
}

That's it.

That's the entire chart.

No pixels, no drawing, just a description of what the data means and how it should be mapped to a picture.

Vega-Lite does the actual drawing.

The LLM's job shrinks down to something it's genuinely good at: filling in a well-defined schema.

Models are much better at "pick mark: bar or mark: line" than "hallucinate 600 pixels of a correct y-axis."

And critically: the LLM never sees the actual numbers before they're rendered.

It writes the SQL, we run it, and the real result set gets stitched into data.values by our own Go code.

The model can be as creative as it wants about presentation.

It gets zero creative license over the numbers.

What actually happens between "how many reviews last month" and a chart on your screen

Here's the pipeline, roughly:

A few things worth dwelling on here, because each one exists because something went wrong first.

Why two SQL-writing steps instead of one? Because the model needs to know how many rows the answer will have before it can decide whether a chart makes sense or whether it should hand you a CSV instead.

Nobody wants a bar chart with 4,000 bars.

So step one is basically "how big is this going to be," and step two is "okay, now actually get me the data and tell me how to draw it."

Why is there a SQL guard at all? Because an LLM writing raw SQL against a multi-tenant database is one confidently-worded prompt away from org_id = 1 OR 1 = 1.

We run every generated query through a guard that rejects anything that isn't read-only, checks every table against a denylist, and specifically looks for the shape of a tenant-isolation bypass (constant-vs-constant comparisons, bare OR TRUE, all the classics).

It's not glamorous work, but it's the difference between "cool AI feature" and "why is Org A looking at Org B's review data" showing up in an incident channel.

(meme placeholder: "Well Yes, But Actually No" / bike fall guy. Top text: "the query has an org_id filter." Bottom text (mid-fall): "WHERE org_id = 1 OR 1=1")

Why does the LLM only ever see a narrowed slice of the schema, not the whole database?

Because our actual schema has north of fifty tables, and dumping all of them into every prompt is both expensive and a great way to get the model confused about which created_at belongs to which table. More on this in a second, it deserves its own section.

Teaching the model which tables even exist: dbctx

Here's a problem that doesn't show up until your schema stops being a toy demo.

We're at 58 tables and counting: reviews, pull requests, AI comments, review feedback, billing, licensing, job queues, the works.

If we pasted the full schema into every single prompt, we'd be burning thousands of tokens per question just describing license_seat_assignments to a model that was asked "how many reviews happened last month" and does not, will never, care.

So instead of "here is the entire database, good luck," we use dbctx, a Go library built specifically for this problem: given a natural-language question and a live Postgres connection, hand back only the tables that actually matter, formatted as compact, LLM-friendly text instead of a raw information_schema dump.

shrsv / dbctx

Compile a PostgreSQL database into compact, queryable context.

dbctx

Compile a PostgreSQL database into compact, queryable context.

dbctx is a Go library and CLI tool that compiles a PostgreSQL database into a portable, queryable context index (.dtx file). It extracts schema, relationships, field semantics, representative values, JSONB structure, and builds a full-text search index — all from deterministic introspection, statistics, and heuristics, with no generative LLM and no external services required for the core index. It also supports an optional local semantic embedding signal and an optional, user-controlled terminology dictionary — both additive, both off-by-default-cost, described below.

Use it to give text-to-SQL systems, AI agents, and database-aware applications a compact, relevant slice of your database schema at query time, instead of dumping the entire information_schema into every prompt.

Longer writeup with real numbers and diagrams: Introducing dbctx.

Key features:

Natural-language query — find relevant tables, columns, and relationships from a text question
Semantic retrieval (optional, on…

View on GitHub

It does this with a genuinely layered retrieval pipeline, not just a keyword grep.

Lexical and fuzzy matching against table and column names, full-text search, matching against actual sampled values in the data, an optional semantic embedding pass, and a curated terminology layer we feed it ourselves (so "LOC" resolves to billable_loc, and "MR" and "PR" both resolve to the same underlying pull-request concept, because our users say both depending on which Git host they came from).

Whatever scores above zero gets pulled in, plus anything reachable through a foreign key from something that scored, because a join target with zero lexical overlap with the question is still often exactly what the query needs.

The payoff is not subtle.

On our real schema, a typical question narrows 58 tables down to somewhere around 25 to 30, which is roughly half the context gone before the model has written a single character of SQL.

That's not a rounding-error optimization, that's the difference between a prompt the model can actually reason clearly about and one where the important tables are buried in a wall of billing and license-seat noise.

The part where pixels finally show up: vl-convert

So now we have a Vega-Lite spec. Great.

If the user is on the web dashboard, we're basically done, more on that in a second.

But what about Slack? What about Discord? Those platforms don't run a JavaScript charting library inside a chat message.

A Slack message is not a browser tab.

You cannot politely ask Slack to interpret a Vega-Lite spec and render SVG for you.

So for anywhere that isn't our own frontend, we need an actual image file.

This is where vl-convert comes in: a Rust binary (with Python and Node bindings, but we shell out to the CLI) that takes a Vega-Lite spec and rasterizes it straight to PNG, no headless browser required.

That last part matters more than it sounds.

The old-and-busted way to render a chart server-side is to spin up a headless Chrome instance, load a page with a charting library, screenshot it, and pray your Docker image doesn't balloon to two gigabytes.

vl-convert skips all of that.

It's a single binary, it takes JSON in, it gives PNG bytes out, and it's fast enough that nobody notices it happening.

(meme placeholder: Kombucha Girl, disgusted-then-intrigued two-panel. Disgusted panel: "spin up headless Chrome to screenshot a chart." Intrigued panel: "one Rust binary, JSON in, PNG out.")

Same spec, two very different destinies

Here's the part I actually think is neat.

We generate one Vega-Lite spec per chart.

What happens to it next depends entirely on where it's going.

(meme placeholder: Trade Offer / Minecraft villager trading. Give: "one Vega-Lite spec." Take: "a live interactive chart in the browser, or a flat PNG in a Slack thread, depending on where it lands.")

On the web, the frontend just hands the raw spec to react-vega and lets the browser do the work.

You get hover tooltips, you get resizing, you get an actually interactive chart, and our backend does zero image rendering for that path.

It just ships JSON.

For Slack and Discord, the exact same spec gets routed through vl-convert instead, turned into a flat PNG, and attached as a file to the message.

The bot doesn't know or care that it's the "same" chart taking a different road.

From the pipeline's point of view, a Vega-Lite spec is just a Vega-Lite spec.

Where it ends up decides whether it becomes living, breathing SVG or a JPEG-adjacent screenshot sitting quietly in a chat thread forever.

This split is also why we can add new chart destinations cheaply.

Want an emailed weekly digest with embedded charts? Same spec, same vl-convert path, new delivery mechanism.

The hard problem (getting a correct, sensible chart spec out of an LLM) is solved exactly once.

Where this leaves us

The whole point of Livi was never "add a chatbot," it was "close the loop between the data we're already collecting and the person who actually needs to act on it."

A CTO asking "are engineers actually using this thing" should get an answer that looks like a calendar heatmap of usage rhythm, not a spreadsheet and a shrug.

The recipe, if you're building something similar, is genuinely not complicated:

Never let the model touch pixels. Let it write a declarative spec.
Never let the model see real numbers before you've run its query yourself.
Guard the query like you mean it, not like a vibes-based regex.
Pick one rendering pipeline (vl-convert, in our case) and let destination decide static-vs-interactive, not the model.
Budget real prompt space for chart taste. This is the part that actually takes iteration.

LiveReview reviews your code, tells you how bad a change could go, and won't shut up until it's fixed — and Livi turns all that accumulated review data into charts a human can actually act on.

If you liked the post, drop a ⭐ on the repo and try LiveReview now.

The Guy Who Invented the Internet's Front Door and Refused to Charge Rent

Athreya aka Maneshwar — Tue, 11 Aug 2026 18:31:35 +0000

Hello, I'm Maneshwar. I'm building git-lrc, a Micro AI code reviewer that runs on every commit. It is free and source-available on Github. Star git-lrc to help devs discover the project. Do give it a try and share your feedback.

Okay so here's a fun one for you.

Imagine you invent the thing that eventually becomes the substrate for Google, Facebook, Amazon, your bank, your ex's Instagram, and every cursed cookie consent banner known to man.

Now imagine you had the legal right to charge a licensing fee for it.

Like, a reasonable one. A cent per page load, say.

You would never have to work again.

Your great-great-grandchildren would never have to work again.

You'd be sipping something expensive on a boat named after a HTTP status code.

Tim Berners-Lee looked at that exact opportunity in 1993 and said, essentially, "nah, you guys keep it."

This has been rattling around in my head for days, so let's talk about it properly, with all the nerdy details.

The web almost lost to a gopher (literally)

Berners-Lee built the World Wide Web in 1989 at CERN, laid out in a proposal called Information Management: A Proposal, mostly so physicists could stop emailing each other giant papers and just... link to things. Wild concept, I know.

But here's the part people forget: the Web wasn't the obvious winner in the early 90s.

It had a genuine rival called Gopher, built at the University of Minnesota, and for a while Gopher was winning.

It was simpler, it was faster on the slow modems of the era, and it had a head start in adoption among universities and libraries.

Then in February 1993, the University of Minnesota did something that, in hindsight, ranks among the great unforced errors in computing history: they announced they'd start charging licensing fees for commercial use of Gopher server software.

Reasonable-sounding at the time (they needed to fund development), catastrophic in practice.

The developer community, which had spent years contributing code for free on the assumption this was an open commons, felt betrayed.

People started actively hunting for an exit.

That exit was sitting right there, and it was free.

Worth noting: Berners-Lee and his CERN collaborator Robert Cailliau had been lobbying CERN's legal department for this before the Gopher fiasco.

They saw the fee-wall problem coming and wanted to preempt it.

Gopher's mistake didn't create the opportunity, it just handed the Web a very well timed advertisement for the opposite approach.

April 30th, 1993: the day CERN gave away a gold mine

CERN's directors signed a document putting the Web's source code (the basic client, the basic server, the common library) into the public domain.

Not "free with attribution."

Not "free for non-commercial use."

Public domain.

Anyone, anywhere, for any purpose, forever, no royalties, no lawyers, no asking permission.

You can still read the actual CERN document server record for this release, and CERN itself has a nice writeup on the 30th anniversary of the decision.

It's a short, dry, bureaucratic memo.

Absolutely nothing in the formatting suggests "this sentence just prevented the internet from having toll booths on every hyperlink."

Here's the part that gets me every time I think about it: this wasn't the default outcome.

Patents on protocols were completely normal.

Unisys famously enforced patent licensing on the LZW compression used in GIF files for years, and that was just an image format, not the entire architecture of networked information.

Berners-Lee had a much stronger claim to a much bigger prize, and he actively worked to make sure nobody, including himself, could ever collect on it.

So how much did he actually give up?

Nobody can put an exact number on "what if every website paid a cent per page view since 1993," but you can get a feel for the scale by looking at who did get rich building on top of what Berners-Lee gave away for free.

Mark Zuckerberg built a social graph on top of the Web and became one of the richest people alive.

Jeff Bezos built a bookstore on top of it and did the same.

Neither of them invented the medium they got rich on.

The guy who did invent it drew a government researcher's salary and later ran the World Wide Web Consortium on a nonprofit budget.

He's not poor, to be clear. He's had a comfortable, respected, knighted career.

But "comfortable" and "owns a controlling stake in the global information economy" are very different tax brackets, and he had a real, legally available path to the second one and turned it down on principle.

If you want a mental model for this, picture the inventor of the highway system also personally owning the patent on wheels, and then just... not charging tolls, ever, to anyone, on purpose.

Public domain vs. "open source": the detail everyone glosses over

Quick technical aside because this matters and it's easy to gloss over.

CERN's 1993 move put the Web's code into the public domain, which is actually a stronger, weirder move than open sourcing it under something like the MIT or GPL license.

Open source licenses still rely on copyright existing so the license terms can be enforced.

Public domain says "there is no copyright claim here to enforce in the first place."

It's the difference between "you may use this under these conditions" and "this belongs to no one, full stop."

Later, when the W3C formalized how web standards (not just that original codebase) get licensed, they landed on a Royalty-Free patent policy in 2003, meaning any patents contributed to W3C standards like HTML or CSS have to be licensed for free to implementers.

That policy is a direct descendant of the 1993 decision.

It's still why you can build a browser, a static site generator, or a weird little Bun script that scrapes HTML, without a patent troll showing up in your inbox.

The counterfactual nobody wants to think about

Here's the fun horrifying thought experiment: what does the internet look like if CERN had licensed the Web instead of freeing it?

Best case, some other protocol wins instead (maybe a fixed-up, de-feed licensed Gopher, maybe something else entirely), and we're having this exact same conversation about a different inventor a few years later.

Protocols that lock down access don't tend to become universal substrates, they become "one option among several enterprise formats," which is exactly the fate Gopher suffered once trust broke.

Worst case: the Web still wins anyway because it's technically better, but every server operator owes a fee, which means every early website needs a business model before it can exist, which means the era of "anyone with a text editor can publish to the whole world for free" never happens.

No GeoCities.

No early blogs.

No Wikipedia edited by strangers for free.

The barrier to publishing stays exactly where it was before the internet: you need capital.

Why almost nobody talks about this

I think the reason this story doesn't circulate much is that it doesn't have a villain.

There's no evil corporation to be mad at, no lawsuit, no dramatic betrayal.

It's just a physics lab's legal department agreeing to a request from two engineers who cared more about adoption than ownership, and then that single administrative decision quietly outcompeting every other decision anyone else made for the next thirty years.

Boring paperwork doesn't trend.

Free stuff staying free forever doesn't make headlines the way free stuff suddenly costing money does.

But it's genuinely one of the highest leverage single decisions in the entire history of technology.

One memo, thirty years ago, is a big part of why you can read this post without anyone charging you, me, or dev.to a licensing fee for the privilege of using hyperlinks.

What he's up to now

When I invented the World Wide Web, I envisioned technology that would empower people and enable collaboration. Somewhere along the way, we lost that human-first approach; today’s web often prioritises profits over people. Solid returns the web to its roots by giving everyone direct control over their own data
-Sir Tim Berners-Lee

Berners-Lee didn't cash out and vanish.

He's been trying to fix the parts of the web that went sideways once the ad-funded, walled-garden era took over, most visibly through the Solid project, which is an attempt to give people back control over their own data instead of it living in some platform's silo.

Whether or not it succeeds, the throughline is consistent: the guy who could have owned the internet has spent three decades since trying to make sure nobody else does either.

Next time someone tells you "nobody does anything for free anymore," you now have a receipt from 1993 that says otherwise, backed by literally the entire internet as evidence.

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs — without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.

Any feedback or contributors are welcome! It's online, source-available, and ready for anyone to use.

⭐ Star it on GitHub:

HexmosTech / git-lrc

Free, Micro AI Code Reviews That Run on Git Commit

git-lrc

Free, Micro AI Code Reviews That Run on Commit

GenAI today is a race car without brakes. It accelerates fast -- you describe something, and large blocks of code appear instantly. But AI agents silently break things: they remove logic, relax constraints, introduce expensive cloud calls, leak credentials, and change behavior -- without telling you. You often find out in production.

git-lrc is your braking system. It hooks into git commit and runs an AI review on every diff before it lands. 60-second setup. Completely free.

In short, git-lrc helps Prevent Outages, Breaches, and Technical Debt Before They Happen

At a glance: 10 risk categories · 100+ failure patterns tracked · every commit…

View on GitHub

Ayo GitHub Quietly Killed the Unreviewable Mega-PR

Athreya aka Maneshwar — Mon, 10 Aug 2026 18:19:38 +0000

If you've ever opened a PR with 47 changed files and a diff so long GitHub just gives up and shows you "Load Diff" seventeen times, this one's for you.

GitHub quietly shipped what might be the biggest pull request update in years, and it's aimed squarely at that problem.

Let's talk about stacked pull requests.

The problem, in one sentence

Big PRs are where good reviews go to die.

Nobody reads a 2000 line diff carefully.

Some folks reach for AI code review tools like LiveReview to take the edge off, and honestly that helps, but even the best reviewer (human or model) does a better job on a tight, focused diff than on a 2000 line wall.

Smaller inputs, better reviews. That's true no matter who's doing the reviewing.

Stacked PRs are GitHub's answer: break one massive change into a chain of small, dependent PRs, where each one only reviews the diff it actually introduces, not everything below it.

What a stack actually is

The rule is simple. You need two or more PRs in the same repo where:

The bottom PR targets your trunk branch (usually main)
Every PR after that targets the PR below it, not main

That's it. That's the whole trick.

Foundational stuff (schemas, shared types) goes at the bottom.

Stuff that depends on it (API routes, UI) goes higher up the chain.

And here's the part that surprised me: if you just do this manually with plain git, by opening PR #11 against the branch for PR #10 instead of against main, GitHub now recognizes that as a stack automatically.

No special tool required.

It just notices the base branches form a chain and lights up a banner.

Stacking isn't a git concept at all, it's purely a GitHub UI concept layered on top of branches you were already making.

Let's actually build one

Enough theory. I built a real stack in one of my own repos (peektea, a terminal file browser I maintain), using a harmless scratch file so nothing real got touched.

Here's the actual terminal session, copy pasted, warts and all.

First I tried to be fancy and use the CLI extension:

$ gh stack --help
unknown command "stack" for "gh"

Yeah. Turns out gh stack needs a CLI extension or a newer gh version than the one sitting in my $PATH, and mine's from a Ubuntu apt repo that hasn't heard about this feature yet.

Software, everyone.

So I did it the "old school" way the docs mention, plain git branches, chained base to base, no extension needed.

Which, from git's point of view, gives you exactly what git always gives you: three branches sitting on top of each other like tired commuters on a train.

Nothing special yet. This is just branches.

The magic happens once you push them and open the PRs with the right bases:

$ git push -u origin stack/01-setup-database stack/02-api-endpoints stack/03-setup-frontend

$ gh pr create --base master --head stack/01-setup-database \
    --title "demo: setup database layer"
https://github.com/lovestaco/peektea/pull/10

$ gh pr create --base stack/01-setup-database --head stack/02-api-endpoints \
    --title "demo: add api endpoints"
https://github.com/lovestaco/peektea/pull/11

$ gh pr create --base stack/02-api-endpoints --head stack/03-setup-frontend \
    --title "demo: setup frontend"
https://github.com/lovestaco/peektea/pull/12

Notice the --base on PR #11 is stack/01-setup-database, not master.

That one flag is the entire secret sauce.

And GitHub actually notices

This is the bit that got me. I expected to have to manually flip some setting somewhere.

Instead, the second I opened the top PR of the chain, GitHub just showed a banner: "This pull request can be stacked with other pull requests," with a "Preview stack" button sitting right there.

Clicking it pops up a little preview that walks the whole chain, top PR down to main, correctly ordered, correctly linked, with zero config from me beyond opening PRs against the right base branches.

Hit "Create stack" and every PR in the list picks up a tiny progress badge, 1/3, 2/3, 3/3, right there in the pull request list, so you can see at a glance how deep any given PR sits in its stack without opening a single one.

According to GitHub's own docs on stacked pull requests, once you're happy with the whole chain there's a "merge stack" action that walks down and merges every PR in order in one go, no manual rebasing between each merge.

I didn't actually pull that trigger on my demo repo (closing four browser tabs is enough chaos for one blog post), but the docs and the UI both point at it being one button for what used to be N sequential merges plus N rebases.

Here's roughly what that flow looks like end to end, CLI or manual, doesn't matter which:

Wait, didn't I already have this?

Kind of, and this is worth being honest about. You could always open a PR against another PR's branch.

That's not new, that's just git plus GitHub's base branch dropdown, and people have been daisy chaining branches like this for a decade.

What's new is that GitHub now understands the relationship, tracks it as a first class object (mine got assigned its own stack ID the moment I hit "Create stack"), shows progress across the whole list view, and gives you one merge action instead of a manual merge-then-rebase-then-merge dance for every layer.

So no, git itself didn't get a new stacked PR primitive.

GitHub's UI did.

If you clone the repo and look at the branches, there is genuinely nothing different about them from any other feature branch.

The "stack" only exists as metadata GitHub keeps on its side.

Why I actually care about this (hint: it's the bots)

Here's the part that got me more excited than a database migration screen usually gets me.

Think about what claude does when you point it at a big task and let it run for a few hours unattended.

Historically you get one of two bad outcomes: either it hands you back one enormous PR that's basically unreviewable, or it opens a dozen totally disconnected PRs that don't tell you which one depends on which.

Stacked PRs give agents a third option: build the feature the way a careful human would, in reviewable layers, and let the dependency chain itself communicate the order.

Schema first, then the API that needs the schema, then the UI that needs the API. You review it the same way the agent built it.

No more choosing between "one unreviewable 3000 line PR" and "twelve PRs with no visible relationship to each other."

The stack is the changelog of how the agent actually thought through the problem.

Should you actually use this

If your team already splits work into small PRs by hand and just eats the rebase pain, yes, obviously, this removes the pain and keeps the habit.

If your team is currently a "one PR per feature, no matter how big" shop, stacked PRs are a nice on ramp, because you get to keep working the way you already do (branch off the previous branch) while GitHub handles the bookkeeping you used to do in your head.

It's still labeled as a newer feature in GitHub's docs, so expect some rough edges (my gh CLI didn't even know the command existed yet), but the web UI side of it worked exactly as advertised the first time I tried it, no config, no opt in flag, just open PRs with the right base branches and watch GitHub connect the dots.

Go forth and stack responsibly. And maybe update your gh CLI before you try the extension route, unlike me.

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs — without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.

Any feedback or contributors are welcome! It's online, source-available, and ready for anyone to use.

⭐ Star it on GitHub:

HexmosTech / git-lrc

Free, Micro AI Code Reviews That Run on Git Commit

git-lrc

Free, Micro AI Code Reviews That Run on Commit

git-lrc is your braking system. It hooks into git commit and runs an AI review on every diff before it lands. 60-second setup. Completely free.

In short, git-lrc helps Prevent Outages, Breaches, and Technical Debt Before They Happen

At a glance: 10 risk categories · 100+ failure patterns tracked · every commit…

View on GitHub

Teaching Your AI Web Design Some Actual Taste

Athreya aka Maneshwar — Sat, 08 Aug 2026 17:30:42 +0000

Let me guess.

You opened Claude Code, typed "build me a modern landing page," hit enter, and got back something that technically works but somehow looks like every other site you have ever scrolled.

Purple to blue gradients.

Inter for everything.

Little rounded icon tiles floating above every heading.

A hero section that could belong to literally any SaaS on earth.

Congratulations, you have been served a fresh bowl of AI slop.

I have been fighting this exact fight for a while now, and I want to walk you through how I actually beat it.

Not with one magic prompt, and definitely not with a 10,000 line DESIGN.md you copied from a thread.

Just three moves, a couple of tools, and a way of working that stops leaving your output to the gods of the one shot.

First, why does slop even happen?

Here is the uncomfortable truth, and it is worth sitting with for a second.

The problem with slop is not technical.

The models are not bad at writing CSS.

They are frankly great at it.

The problem is that the output is generic, and generic is a moving target.

If the models got ten times better tomorrow, they would just raise the bar on what counts as basic.

The floor moves up, the slop moves with it.

Why? Because a model trained on the public internet learns the statistical center of the public internet, and the center of the design internet in 2026 is Tailwind templates, Vercel starters, and other AI generated landing pages.

Ask for "modern" and you get the mathematical average of every landing page ever shipped. That average is the slop.

So the fix is not a better model.

The fix is you. Specifically, your taste. And that is where a lot of us cope instead of cook.

Yeah. That is the cope.

The rest of this post is about doing the opposite.

Here is the whole game on one screen before we dig in:

Step 1: Cultivate some taste (you cannot inject what you do not have)

You have heard "AI has no taste" a hundred times. Fine.

But the sneaky corollary nobody says out loud is that you need taste to hand over, and most of us have not deliberately built any. We just vibe.

So step one is boring and unglamorous and completely non negotiable: go collect stuff you like.

Become a magpie. Open Dribbble, search "web design," sort by popular, and start screenshotting the hero pages that make you feel something.

Do the same on Pinterest.

Then, and this is my personal favorite, go to Twitter slash X, where a genuinely absurd amount of the best UI work gets posted before it lands anywhere else.

Save screenshots. Save links to live sites too, since a real page tells the model way more than a flat image.

Now, you could just let those screenshots rot in a folder called inspo_FINAL_v3. Or you could do the fun version and have Claude Code spin up a tiny inspiration library web app for you.

Mine groups everything by design style, names the aesthetic in actual design vocabulary, and gives me keywords for each piece.

Click a screenshot and I can copy an image prompt (for generating a matching hero background later) or copy a full brief (for generating the whole page).

It turns a pile of pretty pictures into a reusable palette of your taste.

The point of this step is not to copy anyone.

It is to give your future self a base to point at, so you are never starting from a blank prompt and an average result.

You are starting from a direction you already know you like.

Step 2: Arm Claude Code with tools it does not ship with

Out of the box, Claude Code is a strong developer with the visual judgment of a coin flip.

So we hand it better eyes and better hands. Three categories are enough.

A real design skill

The default Anthropic frontend-design skill was a fine start, but at this point it kind of produces the slop it was meant to prevent.

The one I reach for now is Impeccable, an open source Claude Code skill by Paul Bakaus.

Instead of vaguely begging the model to "not look AI generated" (which never works), it does something clever: it names the specific slop patterns and tells the model to avoid them.

It ships as one skill with a stack of commands you invoke like slash commands. A few that I use constantly:

/critique for an honest UX review of hierarchy and clarity
/bolder to push a safe, boring design toward actual impact
/quieter to pull an over caffeinated design back down
/polish for a final alignment and spacing pass before shipping

Under the hood it hunts slop across seven areas: typography, color, spatial design, responsiveness, interaction, motion, and UX writing.

There is even a Chrome extension that highlights slop patterns on a live site, which is a little bit rude and extremely useful.

The before and after examples in the docs sell it better than I can.

If Impeccable is not your flavor, there are other "taste" style skills in the same spirit floating around GitHub, and they work on the same principle.

An image and video MCP

Claude Code cannot draw. It cannot generate that moody cinematic mountain range you want behind your hero text.

So give it the ability with the Higgsfield MCP, which basically hands your agent a backstage pass to 30 plus image and video models through a single connection.

You describe the hero image, it generates it, drops it into the section, done. No tab hopping to five other tools.

A component registry

For the smaller stuff, buttons, cards, pricing sections, pagination (when was the last time you thought hard about pagination?), I browse 21st.dev.

It is an open registry where each component ships with a "copy prompt" button.

Paste that into Claude Code and it rebuilds the component inside your codebase, wired to your stack.

Think of it as step one's taste hunting, but zoomed all the way in to the component level.

One warning before you go tool shopping

Here is the trap, and I have fallen in it more than once.

It is very easy to convince yourself you are one skill away from all your design problems being solved. You are not.

You will find flashy skills that build gorgeous sites.

The catch is they tend to be narrow and extremely prescriptive, so they hand you exactly one kind of output every time.

That is not taste, that is a template with extra steps.

I like Impeccable and Higgsfield precisely because they are flexible.

The downside of flexible is that they will not magically produce greatness. That still depends on your prompting and your taste. Which is the point.

Step 3: Build in loops, not in one shots

This is the mindset shift that changed everything for me, so read it twice: stop trying to one shot.

The one shot is a lottery ticket.

You type "make it premium," hit enter, and pray.

Sometimes you win. Usually you get slop with a slightly nicer font.

Instead, cast a very wide net up front, then narrow down.

Here is the actual sequence I run:

Let me make that concrete.

Say I am building a landing page for a made up AI analytics startup called Kestrel, and the goal is to get people to book a demo.

First, five versions in five styles, all at once. Not one, five.

If you built that inspiration library from step one, you can just tell Claude Code to look at it, pull five aesthetic families, and build a page in each.

Seeing them side by side on one screen makes it obvious which direction has legs, in a way that squinting at a terminal one attempt at a time never does.

Say I land on a "vast quiet" minimalist look with a big cinematic image behind the hero.

Then, three variations of that one direction.

Same aesthetic, different body layouts.

Maybe one is super vertical and minimal, one is a "ledger" style with an index that scrolls alongside you, one frames each section with edges.

I pick the ledger, because that scrolling index is genuinely cool.

Then I nail the hero image before fussing with anything else.

I fire up the Higgsfield MCP, ask for four 2K options that fit the quiet aesthetic, and look at them in the actual hero slot.

Too black and white? Ask for variations with a splash of color.

That gentle golden "alpenglow" one? Sold.

Then transitions and weight.

I ask for the hero to fade into the body instead of hard cutting, and for elements to load in with a bit of heft so the whole thing feels premium rather than snappy and cheap.

Notice what is happening.

At every stage I am seeing options and choosing, not blindly trusting a single generation. That is the whole trick.

The four things worth putting in your prompt

You do not need a giant design doc.

When those get too specific, they just produce the same thing every time, which is the slop problem wearing a fancier coat.

I pass four things, loosely:

Aesthetic. The general family of design you are going for.
Reference image. This is where your taste library earns its keep. Drop a screenshot, or better, an actual URL of a site you like. You are matching a feeling, not copying content.
Intent. What is this and why does it exist? SaaS product? Event page? Who is the audience and what do you want them to do, read, click, or fill out?
Guardrails. The always and the never. This is your anti slop clause. "Never use purple gradients. Never use Inter. No 3D SaaS blobs."

The secret weapon: a live tweak bar

Even after all that, the page felt almost right but a touch too minimal.

Instead of guessing with more "make it pop" prompts, I asked Claude Code to add a live tweak bar to the dev server, the kind of panel you see inside Claude Design.

Font family, font size, accent color, motion, reveal distance, anything where a design decision lives.

Now I iterate by eye.

I flip through fonts in real time instead of asking for ten rebuilt pages and comparing them like a lunatic.

Being able to see differences instantly is the thing that finally gets you to something you actually like. And do not forget: references are not just for the hero.

Feed the model URLs and screenshots for how you want the body laid out too, since Claude Code can look at a live page and apply its structure.

Wrapping up

None of this is a rulebook. Do not follow it to the letter, because the second something becomes a rigid formula, it starts producing its own flavor of slop.

The point is a flexible workflow you can bend to any project:

Cultivate taste so you have something to hand over.

Arm your agent with a design skill, an image MCP, and a component registry.

Then build in loops, wide net first, tweak by eye last, so you are never at the mercy of a single roll of the dice.

The moat was never the toolbox.

It was always your taste.

Go build something that looks like you, and leave the purple gradients where they belong.

If you try this, I would love to see what you ship. Drop a link in the comments and let us compare notes.

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs — without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.

Any feedback or contributors are welcome! It's online, source-available, and ready for anyone to use.

⭐ Star it on GitHub:

HexmosTech / git-lrc

Free, Micro AI Code Reviews That Run on Git Commit

git-lrc

Free, Micro AI Code Reviews That Run on Commit

git-lrc is your braking system. It hooks into git commit and runs an AI review on every diff before it lands. 60-second setup. Completely free.

In short, git-lrc helps Prevent Outages, Breaches, and Technical Debt Before They Happen

At a glance: 10 risk categories · 100+ failure patterns tracked · every commit…

View on GitHub

ratatop: the process table, and the parentheses that ruin everything

Athreya aka Maneshwar — Fri, 07 Aug 2026 18:21:29 +0000

CPU, memory, disks and network were all "read a file, do some arithmetic, draw it".

This one is different.

It reads about 400 directories every tick, and it is the first box you can actually interact with.

There is one bug in here that I would bet real money most /proc parsers have shipped at some point. Let me start there.

The parentheses that ruin everything

Here is a line from /proc/[pid]/stat:

125045 (cat) R 125025 125045 125025 0 -1 4194304 92 0 0 0 11 22 0 0 20 0 7 0 ...

Space separated.

Field 1 is the pid, field 2 is the process name in parentheses, field 14 is user time, field 15 is system time, field 20 is thread count, field 24 is resident memory.

So you split on whitespace and index into the result. Obvious. Works perfectly.

Until someone runs a process called my (weird) app.

42 (my (weird) app) S 1 42 1 0 -1 0 0 0 0 0 5 5 0 0 20 0 3 0 ...

That name is three whitespace-separated tokens, so every field after it shifts by two.

Your thread count is now reading someone's page fault counter.

Your memory is reading a scheduling priority.

Nothing crashes.

The numbers are just quietly, confidently wrong.

And the process name is fully user-controlled.

Anyone can rename a thread to whatever they like.

The fix is to not split the whole line at all.

Find the last closing parenthesis, take the name from between the first ( and that, and only then split what remains:

fn parse_stat(raw: &str) -> Option<Stat> {
    let open = raw.find('(')?;
    let close = raw.rfind(')')?;
    let name = raw.get(open + 1..close)?.to_string();

    // Fields resume at `state`, which is field 3 in the man page's numbering.
    let fields: Vec<&str> = raw.get(close + 1..)?.split_whitespace().collect();
    let field = |number: usize| -> u64 {
        fields.get(number - 3).and_then(|v| v.parse().ok()).unwrap_or(0)
    };
    // ...
}

rfind instead of find. That is the entire fix, and it is why the man page for proc explicitly warns you about this field.

The number - 3 offset is worth a look too.

The man page numbers fields from 1, and the two we consumed manually were 1 and 2, so field 14 lives at index 11 of what is left.

I wrote it as a closure that takes the man page's number directly, so the code reads field(14) and matches the documentation rather than making you do arithmetic while reviewing it.

Percent of what, exactly?

Second decision that changes what the numbers mean.

A process's CPU time is in clock ticks. To turn that into a percentage you need a denominator, and there are two reasonable choices:

Percent of one core. A single-threaded process pinning a core shows 100%.

A process using four cores shows 400%. This is what htop does by default.

Percent of the whole machine. That same core-pinning process shows 12.5% on my 8 core laptop, and the whole table sums to at most 100.

btop defaults to the second, so that is what I did. The denominator is the total tick delta across every core, which I already had from the CPU box:

let total = cpu::sample().total.total;
let elapsed = total.saturating_sub(self.previous_total);

Neither is wrong. But you have to pick one and say so, because "4.9" means very different things under each, and a user comparing your tool to htop will notice the factor of eight immediately.

The spike that isn't

Subtle one, and it took me a moment to reason about rather than observe.

CPU percentage is a delta between two samples.

A process that started since the last sample has no previous sample to subtract from.

If you treat its absent baseline as zero, you compute its entire lifetime CPU time as if it were consumed in the last two seconds.

Every freshly spawned process would flash at some enormous number, immediately sort to the top, and then drop back to reality on the following tick.

// A process that appeared since the last sample has no baseline, and its
// lifetime total would read as a huge spike.
if !self.previous.contains_key(&pid) {
    return 0.0;
}

Reporting zero for one tick is a small lie. Reporting 60% for a process that just started is a much larger one.

Sorting floats is not sorting

Quick Rust one that catches everybody once.

Every other column sorts with sort_by_key:

SortBy::Memory => self.list.sort_by_key(|p| p.memory),

CPU is an f64, and that does not compile. sort_by_key requires Ord, and floats only implement PartialOrd, because NaN compares false against everything including itself.

A type where x == x can be false cannot have a total order.

So the CPU column needs the explicit version:

SortBy::Cpu => self.list.sort_by(|a, b| {
    a.cpu.partial_cmp(&b.cpu).unwrap_or(std::cmp::Ordering::Equal)
}),

Treating an incomparable pair as equal is the pragmatic call here.

A NaN percentage would be a bug upstream, and I would rather the row sit in an odd position than the whole table panic.

A stock widget, finally

Four boxes in and I had not used a single ratatui widget that draws data. Everything was Block, Paragraph, and my own braille graph and meter.

The process table finally has a use for one: Scrollbar.

let mut state = ScrollbarState::new(total.saturating_sub(visible)).position(offset);
Scrollbar::new(ScrollbarOrientation::VerticalRight)
    .begin_symbol(Some("↑"))
    .end_symbol(Some("↓"))
    .thumb_style(Style::default().fg(theme::HI_FG))
    .render(area, buf, &mut state);

Note that this one is a StatefulWidget, not a Widget.

Different trait, and it will not compile until you import it.

The signature takes an extra &mut State argument:

fn render(self, area: Rect, buf: &mut Buffer, state: &mut Self::State);

That is ratatui's answer to a real problem with immediate mode.

Some widgets need to remember something between frames, and if everything is rebuilt every frame there is nowhere to put it.

StatefulWidget makes that state explicit and hands ownership to you, rather than hiding it inside the widget.

Which raises the obvious question about my scroll position.

Scroll offset is derived, not stored

The tempting design is a scroll: usize field that you bump on every key press.

I did not do that, and the reason is terminal resize.

If you store the offset and the user makes the window shorter, the stored value can now point past the end of a shorter list, and the selection can end up off screen with no key press to trigger a correction.

You end up writing clamping code that runs on resize, on list change, on selection change, and you will miss one.

Instead the offset is computed fresh every frame from the two things that are actually true:

fn scroll_offset(selected: usize, visible: usize, total: usize) -> usize {
    if visible == 0 || total <= visible {
        return 0;
    }
    let last_offset = total - visible;
    selected.saturating_sub(visible / 2).min(last_offset)
}

A pure function of selection, viewport height and list length.

Resize the terminal and it just produces the right answer, because it never had a stale answer to begin with.

This is immediate mode paying off, and it is a pattern I would not have reached for coming from a retained UI.

The selection index still has to be stored, and it still needs clamping, because processes exit constantly and the list genuinely shrinks under the cursor.

Small things that add up

Kernel threads have an empty cmdline.

That is how you tell them apart from real processes.

btop shows their comm in brackets instead, so [kworker/4:0-events] is a rendering convention, not something the kernel gives you.

comm is truncated to 15 bytes by the kernel.

That is why codebase-memory shows as codebase-memor in the Program column.

Not my bug, and there is nothing to fix: the full name is in the Command column.

uid to username needs /etc/passwd. /proc/[pid] gives you a numeric uid via the directory's owner.

I read the passwd file once at startup rather than per process, because 400 processes times one file read per tick is a lot of pointless syscalls for a mapping that does not change while the tool is open.

Everything can vanish mid-read.

Between listing /proc and opening /proc/1234/stat, pid 1234 may well have exited. Every failure in that path just means "gone" and skips the entry.

No error, no log, no retry.

What this cost

Worth being honest about the performance side.

The other four boxes read a handful of files per tick.

This one opens roughly 1200 files per tick: stat, cmdline and a metadata call for each of about 400 processes.

My test suite went from about one second to eleven, because several tests construct a full App and that now includes a complete process scan.

It is fine at a 2 second refresh.

It would not be fine at 100ms, which my + key allows.

btop solves this with the "lazy" mode you can see in my top-right corner, updating the expensive columns less often than the cheap ones.

I have the label but not yet the behaviour, which is a slightly embarrassing thing to leave in the UI.

That is on the list.

All four boxes, done

Five days, four boxes, one Rust TUI that reads real system state:

lovestaco / ratatop

Keep an eye on what's cooking in your system

A reimplementation of btop in Rust, built on ratatui.

The goal is a resource monitor that feels like btop: the four-box layout, braille graphs with gradient fills, mouse-driven navigation, and a themable process manager, but written as a modern Rust TUI.

Status

The CPU box works. It samples real data and renders btop's layout:

Per-core braille history graphs, a gradient load bar with sub-cell resolution frequency, package temperature, battery, and load averages.

Everything else, the memory, network, and process boxes, is still to come.

Design notes

Data source: /proc and /sys on Linux first, read directly rather than shelling out. btop's src/linux/btop_collect.cpp is the reference for what to read and how often; the BSD/macOS collectors are out of scope for v1.
Graphs are the hard part. btop's look comes from braille sub-cell plotting with a color gradient applied along the value axis, not from a stock chart widget. Expect…

View on GitHub

From here it is polish rather than new territory.

Filtering the process list, killing and renicing, tree view, theme files, mouse support.

The thing I did not expect from this week is how much of the work was reading kernel documentation carefully rather than writing Rust.

The parentheses in comm, the 512 byte sectors, f_bavail versus f_bfree, MemAvailable versus MemFree, transmit bytes being field nine.

Every box had exactly one trap like that, and every one of them fails silently with a plausible looking number rather than an error.

Which is the actual lesson, I think.

When you are reading a kernel interface, a wrong answer looks exactly like a right answer.

The only defence is reading the docs properly and writing a test that encodes what you learned.

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs — without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.

Any feedback or contributors are welcome! It's online, source-available, and ready for anyone to use.

⭐ Star it on GitHub:

HexmosTech / git-lrc

Free, Micro AI Code Reviews That Run on Git Commit

git-lrc

Free, Micro AI Code Reviews That Run on Commit

git-lrc is your braking system. It hooks into git commit and runs an AI review on every diff before it lands. 60-second setup. Completely free.

In short, git-lrc helps Prevent Outages, Breaches, and Technical Debt Before They Happen

At a glance: 10 risk categories · 100+ failure patterns tracked · every commit…

View on GitHub

Google Quietly Dropped 12 Free AI Tools. Developers Should Probably Care.

Athreya aka Maneshwar — Thu, 06 Aug 2026 18:17:02 +0000

A few years ago the AI conversation looked like this.

"Should I pay $20?"

"No, $200."

"Actually this new tool is $39/month."

My wallet started looking like it had gone through a startup funding winter.

Then Google quietly walked into the room and started dropping free AI tools like Oprah handing out cars.

"You get an AI IDE!"
"You get a workflow builder!"
"You get a GitHub coding agent!"

...except nobody really noticed because Google announced them across five different events, Labs pages, GitHub repos, and random blog posts.

So I spent some time collecting the ones developers will actually find useful.

No "AI that writes your wedding speech."

No "AI that guesses your spirit animal."

Just tools that can actually help you ship software.

Bookmark this one.

1. Pomelli

https://labs.google/pomelli

If you've ever launched a side project, you already know the painful truth.

Building the product is fun.

Writing 37 LinkedIn posts explaining the product... not so much.

Pomelli takes your website, understands what your product does, builds a brand profile, then generates social posts around it.

Think of it as hiring an intern that actually reads your landing page before tweeting.

Would I let it post automatically?

No.

Would I happily let it generate the first draft so I don't stare at a blinking cursor?

Absolutely.

Perfect for:

Indie hackers
SaaS founders
Open-source maintainers pretending they enjoy marketing

2. Stitch

https://stitch.withgoogle.com

Remember when designing an app meant opening Figma...

...moving a button 3 pixels...

...asking for feedback...

...moving it back 3 pixels?

Stitch skips a surprising amount of that.

You describe the interface.

Or upload a sketch.

Or even paste a wireframe.

It generates modern UI designs and can even produce frontend code.

It's not replacing designers.

It's replacing the blank canvas.

That's a huge difference.

3. Antigravity

https://antigravity.google/

Every AI company apparently wakes up and decides:

"You know what? Let's build another code editor."

Google joined the party with Antigravity.

Prompt it.

Generate an app.

Modify code.

Refactor.

Debug.

Sound familiar?

Yes.

But competition here is fantastic.

Cursor, Claude Code, Windsurf and now Google all trying to out-build each other means developers keep winning.

I'm perfectly okay being the spoiled child in this particular custody battle.

4. Mixboard

https://labs.google/mixboard

Imagine Canva and Pinterest had an AI-powered child.

That's Mixboard.

Instead of generating one image...

...you generate multiple concepts.

Mix.

Match.

Replace.

Rearrange.

Build moodboards.

For landing pages, presentations, branding, thumbnails, or app inspiration, it's surprisingly useful.

5. Disco

https://labs.google/disco

This one's still on the waitlist.

The idea is interesting though.

Instead of opening 15 tabs and manually connecting information, Disco understands what's already in your browser and lets AI interact with everything together.

Think NotebookLM...

...except your browser becomes the notebook.

I'm curious to see where this one goes.

6. NotebookLM

https://notebooklm.google

This one deserves way more attention.

Feed it:

PDFs
Docs
YouTube videos
Notes
Research papers

Then ask questions.

Generate summaries.

Create study guides.

Even generate podcast-style conversations.

I've thrown technical RFCs into NotebookLM before.

Reading 80 pages?

No thanks.

Asking "Explain this architecture like I'm joining the team tomorrow"?

Now we're talking.

7. Learn Your Way

https://learnyourway.withgoogle.com/

This feels like Google quietly built a personalized teacher.

Pick a topic.

It creates a learning path around you, not around a generic syllabus.

Want to learn Kubernetes?

It builds the course.

Rust?

Same.

Machine Learning?

Done.

It's surprisingly refreshing compared to watching fifteen random YouTube videos hoping they eventually connect.

8. Flow Music

https://www.flowmusic.app/

Not exactly a developer tool.

Still cool.

You describe the music.

AI produces songs.

Even music videos.

If you've ever wanted your side project launch trailer to sound slightly more cinematic than royalty-free ukulele music...

here you go.

9. Google AI Studio

https://aistudio.google.com/

This is probably the tool developers should spend the most time with.

Prototype prompts.

Test Gemini models.

Build AI apps.

Experiment with structured outputs.

Play with APIs.

Break things.

Fix them.

Repeat.

Think of it as Google's playground where ideas become prototypes ridiculously fast.

10. Jules

https://jules.google/

This one feels like hiring an eager junior developer.

Connect GitHub.

Assign work.

It creates branches.

Implements changes.

Opens pull requests.

It won't replace senior engineers.

But handing it repetitive tasks?

That's where it gets interesting.

Especially for bug fixes, migrations and mechanical refactors.

11. Gemini CLI

https://github.com/google-gemini/gemini-cli

If your happy place looks like this...

git
vim
tmux
terminal
coffee

...Gemini CLI belongs on your machine.

Run commands.

Generate code.

Explain repositories.

Execute workflows.

All without leaving the terminal.

Because apparently opening browsers is becoming optional now.

12. Codewiki

https://codewiki.google/

Open a repository.

Instead of manually reading fifty folders...

...you get a wiki explaining the architecture.

How components connect.

What each module does.

Why things exist.

If you've ever cloned an unfamiliar repository and immediately typed:

where do I even start?

This is your answer.

(If you've used DeepWiki before, you'll immediately understand the appeal.)

Final Thoughts

The interesting part isn't that Google released twelve AI tools.

It's that they're covering almost every stage of building software.

Need ideas?

NotebookLM.

Need UI?

Stitch.

Need code?

Antigravity or GeminiCLI.

Need automation?

Opal.

Need marketing?

Pomelli.

For a company that used to be "the search engine," Google suddenly looks a lot more like an end-to-end developer platform.

The AI race isn't just about building smarter models anymore.

It's becoming a battle over who owns your entire workflow.

And as developers...

...we get to steal the best parts from everyone.

So yes, bookmark this list.

Six months from now you'll probably remember that "Google had that one free tool..."

Now you'll know exactly which one.

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs — without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.

Any feedback or contributors are welcome! It's online, source-available, and ready for anyone to use.

⭐ Star it on GitHub:

HexmosTech / git-lrc

Free, Micro AI Code Reviews That Run on Git Commit

git-lrc

Free, Micro AI Code Reviews That Run on Commit

git-lrc is your braking system. It hooks into git commit and runs an AI review on every diff before it lands. 60-second setup. Completely free.

In short, git-lrc helps Prevent Outages, Breaches, and Technical Debt Before They Happen

At a glance: 10 risk categories · 100+ failure patterns tracked · every commit…

View on GitHub

ratatop: the network box, and why your ISP lies with units

Athreya aka Maneshwar — Sat, 01 Aug 2026 16:48:16 +0000

Day four of building a btop-style system monitor in Rust with ratatui.

CPU, memory, disks are done. Today the network box lands, which means three of btop's four boxes are up.

Three things in there took actual thought.

The unit situation, the shared scale, and the fact that the upload graph is upside down on purpose.

Byte/s and Kibps, side by side

Look at that first row again.

▼ 566 Byte/s  (4.42 Kibps)

Same number. Twice. Different units.

btop does this deliberately, and once you notice why, you cannot unsee it.

Your ISP sells you bandwidth in bits per second.

100 Mbps, 300 Mbps, whatever the sticker says.

Your download manager, your browser, and every file transfer you have ever watched report progress in bytes per second.

The factor between them is 8.

So the "100 Mbps" plan you pay for tops out around 12.5 MB/s in the progress bar, and every few months someone concludes their internet is broken when it is in fact working exactly as sold.

btop refuses to pick a side.

It shows both, so you can compare against your plan and against your download at the same time without doing mental arithmetic.

The conversion in code is unremarkable, which is the point:

fn format_bits(bytes_per_sec: f64) -> String {
    const UNITS: [&str; 4] = ["bps", "Kibps", "Mibps", "Gibps"];
    let (value, unit) = scale(bytes_per_sec * 8.0, 1024.0, UNITS.len());
    let decimals = decimals(value, unit);
    format!("({value:.decimals$} {})", UNITS[unit])
}

Note Kibps and not Kbps. Dividing by 1024 gives you kibibits; dividing by 1000 gives you kilobits.

btop uses 1024, so the label has to say so.

Getting this wrong is a 2.4% error that nobody would ever notice and that would still be wrong.

A column that jitters is a column you cannot read

Small thing I got wrong and had to fix.

My first version formatted rates with a fixed two decimals.

Perfectly reasonable, and it produced this:

▼ Top:  (4.42 Kibps)
▼ Top:  (43.80 Kibps)
▼ Top:  (438.00 Kibps)

The number changes width as traffic grows, so the whole column shuffles sideways every time the value crosses a power of ten.

In a display that redraws twice a second, that is genuinely distracting.

The fix is the same three-significant-figure rule the memory box already used:

fn decimals(value: f64, unit: usize) -> usize {
    if unit == 0 || value >= 100.0 {
        0
    } else if value >= 10.0 {
        1
    } else {
        2
    }
}

4.42, 43.8, 438. Always three digits. Always the same width.

This is the second time in this project I have written that exact function, which is usually a sign it should be shared.

For now it lives in both places because the memory box counts bytes and this one counts bits, and I would rather have two small honest copies than one abstraction that takes four parameters to explain itself.

The upload graph is upside down on purpose

The two graphs on the left are download on top and upload underneath, and the bottom one is mirrored: it hangs from its top edge and grows downward.

flowchart TD
    subgraph BOX[" "]
        D["download graph<br/>grows up from the middle"]
        M["shared baseline"]
        U["upload graph<br/>grows down from the middle"]
    end
    D --- M
    M --- U

It reads as one figure with traffic flowing outward from a centre line, rather than two unrelated charts stacked by coincidence.

My BrailleGraph widget from day one only knew how to fill upward from the bottom, so this needed a new option.

The change turned out to be four lines, because the only thing that differs is which end you count the dot rows from:

let offset = if self.inverted {
    dot
} else {
    dot_rows - 1 - dot
};

That is the whole feature. Everything else, the braille bit packing, the gradient, the two-samples-per-cell trick, is unchanged.

Both graphs must share one scale

Here is the part that is easy to get wrong and produces a chart that actively lies.

Each direction has its own peak.

The obvious move is to scale each graph to its own maximum, so both always use the full height of their box.

Do that and you get a display where a 3 KB/s upload trickle and a 3 MB/s download flood are drawn at exactly the same height.

Two graphs, sitting adjacent, implying a comparison that is off by a factor of a thousand.

So the scale is shared, computed once from whichever direction peaked higher:

pub fn graph_max(&self) -> f64 {
    self.download.top.max(self.upload.top).max(10.0 * 1024.0)
}

Two details worth pointing out.

It scales to the peak seen, not the current value.

Scaling to the current value means the graph rescales every frame, so a flat line and a spike look identical and the shape carries no information at all.

And there is a 10 KiB floor.

Without it, an idle interface scales to its own noise, and three stray bytes of ARP traffic render as a mountain range.

The floor is why the label in my screenshot reads 20K even though nothing much is happening.

There is no file for your IP address

Day three needed a syscall because filesystem usage has no file. Today the same thing happened again, and I did not expect it to.

The rates all come from /proc/net/dev. Easy. But the 192.168.29.14 in the title has no file behind it.

/proc/net/route gives you the gateway, not your address.

/proc/net/fib_trie contains local addresses, but it is a serialised routing trie, not an interface listing, and parsing it is exactly as unpleasant as that sounds.

/sys/class/net/wlo1/ has the MAC, the MTU, the link speed, and no IP.

So it is getifaddrs(3), and my second unsafe block.

unsafe {
    let mut list: *mut libc::ifaddrs = std::ptr::null_mut();
    if libc::getifaddrs(&mut list) != 0 {
        return addresses;
    }

    let mut node = list;
    while !node.is_null() {
        let entry = &*node;
        node = entry.ifa_next;
        // ...
    }

    libc::freeifaddrs(list);
}

This one is chunkier than day three's statvfs, because it is a linked list. You walk it, you filter to AF_INET because an interface carries several addresses and only IPv4 fits the box, you cast a generic sockaddr to a sockaddr_in to reach the actual four bytes, and you free the list exactly once through the same pointer you were handed.

The line I am most pleased with is this one:

node = entry.ifa_next;

It advances the cursor before the body of the loop touches anything. Do it at the bottom instead and every continue in the loop becomes an infinite loop. There are two continues in there.

Field nine, not field two

A parsing trap for anyone reading /proc/net/dev:

Inter-|   Receive                                     |  Transmit
 face |bytes  packets errs drop fifo frame compressed multicast|bytes packets ...
  wlo1: 319815680  240000    0    0    0     0     0    0  137363456  180000 ...

Received bytes is the first counter.

Transmitted bytes is the ninth, because receive gets eight columns before transmit starts.

Grab field 1 for upload and you will be reporting received packets as your upload speed, and it will look plausible enough that you might not catch it.

The two header lines take care of themselves, incidentally.

Neither contains a colon, and the parser splits each line on the colon to separate the name from the counters, so they drop out before any field indexing happens.

I originally wrote a comment claiming the header needed special handling, then actually checked, and it does not.

Worth checking your own comments occasionally.

Cycling interfaces

btop puts <b wlo1 n> in the corner, which is both a label and a keymap: b for the previous interface, n for the next.

KeyCode::Char('n') => app.net.cycle(true),
KeyCode::Char('b') => app.net.cycle(false),

Loopback is filtered out of the list.

It is always present, always busy, and never the thing you opened a monitor to look at.

The default selection comes from /proc/net/route: whichever interface carries the route with a destination of all zeroes is the default route, and that is almost always the one you care about.

If that lookup fails, it falls back to whichever interface has moved the most bytes.

What's next

Processes. The last box, and by a distance the biggest.

Reading /proc/[pid]/stat for every process on every tick, computing per-process CPU deltas, sorting by any column, and making the list scroll with a selection cursor.

htop and btop both have a lot of hard-won edge case handling in that area, so I expect to be reading their source more than usual.

Code so far:

lovestaco / ratatop

Keep an eye on what's cooking in your system

A reimplementation of btop in Rust, built on ratatui.

Status

The CPU box works. It samples real data and renders btop's layout:

Per-core braille history graphs, a gradient load bar with sub-cell resolution frequency, package temperature, battery, and load averages.

Everything else, the memory, network, and process boxes, is still to come.

Design notes

Data source: /proc and /sys on Linux first, read directly rather than shelling out. btop's src/linux/btop_collect.cpp is the reference for what to read and how often; the BSD/macOS collectors are out of scope for v1.
Graphs are the hard part. btop's look comes from braille sub-cell plotting with a color gradient applied along the value axis, not from a stock chart widget. Expect…

View on GitHub

Today's takeaway is small but general: when you draw two things next to each other, you have implied they are comparable.

If they are on different scales, you have drawn a lie. Share the axis or separate the charts.

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs — without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.

Any feedback or contributors are welcome! It's online, source-available, and ready for anyone to use.

⭐ Star it on GitHub:

HexmosTech / git-lrc

Free, Micro AI Code Reviews That Run on Git Commit

git-lrc

Free, Micro AI Code Reviews That Run on Commit

git-lrc is your braking system. It hooks into git commit and runs an AI review on every diff before it lands. 60-second setup. Completely free.

In short, git-lrc helps Prevent Outages, Breaches, and Technical Debt Before They Happen

At a glance: 10 risk categories · 100+ failure patterns tracked · every commit…

View on GitHub

ratatop day 3: disks, statvfs, and my first unsafe block

Athreya aka Maneshwar — Fri, 31 Jul 2026 10:17:57 +0000

Day three of building a btop-style system monitor in Rust with ratatui.

Day one was the CPU box.

Day two was memory, where I learned that MemFree is a number nobody should look at.

Today: disks.

And this one broke a rule I had set for myself on day one.

There is no /proc file for this

My rule was simple.

Read /proc and /sys, never shell out to another tool.

CPU came from /proc/stat.

Memory came from /proc/meminfo. Disks would come from... something.

I went looking for the file. /proc/mounts tells you what is mounted.

/proc/diskstats tells you how much I/O happened.

/sys/block/* tells you device sizes.

None of them tell you how full a filesystem is.

That number does not exist as a file anywhere. It only exists behind a syscall: statvfs(2).

The kernel computes it on demand from the filesystem's own metadata, and the only way to ask is to actually make the call.

So I had two options.

Shell out to df and parse it, which breaks my rule and drags in output-format fragility across distros.

Or make the syscall myself, which means the libc crate, which means unsafe.

I picked the syscall.

df itself is just a statvfs wrapper with a printf on top.

Spawning a process to read a number the kernel would hand me directly is silly.

My first unsafe block

Rust's standard library has no statvfs.

So this is FFI territory.

fn usage(mount: &str) -> Option<(u64, u64)> {
    let path = CString::new(mount).ok()?;
    // SAFETY: `path` is a valid NUL-terminated string that outlives the call,
    // and `vfs` is fully initialised by statvfs before we read it. A failed call
    // is reported through the return value, which we check.
    let vfs = unsafe {
        let mut vfs: libc::statvfs = std::mem::zeroed();
        if libc::statvfs(path.as_ptr(), &mut vfs) != 0 {
            return None;
        }
        vfs
    };

    let frsize = vfs.f_frsize as u64;
    let total = (vfs.f_blocks as u64).saturating_mul(frsize);
    let free = (vfs.f_bavail as u64).saturating_mul(frsize);
    Some((total, free.min(total)))
}

Three things worth pointing out, because they are the parts I had to actually think about.

CString::new is not optional. C wants a NUL-terminated string. Rust &str is not NUL-terminated, it carries a length. If you hand C a pointer to raw Rust string bytes, it reads until it happens to find a zero byte, which could be well past the end of your string. CString does the conversion properly, and it returns a Result because a Rust string containing an interior NUL cannot be represented at all.

mem::zeroed() looks worse than it is. We are handing C a buffer to fill in. statvfs writes every field before returning success. Zeroing first means that even in some bizarre partial-write scenario we get zeros rather than whatever was on the stack.

The SAFETY comment is not decoration. Rust convention is that every unsafe block gets a comment explaining why it is actually safe. Writing that comment is a genuinely useful exercise. It forces you to enumerate your assumptions, and if you cannot write the comment, that is your answer about whether the code is correct.

The nice part is that the unsafety is contained.

One function, ten lines, and a safe Option<(u64, u64)> comes out the other end. Everything upstream of it is ordinary safe Rust that cannot tell the difference.

Your filesystem is lying to you by exactly 5%

Now the fun part.

statvfs gives you three block counts, and picking the wrong one gives you the wrong answer.

f_blocks: total blocks in the filesystem
f_bfree: blocks that are genuinely unused
f_bavail: blocks available to an unprivileged process

Those last two are not the same, and the gap is bigger than you would guess. Real numbers from my root filesystem:

total   91.1 GiB
bfree   23.7 GiB
bavail  19.0 GiB

That is 4.67 GiB, exactly 5.1% of the disk, that is free but that I am not allowed to use.

ext4 reserves 5% of the filesystem for root by default. The idea is that if a runaway process fills the disk, root still has room to log in and clean up, and the filesystem has room to avoid the fragmentation that comes with running completely full.

Which number you subtract changes the headline figure:

used via f_bavail   79.1%
used via f_bfree    74.0%

Five percentage points, from one field name.

btop uses f_bavail, and so does df.

That is the honest choice for a monitor: report the space you can actually use, and treat root's reserve as spoken for.

Showing 74% when df says 79% would just make the tool look broken.

Which mounts are even real?

Next problem. /proc/self/mounts on my laptop has around 40 entries.

Four of them are disks.

The rest is proc, sysfs, cgroup2, tmpfs, a dozen snap squashfs images, and a couple of FUSE mounts from the desktop session.

The obvious move is a blocklist of filesystem types to skip.

I started writing one, then realised the kernel already publishes exactly this information:

$ cat /proc/filesystems
nodev   sysfs
nodev   tmpfs
nodev   proc
nodev   cgroup2
    ext4
    vfat

Anything flagged nodev is not backed by a block device.

That is the kernel telling you, authoritatively, which filesystem types cannot possibly be a disk.

So instead of maintaining a list that goes stale, I read theirs:

let mut types: Vec<String> = raw
    .lines()
    .filter_map(|line| line.strip_prefix("nodev"))
    .map(|name| name.trim().to_string())
    .collect();

New pseudo-filesystem lands in a future kernel? Excluded automatically, no code change.

There is a second filter that does a lot of work for one line: the mount's device has to start with /. A real partition is /dev/nvme0n1p2.

Pseudo-filesystems put a bare name there instead, like proc or gvfsd-fuse. No slash, not a disk.

The kernel escapes your mount paths

Small one, but it would have been a confusing bug.

Mount a disk at a path with a space in it, and /proc/self/mounts does not give you the space:

/dev/sdb1 /mnt/my\040disk ext4 rw,relatime 0 0

\040 is octal for a space. The kernel escapes spaces, tabs, newlines and backslashes this way, because the file is whitespace-separated and an unescaped space would make the line unparseable.

If you pass that raw string to statvfs, it fails. No such path exists. The disk silently vanishes from your monitor and you have no idea why.

So you decode it before using it. Four characters starting with a backslash, parse the next three as octal, emit the byte.

I/O comes from somewhere else entirely

Usage is a syscall. Throughput is back to reading files.

btop reads /sys/block/<device>/stat, which gives you a device's cumulative counters:

234345 84965 16346864 796898 486240 189824 21513416 23255863 0 2406558 24197776

The fields I care about are index 2 (sectors read), index 6 (sectors written), and index 9 (io_ticks, milliseconds the device spent with a request in flight).

Two traps here.

A sector is always 512 bytes in this file. Not the device's real block size. My NVMe drive uses 4096-byte blocks, but these counters are still expressed in 512-byte units, for backwards compatibility with software written when that was universal. Multiply by 4096 and your throughput numbers come out eight times too high.

Partitions are nested. /sys/block/nvme0n1/stat exists for the whole drive. The partition I actually mounted lives at /sys/block/nvme0n1/nvme0n1p2/stat, one level deeper. So the lookup checks the top level first, then scans one level down.

io_ticks is the nice one. It is busy-milliseconds, so dividing by the elapsed wall-clock milliseconds gives you utilisation directly:

let busy_ms = counters.io_ticks.saturating_sub(previous.io_ticks) as f64;
disk.io_util = (busy_ms / (seconds * 1000.0) * 100.0).clamp(0.0, 100.0);

Same delta pattern as the CPU box on day one. Third time I have written saturating_sub on a monotonic counter in this project, and it has earned its keep every time: devices get unplugged and re-added, and counters reset to zero when they do.

Swap is a disk that isn't one

btop lists swap in the disks box, which surprised me until it made sense. You care about how full it is, in the same way and for the same reasons.

But it has no filesystem, so statvfs is meaningless. And it may be a file, a partition, or several of both, so there is no single block device to read I/O from.

It comes from /proc/meminfo instead:

SwapTotal:      21092348 kB
SwapFree:       19857688 kB

So swap is a row that shares the layout but skips two of the three data sources.

In my code it is a Disk with is_swap: true, and the render function checks that flag before drawing the I/O graph.

Drawing an empty graph there would imply a measurement of zero, when the truth is there is no measurement at all.

The distinction between "zero" and "unknown" is one of those things that seems pedantic until your tool confidently reports the wrong thing.

The ratatui side was the easy part

Genuinely almost nothing to say here, which is the point.

Three rows per disk, laid out with the same Layout calls as the other boxes:

let [name_row, io_row, used_row] = Layout::vertical([
    Constraint::Length(1),
    Constraint::Length(1),
    Constraint::Length(1),
])
.areas(area);

The Meter widget from day one and the BrailleGraph from day one both dropped straight in with zero changes. Third box, same two widgets. That is the payoff for writing them as plain structs with one render method.

One layout decision worth mentioning: the box only draws disks that completely fit.

let capacity = (inner.height / ROWS_PER_DISK) as usize;

Integer division, so a disk with room for only two of its three rows is not drawn at all. A half-rendered disk looks like a bug, whereas a missing one just looks like a small window.

What's next

Network. /proc/net/dev is another counter file, so the delta machinery is already there, but auto-scaling units across five orders of magnitude will be new.

Then processes, which is the big one.

Reading /proc/[pid]/stat for every process, every tick, and sorting it.

Code so far:

lovestaco / ratatop

Keep an eye on what's cooking in your system

A reimplementation of btop in Rust, built on ratatui.

Status

The CPU box works. It samples real data and renders btop's layout:

Per-core braille history graphs, a gradient load bar with sub-cell resolution frequency, package temperature, battery, and load averages.

Everything else, the memory, network, and process boxes, is still to come.

Design notes

Data source: /proc and /sys on Linux first, read directly rather than shelling out. btop's src/linux/btop_collect.cpp is the reference for what to read and how often; the BSD/macOS collectors are out of scope for v1.
Graphs are the hard part. btop's look comes from braille sub-cell plotting with a color gradient applied along the value axis, not from a stock chart widget. Expect…

View on GitHub

Today's lesson, if there is one: the rule I set myself ("only read files, never shell out") was a good rule that had exactly one legitimate exception, and finding out why it was an exception taught me more than following it would have.

Sometimes the file you are looking for does not exist because the number was never a file.

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs — without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.

Any feedback or contributors are welcome! It's online, source-available, and ready for anyone to use.

⭐ Star it on GitHub:

HexmosTech / git-lrc

Free, Micro AI Code Reviews That Run on Git Commit

git-lrc

Free, Micro AI Code Reviews That Run on Commit

git-lrc is your braking system. It hooks into git commit and runs an AI review on every diff before it lands. 60-second setup. Completely free.

In short, git-lrc helps Prevent Outages, Breaches, and Technical Debt Before They Happen

At a glance: 10 risk categories · 100+ failure patterns tracked · every commit…

View on GitHub

ratatop day 2: the memory box, and the lie in `free -h`

Athreya aka Maneshwar — Wed, 29 Jul 2026 22:08:04 +0000

Yesterday I got the CPU box working in ratatui and wrote up my first impressions coming from Bubble Tea.

Today: memory.

I assumed this would be the easy one.

CPU needed delta tracking between samples, per-core bookkeeping, braille bit twiddling. Memory is just a file with numbers in it.

Read it, print it, go home.

Reader, it was not the easy one.

Free memory is not free memory

Look at that box again. Total 13.5 GiB. Free: 271 MiB.

Two percent free. That sounds like a machine about to fall over.

It is completely fine. I have 7.10 GiB available right now.

This is the thing that trips up everyone reading /proc/meminfo for the first time, and it tripped me up too.

MemFree means memory the kernel is doing absolutely nothing with. Not caching a file, not buffering a write, nothing. Just sitting there.

And the kernel hates that. Unused RAM is wasted RAM. So it fills spare memory with page cache, and hands it back the instant a process actually needs it.

So MemFree on a healthy machine trends toward zero, by design. It is a measure of how much RAM your kernel is failing to put to work.

The number you actually want is MemAvailable, added to the kernel in 3.14 precisely because everyone was misreading MemFree.

It is an estimate of how much you can allocate right now without swapping, and it accounts for the fact that most of that cache is reclaimable.

Note that Used and Available add up to Total, but Cached and Free do not slot in neatly beside them.

Cached memory is counted inside available. They overlap.

Trying to make all four sum to total is a trap, and I definitely tried for a bit.

Meme 1
Template: Bernie Sanders "I am once again asking"
Text: "I am once again asking you to stop reading MemFree"

So how do you compute "used"?

Here is where I went looking at how btop does it instead of inventing my own.

The obvious approach is to add up the parts.

Total minus free minus cached minus buffers, something like that.

This is what a lot of tools did historically, and it is where the old "Linux ate my RAM" confusion comes from.

btop does the simple thing instead:

used = MemTotal - MemAvailable

That is it. Let the kernel do the hard estimate, because it is the only thing that actually knows what is reclaimable.

In Rust, my collector boils down to this:

pub struct Memory {
    pub total: u64,
    pub used: u64,
    pub available: u64,
    pub cached: u64,
    pub free: u64,
}

Plain u64 bytes, no units baked in. Formatting is the UI's problem, not the collector's.

The bug that a substring gave me for free

/proc/meminfo looks like this:

MemTotal:       14177796 kB
MemFree:          497404 kB
MemAvailable:    7490900 kB
Buffers:         1235656 kB
Cached:          5146132 kB
SwapCached:        81068 kB

Spot the landmine.

SwapCached contains the substring Cached.

If you parse this with a contains or a loose prefix match, SwapCached arrives four lines later and quietly overwrites your real cached value with something roughly 60 times smaller.

Your box renders. No error. No panic. Just a wrong number sitting there looking plausible.

The fix is boring: split on the colon, match the label exactly.

let Some((label, rest)) = line.split_once(':') else {
    continue;
};

match label {
    "MemTotal" => mem.total = bytes,
    "MemFree" => mem.free = bytes,
    "MemAvailable" => available = Some(bytes),
    "Cached" => mem.cached = bytes,
    _ => {}
}

I wrote a test named swap_cached_does_not_get_mistaken_for_cached purely so the next person who "simplifies" this parser gets caught.

Also worth knowing: the kB suffix in that file is a lie too. Those are KiB, 1024 bytes, not 1000. So the multiply is << 10, not * 1000.

Three significant figures, and why

Look at the value column again:

13.5 GiB
6.42 GiB
 271 MiB

Different decimal counts. That is deliberate, and it is what btop does.

The rule is three significant figures, always. Under 10, you get two decimals. Between 10 and 100, one. Above 100, none. The number is always exactly three digits wide, so the column stays aligned no matter what the values do.

let decimals = if unit == 0 || value >= 100.0 {
    0
} else if value >= 10.0 {
    1
} else {
    2
};

Small thing. But a column that jitters between 6.4 GiB and 13.52 GiB looks amateurish in a way you feel before you can name it.

One thing I got wrong on the first pass: my loop divided by 1024 while the value was too large, with no guard on the unit table.

Feed that a u64::MAX and it walks straight off the end of the array.

Now it stops at TiB, with a test that passes u64::MAX specifically.

Where ratatui made this pleasant

Two things stood out building a second box.

Each field gets its own gradient. btop's theme gives used, available, cached and free their own three-stop colour ramps, and I lifted the exact hex values out of btop_theme.cpp.

Because a Gradient is just a value in my code, colouring a meter is passing a different one in:

for (label, value, gradient) in [
    ("Used:",      mem.used,      theme::MEM_USED),
    ("Available:", mem.available, theme::MEM_AVAILABLE),
    ("Cached:",    mem.cached,    theme::MEM_CACHED),
    ("Free:",      mem.free,      theme::MEM_FREE),
] {
    render_value(inner, &mut y, label, value, buf);
    render_meter(inner, &mut y, mem.percent(value), gradient, buf);
}

Immediate mode really pays off here.

There is no widget to construct, register, style and later mutate.

You are in a loop, you have a Rect, you draw. Four fields, four iterations, done.

The meter widget was already written. I built it for the CPU bar on day one, and reusing it for memory took zero changes.

That is the nice consequence of ratatui's Widget trait being tiny: a widget is a struct plus one render method, so a generic one you wrote yesterday just works today.

I did briefly add a Meter::braille() method to make the memory bars look different. Then I noticed it returned self completely unchanged, doing nothing but making the call site read fancier. Deleted it. A method that lies about doing something is worse than no method.

Restructuring, because two boxes is a crowd

Day one had everything in one ui.rs. That was fine for one box and immediately wrong for two.

flowchart TD
    M["ui/mod.rs<br/>splits the terminal, paints background"]
    M --> C["ui/cpu.rs<br/>bar, cores, load"]
    M --> Mem["ui/mem.rs<br/>values, meters, formatting"]
    C --> W["widgets/<br/>BrailleGraph, Meter"]
    Mem --> W
    C --> Col["collect/cpu.rs"]
    Mem --> Col2["collect/mem.rs"]

The useful change was moving layout decisions up.

Previously main.rs computed the box rectangle itself, which was fine when there was exactly one box and completely wrong the moment memory needed the leftover height.

Now main.rs hands over the entire terminal and ui::render decides who gets what:

let [cpu_area, rest] = Layout::vertical([
    Constraint::Length(cpu_height),
    Constraint::Min(0),
])
.areas(area);

CPU takes the top, memory takes a fixed width below it, and the rest stays empty for the network and process boxes.

Adding a box is now a matter of carving another Rect out of rest.

What's next

Network, probably. /proc/net/dev is another counter file, so it needs the same delta treatment the CPU box uses, plus auto-scaling units because network speeds swing across five orders of magnitude.

Then processes, which is the big one. That is where /proc/[pid]/stat lives, and where I suspect I will learn a great deal about how many edge cases a process table has.

Code so far: lovestaco/ratatop.

If you take one thing from this post, make it this: stop looking at free. Look at available. Your machine is fine.

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs — without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.

Any feedback or contributors are welcome! It's online, source-available, and ready for anyone to use.

⭐ Star it on GitHub:

HexmosTech / git-lrc

Free, Micro AI Code Reviews That Run on Git Commit

git-lrc

Free, Micro AI Code Reviews That Run on Commit

git-lrc is your braking system. It hooks into git commit and runs an AI review on every diff before it lands. 60-second setup. Completely free.

In short, git-lrc helps Prevent Outages, Breaches, and Technical Debt Before They Happen

At a glance: 10 risk categories · 100+ failure patterns tracked · every commit…

View on GitHub

Building ratatop: a Rust System Monitor with ratatui

Athreya aka Maneshwar — Tue, 28 Jul 2026 12:24:46 +0000

For a long while now I've been trying to learn how to build TUI apps.

Last month I made peektea, a keyboard-driven terminal file browser. The whole journey is written up here: the peektea series.

lovestaco / peektea

Peek First. Open Later. A TUI file browser built with bubble tea

A minimal terminal file browser built with Bubble Tea.

Peek through your filesystem with arrow keys (or vim keys), then pour each file straight into the app you've configured for it.

Demo

A quick peek before you steep Click below to watch the demo on YouTube (7m), or scroll down to see gif (10s) demo in gif version

Install

One-liner:

curl -fsSL https://raw.githubusercontent.com/lovestaco/peektea/master/scripts/install.sh | sh

Download a binary (no Go required) — grab the latest release for your platform from the releases page:

Platform	File
Linux x86-64	`peektea_*_linux_amd64.tar.gz`
Linux arm64	`peektea_*_linux_arm64.tar.gz`
macOS x86-64	`peektea_*_darwin_amd64.tar.gz`
macOS Apple Silicon	`peektea_*_darwin_arm64.tar.gz`

Extract and put the peektea binary anywhere on your $PATH.

Install with Go:

go install github.com/lovestaco/peektea@latest

Build from source:

git clone https://github.com/lovestaco/peektea
cd peektea
make install

make install puts the binary in ~/go/bin and figures out $PATH for you:

Already reachable — done, nothing to do.
~/.local/bin is on…

View on GitHub

That one was Bubble Tea with Go.

So I got curious about what the other side looks like.

What can Rust do here?

Which is how I landed on ratatui.

I'm connected to Orhun Parmaksız on LinkedIn, I keep seeing his posts about it on my feed, and eventually curiosity won.

So here we are.

I built a basic Linux visual monitor to learn the library:

For the next few days I'll be poking at this and writing down whatever I learn. This is post one.

So what is ratatui?

ratatui is a Rust library for building terminal user interfaces.

It grew out of tui-rs, which went unmaintained back in 2023, and a group of folks picked it up and ran with it.

Orhun is one of the maintainers.

The name is a Ratatouille joke, and honestly the film's whole "anyone can cook" thing turned out to be the right energy for a first project.

You do not need to be a Rust wizard to get something on screen.

One thing to get straight early: ratatui is a library, not a framework.

Bubble Tea hands you an architecture.

You fill in Model, Update, View, and it runs the show.

ratatui hands you a drawing surface and says good luck.

That difference is the whole post, really.

The thing that broke my brain first

Bubble Tea is built on the Elm Architecture.

State goes in, messages come back, you return a new model, the framework re-renders.

It is retained and it is opinionated.

ratatui is immediate mode.

There is no widget tree living in memory between frames.

There is no View() that the framework calls for you.

Every single frame, you build the widgets from scratch, draw them, and throw them away.

Coming from Bubble Tea this felt wrong for about a day.

Where does the state live? Wherever you want. Who calls the render? You do. When do widgets get cleaned up? They were never alive.

Then it clicked, and it felt great.

No lifecycle, no diffing your own state, no "why did this component not re-render".

You want something on screen, you draw it.

Every frame.

The catch is that "you own the loop" also means you own everything else.
Quitting, resizing, timing, keyboard input, all of it is yours now.

The entire app is one loop

Here is genuinely the whole shape of a ratatui program:

fn main() -> std::io::Result<()> {
    let mut terminal = ratatui::init();   // alt screen + raw mode
    let result = run(&mut terminal);
    ratatui::restore();                   // put the terminal back
    result
}

fn run(terminal: &mut DefaultTerminal) -> std::io::Result<()> {
    loop {
        terminal.draw(|frame| {
            let hello = Paragraph::new("hello from the kitchen");
            frame.render_widget(hello, frame.area());
        })?;

        if event::poll(Duration::from_millis(100))? {
            if let Some(key) = event::read()?.as_key_press_event() {
                if key.code == KeyCode::Char('q') {
                    return Ok(());
                }
            }
        }
    }
}

ratatui::init() is the modern convenience wrapper.

It flips on raw mode and switches to the alternate screen buffer, the same trick vim and htop use so your shell history stays clean when you quit.

In peektea that was tea.WithAltScreen().

Same idea, different kitchen.

ratatui::restore() puts everything back.

Worth wiring this into a panic hook too, because a Rust panic inside raw mode leaves your terminal in a genuinely cursed state.

Input is not ratatui's job at all.

That comes from crossterm, which ratatui re-exports as ratatui::crossterm so your versions cannot drift apart.

event::poll with a timeout is what keeps the loop from blocking, so you can redraw on a timer instead of only on keypress.

Everything is a Rect

The core layout idea is small: you have a Rect, and you cut it into smaller Rects.

let [header, body, footer] = Layout::vertical([
    Constraint::Length(1),   // exactly one row
    Constraint::Min(0),      // whatever is left over
    Constraint::Length(1),   // exactly one row
])
.areas(area);

That .areas() returning a fixed-size array is lovely.

The compiler checks that you destructured exactly three areas from three constraints.

Get it wrong and it does not build.

The constraint types cover most of what you want:

Length(n) for exact cells
Min(n) and Max(n) for flexible with a bound
Percentage(n) and Ratio(a, b) for proportional
Fill(weight) for splitting leftovers by weight

There is also .spacing(n) to put gaps between chunks, and .flex(Flex::Center) to control where slack goes when your constraints do not fill the space.

I used Flex::Center to centre a box, then swapped it to Flex::Start to pin it to the top of the terminal.

One enum, done.

Nesting is just calling Layout again on one of the pieces you got back.

That is the whole layout system.

Widgets are cheap, disposable, and consumed

A widget in ratatui is a plain value that gets eaten when you draw it.

The trait is literally:

pub trait Widget {
    fn render(self, area: Rect, buf: &mut Buffer);
}

Note self, not &self. It is consumed.

You are not holding onto it.

Stock widgets get you surprisingly far.

Block is the bordered container, and it composes nicely:

let block = Block::default()
    .borders(Borders::ALL)
    .border_type(BorderType::Rounded)     // ╭─╮ instead of ┌─┐
    .title("CPU")
    .title_bottom(Line::from("q to quit").right_aligned());

let inner = block.inner(area);   // the area inside the borders
block.render(area, buf);

block.inner(area) is the one to remember.

It gives you the space inside the border so your content does not get eaten by the frame.

For text, the hierarchy is Span (styled string) inside Line (a row) inside Text (many rows):

Line::from(vec![
    Span::styled("C", Style::default().fg(Color::Red)),
    Span::styled("PU", Style::default().fg(Color::White)),
])

There is also a Stylize trait that makes this much less shouty, giving you "CPU".red().bold() directly on string literals.

Very nice for quick work.

When the stock widgets are not enough

This is where it got fun.

The look I was going after uses braille characters to fit more resolution into a terminal cell.

Each braille glyph is a 2x4 grid of dots, so one character cell holds 8 addressable points instead of 1.

No stock widget does that. So you write one. You implement Widget, you get a Buffer, and you set cells directly.

impl Widget for MyGraph<'_> {
    fn render(self, area: Rect, buf: &mut Buffer) {
        let cell = &mut buf[(x, y)];
        cell.set_char('⣿');
        cell.set_style(Style::default().fg(Color::Green));
    }
}

Buffer is a flat grid of Cells, where each cell holds a symbol plus its style. That is the entire drawing surface.

Once you realise a custom widget is just "write characters into a grid", the intimidation factor drops off a cliff.

Then I spent an embarrassing amount of time on the fact that braille dot numbering is not sequential.

The bits go 1, 2, 3 down the left column, 4, 5, 6 down the right, and then 7 and 8 got bolted on later as a fourth row.

So the bitmask is 0x01, 0x02, 0x04, 0x40 on the left and 0x08, 0x10, 0x20, 0x80 on the right.

That 0x40 sitting where 0x08 should be is a 19th century design decision reaching out to ruin your afternoon.

Worth it though.

The payoff is graphs that look like graphs instead of blocks.

The one mistake worth confessing

While drawing per-core graphs, I decided that any non-zero reading should light at least one dot.

My reasoning: an idle core showing literally nothing looks broken.

Reasonable. Also completely wrong.

The aggregate CPU line is never zero.

So every single column got exactly one dot, and my beautiful history graph rendered as a perfectly flat line, all the way across, forever.

I had built a very expensive way to draw a dash.

The fix was to delete my clever bit and let low values round down to blank.

Those gaps are the entire texture.

Letting values fall to nothing is what makes it look alive.

How a frame actually reaches your terminal

Last piece, because it explains a debugging trap I fell into.

ratatui keeps two buffers and only emits the cells that actually changed.

That is why redrawing everything every frame is not wasteful.

The trap: I tried to test a feature by piping the app's output and grepping for a string I expected on screen.

Found nothing, assumed the feature was broken. It was not.

Because of the diffing, a changed value never appears as a contiguous string in the output stream. It arrives as a few individual cells with cursor moves between them.

Lesson: test your state and your widgets, not the escape codes.

What I'd cook next

Loading theme files so colours are not hardcoded
More collectors, because right now it only knows about the CPU
Actually reading the ratatui tutorials properly instead of learning by flailing

If you've been on the fence about TUIs, ratatui is a genuinely nice place to start.

The API is small, the docs are good, and the immediate mode model means there is very little machinery hiding from you.

Code is here if you want a look: lovestaco/ratatop

lovestaco / ratatop

Keep an eye on what's cooking in your system

A reimplementation of btop in Rust, built on ratatui.

Status

The CPU box works. It samples real data and renders btop's layout:

Per-core braille history graphs, a gradient load bar with sub-cell resolution frequency, package temperature, battery, and load averages.

Everything else, the memory, network, and process boxes, is still to come.

Design notes

Data source: /proc and /sys on Linux first, read directly rather than shelling out. btop's src/linux/btop_collect.cpp is the reference for what to read and how often; the BSD/macOS collectors are out of scope for v1.
Graphs are the hard part. btop's look comes from braille sub-cell plotting with a color gradient applied along the value axis, not from a stock chart widget. Expect…

View on GitHub

More soon. Anyone can cook.

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.

Any feedback or contributors are welcome! It's online, source-available, and ready for anyone to use.

⭐ Star it on GitHub:

HexmosTech / git-lrc

Free, Micro AI Code Reviews That Run on Git Commit

git-lrc

Free, Micro AI Code Reviews That Run on Commit

git-lrc is your braking system. It hooks into git commit and runs an AI review on every diff before it lands. 60-second setup. Completely free.

In short, git-lrc helps Prevent Outages, Breaches, and Technical Debt Before They Happen

At a glance: 10 risk categories · 100+ failure patterns tracked · every commit…

View on GitHub

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs — without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.

Any feedback or contributors are welcome! It's online, source-available, and ready for anyone to use.

⭐ Star it on GitHub:

HexmosTech / git-lrc

Free, Micro AI Code Reviews That Run on Git Commit

git-lrc

Free, Micro AI Code Reviews That Run on Commit

git-lrc is your braking system. It hooks into git commit and runs an AI review on every diff before it lands. 60-second setup. Completely free.

In short, git-lrc helps Prevent Outages, Breaches, and Technical Debt Before They Happen

At a glance: 10 risk categories · 100+ failure patterns tracked · every commit…

View on GitHub

A VPN Is a Lie You Tell Your Kernel

Athreya aka Maneshwar — Mon, 27 Jul 2026 12:24:24 +0000

A VPN is mostly a polite lie you tell your kernel. Here is how EdgeVPN tells it without a single central server, explained by actually reading the Go

I have used VPNs for years without really knowing what one is.

I typed wg-quick up, saw a new interface show up in ip a, and moved on with my life.

Classic dev move: it works, ship it, never look inside.

Then I found EdgeVPN, a VPN written in Go that has no central server at all.

You generate a token, paste it on two machines, and they find each other across the internet and start routing packets.

No control plane, no 10.0.0.1 server you have to keep alive, no cloud bill.

That sounded suspiciously like magic, so I did the only reasonable thing and read the whole codebase.

This post is me walking you through what I found, from "what even is a network interface" all the way down to how a single IP packet crosses the planet without anyone in charge.

Grab a coffee. This one has depth.

First, the uncomfortable truth about VPNs

A VPN is not a tunnel.

A VPN is a lie you tell your operating system, and the OS is very willing to believe you.

Here is the trick.

Linux (and macOS, and Windows) lets you create a TUN device.

It looks like a normal network interface, it shows up in ifconfig, it has an IP, the kernel happily routes traffic to it.

But it is not connected to any hardware.

It is connected to a file descriptor that your program holds.

That is the whole thing. Really:

Your program reads from that file descriptor, and it gets IP packets the kernel wanted to send out.
Your program writes to that file descriptor, and the kernel believes those packets just arrived from the network.

Everything else a VPN does (encryption, peer discovery, routing) is just deciding what happens in the gap between that read and that write.

If you can move bytes from machine A's file descriptor to machine B's file descriptor, congratulations, you have written a VPN.

Everything after this is engineering.

Here is EdgeVPN's read loop, and it is honestly almost anticlimactic:

func getFrame(ifce io.Reader, c *Config) (ethernet.Frame, error) {
    var frame ethernet.Frame
    frame.Resize(c.MTU)

    n, err := ifce.Read([]byte(frame))
    if err != nil {
        return frame, errors.Wrap(err, "could not read from interface")
    }

    frame = frame[:n]
    return frame, nil
}

That is it. That is the interface. ifce is the TUN device, read gives you a raw packet, and now it is your problem.

The hard part is not tunneling, it is the phone book

Now the real question.

Machine A wants to send a packet to 10.1.0.13.

Machine A reads that packet off the TUN device. Cool. Where does it send it?

10.1.0.13 is a made up address.

It exists only inside your virtual network.

Somewhere out there is a real machine, behind a real NAT, with a real (and probably changing) public IP, that has claimed that made up address.

Something has to map one to the other.

WireGuard solves this by making you do it by hand.

You write AllowedIPs and an Endpoint in a config file for every peer.

It is simple, fast, and it does not scale to "I have twelve laptops behind twelve different routers and one of them is my friend's Raspberry Pi."

Traditional VPNs solve it with a server.

The server knows everyone, everyone talks to the server, the server is the phone book. Also the server is the single point of failure, the single point of trust, and the single thing you have to pay for.

EdgeVPN solves it with a gossiped ledger, which is a fancy way of saying: every node keeps shouting what it knows, and everyone eventually agrees. Let me build up to it.

The token is the entire network

Everything starts with one command:

edgevpn -g > config.yaml
# or, as a portable token
export EDGEVPNTOKEN=$(edgevpn -g -b)

The token is just that YAML, base64'd. Nothing more. Decode one and you get roughly this:

otp:
  dht:
    interval: 9000
    key: 7Kx...43-random-chars...
    length: 43
  crypto:
    interval: 9000
    key: Qz9...43-random-chars...
    length: 43
room: bT2...43-random-chars...
rendezvous: mP4...43-random-chars...
mdns: xL8...43-random-chars...
max_message_size: 20971520

Five random strings and two intervals.

No IPs, no hostnames, no server address, no certificates.

This file is your network.

Which brings us to the most important sentence:

Warning Exposing this file or passing-it by is equivalent to give full control to the network.

Hold that thought, we are coming back to it with receipts.

The clever bit is those otp blocks.

Those keys are not used directly.

They are fed into TOTP, the same algorithm behind the 6 digit codes in your authenticator app, except tuned to spit out a long base64 string instead:

func TOTP(f func() hash.Hash, digits int, t int, key string) string {
    cfg := otp.Config{
        Hash:     f,      // sha256 here
        Digits:   digits, // 43
        TimeStep: otp.TimeWindow(t), // 9000 seconds
        Key:      key,
        Format: func(hash []byte, nb int) string {
            return base64.StdEncoding.EncodeToString(hash)[:nb]
        },
    }
    return cfg.TOTP()
}

So every 9000 seconds (2.5 hours), every node in the network independently derives the same new secret, without talking to each other.

Time is the only coordination they need. This gets used for two different things, and both are neat.

Step 1: finding each other at a rotating rendezvous

To meet a stranger on the internet you need a place to meet.

EdgeVPN uses the IPFS Kademlia DHT as that meeting point, announcing itself under a key that is just TOTP(dht.key).

So your rendezvous on a public hash table moves every couple of hours.

A watcher sees peers cluster around a random looking key, then that key goes cold forever.

One subtle trap, nicely handled: if everyone rotates at exactly time T, a node with a skewed clock rotates early and for a moment nobody finds anybody.

So the DHT announces on the last two rendezvous points at once:

rendezvousHistory: Ring{Length: 2}

Overlapping windows. Unglamorous, and exactly the difference between "works in the demo" and "works at 3am".

On a LAN, mDNS does the same job with the mdns string as the service tag.

Here is the full bootstrap:

Notice the ordering. Peers connect first, and then they exchange the routing table.

The routing table travels over the p2p network it describes. Bootstrapping is fun.

Step 2: the gossip room, sealed twice

Connected peers join a GossipSub topic named from the other OTP.

libp2p already encrypts every connection, and EdgeVPN still wraps another AES layer around each message, keyed the same rotating way:

func (e *Node) sealkey() string {
    return internalCrypto.MD5(internalCrypto.TOTP(sha256.New, e.config.SealKeyLength, e.config.SealKeyInterval, e.config.ExchangeKey))
}

Why double up? The rendezvous is public, so anyone can find the topic and subscribe.

Transport encryption protects the hop, not the payload from someone who legitimately joined the room.

The seal means a lurker hears noise, and since the key retires every 2.5 hours, brute forcing captured traffic chases a key nobody uses anymore.

Layers of secrets, rotating on a timer, all from one shared string. Most elegant idea in the codebase.

Step 3: the ledger, or "eventual consistency by shouting"

Now the phone book. EdgeVPN keeps a tiny blockchain. Before you close the tab: no proof of work, no mining, no coin.

It is a chain of blocks purely for cheap ordering, and each block carries a map[bucket]map[key]value.

The buckets are hardcoded constants that read like a table of contents for the whole product:

const (
    FilesLedgerKey    = "files"
    MachinesLedgerKey = "machines"
    ServicesLedgerKey = "services"
    UsersLedgerKey    = "users"
    HealthCheckKey    = "healthcheck"
    DNSKey            = "dns"
    EgressService     = "egress"
    TrustZoneKey      = "trustzone"
    TrustZoneAuthKey  = "trustzoneAuth"
)

The routing table is just the machines bucket keyed by virtual IP.

Every feature here is "write to a bucket, read other people's writes".

Once that clicked the codebase went from clever to obvious, which is the best thing you can say about an architecture.

Conflict resolution is beautifully blunt:

last := l.blockchain.Last()
if block.Index > last.Index ||
    (block.Index == last.Index && block.Hash > last.Hash) {
    l.blockchain.Add(*block)
}

Highest block wins, ties broken by higher hash so every node breaks them identically. Whole block replace, no vector clocks, no Raft.

"But that loses writes," you say. Yes! And it does not matter, because every node reannounces its own state on a ticker until it sees itself reflected in the chain.

Read it, check if the world agrees with you, and if not, say it again. Louder. Forever.

The system converges not because the merge is smart but because everyone is relentlessly repetitive.

Wipe the entire chain and the nodes refill it in seconds.

The tradeoff is real and the docs own it: every block goes to every peer, so this is chatty by design.

Fine for a routing table, which is why the README warns you off latency sensitive workloads.

Step 4: an actual packet, end to end

Here is the life of one ping, with the real function names.

The lookup is where every piece meets:

value, found := ledger.GetKey(protocol.MachinesLedgerKey, dst)
if !found {
    return notFoundErr
}
machine := &types.Machine{}
value.Unmarshal(machine)

// Decode the Peer
d, err = peer.Decode(machine.PeerID)

Virtual IP goes in, libp2p peer ID comes out.

That one lookup replaces the entire VPN server, and libp2p handles the rest: NAT traversal, hole punching, relays, encryption, multiplexing.

The receiving end checks the sender against that same ledger before copying a byte, and resets the stream otherwise.

If you are not in my routing table, I will not read your packets.

Two jobs, one map.

The bit I did not expect to enjoy: leaderless leader election

Every node drops a timestamp into a healthcheck bucket, and anyone older than maxtime counts as gone.

But some jobs need exactly one node to run them (scrubbing stale entries, handing out IPs).

With no server, who decides? This:

func Leader(actives []string) string {
    leaderboard := map[string]uint32{}
    leader := actives[0]

    for _, a := range actives {
        leaderboard[a] = hash(a) // fnv32a
        if leaderboard[leader] < leaderboard[a] {
            leader = a
        }
    }
    return leader
}

Hash every live peer ID, highest wins. No votes, no terms, no Raft.

Every node computes it locally and agrees, because the ledger already synced the input.

When the leader dies it falls out of the healthcheck bucket, everyone recomputes, and a new leader appears with zero messages exchanged.

Is it Paxos? No. Does deciding who deletes stale map entries need Paxos? Also no. Right sized engineering is underrated.

Same trick powers the built in DHCP: nodes without an IP wait, the leader among them takes the lowest free one, next node repeats.

Distributed DHCP with no DHCP server, built from a hash function and patience.

Now, about that token

Remember that warning. In the default config, holding the token lets you write anything into any bucket. Including this:

machines/10.1.0.13 -> { PeerID: "my-peer-id-actually" }

Congratulations, you just hijacked someone's virtual IP and every node will happily route their traffic to you.

The routing table has no concept of who owns which key.

That is the sort of thing you only catch by reading source, and to their credit the project keeps layering in defenses.

PeerGuardian (pkg/trustzone) adds ECDSA challenge and response, so the token alone does not get you in.

Relay ACL (pkg/config/relay_acl.go) gates who can use you as a circuit relay, with an open bootstrap window because a NAT'd peer often needs a relay before it can prove membership. Chicken and egg, at the network layer.

The good one is ledger ownership (pkg/blockchain/sign.go): sign every entry with the node's libp2p key and enforce per key ownership on merge, in three modes, off, observe, enforce.

That middle mode is the detail I liked most.

Turn it on in a live network, watch the violation logs for a week, then flip to enforce.

That is how you ship a breaking security change to something you cannot restart all at once.

The README also says it plainly: "I'm not a security expert, and this software didn't went through a full security audit".

Respect for that instead of stamping "military grade encryption" on a landing page.

The layer cake

Zooming out, here is how the whole thing stacks.

Everything above the node is optional and plugs into the same two extension points:

The dotted lines matter. Control traffic (who owns what) goes through the gossip ledger, slowly and to everyone.

Data traffic (your actual packets) goes point to point over a dedicated libp2p stream protocol, directly to the one peer that needs it.

Mixing those up is how you build something that falls over at four nodes.

The extension seam is two types, and once you see them you can read any feature in the repo:

// something long running that gets the node and the ledger
type NetworkService func(context.Context, Config, *Node, *blockchain.Ledger) error

// something that handles a raw stream for a given protocol ID
type StreamHandler func(*Node, *blockchain.Ledger) func(stream network.Stream)

The VPN is a NetworkService. So is DNS. So is the file transfer. So is the healthcheck.

Adding a feature means picking a bucket name, announcing into it, and optionally claiming a protocol ID for the data path.

That is the whole framework.

What I actually took away

Coordination is the actual product. WireGuard says "you coordinate, I will be fast". Commercial VPNs say "a server coordinates, pay us". EdgeVPN says "we gossip until we agree". The question was never encryption.

Repeating yourself beats being clever. Every node reannounces its own truth forever, so the merge logic gets to be ten dumb lines and still heals from total data loss. Idempotent shouting as a consistency model. I am stealing this.

Go read some source code. The scariest part of most systems is the part you have not looked at yet, and it is usually about 300 lines.

Repo is github.com/mudler/edgevpn, docs are here, and libp2p's docs are where the real dark magic lives.

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs — without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.

Any feedback or contributors are welcome! It's online, source-available, and ready for anyone to use.

⭐ Star it on GitHub:

HexmosTech / git-lrc

Free, Micro AI Code Reviews That Run on Git Commit

git-lrc

Free, Micro AI Code Reviews That Run on Commit

git-lrc is your braking system. It hooks into git commit and runs an AI review on every diff before it lands. 60-second setup. Completely free.

In short, git-lrc helps Prevent Outages, Breaches, and Technical Debt Before They Happen

At a glance: 10 risk categories · 100+ failure patterns tracked · every commit…

View on GitHub

How terminal-sharing tools put your shell in a browser

Athreya aka Maneshwar — Sun, 26 Jul 2026 16:43:17 +0000

You have probably done this dance.

You are debugging something on a box, your teammate says "can you just show me", and you end up screen sharing a 4K monitor over a video call so they can squint at 11px monospace text that has been compressed into oatmeal.

There is a better way, and it has existed for years.

Tools like ttyd, TermPair, and sshx put your actual terminal in someone else's browser. Real text. Real selection.

Real copy paste.

I got curious about how they pull this off, so I cloned all three and read them.

Turns out they are solving the same problem in three very different ways, and the differences are genuinely interesting.

Let's get shell shocked together.

what even is a terminal

Before any of the web stuff makes sense, you need one concept: the pseudoterminal, or PTY.

When you run bash in your terminal app, bash is not talking to your keyboard.

It is talking to a file.

Specifically, a pair of linked file descriptors that the kernel sets up to impersonate an actual physical teletype from 1965.

One end is the master, one end is the slave.

Your terminal emulator holds the master. Bash holds the slave, and bash has no idea it is being catfished.

Anything you write to the master shows up as keyboard input to bash. Anything bash prints comes back out of the master.

That is the entire trick.

Terminal sharing tools are just programs that hold the master end and forward those bytes somewhere more interesting than a window on your laptop.

Here is sshx doing exactly that, in crates/sshx/src/terminal/unix.rs:

use nix::pty::{self, Winsize};
use nix::unistd::{execvp, fork, ForkResult, Pid};
use nix::libc::{login_tty, TIOCGWINSZ, TIOCSWINSZ};

pub struct Terminal {
    child: Pid,
    master_read: File,
    master_write: File,
}

Fork, call login_tty in the child so the slave fd becomes its controlling terminal, execvp the shell, and keep the master in the parent.

ttyd does the same thing in C.

TermPair does it in Rust.

Three codebases, one ancient POSIX handshake.

Everyone takes the same fork in the road.

Oh, and TIOCSWINSZ is how the terminal size gets set.

When you resize your browser window, that ioctl is what eventually fires so that vim redraws correctly instead of smearing itself across the screen.

Resize handling is not a nice-to-have here, it is load bearing.

The simplest possible version: ttyd

ttyd is the "no, seriously, that's it" implementation.

One C process, built on libwebsockets and libuv.

It is the web server and it is the terminal host.

There is no relay, no separate client, no key exchange.

The protocol is beautifully dumb. From src/server.h:

// client -> server
#define INPUT           '0'
#define RESIZE_TERMINAL '1'
#define PAUSE           '2'
#define RESUME          '3'
#define JSON_DATA       '{'

// server -> client
#define OUTPUT            '0'
#define SET_WINDOW_TITLE  '1'
#define SET_PREFERENCES   '2'

Single byte opcode, then payload. That is the whole wire format.

'0' plus your keystrokes goes up, '0' plus terminal output comes down.

PAUSE and RESUME exist because a fast-scrolling cat of a huge file can outrun the browser, so the client can apply backpressure instead of dying.

Here is the full round trip:

Two details worth stealing from ttyd:

The frontend ships inside the binary.

The Preact and xterm.js app in html/ gets bundled, gzipped, and inlined into src/html.h as a C byte array.

You get a single executable with no static file directory to misplace.

The tradeoff is that touching a .tsx file means running yarn run inline and then rebuilding the C binary, which surprises people exactly once.

It is read only by default. You have to pass -W to let viewers actually type.

ttyd -p 7681 -c user:pass -O -W bash

That said, ttyd's threat model is "you trust the server, because the server is your machine."

The bytes are plaintext over the wire unless you turn on TLS.

Which brings us to the interesting question.

What if you don't trust the server?

The moment you want to share a terminal with someone across the internet, you need a middleman with a public IP. And now that middleman can read everything you type.

TermPair and sshx both took that guy's advice.

They make the server a blind relay: it routes ciphertext between the terminal host and the browsers, and it structurally cannot decrypt any of it.

Green means "can read your terminal."

The whole game is shrinking the green.

The key delivery trick

So the client encrypts and the browser decrypts. Both need the key.

The server must not have it. But the browser gets its entire existence from the server.

How do you hand a secret to a page that the server itself sent you?

The answer is a URL fragment.

https://sharemyclau.de/s/abc123#key-goes-right-here

Everything after # is never sent in the HTTP request.

It is a client side construct.

Browsers use it for anchor scrolling and hash routing, and it stays in the address bar and in JavaScript's location.hash while the server sees only /s/abc123.

So you share one link, the recipient's browser reads the key out of its own address bar, and the relay in the middle sees an opaque session ID and a stream of noise.

Here is the flow end to end:

The security of this rests entirely on the link. Anyone who gets the full URL gets the session.

Don't paste it in a public Slack channel and then act surprised.

Two flavors of crypto

TermPair and sshx both do AES, but they made different calls, and the differences are instructive.

TermPair: AES-128-GCM with counter IVs

From crates/termpair-common/src/encryption.rs:

pub fn iv_from_count(count: u64) -> [u8; IV_LENGTH] {
    let mut iv = [0u8; IV_LENGTH];
    let bytes = count.to_le_bytes();
    iv[..bytes.len()].copy_from_slice(&bytes);
    iv
}

GCM gives you authentication for free, so a tampered message fails to decrypt rather than quietly turning into garbage that your terminal then interprets as escape sequences.

The IV is a plain message counter, which is fine and correct as long as you never reuse one with the same key.

Nonce reuse in GCM is not a "slightly weaker" situation, it is a "here is your key, thanks for playing" situation.

Which is why constants.rs has this:

pub const ROTATION_THRESHOLD: u64 = 1 << 20;
pub const MAX_MESSAGES_PER_KEY: u64 = ROTATION_THRESHOLD * 2;

After about a million messages, the key rotates.

There is a whole aes_key_rotation event in the protocol for it.

Separate keys for terminal output and browser input, plus a bootstrap key for the handshake, so the counter spaces cannot collide.

It is careful work, and the kind of thing that is invisible when it is done right.

sshx: Argon2 stretched key with AES-CTR

sshx made a different bet. From crates/sshx/src/encrypt.rs, with a comment I really enjoyed:

const SALT: &str =
    "This is a non-random salt for sshx.io, since we want to stretch the security of 83-bit keys!";

let hasher = Argon2::new(
    Algorithm::Argon2id,
    Version::V0x13,
    Params::new(19 * 1024, 2, 1, Some(16)).unwrap(),
);

The key in your URL is only 83 bits of entropy, because sshx wants the shareable link to stay short enough to actually paste in chat.

83 bits is not a lot by modern standards, so it runs Argon2id over it with real memory cost parameters. Brute forcing now costs 19MB and real CPU time per guess instead of a nanosecond.

It is a deliberate trade of raw entropy for ergonomics, paid back with a KDF.

Then it uses CTR mode with a clever addressing scheme:

pub fn segment(&self, stream_num: u64, offset: u64, data: &[u8]) -> Vec<u8> {
    assert_ne!(stream_num, 0, "stream number must be nonzero"); // security check
    let mut iv = [0; 16];
    iv[0..8].copy_from_slice(&stream_num.to_be_bytes());
    let mut cipher = Aes128Ctr64BE::new(&self.aes_key.into(), &iv.into());
    cipher.seek(offset);
    cipher.apply_keystream(&mut buf);
    buf
}

Because CTR mode is seekable, sshx can encrypt "the bytes at offset N of stream M" without touching anything before them.

That is not a crypto flex, it is an architecture decision: it means a browser that reconnects can say "I have everything up to byte 4096, send me the rest" and the server can serve that from its buffer.

Encryption and resumability designed together.

The assert_ne!(stream_num, 0) guard is there because stream 0 is used for the encrypted zeros block that proves you have the right key.

Reusing it would mean reusing a keystream.

Nice to see the security check written down instead of assumed.

The part that makes sshx feel fast

Here is my favorite detail in any of these codebases.

There is a fundamental problem with remote terminals: your keystroke has to go to the server, into the PTY, back out, and back to you before you see the character.

On a 200ms link, typing feels like moving through syrup.

sshx solves this the way Mosh does, with predictive echo. From src/lib/typeahead.ts:

// A terminal "local echo" or typeahead addon for xterm.js.
//
// This is forked from VSCode's typeahead implementation at
// https://github.com/microsoft/vscode/blob/1.80.1/...

The client guesses. You press k, it draws a k immediately (slightly dimmed) while the real round trip happens in the background.

When the server's actual output arrives, it reconciles.

If the guess was right, nothing visibly changes.

If it was wrong, because you were in vim or hitting a password prompt, it rolls back.

The tricky part is knowing when not to predict.

Predicting into a password prompt would echo your password onto the screen, which is a memorable way to lose a friend.

So the addon tracks terminal modes and bails out when it is not confident.

Getting a-head of the output, but politely.

Sessions, state, and the boring stuff that matters

The last layer is lifecycle. Sessions are long lived, connections are not. Wifi drops. Laptops sleep.

sshx handles this with sequence numbers in the protocol (crates/sshx-core/proto/sshx.proto):

message TerminalData {
  uint32 id = 1;
  bytes data = 2;
  uint64 seq = 3;  // Sequence number of the first byte
}

message SequenceNumbers {
  map<uint32, uint64> map = 1;  // Active shells and their sequence numbers
}

Every shell is a stream with a byte offset. On reconnect, the client sends where it left off and the server replays the difference.

Combined with seekable CTR encryption, resume is nearly free.

It also has to decide when to give up on a session:

/// Timeout for a disconnected session to be evicted and closed.
const DISCONNECTED_SESSION_EXPIRY: Duration = Duration::from_secs(300);

Five minutes without a backend client and the session is closed and dropped from the DashMap. Otherwise every crashed laptop leaks memory forever.

And because sshx runs a globally distributed mesh, session state also goes into Redis via crates/sshx-server/src/state/mesh.rs, so you can connect to the nearest server rather than always crossing an ocean.

TermPair, meanwhile, caps things with hard limits (MAX_TERMINALS: 200, MAX_BROWSERS_PER_TERMINAL: 50, MAX_WS_MSGS_PER_SEC: 500) which is the sensible answer when you are running one modest box instead of a mesh.

So which one should you use

Genuinely depends on what you are doing.

ttyd if the network is already trusted. Homelab, LAN, behind a VPN, embedded devices, an OpenWrt router. It is one small C binary with no runtime dependencies and it will outlive us all. ttyd -W bash and you are done.

TermPair if you want end to end encryption with a simple mental model and the option to self host the relay. The three-key design with rotation is easy to reason about and the code is small enough to read in an afternoon.

sshx if you want the polished product experience. Multiple terminals on an infinite canvas, other people's cursors moving in real time, predictive echo, global mesh, automatic reconnect. Worth noting the README says self hosting is explicitly not supported, so this is "use sshx.io" rather than "run your own."

The takeaway

Every one of these tools is, at its core, fork(), a PTY master fd, and a loop that shovels bytes into a WebSocket.

That part is 1970s technology wearing a 2020s hoodie.

Everything else, the encryption, the sequence numbers, the key rotation, the predictive echo, the session eviction, exists to answer one question: how much do you trust the machine in the middle? ttyd says "it's mine, so completely."

TermPair and sshx say "not at all, and here is the math."

Reading three implementations of the same idea side by side is the fastest architecture lesson I have had in a while.

If a concept keeps showing up in every version, it is essential.

If it only shows up in one, it is a product decision.

That distinction is hard to see from a single codebase and obvious from three.

Go clone them.

It is more fun than another framework tutorial, and you will never look at location.hash the same way again.

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs — without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.

Any feedback or contributors are welcome! It's online, source-available, and ready for anyone to use.

⭐ Star it on GitHub:

HexmosTech / git-lrc

Free, Micro AI Code Reviews That Run on Git Commit

git-lrc

Free, Micro AI Code Reviews That Run on Commit

git-lrc is your braking system. It hooks into git commit and runs an AI review on every diff before it lands. 60-second setup. Completely free.

In short, git-lrc helps Prevent Outages, Breaches, and Technical Debt Before They Happen

At a glance: 10 risk categories · 100+ failure patterns tracked · every commit…

View on GitHub