Blog | lillecarl

self-verifying agents: I built a VT multiplexer I don't understand

Sat, 10 Oct 2026 00:00:00 +0000

cmatrix in a background window pegged a whole core and drew five frames in five seconds. My multiplexer was working harder to show nothing than to show something. That multiplexer is pymux — Jonathan Slenders’ Python tmux, dead since 2017, which I forked and let agents rebuild: 820 commits since January, all agent-written except the prompts. I still can’t read VT by sight. CSI 4:1 m means nothing to me, and I stayed ignorant on purpose.

This post isn’t about pymux. It’s about the only agentic workflow I’ve seen actually work: the human builds the machine that checks the work, the agents do the work. My contribution is test facilities with mechanical verdicts. Pymux just fit that workflow like a glove, because terminal correctness is observable: six other emulators to vote, pixels to subtract, bytecode to count. Where correctness needs taste, agents guess — so the harness never asks them to.

The trick: I never let the agent decide what “correct” means. I made it count shit instead.

There is no spec, only whatever xterm does

VT “spec” is a polite fiction. The real spec is xterm’s mood that day, plus 40 years of programs that depend on its bugs.

Fuck documents. I test against six other terminals that hate each other: kitty, WezTerm, Alacritty, libvterm, Ghostty, xterm.js. C, Rust, Zig, TypeScript — different bloodlines, different bugs. Same bytes go into my widget (ptterm draws one terminal, pymux arranges several) and into all six, and the harness compares screens cell by cell.

xterm itself sits in the corner as a seventh oracle. It answers characters but no attributes over DECRQCRA, so it gets to comment but never vote. Fair. It invented the game.

A judge that can’t hold something abstains instead of lying. Only libvterm and WezTerm know what SGR 73 even is, so the rest sit that round out. The verdict stays dumb on purpose. Agree means ship it. ptterm-wrong means every voting judge agrees with each other and not with me, so I eat the bug. Split means the judges fight each other, so it’s taste, not a bug: write it down, touch nothing. No LLM judgment call anywhere. I just count shit.

The same harness flogs borrowed suites. esctest2 runs from the inside: 5 fails bare, 9 fails in a pane, and that delta is what pymux adds. vttest goes screen by screen. libvterm’s own 43 test files get turned around and fired at us (270 assertions). Alacritty’s 45 recordings of vim/tmux/fish replay through a real pane into a real Term (Alacritty’s grid struct). What breaks in a pane but not on a pty is my fault. What breaks in both belongs to the emulator. That split ends hours of pointing fingers.

Price: the panel group needs kitty, Rust, C, node and X. 19 files carry that weight, 17 stay pure Python. A new test lands in the right group by the import it writes, and a unit test that tries to skip fails loud. No silent green.

Screenshots caught the shit cells couldn’t

The model holds cells. Your eyeballs eat pixels. Those two divorce exactly where it hurts: double-size lines, blinking cursors, underlines.

checks.pymux-pictures runs the same program twice in the same real terminal — once bare, once inside a fullscreen pymux pane — and subtracts the screenshots. Never cross-compare terminals; every font stack draws different glyphs, so that diff is toilet paper. Bare-vs-pane in the same emulator or GTFO.

That’s how we caught two ghosts: a cursor that stopped blinking, and an underline that showed up uninvited. Every cell check waved both through.

And sometimes the diff says the other guy is the idiot. A pane re-spells CSI 4:1 m into CSI 4 m. xterm ignores the first and draws the second, so 206 pixels differ. foot reads both forms, pictures identical. Verdict: the difference belongs to xterm, written down in picture-differences.txt with the reason. That list gets judged in both directions, so a regression screams and a fix screams too. Same deal for the esctest/vttest/vterm failure lists.

Want a real fixture instead of a hand-made toy? Record your own broken session:

ptterm-record --into pymux/tests/recordings --lines 24 --columns 80 \
 claude -- claude

Go use the thing, reproduce the fuckup, quit. Now recorded-claude replays your actual bytes, bare vs pane. A hand-written fixture only holds what somebody bothered to imagine. This one holds what actually bit you. Read it before you commit it, it holds your screen.

Flaky bit: vttest pictures item 2 still flaps on a fixed-delay change after one screen draw, pure timing flake. It stays non-gating. A flaky gate is worse than no gate.

Wall-clock lies, so I count bytecode

Agents love making code slower while all tests stay green. Wall-clock can’t fail a build — a second belongs to whatever else was running on the box. So I count bytecode instructions with sys.monitoring. Same code + same bytes + same interpreter = same number, regardless of box load. Carl’s law: “number go up = bad.”

Budgets live in *-budgets.txt next to the tests. Drift >5% either way and you’re red. Up means you got slow. Down means you forgot to update the budget, also red. PYTHONHASHSEED pinned, Python upgrade means re-record everything. That’s the bill, pay it.

Counting found the fat one: every title bar re-measured the whole window, 950k instructions against a 55k frame. We now measure the plan once. The census also found a one-pane layout is 106 nested boxes and 36 of them are chrome (borders, title bars, status fluff) for that single pane (#366). A key press still walks the whole layout to build a cache key that then hits (#317), 33% of the press, growing with every overlay. The fix needs a layout version counter prompt-toolkit doesn’t have. So it sits open, with numbers, instead of rotting in someone’s head.

Current damage, counted and timed:

bare pty: 0.05 ms median
pymux: 3.85 ms median, 7.6 ms p99 (1.1 ms in, 2.7 ms out)

Socket vs in-process transport: identical. The socket costs nothing here; the renderer costs everything.

The cmatrix story from the top? ptyhost polled for an idle loop that never comes while prompt-toolkit reposted redraws the same way: 40,552 reposts to defer one read a quarter second (#253). After: 19% of a core, 26 frames in 5s instead of 5. Same shape fixed nyancat, pipes, tty-clock. And the “impossible rate” tell: one cold count showed 500M instr/s next to 132M in the same run. Can’t happen. We had compared two different piles of work, first-frame paint vs steady-state, merged keybindings vs hot path. Split them and the numbers made sense again.

Big-screen tax, measured not guessed: 80x24 idle 6.9 ms, 342x74 idle 22.2 ms. A frame is ~5.7 ms fixed + 0.65 µs per cell. So frame-rate 30 (default) stays because uncapped melts cores: uncapped cmatrix eats 93% of a core at 45 fps, capped at 10 it eats 32% at 9.8 fps, typing latency unchanged. That’s a window option because a window is what you look at.

557 issues and I wrote zero of them

Over 500 issues on the tracker. I filed none. Not one. The rule agents actually follow: file an issue for what you find and do not fix. The issue is how you stay on the task instead of wandering off to stroke shiny crap.

So the tracker reads like a drunk lab journal, and I love it:

#227 — every scrollback row allocated a closure just to return one shared cell. 10.7 MB of identical lambdas at 50k rows. Of ~800 bytes a row, 215 was the Row and its little hat.

#426 — resize on the alternate screen eats a wrapped line. pyte-roaming finds it one run in ten with a two-chunk seed. Fucker hid since before the fork.

#232 — 45% of a keystroke was neither work nor socket, just waiting. Instruction counts can’t see waiting by construction. So now we count loop turns too.

#254 — a frame builds 11,033 cells to emit 437 characters. The diff emits only what changed, but everything before it rebuilds the universe to find out.

437 closed, 120 open as I type this. All in Lillecarl/pymux, even the cross-repo ones. If it’s not in an issue it doesn’t exist, and if your exclusion pattern matches nothing the gate fails — so dead excuses die fast.

Count votes, diff pixels, budget bytecode

Full disclosure like last time: robots wrote ~all the code, and one wrote the first draft of this post. Recursion is the point.

What actually transferred, in order:

Give the robot a number and it behaves: agree/wrong/split, pixel diffs, instruction deltas. Ask it “is this correct?” and you get vibes back.

Record reality. ptterm-record your broken Claude session instead of inventing bytes. Alacritty’s vim recordings beat any synthetic corpus. Real programs or it didn’t happen.

Keep failure lists bidirectional. Every *-failures.txt / *-budgets.txt / picture-differences.txt fails on regression and on silent fix. A fix you didn’t notice means your test is blind.

This setup survives because the verdicts are mechanical and the evidence is checked in. I built the checker, not the knowledge: I still can’t read VT. I can read a vote, a diff, and a budget. That’s the whole fucking job, and I get to stay dumb.

Umbrella with all eight repos and every check: github.com/Lillecarl/pyterm. The fork: github.com/Lillecarl/pymux. Run nix build --file . checks.all, then checks.pymux-pictures.run and go look at the pictures — that’s the fun one.

ghanix (GitHub Actions workflows as NixOS modules)

Wed, 16 Sep 2026 00:00:00 +0000

This site’s deploy workflow used to be the usual thing: a step to wget a Hugo .deb, a step to build, a step to upload. Earlier this year I got tired of it and moved the whole build into Nix — the flake holds the site package and the spell check, and the YAML job shrank to installing Nix and running two nix build calls. All the logic lives where it can be tested; the YAML is a shell.

That left exactly one piece of YAML worth complaining about: the workflow file itself. So I wrote ghanix — write GitHub Actions workflows as NixOS modules, and get back plain values that a caller turns into YAML.

Why Bother?

Because a workflow is configuration of exactly the kind the module system already solves, and GitHub Actions’ answer to composition is copy-paste. The workflow I actually want to write looks like this:

ghalib.evalWorkflow {
 name = "On commit";
 on.push = { };
 jobs.build.steps = [
 (ghalib.steps.checkout { })
 (ghalib.steps.installNix { })
 ];
}

evalWorkflow runs the attrset through lib.evalModules against a schema of the workflow, job and step shapes, then strips nulls. A declared key gets a type, a default and a description. And the result is values, not text — which means a job is code: one definition shared by two variants, a step list built by a function, a timeout computed once instead of pasted into four places where it will drift.

What it does not give you

Being a spell-checker. The workflow level is closed — a key it does not know is an evaluation error — but jobs and steps are deliberately freeform, so GitHub can grow a key and nothing here has to be taught it. The cost is that a typo passes:

jobs.a.steps = [ { run = "true"; tiemout-minutes = 5; } ];
# renders "tiemout-minutes": 5, and GitHub ignores it

Note the irony on a site whose CI now runs typos at build time. The point is: the schema is there to give the common keys a type and a sane default, not to police the rest. What ghanix buys is that the workflow is code. What it does not buy is that you spelled it right.

The job preamble

The steps at the front of every job are the same in every repository, and writing them out is how they drift. So a job can ask for them by name:

jobs.test = {
 ghanix = {
 checkout.enable = true;
 nix.install = {
 enable = true;
 settings.trusted-users = [ "root" "runner" ];
 };
 nix.cachix.enable = true;
 userNamespaces.enable = true; # the Nix sandbox, and passt
 freeDiskSpace.enable = true;
 };
 steps = [ { run = "nix build --file . thing"; } ];
};

Each contributes to steps through mkOrder, below the 1000 a plain list definition gets, so they come first and in a fixed order: checkout, room on the disk, Nix, cachix, then the runner’s own permissions. Everything the job wrote for itself follows.

The nix.install.settings trick is my favorite: it is an attrset of nix.conf keys, where a list joins on spaces. That lets a project with a cache of its own drop the composite action it would otherwise carry around — and a composite action cannot hold timeout-minutes at all, which is the kind of thing you learn by losing twenty minutes to it.

Every step constructor also carries a default timeout-minutes, generous against the measured time — the cap is there to catch a step that stopped, not a step that is slow.

Rendering is the caller’s job

evalWorkflow returns an attrset and the caller writes the file. That is not laziness; it is that my two consumers disagree about how. nanopynix renders through its own to_yaml because it wants the key order, and a pytest gate compares the result against the checked-in YAML. nixkube writes with pkgs.formats.yaml, runs yamlfmt, and ends CI in git diff --exit-code. Both gates compare values, so style never fails a build.

(YAML is a superset of JSON, so builtins.toJSON into a .yml file is also a valid workflow and needs no builder at all. It is unreadable in a diff, which is usually the reason not to.)

Takes lib and nothing else

The constraint that makes it a project instead of a directory: lib from nixpkgs — for evalModules, types and asserts — and nothing else. No flake, no store path, no nixpkgs source. A repository that pins its own nixpkgs, or none, can still import it.

ghanix grew inside nanopynix, which is still its first consumer. The header there used to say the split “would let this directory be lifted into its own project unchanged”. It was, and it was: three files moved without an edit to any of them. That is the kind of sentence I want more of in my repos.

Try it

Source at github.com/lillecarl/ghanix, with the honest caveat from its own CV entry: good, but not even half-finished. The step library covers what my repositories needed; yours will want more. If writing a workflow as a module system configuration sounds like your kind of Tuesday, it is usable today — and if it sounds like heresy, the YAML was always this shape, ghanix just makes you look at it.

pyedit (super editing powers for agents)

Tue, 15 Sep 2026 00:00:00 +0000

As promised in the first post: an occasional opinion. This one comes with software.

If you run AI coding agents you have watched the edit-tool saga unfold. First came line-number patching, and line numbers go stale the moment two edits touch the same file. Then search-and-replace, and the model replaces a string in a different file than it meant to. Underneath both sits the same mistake: every edit is a discrete gamble with no receipt. A complicated edit — ten files, one refactor — is twenty little gambles, and if gamble twelve is wrong you find out by reading.

Then Anthropic decided the dedicated tools were the problem. Recent Claude Code builds inject a standing instruction while auto mode is active, verbatim from the binary:

Do your work through the Bash tool wherever it can accomplish the job: read files with cat, head, or sed -n, search with grep and find, and make file changes with sed, heredocs, or short scripts, rather than using the dedicated Read, Edit, or Write tools. Fall back to a dedicated tool only when Bash genuinely cannot do the job.

So Claude started editing files with bare Python, everywhere, all the time. In practice that is a python3 - <<'PY' block doing src.replace(...) on real code: no diff to review, no failure when the anchor text is wrong, nothing anyone can run again — and per the bug reports, occasionally half a document deleted because a one-liner misfired. The instruction is hardcoded behind an undocumented experiment gate with no setting to turn it off, two changelog entries that had shipped the opposite guidance as fixes a few versions earlier never got a reversal entry, and the issue tracker filled up.

Now, my own rule file opens with the standard countermeasure: never rewrite a source file by piping a Python or sed program into the shell. But somewhere around the fifth Python heredoc of the week it clicked: if Anthropic thinks bare Python is good enough for editing files, why not make bare Python actually good at editing files? Not another rule telling the model to stop — a proper library and runner for scripted edits.

So I wrote pyedit. It gives an agent super editing powers, and the edits stop being gambles.

Full disclosure, since we are being honest: pyedit was built with AI, and the first draft of this post was written by one. I am not even trying to hide it — I am firmly in the “honesty is best” camp. A tool for AI agents, built with AI, announced in an AI-written post: the recursion is the point.

Why Bother?

pyedit runs a Python edit script. That is the whole interface — everything around the script is the point:

Every file the script touches lands in an in-memory overlay. The first read proxies to disk and caches the whole file; writes stay in memory. Reads see staged content, so read-your-writes holds.
A run prints a unified diff and touches nothing. Disk is written only with --apply. The diff is not a prediction of what would happen, it is a rendering of what --apply will write.
Syntax is checked before the diff prints — tree-sitter where a grammar is installed, compile() for Python. Applying known-broken syntax refuses without --force.
Every applied change prints an undo id — a reverse patch, rendered before the write. pyedit apply <id> un-does the whole run.

The invariant: staged state lives in memory, and one function is the only thing that writes to disk. A dry-run is not a second code path — it is a run that reaches the end without calling apply.

Many edits, zero line numbers

The part agents actually care about. pyedit allows edits in multiple VFSes, so the model never needs to be concerned with multi-edit line number differences:

pyedit.edit("src/app.py", "def parse(cfg):", "def parse(cfg, strict):")
with pyedit.VFS():
 pyedit.edit("src/app.py", "import json", "import json\nimport os")

A pyedit.VFS() scope is an independent overlay on top of disk truth. It cannot see the parent’s staged state, and sibling scopes cannot see each other. When the scope exits, pyedit merges it with git’s own three-way merge: disk is the ancestor, the parent is ours, the scope is theirs. Edits in different regions merge clean no matter what line numbers each one was written against; two edits to neighboring lines belong in one scope, and git says so.

That is the whole trick — line numbers never enter into it. A conflict is a Collision, never a guess, and nothing is staged before every conflict is known. (Rename detection rides along, like git’s: a delete is paired with a similar add so an edit follows the file to its new name. --no-rename-detection turns it off.)

git does the paperwork

Storing and replaying patches is a solved problem, and the solver is libgit2. pyedit runs it entirely in memory — a repository with a mempack object database, no workdir, no index file, no path on disk. It owns every format git invented: hunk rendering, base85 binary payloads, symlinks as mode-120000 blobs.

So pyedit’s own patches are git’s own, written by libgit2 and applied by libgit2:

A dry-run wraps its diff in # pyedit dry-run <id> comments, and pyedit apply <id> applies that stored patch later. Handy when a human wants to review agent output before it lands.
An applied run’s undo id is the reverse patch, written before the write.
No Python parses a diff anywhere on this path. Line numbers are exact by construction, so nothing needs fuzzy matching.

Trusting patch confetti

Agents also handle other people’s patch formats — OpenAI apply_patch envelopes, unified diffs from tool output — and what arrives is often patch confetti. libgit2’s apply refuses most of it: no diff --git line (agents write these constantly), creates without mode headers, zero-hunk sections. So pyedit meets the confetti where it is:

pyedit.apply_v4a(text) — the vendored OpenAI primitive
pyedit.apply_diff_git(text) — libgit2, exact line numbers
pyedit.apply_diff_unidiff(text) — the unidiff library, with hunks anchored by search and a whitespace-insensitive fallback, because an @@ number from a model is a suggestion, not a promise

Fail closed, always: one hunk that will not anchor fails the whole input and nothing is staged. --force downgrades that to per-file skips.

The same spirit runs the semantic layer: rope does Python renames and reference finding in-process, a real language server covers other languages, and tree-sitter serves position queries and outlines — all reading staged content, so the tools agree with the diff.

Try it

Source and the full manual live at github.com/Lillecarl/pyedit — pyedit skill prints the whole agent-facing manual as markdown, which is the authoritative usage guide and doubles as a decent architecture lesson.

The pitch: if your agent makes three search-and-replace calls to rename one function, give it pyedit. It writes one script, reads one diff, applies one patch — and if the result is wrong, one id un-does the whole thing.

Hello world... Hello Carl!

Sun, 25 Jan 2026 00:00:00 +0000

Finally got around to setting up a proper website. Built with Hugo, deployed via GitHub Actions, styled to be as minimal as possible.

Why Bother?

A little portfolio thingy can be useful when selling yourself online, if I ever decide to write something that isn’t code I don’t want to lock it behind some evil megacorporations ad network (The hypocracy is strong with this one, using GitHub pages).

What to Expect

Mostly technical content - infrastructure, DevOps, NixOS, that sort of thing. Occasional opinions. Infrequent updates, probably.

The Stack

Hugo for static site generation
GitHub Pages for hosting
GitHub Actions for deployment
Custom minimal theme because I don’t need much
Fully vibecoded with Claude Opus 4.5

No JavaScript frameworks were harmed in the making of this site.