Open-Source | Bas Nijholt

Roll your own, fork the rest 🍴

Mon, 19 Oct 2026 00:00:00 +0000

Introduction: a follow-up to something I wrote #

In April 2025 I published Confessions of an asymmetric hypocrite, about my split personality on dependencies. Strict minimalism for the libraries I publish, and then, for applications:

For applications (especially CLIs in isolated environments), I’m far more liberal with dependencies to build features quickly.

I also wrote that I “strongly prefer dependencies that are already widely adopted and trusted by the community” because “these are less likely to cause unexpected issues”.

Then I spent a year building MindRoom, which is an application, exactly the category where I said I could relax.

I want to report back. “Prefer battle-tested dependencies” was the right rule. I just had the wrong idea of what battle-tested means. I thought a project with tens of thousands of GitHub stars qualified. Now I think it means millions of downloads, every day.

Table of contents

Update 2026-10-31: In the two weeks after publishing, I took my own advice twice. MindRoom’s knowledge search no longer uses ChromaDB, and code MindRoom owns has replaced Agno’s runtime. Agno is now only MindRoom’s tool library. The full stories are in the comments.

1. Stars measure interest, not usage #

When I picked Agno as MindRoom’s AI framework, it looked like the safe choice. Today it has over 42,000 stars and 6,000 forks.¹

It also gets about 78,000 downloads a day on PyPI. httpx, one of Python’s standard HTTP libraries, gets about 25 million.²

A star is something you click once, when a README looks exciting. A download happens every time some project installs the package.

Most of those downloads are CI, not people, so downloads are not users either. But a package with millions of downloads a day is installed by a huge number of different projects. Many of them use the same functions you are about to use, so they hit the bugs before you do.

Battle-tested is also not the same as old. I use uv for everything, and it has only been around for a couple of years. I run into bugs in uv too, but there is simply no better alternative, and it gets about 3.6 million downloads a day.

2. A popular protocol is not a popular library #

The other place my old idea failed was Matrix.

Building on Matrix felt obviously correct. An open protocol, about a decade old, with serious security reviews from large organizations and governments. Millions of people use it.

Matrix is still a good protocol and I am still on it. But even though millions of people use Matrix, there are only a few client libraries.

MindRoom streams agent replies by editing the same message many times a second. Almost every part of the ecosystem I touched had a problem with that: Element, Cinny, matrix-nio, and the Matrix JavaScript SDK. In the JavaScript SDK, edits that arrived while a thread was still loading were silently dropped, so you saw stale text until you reloaded.³

What counts is how many projects use the library you build on. Element’s users do not test matrix-js-sdk for you. Other people building on matrix-js-sdk do. It gets roughly 100,000 downloads a day. matrix-nio, the Python client, about 23,000.

3. I checked the rule against my own code #

I pulled the daily download numbers for the packages I use and looked for workarounds, patches and forks in my own source.⁴

Package	Downloads per day	What it cost me
requests	49M	nothing I had to work around
pydantic	35M	nothing
numpy	33M	nothing
httpx	25M	nothing
aiohttp	18M	nothing
FastAPI	17M	nothing
chromadb	270K	workarounds for a bug that holds the GIL
matrix-js-sdk	~100K	patched
mem0ai	79K	largely reimplemented
agno	78K	126 documented workarounds
matrix-nio	23K	forked

Above a million a day, I had nothing to work around. Below it, every package on this list cost me a patch, a fork, a rewrite, or a pile of workarounds.

Take ChromaDB, the vector database behind MindRoom’s knowledge bases. In some cases it holds Python’s GIL during I/O, which blocks every other thread in the process. I opened a pull request to fix it, and nobody has looked at it yet. Instead of forking, I run every knowledge read in a short-lived child process, because a process can be killed and a blocked thread cannot.⁵

My fork of matrix-nio has about 8,900 lines added and 2,000 removed in the library code since the last upstream release.⁶

This does not mean every small package needs replacing. MindRoom pulls in a few hundred packages in total, and plenty of them have modest download numbers. The scrutiny should match how much I depend on a package. Something I use for one small, specific purpose is fine. Agno and matrix-nio are the base that MindRoom is built on, which is probably also why they hurt the most.

4. Roll your own: the library gives you the easy 10% #

Take memory libraries, Mem0 and friends. I have already written about this: I cloned LlamaIndex, LangChain, Letta, Mem0 and PydanticAI, studied how they work, and re-implemented the parts I needed. My memory system ended up “mostly modeled after Mem0”.

The core idea is not hard. With RAG, you chunk, embed, retrieve, re-rank and reconcile. Once you have read a couple of implementations you can write it, and afterwards you understand every line.

The same is true of an agent framework. It builds a JSON payload, posts it to an HTTP endpoint, parses a streaming response, keeps a list of messages, and loops when the model asks for a tool call. With AI, that is a day or two of work.

The hard part is making it reliable at scale: never blocking the event loop, and handling the crazy edge cases. With an agent system you end up building a very complicated state machine, and if you do not watch it, any combination of states is possible. Almost all of them are edge cases.

A library gives you the easy 10% and leaves you the hard 90%. And you do that 90% inside somebody else’s code, where you cannot fix the root cause.

MindRoom is now about 360,000 lines of Python, plus about 750,000 lines of tests.⁷ A good part of that is code I wrote instead of depending on a library:

Memory and knowledge: about 15,600 lines across 50 files.
Conversation history and compaction: about 8,400 lines.
An OpenAI-compatible API: about 2,300 lines, so MindRoom agents show up as selectable “models” in any chat frontend that speaks the OpenAI protocol.
Claude provider support: about 3,000 lines.

If I have to write the hard 90% either way, I might as well write the easy 10% too.

5. Fork your own: when the problem is hard #

I am not going to write my own end-to-end encrypted Matrix SDK, or my own homeserver. Those are hard, and also far below the line. So there I fork.

I forked the Python Matrix client. MindRoom ships its own fork of matrix-nio rather than the upstream package.

I forked the Matrix server, twice. First Synapse. When I ran into scaling problems I moved to Tuwunel and forked that.

I forked the web client. Cinny is the Matrix web client MindRoom uses.

None of these are AI projects. AI is just where I felt it most.

Whether a fork stays a fork depends on the maintainers. Tuwunel is extremely receptive to my patches, so I upstream anything that is general enough, and over the last six months I am its fourth most active contributor by commits.⁸ Cinny has not accepted any of my pull requests, so I forked it and stopped trying to upstream. Same with LibreChat: I had patches open for over a year without a reply, so I forked.

Keeping a fork up to date used to be miserable. With an LLM doing the rebasing, pulling in the latest upstream is now cheap, though still a bit of a risk every time. The bigger cost is that once you fork, you are responsible for the whole codebase, including the parts you never changed.

Agno: patches instead of a fork #

I did not fork Agno. I monkey-patched it. Agno is very actively developed, I have talked to the maintainer, and they know about these problems, so I hoped to upstream my fixes. I have filed 33 issues and pull requests there.⁹

That got out of hand. MindRoom now carries 126 documented workarounds for Agno across 59 files. Most of them live in 36 dedicated compatibility modules, about 7,200 lines of code, with the rest patched inline in 23 other files. Every one uses the same comment format, so I can find all of them with one search. Each one says what is wrong upstream, links the issue or PR, and says when I can delete it.¹⁰ A few examples:

Search failures become plausible empty results. A failed knowledge search and an empty index return the same empty list, so my agents confidently told me things did not exist.¹¹
Streamed tool calls get malformed or merged.¹²
Reasoning is silently lost when tool calls are replayed.¹³
Provider errors collapse into a generic 502, which throws away the error code you need to decide whether to retry.¹⁴

At this size, the patches amount to a fork.

6. I am not dunking on open source, including mine #

Everything I named is open source I use every day, for free, built by people doing their best. I filed issues and PRs, and where maintainers merged fixes I deleted my workarounds.

My own software is in the same category. Most new AI tooling is not very good, and MindRoom may well be included. It is large, fast-moving, and nowhere near millions of daily downloads. By my own rule, you should think twice before depending on it.

I also have to admit that I have not yet built a project the roll-your-own way from the start. So comparing “what I would do next time” with what I actually did is not entirely fair. This is what I think right now, and a year from now I may have to write another post correcting this one.

7. My rule for the next `uv add` #

I weigh three questions.

How many projects use it? Daily downloads of the actual package, not stars, and not how many people use the product built on top. In the millions: depend on it.

How much do I rely on it? Agno and matrix-nio are the base of MindRoom. A library I use in a CLI to format a question is not, and if I use it in a narrow way I do not need my own version.

How hard is it, and how receptive is upstream? If the library is something AI can write in a couple of days, roll my own. If it is hard, fork it. If the maintainers accept patches, upstream what is general enough.

If I started MindRoom over today, I would write the HTTP requests to the model providers myself. Not even the OpenAI or Anthropic SDKs. And even httpx is less safe than its download numbers suggest: in early 2026 its maintainer closed the issue tracker and discussions, and the latest stable release is from December 2024.¹⁵

In 2025 I wrote that the right answer is “it depends on the situation”, and I still believe that. I just had the wrong threshold. Battle-tested means millions of downloads a day. Below that: roll your own, and fork the rest.

From the GitHub API (api.github.com/repos/agno-agi/agno) on 2026-10-02: 42,385 stars and 6,041 forks. ↩︎
PyPI numbers are the last_day field of the pypistats.org API (/api/packages/<name>/recent), fetched on 2026-10-02, except uv, fetched on 2026-10-18 (3,648,827). The matrix-js-sdk number is npm’s weekly download count (about 730,000) divided by seven. Daily numbers wobble, so treat them as orders of magnitude. ↩︎
When events arrive for a thread that has not finished initializing, the SDK’s replay path never applies them, so an m.replace edit (the event type Matrix uses for “this replaces message X”) is stored and never shown. I replayed a captured event trace through the SDK: unpatched, zero of seventeen edits reached the listeners; patched, all seventeen. MindRoom carries the fix as a patch-package patch on the SDK’s thread.ts. ↩︎
For each direct dependency I looked at three things in the MindRoom repository: whether pyproject.toml pins a fork instead of the upstream package, whether patch-package patches it, and whether the source has workaround markers or comments pointing at upstream issues for it. The packages above a million downloads a day had none of those. ↩︎
The PR is titled “Release GIL during metadata I/O”. On the MindRoom side, knowledge/read_process.py starts the child process, and a TODO says to remove it once a Chroma release with the fix is pinned. A blocked thread holding the GIL cannot be interrupted from Python, but the kernel will always terminate a child process. ↩︎
Compared with upstream matrix-nio 0.25.2 (released 2024-10-04): git diff --shortstat on the library code gives 8,872 lines added and 1,966 removed across 52 files, from 89 commits, 76 of them mine. The fork is published on PyPI as mindroom-nio. ↩︎
Counted with git ls-files and wc -l on the MindRoom repository on 2026-10-18: 360,513 lines in 1,222 Python files under src/, 750,657 lines under tests/, and another 81,543 lines of TypeScript in the frontend. The per-feature numbers below come from the same count over the relevant directories. ↩︎
Non-merge commits on Tuwunel’s main branch since 2026-04-18: Jason Volk 1,332, June Strawberry 325, dasha_uwu 55, me 42. ↩︎
Issues and pull requests in agno-agi/agno with me as the author, counted on 2026-10-02. ↩︎
Every workaround starts with a comment like # AGNO_COMPAT: Knowledge search hides provider failures as empty results., followed by Reason:, Upstream issue:, Upstream PR:, Remove when: and the tests that cover it. The counts come from grep over src/: 126 AGNO_COMPAT: markers in 59 files, and 7,160 lines in the 36 agno_compat_* modules. ↩︎
Knowledge.search catches vector store and provider errors and returns []. agno#10150, partially fixed by agno#10152. ↩︎
When a streamed tool-call index does not start at zero, Agno leaves empty placeholder calls. agno#8879, fix proposed in agno#8880. ↩︎
With the OpenAI Responses API, Agno keeps only the last reasoning item, so it cannot be replayed with the tool calls it belonged to. agno#9960; partial fixes landed in agno#10075 and agno#10395. ↩︎
Unclassified ModelProviderError failures default to HTTP 502, so a real network blip and a permanent error look the same. agno#8869, partially addressed by agno#8870. ↩︎
The latest stable release on PyPI is 0.28.1, uploaded 2024-12-06. There have been 1.0 development pre-releases since, the latest in August 2026. The closing of issues and discussions was widely discussed in the Python community in March 2026. ↩︎

Friend-to-friend ZFS backups, version two

Mon, 28 Sep 2026 00:00:00 +0000

Two years ago I wrote about friend-to-friend backups with TrueNAS. A friend and I store each other’s ZFS snapshots, which is the cheapest off-site backup there is. TrueNAS’s replication tasks wanted root on the receiving system, and neither of us wanted to give the other root on the machine that holds our family photos. So each of us ran a TrueNAS VM on a hypervisor, backed by an iSCSI zvol on the real NAS, and gave the other person root inside that VM instead. Sounds complicated? It was. It worked, but it meant running ZFS on a zvol on ZFS, inside a VM that each of us had to keep updated.

Since then I replaced TrueNAS with NixOS, and my friend plans to move his machines to NixOS too. This time we looked for the simplest solution, built from standard Linux and ZFS features wherever possible. He wanted plain zfs send and zfs receive, with his data still encrypted and his keys never on my server. I agreed, on one condition: neither of us should be able to destroy the other’s datasets.

The result is zfs-tenant, which is now on PyPI and has documentation.

Table of contents

Why ZFS #

OpenZFS is a filesystem and a volume manager in one. You add disks to a pool, and it behaves like one large partition: every dataset you create draws from the same free space, and each can still have its own quota and encryption. ZFS checksums every block it writes, so it notices when a disk hands back something else, and with a mirror or RAIDZ it repairs the block from a good copy. That protection costs disk space: a mirror of two disks holds one disk’s worth of data.

For me, snapshots are one of the coolest parts. ZFS never overwrites data in place, so a snapshot only has to hold on to the blocks that existed at that moment. Taking one is instant, and it costs no space until the data changes. zfs send turns a snapshot, or the difference between two snapshots, into a stream that zfs receive writes into a pool on another machine, usually piped through SSH. It moves blocks, not files: an incremental send contains only the blocks that changed, and ZFS knows which ones those are without visiting a single file. A bajillion one-kilobyte files do not slow it down, because nothing has to look at them one by one. For comparison, restic on my PC needed an hour and a half per run just to check close to a hundred million files for changes.

Two tools from the same project automate this. sanoid takes snapshots on a schedule and prunes them by policy, for example hourly ones for a day and daily ones for a month. syncoid wraps zfs send and zfs receive over SSH: it finds the newest snapshot both sides share and sends everything after it.

What we wanted #

We wrote down the rules before anything else:

He cannot see any of my data, including metadata like dataset names and sizes.
He cannot change or destroy anything of mine.
I cannot read his data, because his keys stay at his house.
He gets one dataset where he can create and remove nested datasets as he likes.
That dataset has a size limit.
No new replication tool on either side: plain zfs send or syncoid.

Until then his NAS runs TrueNAS, so whatever I built also had to work on a machine without NixOS.

ZFS already had most of it #

OpenZFS has a permission system that most people never touch: zfs allow. It delegates individual operations like receive, create, and destroy on one dataset to an unprivileged user. Put a root-owned quota on that dataset and the user cannot store more than you agreed. Raw sends (zfs send -w) ship the encrypted blocks as they are, so the receiving side never needs the key.

On paper, that covers five of the six rules. The gap is visibility. Any local user can run zfs list and see every dataset on the machine, with names, sizes, and properties. And an SSH account for replication is, by default, also a shell.

There are tools that would sidestep some of this. zrepl has a sink mode with a subtree per client, but it replaces sanoid and syncoid on both sides and runs as root on the receiver. restic or borg to a friend’s box would also work, but everything else on my network is ZFS: my machines replicate to the NAS with syncoid, and a restore is zfs send and zfs receive. Adding another backup format means one more thing to understand when something breaks. My current off-site copy goes to Backblaze B2 with rclone. Ideally that would be ZFS as well, and some hosting services accept zfs send, but they cost far more than object storage. A friend with a ZFS box costs nothing.

Rehearsing the permissions in a VM #

Before writing any code, I had an agent build a throwaway NixOS VM test with a real pool, a delegated user, and a list of probes. Each probe tried one thing the friend should not be able to do and recorded what ZFS answered.

The first surprise came from the most obvious setup. With a plain zfs allow -u joe create,receive,destroy,... tank/friends/joe, the delegated user could run zfs destroy -r tank/friends/joe and delete the dataset I had created for him, quota included. Delegated rights apply to the dataset itself as well as everything below it, unless you say otherwise. The fix is to split them: on the root itself only create,mount,receive with zfs allow -l, and the full set only for descendants with zfs allow -d. After that change, destroying, snapshotting, re-delegating, or changing the quota of the root all failed with permission denied.

A send stream can carry properties too, such as a hostile mountpoint=/etc. ZFS applies them with the receiving user’s rights, so in the VM that property failed with permission denied.

The probes also confirmed the gap: the delegated user saw my tank/host dataset in zfs list, and zfs get used tank/host returned its size.

A gate that speaks syncoid #

The shell part has a standard answer. An authorized_keys line with restrict,command="..." runs one fixed program for every login, and passes whatever the client asked for in SSH_ORIGINAL_COMMAND. zfs-tenant gate is that program. It tokenizes the request, accepts only the handful of command shapes a backup needs, checks that every dataset name is inside the friend’s dataset, and runs zfs with an argument list it builds itself. It never starts a shell, so there is nothing to inject into.

The hard part was knowing exactly which commands syncoid sends, so an agent read syncoid’s Perl and logged every remote command it ran. Most are the zfs commands you would expect. One surprise: before each receive, syncoid runs ps -Ao args= on the receiving machine, to check that no other transfer is already writing to the same dataset. That command prints every running process with its full command line. On my NAS, it would show my friend everything I run, so the gate answers with an empty list.

Reading syncoid that closely also turned up a remote code execution (RCE) bug in version 2.3.0, outside zfs-tenant itself. In push mode, syncoid asks the receiving host for a ZFS resume token. It passed that answer unescaped into shell commands for estimating and resuming the send, which run on the source machine. A malicious or compromised backup host could therefore return shell syntax instead of a token and execute arbitrary commands on the sender with the privileges of the syncoid process.

I reproduced this in two isolated NixOS VMs using real ZFS and SSH: a harmless command embedded in the receiver’s answer created a marker file on the sender. I reported it to the maintainer and opened sanoid PR #1114 with a small fix that shell-quotes the token at both uses. Even with that fix, the sending side should run syncoid as an unprivileged user that may only send and hold. nixpkgs’ services.syncoid already works that way, so my friend needs nothing from zfs-tenant at all.

Zones: a second wall in the kernel #

At that point the gate was the only thing hiding my datasets. Then my friend sent me a message: ZFS has a feature called zones, which restricts a dataset tree to a Linux user namespace.

zfs zone attaches a dataset to one user namespace, and inside that namespace the ZFS kernel module answers dataset does not exist for everything that is not attached. Even if my gate had a bug that let arbitrary zfs commands through, tank/host would stay invisible. The zone does not replace the gate, though: it only filters ZFS, and it only applies once the gate has put the SSH session inside it. Who stops what shows how the two divide the work.

A user namespace can give its processes different user IDs than they have outside. Containers usually use that to make the user root inside the namespace, while it stays an ordinary user outside. ZFS treats root inside a zone as the zone’s administrator, allowed to do anything to the attached datasets, whatever zfs allow says. In the VM test, that let the friend destroy the dataset I had created for him. So zfs-tenant keeps him as his own ordinary user inside the namespace: he has no special rights there, zfs allow decides what he may do, and the kernel still hides everything else.

Root inside a user namespace also turned up in a real OpenZFS bug in August: before 2.4.4, 2.3.9, and 2.2.11, several pool operations, such as destroying a pool, accepted it as host root (CVE-2026-79619). Joe cannot reach that through the gate, but zfs-tenant needs unprivileged user namespaces, so a host running it should load a patched module: cat /sys/module/zfs/version shows the loaded one, which only changes after a reboot.

A zone needs a running namespace to attach to, so zfs-tenant runs a small service per friend that holds one. The gate joins that namespace before it looks at the command, drops the capabilities that joining grants, and refuses to run if the service is down.

Who stops what #

When Joe and I talked it through, I found it hard to say clearly which part protects against what, so I made this diagram.

Each column answers one question: who can connect, what he can run, what ZFS shows him, and what he can change. For the network, our tailnet only lets his router reach port 22 on my NAS, and from= in authorized_keys only accepts his key from that address. Raw sends then keep whatever reaches my pool unreadable to me.

The gate and the zone overlap in one job: hiding my other datasets. The gate does it first, by refusing any name outside his root before zfs runs. The zone repeats that check in the kernel, so hiding my datasets would take a bug in both. Everything else the gate does, the zone cannot:

Without the gate, his key would be a normal account on my NAS. The zone only filters ZFS; it would not stop him from reading /etc or running programs.
An SSH login does not start inside a user namespace. The gate joins the zone before it runs anything, so without the gate the zone would never apply.
The zone leaves some things visible: zpool status still shows my disks and how full the pool is, and the datasets above his root still show their sizes. User namespaces do not hide processes either, hence the empty answer to ps.
It deletes any unencrypted dataset he pushes by mistake, so I never keep his plaintext.
It logs every command, which is how I saw Joe try bash below.

The security model in the documentation lists every promise with the mechanism behind it.

What it cannot hide #

ZFS encryption protects file contents, not structure. In the words of zfs-load-key(8), ZFS “will not encrypt metadata related to the pool structure, including dataset and snapshot names, dataset hierarchy, properties, file size, file holes, and deduplication tables.” So I can see the names, sizes, and snapshot times of whatever my friend sends me. Boring dataset names help, and sending without -p keeps properties out of the stream.

I can also always delete his copy, because I am root on my own machine. What I can never do is read it. My monthly scrubs still verify his data without his key, because ZFS checksums the encrypted blocks.

What we protect against is a dead machine: a failed pool, a fire, a flood. His key may destroy anything below his root, which is what lets syncoid mirror his snapshot retention, so someone who steals that key can also delete his backups on my NAS. Covering that would take holds that I place as root and release on a schedule. We left them out on purpose, although I am reconsidering.

Setting it up #

On a NixOS host, giving a friend space takes this:

services.zfs-tenant = {
 enable = true;
 tenants.joe = {
 dataset = "tank/friends/joe";
 quota = "2T";
 authorizedKeys = [ "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... joe-nas" ];
 allowedFrom = [ "100.64.0.12" ]; # his tailnet address
 };
};

That creates the user, pins the key to the gate, applies the dataset, properties, and delegation on every boot, and runs the zone service. My own setup is in friend-backups.nix, with his real key and address. If your sanoid snapshots the whole pool, exclude the tenant tree: your sanoid must neither snapshot nor prune it, or his next incremental push finds snapshots on the target that he never sent. Once my friend is on NixOS, he can push with nixpkgs’ own module:

programs.ssh.knownHosts.bas-nas.publicKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA...";

services.syncoid = {
 enable = true;
 sshKey = "/var/lib/syncoid/id_ed25519";
 localSourceAllow = [ "send" "hold" ];
 commonArgs = [
 "--no-sync-snap"
 "--compress=none"
 "--delete-target-snapshots"
 "--sshoption=StrictHostKeyChecking=yes"
 ];
 commands."tank/offsite" = {
 target = "zfs-tenant-joe@bas-nas:tank/friends/joe/offsite";
 recursive = true;
 sendOptions = "w";
 };
};

My NAS will push to his with the same configuration once he hosts a root for me.

For his TrueNAS box, every release has a single zfs-tenant.pyz that runs with the Python TrueNAS already ships, and the getting started guide covers both setups. Hosting on TrueNAS has only run in VMs so far (issue #4). Sending from TrueNAS is where its built-in tools stop working: replication tasks wrap every remote command in sh -c, which the gate refuses, so he pushes with zfs send or syncoid instead.

Knowing when it stops working #

The last btrfs machine taught me a fifth question for any backup: how do I find out when it stops working? A failed push shows up in systemctl status on the sending side, which nobody reads. The check belongs on the receiving side, and it has to look at every pushed dataset separately, because one healthy dataset can hide another that stopped replicating. That is how I watch my own machines: the NAS checks the newest snapshot of every dataset it replicates every hour and alerts my phone when one is too old. zfs-tenant does not alert yet; issue #3 tracks it.

Restoring #

The gate also allows zfs send of his own snapshots, so getting data back is one pipe, run at his house:

ssh zfs-tenant-joe@bas-nas zfs send -w tank/friends/joe/offsite/photos@autosnap_2026-09-25_00:00:01_daily \
 | zfs receive -u tank/photos
zfs load-key tank/photos
zfs mount tank/photos

My photos are a child dataset that inherits its key from an encryption root, and I only push the child. If my NAS dies and I pull the child back, can I still unlock it without the root? A throwaway VM says yes: a raw send carries the dataset’s own wrapped key, so the child arrives as its own encryption root and opens with the same passphrase. The one catch: after a zfs change-key, the next push carries the new wrapping, so the passphrase that matters is the one at the time of the last push, and it has to live somewhere other than the NAS. Mine does: zfs-unlock keeps the passphrases on a separate device and unlocks the NAS after every boot.

The first real push #

Once my side was deployed, Joe tried it from his TrueNAS box. His first move was to see what else his key could do. The gate logged every attempt on my NAS:

root=tank/friends/joe denied interactive session
root=tank/friends/joe denied 'ls': only zfs commands and syncoid's probes are allowed
root=tank/friends/joe denied '/usr/bin/bash': only zfs commands and syncoid's probes are allowed
root=tank/friends/joe denied '/bin/bash': only zfs commands and syncoid's probes are allowed
root=tank/friends/joe allowed 'zfs receive -s -u tank/friends/joe/zt-test'

The last line is a small encrypted test dataset, sent with zfs send -w piped into ssh, without syncoid. It arrived with keystatus set to unavailable. Then I tried to read it as root on my own machine. zfs mount answered cannot mount 'tank/friends/joe/zt-test': dataset is exported to a local zone, and zfs load-key with a guessed passphrase gave Key load error: Incorrect key provided. The only readable text in the raw stream was ZFS property names and the snapshot name, which is the metadata ZFS leaves unencrypted, as described above.

Tested like everything else #

Every security claim in this post is also checked by a VM test: two NixOS machines back each other up, the way my friend and I do, with real sanoid and syncoid 2.3.0, through real sshd and the gate, into real OpenZFS 2.4.4. It also checks what happens over time, such as snapshot retention and both machines rebooting, and it runs on every push in GitHub Actions.

The route to the remote code execution bug in syncoid was slightly absurd. I built the initial version of zfs-tenant through coding agents, literally from the bathtub, and then asked several frontier models to review the security boundary independently. One of them followed receiver-controlled data beyond my new code and into syncoid. A model’s suspicion is not evidence, so I turned it into the two-VM reproduction above: it failed on unpatched syncoid 2.3.0 and passed after the seven-line fix. The most consequential result of reviewing my small new project was a command-injection bug in the mature tool next to it.

The whole thing is about 930 lines of Python, not counting comments and docstrings, with no dependencies. The kernel does the actual enforcing: delegation, the quota, and the zone. The gate only removes the shell, and it is small enough to read in one sitting.

AI scope creep or useful? #

The first version had grace holds: every day, the host placed a hold on the newest snapshot of each of my friend’s datasets and released it 14 days later. ZFS will not destroy a held snapshot until the hold is released, and only the host can release it. The agent built it without me asking for it, so I removed it right away as scope creep.

Then every model I asked to review the project suggested them again, each in its own context window: Opus 5.5, GPT-6 Astra, and even the one that reviewed a draft of this post. Joe and I had set out to protect against a machine dying (a fire or a flood), not against one of our own machines being hacked. But I am tempted to add the holds back. They cover the case where malware or an attacker gets onto my machine and uses my key to delete my backups on his NAS, or to replace them with garbage. Adding the feature without asking was still wrong; the feature itself might not be.

References #

MindRoom: AI agents that live in Matrix and work everywhere 🧠

Fri, 26 Jun 2026 00:00:00 +0000

Table of contents

1. The problem: your AI is trapped in apps #

Programming is my biggest passion in life. I’ve been actively involved in open source for over ten years now, maintaining 40+ installable packages across Python, JavaScript, and Rust. Some of these have over 100,000 users; others have exactly one—me. I mention this because it matters for what comes next: when AI coding tools arrived, I didn’t start from zero. As I wrote about in my agentic coding post, AI has completely transformed how I work—when I’m AFK, I regularly build full features or entire projects by dictating to my phone and routing it through my own transcription software.

Through all of this, I became deeply convinced that AI agents are the future. Not just a useful tool for programmers—a fundamental shift in how everyone will interact with computers.

But if that’s true, then the way agents work today is broken.

We’ve built artificial barriers between artificial intelligences. ChatGPT knows you in one tab, Claude knows you in another, your Slack bot knows you in a third. Your email AI can’t tell your calendar AI about that meeting invitation. Your coding assistant has no idea about the project specs sitting in your document AI. Switch platforms, and your AI starts from scratch.

Most agent frameworks require you to program them. That works for developers like me, but if agents are truly the future, they need to work for everyone. Non-programmers don’t want to write code—they just want a chat.

And then there’s privacy. I’m fine sharing my email with Gemini—Google already owns my Gmail. But do I want to send my financial data, my health records, or my personal notes to a cloud provider? Not really. I’d rather use a local model for sensitive tasks and pick the best, cheapest Chinese model for general-purpose deep research.

So I built MindRoom on a chat protocol—if people just want a chat, give them a chat. Agents live in the same rooms as you, collaborate in threads, and follow you across every platform. The first commit landed on July 29, 2025 (four months before OpenClaw’s first commit 😅), so by the time I’m publishing this MindRoom has been with me for nearly eleven months: first as an obsessive side project, then, since March, with much more sustained focus. At first I got so obsessed with it that I eventually burned out and had to step away completely.

Recently, seeing OpenClaw gain massive traction solving a similar problem reminded me that what I’d been building wasn’t just a niche obsession. So here I am, dusting off MindRoom and writing about what it is, how it works, and why I think the approach still matters.

Live chat.mindroom.chat Personal thread with the prompt: “Explain how MindRoom and what you can do.” Mind answers in the real Matrix room, using tool calls and the Codex-backed local MindRoom runtime.

2. What is MindRoom? #

MindRoom is an open-source system that creates AI agents living inside the Matrix protocol. If you’re not familiar with Matrix—it’s a federated, end-to-end encrypted communication standard. The same protocol used by the French government for 5.5 million civil servants, by German healthcare for 150K+ organizations, and by the Element app that millions of people use daily.

The key insight: Matrix has bridges to many major platforms—Slack, Telegram, Discord, WhatsApp, IRC, email, even SMS.

So if your AI agent lives in Matrix, it can reach you on any platform. One agent, every platform, continuous memory.

One practical caveat: Matrix bridges vary in maturity. Some, like the Telegram bridge, work very well, while others can be finicky. Your mileage may vary depending on which platforms you need.

Here’s what a typical setup looks like in config.yaml:

agents:
 code:
 display_name: CodeAgent
 role: Generate code, manage files, execute shell commands
 model: opus-4.8
 tools: [file, shell, github]
 instructions:
 - Always read files before modifying them.
 rooms: [lobby, dev]

 research:
 display_name: ResearchAgent
 role: Search the web, summarize papers, find information
 model: gpt-5.5
 tools: [tavily, arxiv, wikipedia]
 rooms: [lobby, research]

teams:
 super_team:
 display_name: Super Team
 agents: [code, research]
 mode: collaborate

Define your agents, give them tools and rooms, and they show up in Matrix as real users—with avatars, typing indicators, and online status.

MindRoom agents are real Matrix users with their own accounts, generated avatars, display names, room memberships, and online presence.

3. How it actually works #

At the core sits what I call the MultiAgentOrchestrator—a class in bot.py that boots every configured entity (router, agents, teams), provisions Matrix user accounts for each one via matrix-nio, and keeps sync loops alive. The agents themselves are powered by the Agno framework, which provides a unified interface across AI model providers.

When someone sends a message in a Matrix room:

Explicit mentions go directly to the named agent (@mindroom_code help me debug this)
Thread continuations keep the same agent responding (no weird context switches mid-conversation)
New conversations hit the router—an AI that analyzes the message and picks the best agent based on capabilities

All conversations happen in threads, which keeps rooms organized. Agents stream their responses in real-time, editing a single message as they think rather than spamming new ones. You see tool calls happening live:

🔧 Tool Call: search_web(query="matrix protocol bridges")
[waiting for result...]
✅ search_web result:
[results here]

The recording below starts in the main Personal room, sends the prompt Explain how MindRoom and what you can do., and then follows MindRoom as it opens the new thread and streams the reply to completion. It is sped up 2.5x to keep the flow skimmable.

4. Building on Matrix: the good and the tricky #

One of the best things about building on Matrix is what you get for free. End-to-end encryption, a deeply interoperable chat protocol with bridges to many platforms, a choice of clients, federation between organizations—all of that comes with the protocol. You don’t have to build any of it yourself.

But because Matrix has such a tight specification, it also brings challenges.

The protocol doesn’t support streaming. AI agents that think for 30 seconds before dumping a wall of text make for a terrible chat experience, so I hacked streaming in by rapidly editing the same message as new tokens arrive. An ⋯ marker shows while the agent is still thinking—a small touch, but it makes the experience feel responsive and alive.

There’s also a size limit on message content. That’s fine for human chat, but AI responses can get long—especially when tool calls and their results are included. I worked around this by using Matrix’s attachment feature: when a response exceeds the limit, the content continues in an attachment that gets updated as the message keeps streaming in. This required forking the Cinny chat client so that attachments display inline rather than as downloadable files, making the whole thing seamless.

5. Memory that follows you #

MindRoom currently supports two memory implementations.

The first is the more traditional semantic memory system built on Mem0’s AsyncMemory, with configurable embedding providers (OpenAI, Ollama, or HuggingFace) and vector storage via ChromaDB. This gives agents searchable memory for preferences, project context, decisions, and recurring facts.

The second is a file-based memory system inspired by the simplicity of OpenClaw-style agent files. Instead of burying identity in a database, durable context can live in plain Markdown files that travel with the agent. That portability matters: I can move the same agent identity from OpenClaw to Hermes to MindRoom without starting from scratch.

MindRoom also has a memory flush step that periodically extracts durable facts from conversations and writes them back into memory. So the chat transcript remains chat, while stable preferences, decisions, and identity details become reusable context for future turns.

A live Personal memory demo: MindRoom stores a harmless preference in one turn and retrieves it later from the same Matrix conversation.

6. 100+ built-in tool integrations #

Agents can use over 100 built-in integrations:

Category	Examples
Communication	Gmail, Slack, Telegram, Discord
Development	GitHub, Shell, Python, Docker
Search	Tavily, Wikipedia, Arxiv, DuckDuckGo
Productivity	Google Calendar, Jira, Linear, Todoist
Smart Home	Home Assistant
AI/ML	DALL-E, ElevenLabs, Replicate
Data	Pandas, SQL, DuckDB, Yahoo Finance
Web	Firecrawl, Crawl4ai, Browser automation

Tools are lazy-loaded and credential-managed, so an agent only loads what it needs.

7. Teams: agents that collaborate #

Single agents are useful, but sometimes you need a team. MindRoom supports two collaboration modes:

Coordinate mode: A lead agent orchestrates others. You ask a question, the lead delegates subtasks, collects results, and synthesizes a unified response.

Collaborate mode: All agents work on the same task in parallel, each providing their independent analysis. The system then merges their responses with a consensus summary.

In practice, you might have a research team where one agent searches academic papers, another checks industry news, and a third validates claims—all triggered by a single message. The live room view below shows a real team response in the same Matrix thread surface normal agents use: threads, routed agents, and room history are all first-class chat objects rather than a separate dashboard.

Live Lobby thread in chat.mindroom.chat showing a real Team Response from HomeAssistant and AgentBuilder. Team collaboration uses the same Matrix-native interface as regular agent chats, with routed agents and room membership visible beside the conversation.

8. Hot-reload: change config and plugins without downtime #

config.yaml is watched at runtime. When you edit it—add an agent, change a model, update instructions—MindRoom diffs the old and new config, gracefully restarts only the affected agents, and has them rejoin their rooms. No downtime, no full runtime restart required.

The same development loop applies to plugins. MindRoom has a rich Python hook system, and plugins can be live-developed while the system is running. Change a plugin file, save it, and MindRoom automatically reloads the plugin without restarting the Python runtime.

This sounds minor, but when you’re iterating on agent behavior or plugin hooks, being able to tweak code and config and see results in seconds significantly improves the development loop.

9. Voice, scheduling, and other features #

Some features I built purely because I wanted them for myself (a recurring theme in my projects, as anyone who’s read my local AI journey can attest). I even built Matty, a Matrix CLI client, from bed at midnight because I needed a way to interact with my agents from the terminal:

Voice messages: Audio messages in Matrix are auto-transcribed via Whisper and treated as regular text input. You can talk to your agents.
Scheduled tasks: Natural language scheduling (!schedule "check my email every morning at 9 AM") backed by cron jobs. Agents can run tasks in the background and escalate to you when needed.
DM support: Agents respond naturally in 1:1 conversations without needing mentions.
Cross-organization federation: Because Matrix is federated, two companies’ AI agents can collaborate in a shared room—something that’s hard to do on proprietary platforms.

10. The obsession, the SaaS dream, and the burnout #

I need to be honest about what actually happened with MindRoom, because “life got in the way” is a sanitized version of the story.

What really happened is that I got completely, utterly obsessed. Every single second I wasn’t working at my day job or sleeping, I was working on MindRoom. Many hundreds of hours went into it. I seriously considered quitting my job and starting an AI startup around it.

If you’ve read Armin Ronacher’s post Agent Psychosis: Are We Going Insane?, you’ll know exactly what I’m talking about. The dopamine hit from building with AI agents is incredibly real. As Armin writes: “You feel productive, you feel like everything is amazing, and if you hang out just with people that are into that stuff too, without any checks, you go deeper and deeper into the belief that this all makes perfect sense.”

That was me. I was building and building, shipping feature after feature, and it felt incredible. The codebase grew to over 1,000 commits. I built the core system, then a React dashboard, then I started on a full SaaS platform—Kubernetes deployments on Hetzner Cloud, a FastAPI backend, a Next.js 15 frontend, Stripe integration, Supabase auth, Helm charts for multi-tenant isolation.

And that’s where the enthusiasm started to erode. Not because the core idea was bad, but because the work shifted from building interesting things (agent orchestration, memory systems, routing intelligence) to grinding through SaaS boilerplate: GDPR compliance, payment processing, automated Kubernetes deployments, terms of service, cookie banners. The dopamine loop that kept me going at 2 AM broke when the work stopped being creative and started being compliance paperwork.

The hosted control plane lives at app.mindroom.chat. I am deliberately not turning this section into a dashboard tour; the interesting part, and the part I still care about most, is the Matrix-native runtime underneath it.

11. OpenClaw and why it matters #

OpenClaw takes a different approach to the same core problem. Where MindRoom builds on Matrix federation as the backbone, OpenClaw runs a local Gateway on your machine and connects to messaging platforms directly (WhatsApp via Baileys, Telegram via grammY, Discord via discord.js, and so on).

The similarities are striking:

Both give you a single AI assistant across all your messaging platforms
Both have persistent memory
Both support multiple tools and integrations
Both are open-source and privacy-focused
Both let you choose your own AI model

The differences are interesting too. OpenClaw is local-first and TypeScript-based with 380K+ stars and a massive community. MindRoom is Python-based, federation-first, and… well, let’s just say my GitHub star count is a few orders of magnitude lower.

But seeing OpenClaw validate the core idea—that people want AI assistants that aren’t trapped in apps—reminded me that what I’d been building matters. The federation angle is something OpenClaw doesn’t have: the ability for agents from different organizations to collaborate natively, with end-to-end encryption (Olm/Megolm), on a protocol that governments already trust and deploy at scale.

MindRoom uses Matrix as the federated backbone; OpenClaw takes a local-gateway, direct-connector approach.

And then there’s Moltbook—a social network built exclusively for AI agents that the internet was losing its mind over for a couple of days. I’m not personally convinced it’s the next big thing, but what caught my attention is that MindRoom could support something like it natively. Matrix is already federated—agents on different servers can already interact, join shared rooms, and collaborate across organizational boundaries. A bridge from a Reddit-like platform to Matrix and your agents could participate without any special integration.

Building agent-to-agent infrastructure from scratch also means building security from scratch—and that’s where new platforms tend to struggle. Matrix has spent years hardening its E2E encryption, and it’s already deployed by governments and healthcare organizations at scale. Building on that foundation means you inherit those security properties rather than hoping to get them right yourself.

12. What’s next #

I first drafted this post a couple of months ago, when MindRoom was still something I was trying to come back to. That part is already out of date. Since January I’ve been spending nearly every free hour on it again, and since March it has effectively been my full-time work. The codebase supports 8+ AI model providers—OpenAI, Anthropic, Ollama, Groq, Google, OpenRouter, DeepSeek, Cerebras—and the core architecture is solid. It also has real users now. My rough guess is that something like 30-100 people have tried MindRoom in one form or another, which is still early, but meaningfully different from “only I have touched this.” There’s already a Docker Compose file and a starter repository to get started, but I want to make it even simpler.

What I’m focusing on now:

Skills system: Building an ecosystem of reusable agent behaviors (already partially implemented with OpenClaw-compatible format)
Even easier onboarding: A docker compose up gets you running today, but I want a wizard that gets you from zero to working agents without touching a YAML file
Community: Turning the small group of early users into a real operator and contributor community
Scope discipline: Keeping the work sustainable now that MindRoom is effectively full-time, not slipping back into the obsessive 2 AM marathon from before

I’m deliberately leaving the SaaS ambitions aside for now. The core system is what matters, and that’s where the energy is going.

If you’re interested in AI agents that live in Matrix and work everywhere, check out MindRoom on GitHub.

Sometimes seeing someone else succeed with a similar idea is enough to remember why you started building in the first place. And sometimes the most important lesson from a project isn’t technical—it’s learning when to step away and when to come back.

Are you running AI agents on any messaging platforms? Have you tried Matrix for anything beyond regular chat? I’d love to hear about your setups!

Links and resources #

Auto-installing extras at runtime so users never have to think about dependencies

Wed, 11 Feb 2026 00:00:00 +0000

Table of contents

1. From one command to a dependency maze #

agent-cli started as a simple thing. Voice in, text out. It connected to a Wyoming Whisper server for speech-to-text and a Piper server for text-to-speech, basically a local, open-source Siri triggered from terminal hotkeys. I wrote about the early version in my local AI journey post.

And then, as tends to happen with side projects I use every day, I kept adding things.

First a RAG proxy with ChromaDB, so I could chat with my documents. Then a long-term memory system, so conversations could remember context across sessions. Server commands that run Kokoro TTS or Whisper locally, optimized for whatever hardware you have—Apple Silicon gets MLX, NVIDIA gets CTranslate2. Voice activity detection with Silero VAD. Audio speed adjustment. An agent orchestration system. systemd/launchd service management for running background daemons.

Each of these features pulled in wildly different dependency trees. torch and transformers for GPU-accelerated Whisper. sounddevice and numpy for microphone access. chromadb and onnxruntime for vector storage. kokoro with its entire spacy pipeline for neural TTS.

Today the project has 13 optional extras. The tool became much more useful, but dependency UX got progressively worse with every feature.

2. Why “just use extras” breaks down #

Python’s optional-dependencies in pyproject.toml is the standard mechanism for this, and it’s the right packaging primitive. You define groups, users install with pip install agent-cli[rag]. On paper, this is perfectly reasonable.

In practice, it falls apart when you have 13 of them:

[project.optional-dependencies]
audio = ["numpy", "sounddevice>=0.4.6", "agent-cli[wyoming]"]
llm = ["pydantic-ai-slim[openai,google,duckduckgo,vertexai]>=0.1.1"]
rag = ["pydantic-ai-slim[openai,google]>=0.1.1", "chromadb>=0.4.22", ...]
memory = ["pydantic-ai-slim[openai,google]>=0.1.1", "chromadb>=0.4.22", ...]
vad = ["onnxruntime>=1.16.0"]
faster-whisper = ["faster-whisper>=1.0.0"]
mlx-whisper = ["mlx-whisper>=0.4.0; sys_platform == 'darwin' and platform_machine == 'arm64'"]
kokoro = ["kokoro>=0.9.0", "soundfile>=0.12.0", ...]
piper = ["piper-tts>=1.2.0"]
# ... and more

The UX problem is obvious. If I want to transcribe voice to text, do I need audio? llm? vad? All three? What if I want the Whisper server to run locally—is that faster-whisper or mlx-whisper? Do I also need server for that?

Expecting users to study a dependency matrix before running a CLI command is a terrible experience. I wanted three things:

A lightweight base install that’s fast and doesn’t pull in heavy ML dependencies.
Commands that “just work” when first used.
A clear opt-out for people who don’t want automatic installs.

3. The decorator #

The core idea is simple. Each CLI command declares what it needs, and the decorator handles the rest:

@app.command("transcribe", rich_help_panel="Voice Commands")
@requires_extras("audio", "llm")
def transcribe(...):
 ...

That’s it from the command author’s perspective. One line, and you never think about dependency management in that command again.

Here are a few more examples from the codebase to show how this scales:

# Continuous transcription needs audio, voice activity detection, and an LLM
@requires_extras("audio", "vad", "llm")
def transcribe_live(...):
 ...

# TTS server needs the server framework + one of two TTS backends + Wyoming protocol
@requires_extras("server", "piper|kokoro", "wyoming")
def start_tts_server(...):
 ...

# Whisper server: any of three ASR backends will do
@requires_extras("server", "faster-whisper|mlx-whisper|whisper-transformers", "wyoming")
def start_whisper_server(...):
 ...

Notice the pipe syntax: "piper|kokoro" means “you need either Piper or Kokoro—any one of these satisfies the requirement.” On Apple Silicon, if you already have mlx-whisper installed, it won’t try to install faster-whisper instead.

The decorator itself is straightforward:

def requires_extras(*extras: str) -> Callable[[F], F]:
 def decorator(func: F) -> F:
 @functools.wraps(func)
 def wrapper(*args, **kwargs):
 if _check_and_install_extras(extras):
 raise typer.Exit(1)
 return func(*args, **kwargs)
 return wrapper
 return decorator

The real complexity lives in _check_and_install_extras, which handles several installation scenarios. But the interface for command authors is always a single line.

4. Checking without importing #

You don’t want to import torch just to check if it’s available—that takes seconds and loads hundreds of megabytes into memory. Instead, I use importlib.util.find_spec, which checks whether a module exists on the import path without executing any of its code. No heavy imports, no GPU initialization, no side effects. The check is essentially free.

5. The metadata bridge #

There’s a gap between what pyproject.toml knows and what the runtime check needs. pyproject.toml says the rag extra requires chromadb>=0.4.22—that’s the pip package name. But at runtime, I need to check Python import names. Sometimes these are the same (chromadb → import chromadb), but often they’re not: pydantic-ai-slim is imported as pydantic_ai, piper-tts as piper.

To bridge this, I generate an _extras.json file that maps each extra to its description and the Python import names needed for the runtime check:

{
 "audio": ["Audio recording/playback", ["sounddevice"]],
 "rag": ["RAG proxy (ChromaDB, embeddings)", ["chromadb", "pydantic_ai"]],
 "memory": ["Long-term memory proxy", ["chromadb", "yaml", "pydantic_ai"]],
 "vad": ["Voice Activity Detection (Silero VAD via ONNX)", ["onnxruntime"]],
 "faster-whisper": ["Whisper ASR via CTranslate2", ["faster_whisper"]]
}

This file is generated by a script that parses pyproject.toml and applies a mapping table for the package-name-to-import-name conversions. A pre-commit hook ensures it stays in sync—if you add an extra to pyproject.toml and forget to update the metadata, the commit fails.

I wish Python packaging had a standard way to discover a package’s top-level import name from its distribution name. It doesn’t, so the mapping table is the least-bad option I found.

6. Three environments, three strategies #

The hard part is that people run agent-cli in several different ways, and each needs a different installation strategy.

A) `uv tool install` — the persistent environment #

When installed via uv tool install agent-cli, the tool lives in a persistent environment under ~/.local/share/uv/tools/agent-cli/. This environment has a uv-receipt.toml file that tracks which extras are installed.

When auto-install triggers, the system reads the current extras from that receipt, merges in the new ones, and reinstalls:

def install_extras_impl(extras, *, quiet=False):
 if is_uv_tool_install():
 current_extras = _get_current_uv_tool_extras()
 new_extras = sorted(set(current_extras) | set(extras))
 return _install_via_uv_tool(new_extras, quiet=quiet)

So if you already had audio installed and now run a command that needs llm, it becomes uv tool install agent-cli[audio,llm] --force.

The key insight: uv tool upgrade reads uv-receipt.toml and preserves the extras list. Once auto-install adds an extra, it persists across future upgrades. You never have to install it again.

(Full implementation)

B) `uvx` — the ephemeral environment #

uvx is uv’s tool for running packages in temporary, disposable environments. Running uvx agent-cli transcribe creates a fresh environment, installs agent-cli, runs the command, and throws the environment away.

The problem: there’s nowhere to persist extras. No uv-receipt.toml to update, no virtualenv that survives the invocation.

The solution is one of my favorite tricks in this system: re-execute the entire command with the extras baked into the uvx invocation itself:

def _maybe_reexec_with_uvx(extras):
 if os.environ.get(_REEXEC_MARKER) or not _is_uvx_cache():
 return
 uvx_path = shutil.which("uvx")
 if not uvx_path:
 return
 extras_str = ",".join(extras)
 cmd = [uvx_path, "--python", "3.13",
 f"agent-cli[{extras_str}]", *sys.argv[1:]]
 _maybe_exec_with_marker(cmd, f"Re-running with extras: {extras_str}")

So uvx agent-cli transcribe transparently becomes uvx agent-cli[audio,llm] transcribe. The user sees a brief “Re-running with extras: audio, llm” message, and then the command works.

Environment detection is straightforward—uvx environments live under the uv cache directory:

def _is_uvx_cache():
 prefix_str = Path(sys.prefix).resolve().as_posix()
 return "/cache/uv/" in prefix_str or "/archive-v" in prefix_str

(Full implementation)

C) Regular virtualenv, `pipx`, or system install #

For plain pip install agent-cli, pipx, or virtualenv installs, the system falls back to direct installation. Each extra has a pre-generated requirements file with pinned versions (e.g., _requirements/audio.txt), and the install command adapts to whatever’s available:

def _install_cmd():
 in_venv = sys.prefix != sys.base_prefix
 if shutil.which("uv"):
 cmd = ["uv", "pip", "install", "--python", sys.executable]
 if not in_venv:
 cmd.append("--system")
 return cmd
 cmd = [sys.executable, "-m", "pip", "install"]
 if not in_venv:
 cmd.append("--user")
 return cmd

Prefers uv pip when available (fast), falls back to regular pip. Uses --system or --user as appropriate when not in a virtualenv. This is also the path that pipx installations take—pipx creates a regular virtualenv under the hood, so the auto-installer detects it as a venv and installs directly into it.

(Full implementation)

7. Preventing infinite re-execution loops #

There’s an obvious footgun here: what if the install succeeds but the package still isn’t importable for some reason? You’d get an infinite loop of install → re-exec → check → install → re-exec → …

The fix is a simple environment variable marker:

_REEXEC_MARKER = "_AGENT_CLI_REEXEC"

def _maybe_exec_with_marker(cmd, message):
 if os.environ.get(_REEXEC_MARKER):
 return # Already re-executed once, don't loop
 new_env = os.environ.copy()
 new_env[_REEXEC_MARKER] = "1"
 os.execvpe(cmd[0], cmd, new_env)

os.execvpe replaces the current process entirely—it never returns. The marker ensures we only do this once. If the second run still can’t find the packages, it falls back to a helpful error message instead of looping forever.

8. What users actually see #

With auto-install enabled (the default), a first run looks like this:

Auto-installing missing extras: audio, llm
Running: uv tool install agent-cli[audio,llm] --force --python 3.13 -q
Installation complete!
Re-running with installed extras...

And then the command runs normally. Next time, it runs instantly—no install needed.

With auto-install disabled, the user gets a clear message telling them exactly what to do:

This command requires the 'audio' extra (Audio recording/playback).

Install with:
 uv tool install -p 3.13 "agent-cli\[audio]"
 # or
 agent-cli install-extras audio

If you prefer explicit control, there’s also a manual install-extras command:

agent-cli install-extras rag memory # Install specific extras
agent-cli install-extras --all # Install everything
agent-cli install-extras --list # Show available extras with descriptions

You can opt out via environment variable or config file:

export AGENT_CLI_NO_AUTO_INSTALL=1

# ~/.config/agent-cli/config.toml
[settings]
auto_install_extras = false

9. Keeping everything in sync #

The runtime system depends on two generated artifacts:

_extras.json: maps extras to descriptions and import names (for the find_spec check)
_requirements/*.txt: pinned dependency files for each extra (for the pip/uv install)

_extras.json is generated by sync_extras.py (run manually or in CI). The requirements files are generated by sync_requirements.py, which runs as a pre-commit hook whenever pyproject.toml or uv.lock changes. A check script enforces that _extras.json stays consistent with pyproject.toml—if you add an extra but forget to update the metadata, the commit fails with a clear error.

This means the runtime system never drifts from the source of truth. pyproject.toml is the canonical definition, everything else is derived.

10. Why uv made this practical #

I want to be clear: this system would be much harder without uv.

uv tool install with persistent extras in uv-receipt.toml—extras survive upgrades automatically
uvx for ephemeral execution with extras specified inline
uv pip install that’s fast enough for runtime auto-install to feel acceptable
uv export for generating pinned requirements files from uv.lock

With traditional pip, auto-installing at runtime would take 30-60 seconds and feel terrible. With uv, it typically takes a second. That’s the difference between “annoying” and “barely noticeable.”

11. Tradeoffs #

This approach works well, but it’s still a tradeoff:

There’s metadata to maintain. The package-name-to-import-name mapping requires a lookup table with special cases like piper-tts → piper and pydantic-ai-slim → pydantic_ai. I wish pyproject.toml had a field for this.
The check only verifies importability, not version compatibility. find_spec tells you a module exists, not whether it’s the right version. In practice this hasn’t been a problem because uv’s pinned requirements handle versions, but it’s a theoretical gap.
Auto-install can fail in restricted environments. Corporate machines, read-only containers, air-gapped systems—the opt-out exists for a reason.
Re-exec is a CLI pattern, not a library pattern. os.execvpe replaces the process, which means any shell hooks or signal handlers set up before the decorator runs are lost. Fine for CLI tools, would be problematic for libraries.

12. Not dependency injection #

I originally called this “dependency injection” in my head, but that’s the wrong term entirely. Dependency injection is about providing object dependencies through constructors or function parameters. This is something different.

The best names I’ve come up with:

runtime optional dependency resolution — accurate but a mouthful
on-demand extras installation — emphasizes the user experience
lazy extras — short, probably what I’d use in conversation

If there’s a standard term for this pattern, I haven’t found it.

13. Conclusion #

The underlying principle is simple: the tool should know what it needs, and it should get it. Users shouldn’t have to study a matrix of 13 optional extras to figure out which pip command to run. They should just type the command they want, and it should work.

uv’s speed and tooling model made this practical. A decorator made it ergonomic for command authors. Pre-commit hooks made it maintainable. And three environment-detection strategies made it work regardless of how the user installed the tool.

If you’re building a Python CLI with optional features that keep growing, consider this pattern. Your users will thank you, mostly by never having to ask “which extras do I need?”

The code discussed here is part of agent-cli, an open-source suite of AI-powered command-line tools. The implementation lives primarily in agent_cli/core/deps.py.

Parallel agentic coding made trivial with `agent-cli dev`

Tue, 13 Jan 2026 00:00:00 +0000

Table of contents

1. The “just use worktrees” problem #

Last week, I was chatting with a friend about my agentic coding workflow. I was sharing some of my best practices, and when the topic of parallel development came up, I said:

“Just use git worktrees with quickly installable environments.”

He stared at me blankly.

And then it hit me: for most developers who just git add, git commit, git push and don’t touch their environment setup once it works, this is not trivial. What seems obvious to me involves:

Understanding what git worktrees even are
Knowing the git worktree add command and its flags
Remembering to fetch before creating
Creating a sibling directory structure
Running your package manager’s install command
Copying over .env files
Setting up direnv or manually activating your virtual environment
Opening a new terminal tab
Navigating to the worktree
Finally launching your coding agent

That’s a lot of friction for something you want to do frequently when using agentic tools.

So I built agent-cli dev.

2. Why parallel development matters for agentic coding #

In my previous post on agentic coding, I described my workflow of running 5-6 Claude Code sessions simultaneously, each working on a different feature. This is how I can easily work on multiple features in parallel while waiting for an agent to process and generate code.

The usual way: Start feature A → wait for Claude to finish → review → move to feature B → repeat.

The better way: Start feature A in tab 1 → switch to tab 2, start feature B while A is working → switch to tab 3, start feature C → circle back to tab 1, review what Claude did → give feedback, move to next tab → repeat every 10-15 minutes.

This parallel approach allows me to go much faster. But it only works if each tab has its own completely isolated and working environment.

That’s where git worktrees come in. A worktree gives you a separate working directory for a branch, sharing the same git history but with independent file states.

The problem is the setup. Every time you want to start a new feature:

# The manual way (don't do this)
git fetch origin
git worktree add ../my-project-worktrees/cool-feature -b cool-feature origin/main
cd ../my-project-worktrees/cool-feature
uv sync --all-extras # or npm install, or poetry install, or...
cp ../.env .env
# Now open a new terminal tab...
# Navigate there...
# Finally start claude

After the 100th(?) time doing this manually, I knew I needed to automate it.

3. One command to rule them all #

Here’s what I built:

agent-cli dev new --agent

That’s it. One command. Here’s what it looks like:

→ Generated branch name: cool-crane
→ Creating worktree for branch 'cool-crane'...
→ Running: git fetch origin
→ Running: git worktree add -b cool-crane ~/Work/project-worktrees/cool-crane origin/main
✓ Created worktree at ~/Work/project-worktrees/cool-crane
✓ Copied env file(s): .env.example, .envrc
→ Detected Python project with uv
→ Running: uv sync --all-extras
→ Running: direnv allow
✓ direnv: allowed existing .envrc
✓ Started claude in new iterm2 tab

╭─────────────────────────────────────────────── Success ───────────────────────────────────────────────╮
│ Dev environment created: ~/Work/project-worktrees/cool-crane │
│ Branch: cool-crane │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────╯

4 seconds later, I have a new terminal tab with Claude Code already running in a fresh, isolated environment. Ready to work on my next feature.

What happens under the hood:

Generates a random branch name like clever-fox (you can just set the name yourself of course)
Creates the git worktree in a sibling directory
Detects the project type and runs the appropriate setup (uv sync, npm install, etc.)
Copies .env files from the main repo
Sets up direnv so the environment activates automatically
Opens a new terminal tab (works with tmux, zellij, iTerm2, and more)
Launches your coding agent in that tab

The Docker-style random names (clever-fox, happy-bear, swift-owl) there just for those too lazy to pick a name. Just agent-cli dev new --agent and start coding.

4. It knows your stack #

The command auto-detects your project type:

If it sees…	It runs…
`uv.lock`	`uv sync --all-extras`
`pixi.lock`	`pixi install`
`poetry.lock`	`poetry install`
`requirements.yaml`	`unidep install -e .`
`package-lock.json`	`npm install`
`Cargo.toml`	`cargo build`
`go.mod`	`go mod download`

For my projects using unidep, it even detects monorepos and adjusts the command accordingly.

It also generates the right .envrc for direnv. For a Python project with uv, that’s source .venv/bin/activate. For a conda/unidep project, it’s the full micromamba activation. For Nix projects, it’s use flake.

This means when you cd into the worktree later, your environment is automatically activated. No more source .venv/bin/activate.

5. Terminal magic #

The real magic is opening a new terminal tab with the agent already running.

The command detects which terminal you’re in and uses the appropriate API—whether that’s iTerm2, Kitty, Warp, or GNOME Terminal. It even works with terminal multiplexers like tmux and zellij (my current favorite), opening a new window/tab in your existing session.

6. Spawning agents with prompts #

The --prompt option transforms how I spawn parallel agents. Instead of just opening a blank Claude session, I can give the new agent its task immediately:

agent-cli dev new fix-auth-bug --agent --prompt "Fix the login validation bug in auth.py. The issue is that empty passwords pass validation."

The agent opens with the prompt already loaded and starts working immediately. No copy-pasting, no context switching, no “let me explain what I need you to do.”

For longer, more detailed prompts (which you should use for complex tasks), there’s --prompt-file:

agent-cli dev new new-feature --agent --prompt-file .claude/spawn-prompt.md

This is particularly powerful when you’re in a Claude session and discover a feature that needs work but is unrelated to your current task. Instead of context-switching or noting it for later, you can spawn a new agent right there:

Write a detailed prompt to a file (Claude can do this)
Run agent-cli dev new unrelated-feature --agent --prompt-file .claude/spawn-prompt.md
A new terminal tab opens with a fresh Claude session already working on the task
Continue with your original work

The spawned agent works independently in its own branch while you stay focused.

7. Teaching Claude to spawn agents #

Here’s where it gets really interesting: you can teach Claude Code itself how to spawn parallel agents.

agent-cli dev install-skill

This installs a Claude Code skill that teaches Claude how to use agent-cli dev. The skill includes detailed examples and prompt templates following Anthropic’s prompt engineering guide.

With the skill installed, you can say things like:

“Work on auth, payments, and notifications in parallel”
“This feature is unrelated to what we’re doing—spawn a new agent for it”
“Split this refactoring by module and work on them simultaneously”

Claude will write well-structured prompts (using proper XML tags, clear context, explicit requirements) and spawn the agents for you. Each spawned agent writes a report to .claude/REPORT.md when done, so you can easily review what happened.

One of my favorite patterns: I ask Claude to look at the latest 10 open GitHub issues and spawn an agent for each one. Ten independent parallel environments, set up in seconds, each working on a different issue. That’s the kind of leverage this enables.

8. My actual workflow #

Here’s how I use this in practice. I’m working on agent-cli itself, and I want to add three features:

# Tab 1: New RAG feature
agent-cli dev new rag-improvements --agent --prompt "Improve RAG chunking strategy for better retrieval accuracy"

# Tab 2: Fix a bug in the transcribe command
agent-cli dev new fix-transcribe-vad --agent --prompt "Fix VAD detection cutting off words at sentence boundaries"

# Tab 3: Refactor the config system
agent-cli dev new config-refactor --agent --prompt "Refactor config.py to use a single Config class with lazy loading"

Three commands, three isolated environments, three Claude Code sessions already working on their tasks.

I cycle through the tabs every 10-15 minutes:

Review what Claude did
Give voice feedback using my transcription workflow
Move to the next tab

When a feature is done, I have Claude open a PR from that branch. When the PR is merged:

agent-cli dev clean --merged

This uses the GitHub CLI to check which branches have merged PRs, then removes those worktrees and deletes the branches. No more zombie worktrees cluttering my disk.

9. Managing environments #

A few other commands I use regularly:

# List all worktrees
agent-cli dev list

# Navigate to a worktree
cd "$(agent-cli dev path clever-fox)"

# Remove a worktree
agent-cli dev rm clever-fox

# Force removal + delete branch
agent-cli dev rm clever-fox --force --delete-branch

# Check what's available on your system
agent-cli dev doctor

The doctor command is handy for seeing which terminals, editors, and coding agents are installed and detected.

10. Getting started #

agent-cli dev is part of the agent-cli package:

# With uv (recommended)
uv tool install agent-cli

Then in any git repository:

# Check what's available
agent-cli dev doctor

# Create your first parallel environment with a task
agent-cli dev new my-feature --agent --prompt "Add user profile page with avatar upload"

# Or install the skill so Claude can spawn agents for you
agent-cli dev install-skill

Supported coding agents: Claude Code, Codex, Gemini, Aider, GitHub Copilot, Continue, OpenCode, and Cursor Agent. Use --with-agent gemini to pick a specific one, or set a default in your config.

Supported terminals: tmux, zellij, iTerm2, Terminal.app, Kitty, Warp, and GNOME Terminal.

Supported editors: Cursor, VS Code, Zed, PyCharm (and other JetBrains IDEs), Neovim, Vim, Emacs, Sublime Text, and nano.

Conclusion #

The barrier between “I want to work on this feature” and “I’m actually working on it in an isolated environment” should be zero.

Before:

2-5 minutes of manual setup per feature
Often skipped because “it’s not worth it for a small change”
Mental overhead remembering all the steps

After:

One command, few seconds
No excuse not to work in isolation
More parallel features, faster iteration

If you’re using agentic coding tools and not yet working in parallel, you’re leaving productivity on the table. And if the setup friction was stopping you—well, now it’s gone.

Try it out and let me know what you think! The code is open-source at github.com/basnijholt/agent-cli.

Links #

SOTA RAG & Memory without the database: Files, Git, and simple folders

Wed, 10 Dec 2025 00:00:00 +0000

Table of contents

1. The amnesia problem #

If you’ve read my posts on agentic coding or my local AI journey, you know I am all-in on using AI to control my computer and write software. But one critical piece was missing: Context.

LLMs are powerful but stateless. Every time I start a new chat, the model forgets who I am, what I’m working on, and that I prefer functional Python code over object-oriented styles. Worse, it also forgets the thing I just told it five minutes ago in another window.

The standard solution to this is RAG (Retrieval-Augmented Generation) and Memory. But when I looked at the available tools, I hit a wall.

Most solutions fell into two buckets:

SaaS / Web UIs: Upload your files to a cloud service or use a specific web chat interface that locks you in.
Developer Libraries: “Just use LangChain/LlamaIndex!” they say. Great, now I have to write a Python script every time I want to ask a question about a PDF?

I didn’t want a library. I didn’t want a web UI. I wanted a folder. I wanted to drop a file into ~/my-docs, and have my AI instantly know about it. And I wanted my AI’s “memory” to be a file I can edit, not a hidden vector in a database I can’t inspect.

So I decided to build my own file-based solution.

2. Learning from failure: AI Journal #

This isn’t my first attempt at building a memory system.

A few months ago, I built AI Journal—an ambitious local-first journaling app where an AI would read your entries and build a “living self-model” of who you are. It had sophisticated features: a structured “persona core,” typed “claim atoms” with evidence links, four organizational layers (L1→L4), recency-aware scoring with decay functions, and Git-based time travel to “ask questions of your younger self.”

The architecture seemed solid. The problem was simpler: local models aren’t good enough yet.

I designed the whole thing to run entirely on Ollama with my dual RTX 3090s. But even with a 48GB of VRAM, the models couldn’t reliably extract structured claims, handle the multi-step reconciliation, or maintain coherence across long conversations. Whether the design was right, I still don’t know—but the execution definitely hit the wall of current local LLM capabilities.

The lesson: I tried to build the entire system at once without validating the core concepts and individual ideas first. This time, I took a different approach: tackle it problem by problem. Instead of designing a complete system upfront, I would validate each piece—chunking, retrieval, re-ranking, memory reconciliation—before combining them. The experience and UX would be my own, but the algorithms would be adapted from established projects.

3. How I studied SOTA: clone, read, re-implement #

My approach was more methodical this time. I cloned five major frameworks into the same workspace as agent-cli:

LlamaIndex: The OG RAG framework
LangChain: The kitchen-sink approach
Letta (formerly MemGPT): Stateful agents with long-term memory
Mem0: Focused specifically on memory extraction
PydanticAI: Clean, typed agent framework

I didn’t read through all this code myself—that would take months. Instead, I used AI coding agents to search the codebases and write summaries of the technical implementation details:

Gemini CLI (Gemini 3.0 Pro)
Claude Code (Opus 4.5)
Codex CLI (GPT-5.1-Codex-Max)

I fed those summaries into ChatGPT 5 Pro together with my high level plan of what I wanted to create, and it created an implementation plan. Then I took that plan back to the coding agents for implementation. I personally found Opus 4.5 the best coding model, but GPT‑5.1 Codex Max was the best at reviewing the code and actually identifying critical bugs.

For validation, I used clip-files to copy the agent-cli source code plus the architecture documents (like memory.md and rag.md) into ChatGPT 5 Pro to validate the approach.

The AI did the searching and implementing; I did the understanding and decision-making.

4. The dependency problem: why ONNX over PyTorch #

One thing became immediately clear when going through these frameworks: they’re massive.

Installing LlamaIndex with all its dependencies pulls in PyTorch. PyTorch alone is 2-3GB. Add transformers, sentence-transformers, and the kitchen sink, and you’re looking at an 8GB+ environment just to ask questions about some PDFs.

This felt excessive for a CLI tool.

One of my core design goals was minimal dependencies. I wanted agent-cli to install in seconds, not minutes. I wanted it to work on my Mac, my NixOS server, and my friend’s laptop without downloading half the internet.

The solution: ONNX Runtime.

ONNX Runtime is ~200MB and runs inference on basically anything—CPU, CUDA, even Apple Silicon. For embeddings, I use embeddinggemma running locally via llama.cpp. For re-ranking, I use a cross-encoder exported to ONNX (Xenova/ms-marco-MiniLM-L-6-v2).

The result: pip install agent-cli[rag] takes about 30 seconds and adds ~300MB. The key insight: embeddings and re-ranking are cheap operations. You don’t need a GPU for them—CPU is perfectly fine. PyTorch with CUDA support can easily reach 2-3GB+; ONNX Runtime is ~200MB and runs anywhere. Since I’m not training models, just running inference on small encoders, ONNX is the obvious choice.

5. RAG: just let me grep it (kind of) #

My requirement for RAG was simple: Files on disk are the source of truth.

I didn’t want to manage an ingestion pipeline or trigger APIs. I implemented a RAG proxy that uses OS-level file watchers (watchfiles). Here is the workflow:

I drop a PDF, Markdown, or Python file into ~/rag_docs.
The system detects the Create event.
It chunks the text and embeds it into a local ChromaDB instance.
It’s immediately searchable.

When moving or deleting files, the system updates the index accordingly.

The architecture: OpenAI compatibility #

The “secret sauce” isn’t the retrieval itself; it’s how I expose it. Instead of building a custom chat app, I built an OpenAI-compatible proxy.

flowchart LR Client["Client
(Cursor, Open WebUI)"] --> Retrieve subgraph Proxy ["RAG Proxy"] direction TB Retrieve --> Augment["Augment & Forward"] Chroma[("ChromaDB")] -.-> Retrieve Watcher["File Watcher"] --> Chroma end Augment --> Upstream["Upstream LLM"]

# Point any OpenAI-compatible tool at your local proxy
export OPENAI_BASE_URL=http://localhost:8000/v1

That’s it. Any tool that supports custom OpenAI endpoints—Cursor, Cline, Open WebUI, LibreChat—instantly gains the ability to “read” my document folder.

Two-stage retrieval: the SOTA approach #

I looked at LlamaIndex here. Standard “semantic search” (using just embeddings/bi-encoders) is often disappointing. It finds text that looks similar but isn’t actually relevant.

A common pattern in modern RAG systems is Two-Stage Retrieval.

Fast Stage: Retrieve 3x candidates using standard embeddings (text-embedding-3-small or local models like embeddinggemma).
Smart Stage: Use a Cross-Encoder to re-rank the results.

A cross-encoder looks at the query and the document together and outputs a relevance score. It’s computationally heavier, but since I’m running this locally on my RTX 3090 (or even CPU via ONNX), the 50ms latency penalty is worth it for results that are actually useful.

This isn’t a new idea, but implementing it cleanly with ONNX avoided the huge dependency tax.

6. Memory: files over databases #

This is where my approach diverges most from standard tools like Mem0. Most memory systems treat memories as database rows. If the AI remembers “User likes pizza,” that’s a vector in a DB. If it hallucinates and records “User hates pizza,” good luck fixing it. You need to write a script to query the DB and delete the row.

I prefer data I can inspect.

My memory system stores every fact as a Markdown file with YAML front matter.

---
id: "550e8400-e29b-41d4-a716-446655440000"
role: "memory"
created_at: "2025-12-15T10:00:00Z"
conversation_id: "default"
---
The user prefers using 'uv' for Python package management.

Git integration: versioning memory 🕰️ #

Because memories are just files, I added a feature that I haven’t seen anywhere else: Automatic Git Versioning.

Every time the AI learns a new fact, updates an old one, or deletes a contradiction, the system automatically commits the change to a local git repository.

This leads to incredible capabilities:

Inspectability: I can git log and see exactly when the AI learned something.
Correction: If the AI learns something wrong, I open the markdown file in VS Code, edit it, and save.
Reversion: Agent hallucinated wildly yesterday? git reset --hard HEAD~1.

The reconciliation loop #

The logic for storing memories isn’t just “append to file.” Digging into Mem0 (and Letta) showed me that memory systems need active reconciliation. When I say “Actually, I switched to nix instead of uv,” the system:

Retrieves existing memories about package managers.
Decides (using a lightweight LLM) whether to ADD, UPDATE, or DELETE.
Executes the file operation (moving the old fact to a deleted/ folder for audit trails).

This keeps the memory bank clean and contradictory-free, unlike simple vector stores that just accumulate conflicting junk over time.

The tiny detail that broke everything #

After implementing the memory system—mostly modeled after Mem0—I noticed it didn’t work as well. After a lot of debugging, I found a tiny difference: I was asking the model for structured data via a tool call, whereas Mem0 uses freeform JSON that the LLM returns directly.

Since I use PydanticAI, fixing this was a one-line change:

agent = Agent(
 model=model_cfg,
 system_prompt=UPDATE_MEMORY_PROMPT,
- output_type=list[MemoryDecision],
+ output_type=PromptedOutput(list[MemoryDecision]), # JSON mode instead of tool calls
 retries=3,
)

This is exactly why reading the source code matters—not just the algorithms, but the tiny details that make them work.

7. Why building this was necessary #

You might ask: “Bas, why write thousands of lines of code for this? Why not just use ChatGPT’s memory or install LangChain?”

Three reasons: Privacy, Integration, and Dependencies.

Privacy #

I want to feed my AI my financial records, my health data, and my private journals. I am not comfortable sending that to OpenAI’s long-term storage or some VC-backed startup’s vector cloud. With agent-cli, the vectors live in ~/.cache/agent-cli/chroma, the files live in ~/documents, and the only thing leaving my machine is the specific context needed for a specific query (if I use a cloud model) or nothing at all (if I use Ollama/llama.cpp).

Integration #

By building this as an API proxy, I solved the “fragmented tools” problem. Any tool that supports custom OpenAI-compatible endpoints works out of the box:

agent-cli chat in the terminal
Cursor or Cline for agentic coding
Open WebUI, LibreChat, or Lobe Chat in the browser

Because my system speaks “OpenAI,” all of these tools share the same memory and the same document index. If I tell the terminal agent “I’m working on Project X,” and then switch to Cursor, Cursor knows about Project X. I can try a new chat UI tomorrow without losing anything—just point it to localhost:8000.

Dependencies #

To me, it just doesn’t feel right that asking questions about a PDF requires downloading 8GB of PyTorch. By choosing ONNX Runtime over the PyTorch ecosystem, I kept the entire install lightweight and fast. This matters when you want to run the system on a cheap VPS or your friend’s laptop.

8. Try it yourself #

The entire system is open-source and available in agent-cli.

Try Memory #

Get an LLM that remembers you using Ollama.

# 1. Pull models and start proxy
ollama pull embeddinggemma:300m && ollama pull gpt-oss:20b
uvx -p 3.13 --from "agent-cli[memory]" agent-cli memory proxy \
 --memory-path ./my-memories \
 --openai-base-url http://localhost:11434/v1 \
 --embedding-model embeddinggemma:300m

# 2. Chat from the terminal (env vars point to proxy)
export OPENAI_BASE_URL=http://localhost:8100/v1 OPENAI_API_KEY=dummy

# Tell it something about yourself
uvx openai api chat.completions.create -m gpt-oss:20b -g user "My name is Alice and I love hiking"

# Later, ask if it remembers
uvx openai api chat.completions.create -m gpt-oss:20b -g user "What's my name?"

Try RAG #

Chat with your documents.

# 1. Start the RAG proxy (runs in foreground)
uvx -p 3.13 --from "agent-cli[rag]" agent-cli rag-proxy \
 --docs-folder ./my-docs \
 --openai-base-url http://localhost:11434/v1 \
 --embedding-model embeddinggemma:300m

# 2. Chat with your docs
OPENAI_BASE_URL=http://localhost:8000/v1 OPENAI_API_KEY=dummy \
 uvx openai api chat.completions.create \
 -m gpt-oss:20b \
 -g user "What does my documentation say about X?"

9. What I learned #

This journey reinforced a few beliefs:

Validate components first. AI Journal failed not because the ideas were wrong, but because I tried to build a complete system before validating individual components. This time I tackled problems one at a time—chunking, retrieval, re-ranking, memory reconciliation—and only combined them once each piece worked.
Study implementations, not just papers. Reading about two-stage retrieval is one thing. Reading how LlamaIndex actually implements it—the edge cases, the defaults, the performance tradeoffs—is far more valuable. Clone the repos. Read (or make AI read) the code.
Dependencies matter. A 30-second install versus a 10-minute download changes whether someone actually tries your tool. I am happy with the ONNX Runtime over PyTorch choice.
Files are the ultimate API. By stripping away the complex databases and proprietary interfaces, I ended up with a system that is robust, version-controllable, and surprisingly simple to reason about.
Use the best model for each job. I used 4 different AI models during development, each with different strengths. Gemini 3.0 Pro, Opus 4.5, GPT-5.1-Codex Max. I used all of them during the implementation phase, but each one has its own strengths. Fore example, Opus 4.5 was the best coding model, but GPT-5.1 Codex Max was the best at reviewing the code and actually identifying critical bugs (use the built-in /review feature).

On agentic coding 🤖

Mon, 25 Aug 2025 00:00:00 +0000

Table of contents

1. From skepticism to productivity #

About eight months ago, I wrote about my disastrous experience with “vibe coding"—where I let AI generate code without careful review. What started as a fun 3-hour prototype turned into a 15-hour debugging nightmare. I concluded that while AI was fantastic for quick prototyping, it was dangerous without human oversight. I even declared I’d “never invest in, build upon, or use such products.”

Fast forward to today, and something remarkable has changed. Not my core principle—I still never merge code I don’t understand—but the tooling and my approach have evolved through two distinct phases.

First, let’s look at the evidence of AI’s overall impact on my productivity:

This graph tells an interesting story. After maintaining a steady pace for years (2016-2023), my productivity exploded with the introduction of AI tools. In 2024-2025 alone, I’ve published 14 new Python packages and made over 400 releases. That’s more new packages than in the previous 6 years combined!

But this transformation didn’t happen overnight—it came in two distinct phases that fundamentally changed how I write code.

2. But don’t you love programming? #

I’ve heard this objection countless times: “I love programming too much to let AI do it for me.”

Sure, I get it. It’s like preferring analog photography over digital, or writing letters by hand instead of typing. Some people genuinely enjoy the manual process, and that’s valid.

But here’s the thing: I absolutely love programming. It’s my biggest passion in life. As I mentioned in my local AI journey, I bought a gaming PC to play games but have only used it for coding and local AI experiments. My idea of a fun weekend? Writing code until 3 AM. I’ve been doing this for over 10 years, and I’ve never had as much fun programming as I do now.

What I’ve discovered is that I don’t just love the act of typing code—I love building and creating things. There’s a difference.

I’m ridiculously particular about code quality. I literally cannot look at poorly formatted code without feeling physical discomfort. Every operator, every indentation, every naming convention matters to me. I enforce strict linting rules and will spend time refactoring code just because the style bothers me. This isn’t about being pretentious—it’s about caring deeply about my craft.

The revelation: AI doesn’t take away my ability to care about these details. Instead, it gives me insane leverage to create more while maintaining my personal standards. I still review every line (although I am more lenient in certain cases), still enforce my style guides, still refactor when something bothers me. But now I can build 10x faster.

It turns out that what I truly love isn’t the mechanical act of typing—it’s the creative act of bringing ideas to life. And with AI, I can bring more ideas to life than ever before.

The power to explore #

AI has unlocked something incredible: the ability to explore ideas that weren’t worth the effort before. It’s now trivial to write 2,000 lines of code to solve a simple problem. Before AI, spending 5+ hours on a utility script wasn’t justifiable. Now? I can build it in 10 minutes.

Here are just some of the “wouldn’t have been worth it” projects I’ve built recently:

Financial independence tracker: A full website visualizing my path to FIRE
Tuitorial: Terminal-based presentation software
Stream Deck home control: Complete tool to control my entire house from a Stream Deck
Dotbins: Automatic binary dependency syncing across all my machines
Agent-CLI: A local, open-source Siri that actually works

Each of these would have taken weeks of manual coding. The effort-to-reward ratio just wasn’t there. But with AI? I can explore every random idea that pops into my head at 2 AM.

The Matty story: from midnight idea to working code #

Here is the perfect example of this power: One night around midnight, I was lying in bed (slightly intoxicated) when I had an idea—I needed a way for my AI agents to communicate via Matrix. So I grabbed my iPhone, SSHed into my machine, and started building.

One hour later, at 1 AM, I had created Matty—a fully functional terminal-based Matrix client. Built entirely from my phone. In bed. (Poor sleep hygiene, I know.)

When I woke up the next morning and tested it… it actually worked! I spent a few more hours adding tests and cleaning it up, but the core functionality was built in that hour between midnight and 1 AM.

This is impossible without AI. Nobody’s writing a Matrix client from their phone in bed at midnight. But with Claude Code? It’s just another Tuesday night idea that becomes reality.

clip-files UI: when ideas strike at random moments #

What happens more often than you’d think: I get an idea at a completely random moment and NEED to implement it immediately.

Case in point: I was sitting in the bathtub during my copy-paste AI era when I realized I needed to access my codebases from anywhere. I’d already built clip-files—a CLI tool that copies entire codebases to your clipboard—but I wanted it accessible from my phone.

So I got out of the bathtub, built a web UI for it in 20 minutes, and got back in. The UI lets me:

Browse all my GitHub repositories
Select any branch
Click one button to copy all source code to clipboard
Paste it into my self-hosted AI chat from anywhere

Ironically, I rarely use this tool now—Claude Code can explore codebases directly. But back in the copy-paste era, this 20-minute bathtub interruption made mobile AI coding possible.

The barrier between “wouldn’t it be cool if…” and “here’s a working prototype” has essentially disappeared.

The 800-rule marathon: 80 AI agents at once #

Another thing that would be literally impossible without AI: I decided to enable ALL 800+ Ruff linting rules on a 20,000-line codebase.

For context, Ruff is a extremely fast Python linter that implements rules from over a dozen different tools. Most projects enable maybe 50-100 rules. I wanted all 800+.

The result? ≈2,500 violations across the entire codebase.

Fixing these by hand would take 20 hours if I could fix one per 30 seconds… But with Claude Code’s agent spawning capabilities, I did something insane:

Opened 8 terminal windows with Claude Code
Created a work orchestration document that one AI managed
Each session spawned 10 parallel sub-agents using /agents
Total: ~80 AI agents working on my code simultaneously
Two hours later: 100% compliance with all 800 rules

The orchestrator agent would assign work like:

“Session 1: Fix all E501 line-too-long violations in src/core/”
“Session 2: Handle all B008 function-call-in-default-argument issues”
“Session 3: Fix all RUF100 unused-noqa violations”

Each session’s sub-agents would tackle different files in parallel. When conflicts arose, the orchestrator would resolve them. This is the kind of code quality improvement that simply wouldn’t happen without AI—not because it’s technically difficult, but because the human effort required is unrealistic.

1,400 commits, rewritten in minutes for $2.50 #

Here’s another “impossible without AI” story: I had 1,400 commits with terrible messages (in a not-yet-released and private project).

Since I commit so frequently (using them as snapshots in feature branches), my commit messages were all over the place:

Some were just a period “.”
Some were decent descriptions
Some were just merge commits
Zero consistency in style

I wanted them all to follow a consistent convention with prefixes like fix:, feat:, test:, ci:, etc.

Obviously, rewriting 1,400 commit messages by hand is not going to happen. But with AI?

I had Claude write me an agent using the Agno framework that would:

Read each commit’s full diff using git show
Analyze the changes to understand what was done
Return structured JSON with three fields:
- commit_message: The improved message (or empty to keep original)
- keep: Boolean flag whether to keep the original
- reasoning: Why the AI made that decision

Then the magic happened: I spawned 1,400 AI agents simultaneously using the DeepSeek API.

Ten minutes and $2.50 later, all my commit messages were rewritten with consistent, meaningful descriptions. The entire Git history now looks more professional and searchable.

The barrier between “wouldn’t it be cool if…” and “here’s a working prototype” has essentially disappeared.

3. The two-phase AI revolution #

My AI coding journey wasn’t a single leap—it happened in two distinct phases, each with its own breakthrough moment.

Phase 1: copy-paste era (March 2023 - July 2025) #

When GPT-4 launched in March 2023, it changed everything. I built tools like clip-files to efficiently copy code context into a ChatGPT-like web interface. For over two years, this workflow was:

Manual but effective: Copy code → paste into AI → review suggestions → implement manually
Limited by context: Could only share what fit in a single message
No validation: AI couldn’t test its suggestions
Still valuable: Helped with ideation, code review, and refactoring

This phase was already productive—I was shipping more code than before. But I was still the one running tests, debugging errors, and validating everything.

Phase 2: the Claude Code revolution (July 2025) #

Just two months ago, in July 2025, everything changed again. Frustrated with Cursor becoming painfully slow, I tried Claude Code based on the buzz online. That first night, I spent $70 on API tokens. Not by accident—I just kept adding $10-$20 increments like a gambling addict. The experience was so mind-blowing that within two weeks, I’d spent nearly $200 and immediately upgraded to the $200/month Pro plan.

To put this in perspective: Using a command-line tool ccusage to track token consumption, I calculated that I used $10,000 worth of API tokens in my first month. Thankfully, the Pro plan capped my cost at $200!

What made Claude Code different? #

The shift from copy-paste to agentic AI was like upgrading from a bicycle to a spaceship:

Before (copy-paste with ChatGPT/Claude Web)

Generate code based on prompts
No access to your codebase
Can’t run tests or see errors
You debug everything manually

After (Claude Code)

Reads and searches your entire codebase
Executes commands and runs tests
Sees error messages and debugs itself
Iterates until tests pass
Uses tools to explore and validate

The difference is profound. I went from carefully copying snippets with clip-files to having an assistant that can explore my entire project, run my test suite, fix failures, and even commit the changes.

4. My current agentic workflow #

Here’s how I actually work with Claude Code on a typical project:

Parallel development: 6 features at once #

One of Claude Code’s superpowers is enabling truly parallel development. Here’s my setup that would make any developer from 10 years ago think I’m insane:

I use Zellij (a terminal multiplexer like tmux) with a custom layout for my projects:

5 main tabs: Each split into two panes—Claude Code on one side, terminal on the other
Using independent copies of same repository: Each tab is a separate Git worktree with its own environment, own environment variables, own deployment
Each tab = different feature: Using Git worktrees to work on 6 features simultaneously
Monitoring tabs: ccusage for tracking Claude usage, htop for CPU, nvtop for GPU
Voice-driven orchestration: I cycle through tabs, review code while speaking, move to next

My workflow looks like this:

Start feature A in tab 1, give Claude instructions
Switch to tab 2, start feature B while A is working
Continue through all 5 tabs, starting different features
Circle back to tab 1, review what Claude did, give feedback via voice
Repeat the cycle every 10-15 minutes

This parallel workflow is how I built a complex project (that I haven’t released yet) in one month that would have taken 9+ months before. The key is Git worktrees—each feature gets its own working directory, so there’s no context switching overhead.

Starting a new package #

# I describe what I want to build
"I need a Python package that manages CLI tool binaries within Git repositories,
automatically downloading the correct binary for the user's platform, here <insert path> is a repo with boilerplate skeleton to copy (use same conventions)"

# Claude Code then:
# 1. Creates the project structure
# 2. Implements core functionality
# 3. Writes comprehensive tests
# 4. Generates documentation
# 5. Sets up CI/CD workflows

The key difference: iteration and validation #

Unlike my vibe coding disaster, Claude Code doesn’t just dump code and leave. Here’s a real interaction pattern:

Claude writes initial implementation
Claude runs the tests → Several fail
Claude reads the error messages and fixes the code
Claude runs tests again → More pass, some still fail
Claude debugs the remaining issues
Claude validates all tests pass
I review the final code and understand it (tell it to make changes if needed)
Claude creates a proper Git commit

This iterative, validated approach is what makes agentic coding so powerful. It’s not about blindly accepting generated code—it’s about having an assistant that can explore, test, and refine solutions.

5. The evidence: explosive productivity #

Let me share some concrete data from my PyPI packages analysis:

Package creation by year #

2016-2022 (7 years pre-AI): ~2 packages/year average
2023 (GPT-4 launch year): 6 packages
2024 (full year with copy-paste AI): 7 packages
2025 until 3 months ago (6 months): 7 packages
since 3 months (2 with Claude Code, 1 with Codex CLI): wrote about 400k line of code (although this includes many iterations)!

The acceleration with AI is clear!

Recent packages built with agentic AI #

Here are some packages I’ve built recently with Claude Code:

matty: Terminal-based AI chat with file integration
agent-cli: Local-first AI-powered CLI agents (built in days, not weeks!)

Each of these would have taken me weeks or months to build alone. With Claude Code, I’m shipping production-ready packages in days.

6. Why this isn’t “vibe coding” (but with nuance) #

You might wonder: isn’t this just vibe coding with extra steps? The answer is nuanced and depends on the context—similar to my philosophy on dependencies.

My context-driven standards #

Just like I have different standards for dependencies in libraries versus applications, I apply different levels of scrutiny based on what I’m building:

For critical libraries (e.g., Adaptive, pipefunc, unidep)

Maximum scrutiny - These are packages others depend on:

Every single line reviewed and understood
100% test coverage with careful test review
Architecture decisions carefully considered
Documentation must be comprehensive
My reputation is on the line

For experimental CLIs and personal tools

Pragmatic approach - Isolated tools with no downstream dependencies:

Core architecture must be fully understood
Implementation details can be AI-generated if tests pass
Test generation can be more automated
Focus on functionality over perfection
Similar to my relaxed dependency stance for applications

The internal dependency graph principle #

The key insight: My scrutiny level correlates with how foundational the code is within the project:

Core/foundational code (what everything else depends on): Maximum scrutiny, every line matters
- Data models, core algorithms, API interfaces
- Authentication, database operations, state management
- These are the “roots” that everything else builds upon
Peripheral/leaf code (nothing depends on it): Can be more AI-delegated
- Plotting functions, display utilities, CLI formatters
- Test helpers, documentation generators
- These are the “leaves” that don’t affect other code
Work projects: Always maximum scrutiny for foundational code, regardless of project type

This isn’t about being lazy—it’s about focusing human attention where it matters most. I can trust AI more with a plotting function that nothing depends on than with a core data structure that the entire system uses.

Building constraints around AI #

The secret to productive agentic coding isn’t just the AI—it’s the constraints and guardrails I build around it:

Automated quality gates

Ruff with strictest rules: Catches style issues, complexity problems, and common bugs
MyPy in strict mode: Enforces type safety across the entire codebase
Pre-commit hooks: Automatically format and validate code before commits
Comprehensive test suites: AI must make tests pass, not just write code

Project-specific guidance

Every project gets a CLAUDE.md file with explicit rules:

No defensive programming: Don’t wrap things in try-except unless necessary
Functional over classes: Prefer simple functions in Python
No backward compatibility: For new projects, embrace breaking changes
Be ruthless: Aggressively remove unused code

Custom commands and workflows

I’ve built specific commands that inject context and constraints:

Anti-cruft reviews: Remove over-engineering and defensive code
Safe commit practices: Never use git add ., always selective staging
Initialize understanding: Load project context and current work state

Local virtual environments: stop the hallucinations

Here’s a critical tip that eliminated a lot of my AI frustrations: keep a virtual environment with all dependencies installed locally.

Instead of letting Claude hallucinate how libraries work, I tell it explicitly in my CLAUDE.md:

### Step 1: understand the context

- **READ THE SOURCE CODE**: This library has a `.venv` folder with all dependencies installed.
 So read the source code when in doubt.
- **Never guess API behavior**: If unsure, inspect the actual implementation in `.venv/lib/python*/site-packages/`

This simple addition transforms Claude from guessing about library APIs to actually reading them:

Before: “I think your custom AsyncProcessor.batch() method takes a list…”
After: Reads /path/to/.venv/lib/python3.11/site-packages/my_internal_lib/processor.py and knows it actually takes an iterator

When Claude can read the actual source of your own packages, internal company libraries, or niche dependencies, it stops making assumptions and starts working with facts. This is especially powerful for:

Your own libraries that Claude has never seen before
Internal company packages that aren’t public
Niche libraries with barely any GitHub stars or documentation
Modified versions of popular libraries with custom patches
Edge cases where even good documentation doesn’t cover everything

These constraints transform AI from a loose cannon into a precision tool.

7. Common pitfalls I’ve noticed #

After a few months of using agentic AI tools, I’ve noticed consistent patterns that require vigilance:

Note from the future: I now realize this is very model dependent! GPT-5 has different pitfalls than Claude Opus 4.1

The “defensive programming” trap #

# AI loves this:
try:
 result = some_function()
except Exception:
 pass # Silently suppress errors 😱

# But we need this:
result = some_function() # Let it fail loudly if something's wrong

Claude tends to wrap everything in try-except blocks, suppressing errors that should bubble up. This is why my CLAUDE.md explicitly forbids unnecessary error handling.

The “backwards compatibility” obsession #

Claude constantly adds backwards compatibility for features that were literally just introduced in the same session:

“Maintaining compatibility with the old version” (that never existed)
Fallback mechanisms for code paths that were just created
Multiple ways to do the same thing “for flexibility”

The “over-engineering” disease #

Implements factory patterns for simple object creation
Adds abstraction layers that serve no purpose
“Production ready” code for experimental scripts

The git commit sins #

Despite explicit instructions in CLAUDE.md:

Creates your_module_v2.py alongside your_module.py instead of updating
Still tries git add -A or git add . regularly despite explicit bans
Loves to “helpfully” revert debugging changes from other files
Commits .env files if not watched carefully

The “helpful” anti-patterns #

Loves defensive programming: Validates things that can’t be wrong
Gladly reads .env: Will expose secrets if not careful
Reverts unrelated changes: “Cleans up” debugging code from other features

The “mission accomplished” hallucination #

This is a dangerous pitfall. Claude Code will sometimes claim complete success when it hasn’t actually fixed anything:

Claims victory: “I’ve fixed all the issues!”
Ask for proof: “Show me the test output”
Backpedals: “Oh, let me actually run the tests…”
Still claims success: “Yes, I can see in the logs it works!”
Demand the actual log: “Show me the exact log file”
Finally admits: “Actually, there are no log files. The tests don’t pass.”

Always demand proof. Never accept “it’s done” without seeing actual test output.

The nuclear option #

I’ve had Claude Code literally try to delete all project files when “cleaning up”:

# Claude's "helpful" cleanup:
"Task complete! Let me remove the temporary files..."
rm -rf src/ # 😱

This is why frequent git commits are non-negotiable. I commit after every small success.

The debugging debris #

During problem-solving, Claude Code leaves a trail of attempts:

Debug logging statements everywhere
Failed attempt code commented out
Multiple approaches tried in parallel
Temporary test files and scripts
Extra imports and unused functions

Before merging, always ask: “Review your changes and remove all debugging artifacts and failed attempts.” Getting to a high code coverage (approaching 100%) helps ensure no dead code remains, as long as your tests use public APIs.

Why this happens #

These patterns emerge because AI is trained on public code that often:

Maintains backward compatibility for years
Uses defensive programming for public APIs
Includes extensive error handling for user input
Follows “enterprise” patterns even for simple scripts
Contains debugging code from development

This is why constraints are essential—without them, Claude defaults to these “safe” but overcomplicated patterns.

8. Critical success factors: what actually makes this work #

After two months of intense usage, here are the non-negotiable practices that make agentic coding actually productive:

Teach it your test commands (day 1 priority) #

This is absolutely crucial. Claude Code needs to know how to run your tests and how to activate the environment:

# To run tests, use: 
uv run pytest tests/ -xvs"

# For coverage:
uv run pytest --cov=src --cov-report=term-missing

# To run specific test
uv run pytest tests/test_module.py::test_function

Without this, it’s just guessing whether code works. With it, it becomes genuinely useful.

Git commits are your safety net #

I commit obsessively when using Claude Code:

After every successful (even partial) feature implementation
Before letting it attempt any major refactoring
Whenever tests pass
Before any “cleanup” operation

But here’s the key: I develop every feature in its own branch, even as a solo developer. My workflow:

Create a feature branch for each new feature or fix
Make frequent commits as snapshots (sometimes just a period for the message or tell Claude to commit)
Open a pull request to review the full diff myself
Merge only after reviewing all changes

This has saved me from disaster multiple times. Git is your undo button when Claude goes nuclear (e.g., breaks or removes your code).

Maintain healthy skepticism #

Never trust, always verify:

“I fixed it!” → “Show me the test output”
“It’s working now!” → “Run the tests again with -xvs”
“The logs show success!” → “Cat the actual log file”
“It’s production ready!” → “Did you run the tests?”

Think of Claude Code as an enthusiastic junior developer who sometimes exaggerates their accomplishments.

Force it to clean up after itself #

After any debugging session, always:

"Review all your changes and remove:
- Debug print statements
- Commented out code
- Failed attempt implementations
- Temporary test files
- Unused imports"

My custom /anti-cruft command automates this, but you can do it manually too.

Code coverage is your friend #

High test coverage (90%+) ensures:

The code Claude wrote actually runs
No dead code from failed attempts
All paths are exercised
You can refactor confidently

9. My secret weapon: voice-to-code workflow #

One of my biggest productivity multipliers isn’t Claude Code itself—it’s how I communicate with it. Using my agent-cli tool, I’ve developed a voice-first workflow that’s transformed how I write prompts.

The problem with typing prompts #

Effective agentic coding requires precise, detailed instructions. A good prompt isn’t 20 words—it’s often 200-500 words explaining exactly what you want, what to avoid, and how to approach the problem. Most people don’t want to type that much.

My voice workflow #

Here’s my actual workflow:

Start recording with agent-cli transcribe (hotkey triggered)
Review Claude’s changes while speaking my thoughts aloud
Speak for minutes about what I want, what’s wrong, what to fix
Paste the transcription directly into Claude Code

This is powered by OpenAI’s Whisper model running locally on my RTX 3090 at home. It’s more reliable than macOS dictation and gives me complete privacy.

Why this works so well #

Rich prompts: I naturally give more context when speaking
Code review narration: I can review code while explaining issues
Thinking out loud: Speaking helps clarify my own thoughts
Speed: Speaking is 3-4x faster than typing
Precision: I can be incredibly specific without typing fatigue

For example, instead of typing “fix the bug,” I might say:

“I’m looking at line 45 where you’re handling the authentication. The problem is you’re not checking if the token has expired before making the API call. Also, you’ve added a try-except block here that’s suppressing errors—remove that. And while you’re at it, the logging statement on line 52 is using the wrong format. Make sure to follow our project’s logging conventions…”

This level of detail is what makes AI coding actually productive.

10. Additional tips for agentic coding #

Beyond the critical success factors and voice workflow, here are more tips to maximize your productivity:

Set clear constraints #

Create a CLAUDE.md or similar file in your project root with your preferences:

## Project standards

- Never use try/except to suppress errors silently
- Always run pytest before marking task complete
- Use type hints for all functions
- Prefer simple solutions over clever ones

Use the task system #

Claude Code’s todo system is great for complex work:

1. ✅ Implement core functionality
2. ✅ Write comprehensive tests
3. 🔄 Fix failing tests
4. ⏳ Add documentation

Leverage the search capabilities #

Let Claude search for existing patterns:

“Find all API endpoint implementations in this project”
“Show me how we handle authentication elsewhere”
“What testing patterns are we using?”

Review in chunks #

Instead of reviewing 500 lines at once:

Have Claude implement a single feature
Review and understand it
Run tests
Commit(s) and PR
Move to the next feature

11. The tools I’ve tried #

My journey through AI coding assistants has been evolutionary:

Pre-AI era #

Manual coding with IDE autocomplete
Stack Overflow copy-paste
Productivity baseline: 1-2 packages per year

Phase 1: copy-paste tools (March 2023 - July 2025) #

ChatGPT/Claude Web + my clip-files tool
Manual context sharing
Helpful for ideation and code review
Productivity: 3x improvement (from 2 to 6 packages/year)

Cursor (early 2024) #

Great autocomplete
Limited context awareness
Became frustratingly slow
Still led to my vibe coding disaster
Productivity: 5x improvement (but with quality issues)

Phase 2: Claude Code (July 2025 - present) #

Full codebase awareness
Can execute commands and debug
Self-correcting through test iterations
Maintains context across sessions
$70 spent on first night, $10,000 worth in first month
Productivity: 24x improvement over pre-AI baseline with maintained quality

OpenAI’s Codex CLI (the reasoning beast) #

Recently tried OpenAI’s Codex—their new CLI alternative to Claude Code—and I’ll admit, for pure reasoning with their GPT-5-Codex model, it’s impressive:

Solved a race condition in an unfamiliar language that took me hours with Claude Opus
More elegant solutions for complex algorithmic problems
Better at deep reasoning when given the same context

But here’s why I still use Claude Code daily:

Claude Code’s UX is superior: Resume conversations, better interface
Codex’s CLI is fragile: Hit Ctrl-C accidentally? Lose everything, start over (muscle memory keeps betraying me!)
Claude Code handles interruptions: First Ctrl-C clears text, second quits gracefully
No session persistence: Codex forgets everything, Claude Code remembers
Context management: Have to re-provide all context after accidental exits

For a complex race condition bug, Codex with GPT-5 gave me the most elegant solution. But for day-to-day development where I need reliability, good UX, and the ability to resume work?

Why not Copilot or other “cheaper” tools? #

Let me be blunt: You get what you pay for. People often say “I tried Copilot and it wasn’t that useful” or “Gemini in chat didn’t help much.” Of course not—these tools are at least 10x cheaper than Claude Code with Opus.

Your $20/month GitHub Copilot subscription simply cannot provide the same quality or quantity of high-quality tokens as Claude Code. It’s like comparing a bicycle to a Ferrari and wondering why the bicycle isn’t as fast. The economics don’t work out:

Copilot: $20/month for limited autocomplete
Claude Code Pro: $200/month for unlimited* agentic assistance (*capped, but generous)
Actual API value used: $10,000+/month at my usage level

The 10x price difference reflects a 10x (or more) difference in capability. Copilot is autocomplete on steroids. Claude Code is a tireless pair programming partner with perfect memory who can debug, test, and iterate. The ROI is obvious when you’re shipping 10x more code.

12. Is this sustainable? #

You might wonder if this productivity is sustainable or if I’m just building lower-quality software faster. Here’s my honest assessment:

The good #

Faster prototyping: Ideas to working code in hours, not days
Better test coverage: AI never gets lazy about writing tests
More experimentation: Lower cost to try new ideas
Improved documentation: AI loves writing docs (I don’t)
Reduced burnout: Less time on boilerplate, more on interesting problems

The challenges #

Code review fatigue: You must stay vigilant
Dependency on tools: What if Claude Code disappears?
Cost: $200/month Pro plan (but worth every penny given the $10K+ value)
The temptation to “vibe”: Constant discipline required
Addiction potential: I literally couldn’t stop coding, having the desire to deplete all tokens and get my money’s worth!

My verdict #

It’s absolutely sustainable if you maintain discipline. The moment you start accepting code you don’t understand, you’re building a house of cards. But with proper review and testing, agentic AI is a massive force multiplier.

13. The experience multiplier: why seniority matters more than ever #

Here’s a counterintuitive truth about agentic AI tools: they amplify your existing skills exponentially, not linearly. This creates a fascinating paradox where these tools become increasingly valuable as you become more experienced.

The exponential trap for beginners #

For beginners, agentic tools can feel like a superpower initially. They can build a working application in hours! But here’s the danger: without the experience to recognize bad patterns, they’re essentially building at 10x speed in the wrong direction. It’s like giving a Formula 1 car to someone who just got their driver’s license—the speed multiplies both the distance traveled and the potential for catastrophic crashes.

A beginner using Claude Code might:

Accept complex solutions they don’t understand
Build massive technical debt at record speed
Miss architectural problems that will haunt them later
Create code that “works” but is impossible to maintain

They’re forced into a difficult position: either slow down to understand everything (negating the speed benefit) or accumulate technical debt at an exponential rate.

The senior developer advantage #

For experienced developers, it’s a completely different game. When I look at Claude Code’s suggestions, I can instantly recognize:

“Oh, that’s the Factory pattern—makes sense here”
“This error handling is too defensive, let’s simplify”
“That’s going to cause N+1 queries, need to refactor”
“This violates our project’s conventions, fix it”

The review process that might take a beginner hours takes me minutes. I’m not learning what the code does—I’m validating that it does what I already know it should do.

The right way for every level #

That said, everyone can benefit from agentic tools—you just need to adjust your approach:

For beginners

Use AI as a learning accelerator: Ask it to explain every decision
Build small projects first: Master fundamentals before scaling up
Prioritize understanding over speed: Better to build slowly and learn
Pair with mentors: Have experienced developers review AI-generated code

For intermediate developers

Focus on patterns: Use AI to learn architectural patterns and best practices
Experiment safely: Try new approaches in side projects first
Question everything: Don’t accept solutions without understanding the tradeoffs

For senior developers

Leverage for velocity: Use your experience to review and direct quickly
Focus on architecture: Let AI handle implementation while you design systems
Teach the AI: Create project-specific guidelines to improve output quality
Push boundaries: Explore more ambitious projects now that implementation is faster

The real multiplier effect #

The productivity boost isn’t just about writing code faster. For senior developers, agentic tools multiply:

Architecture exploration: Test multiple approaches quickly
Refactoring confidence: Refactor fearlessly with AI helping maintain functionality
Learning velocity: Explore new languages and frameworks with a knowledgeable assistant
Documentation quality: Finally have time (and help) for comprehensive docs
Testing coverage: AI never skips tests, even for “simple” functions

This is why I’ve been able to ship 14 packages in 18 months. It’s not just that I’m writing code faster—I’m able to explore ideas, validate approaches, and iterate on designs at a pace that was previously impossible.

14. Reality check: what AI can and can’t do #

Many people try AI coding and give up disappointed. That’s because they’re treating it like a magic genie that will solve the unsolved problems of the universe. It won’t.

What AI CAN do (the churn work) #

AI excels at tasks you could do yourself but would take hours:

Setting up CI/CD pipelines: Boilerplate YAML configuration
Writing tests: Especially unit tests for existing code
Fixing dependency issues: Adapting to breaking changes in libraries
CRUD operations: Basic create, read, update, delete functionality
Data transformations: Converting between formats, parsing, serialization
Documentation: README files, docstrings, API documentation
Refactoring: Renaming variables, extracting functions, reorganizing code
Bug fixes: Especially those with clear error messages

This is the “churn”—the necessary but time-consuming work that makes up 80% of development.

What AI CAN’T do (the creative work) #

Don’t expect AI to:

Solve novel algorithmic problems: It won’t invent the next PageRank
Make architectural decisions: It can’t decide if you need microservices
Understand business logic: It doesn’t know why your company does things
Create truly innovative solutions: It remixes what it’s seen, not invents
Make judgment calls: Security vs convenience, performance vs maintainability

The sweet spot #

I use AI for tasks where:

I know how to do it but it would take time
The solution exists somewhere in its training data
Success is measurable through tests or clear output
The problem is well-defined with clear constraints

This isn’t about AI doing things you can’t do—it’s about AI doing things you don’t want to spend time doing. Once you understand this, AI becomes incredibly powerful.

15. Looking forward: the future of development #

As I showed in my local AI journey, I’m deeply interested in where AI and development intersect. Agentic coding represents a fundamental shift in how we build software:

From writing code to reviewing and directing
From memorizing APIs to understanding patterns
From debugging alone to collaborative problem-solving
From slower iteration to rapid experimentation

This isn’t about replacing developers—it’s about amplifying our capabilities. I’m still the architect, the decision-maker, and the quality gatekeeper. But now I can focus on the interesting problems while my AI assistant handles the implementation details.

16. Conclusion: principles over process #

My journey from vibe coding skeptic to agentic coding advocate might seem like a complete reversal, but it’s not. My core principle remains unchanged: never commit code you don’t understand.

What’s changed is the tooling has finally caught up to the promise. With agentic AI assistants, I can maintain my standards while dramatically increasing my output. Most of those 32 packages on PyPI have users and are well-tested and documented projects that solve real problems.

The key is treating AI as what it is: an incredibly powerful assistant, not a replacement for thinking. Use it to explore ideas faster, implement solutions quicker, and test more thoroughly. But always, always understand what you’re building.

As I continue building in public and sharing my tools, I’m excited to see where this technology takes us. If you’re interested in trying agentic coding yourself, start small, maintain your standards, and prepare to be amazed by what you can build.

What’s your experience with AI coding assistants? Have you tried moving from generative to agentic tools? I’d love to hear your thoughts!

Links and resources #

How a 3090 turned into two local‑first AI projects 🎮

Mon, 14 Jul 2025 00:00:00 +0000

Table of contents

1. Introduction: The Unplayed Games #

I’ve wanted to dabble with local AI for a long time, mainly because of the possibilities it unlocks. Local AI allows me to use all of my data—financial records, personal messages, location history, even transcribing everything I say—without the privacy concerns of sending it to a cloud provider. This level of deep, personal data analysis is only something I’d be comfortable with on my own hardware.

However, I couldn’t justify buying a powerful GPU just for an imagined AI project that I might never really start. Then it hit me: I could also use it for gaming (duh). Because I really enjoyed The Last of Us series, I thought, “Okay, why not play The Last of Us on PC?” This was the push I needed. So, a couple of weeks ago, I convinced myself to buy someone’s old gaming machine. After many deep research sessions with ChatGPT about the best bang-for-the-buck consumer-grade GPU, I landed on an NVIDIA 3090. I found an (old) beast of a machine, and my initial idea was set.

Click here to see the full system specs ($1350 for all this!)

GPU: ASUS ROG STRIX RTX 3090 OC (24GB)
CPU: AMD Ryzen 9 3900X (12-Core)
Motherboard: ASUS ROG Crosshair VIII Hero
Power Supply: Be Quiet! 1200W Dark Power Pro
RAM: 32GB G.Skill Trident Z Royal DDR4
Storage: 2TB Intel M.2 NVMe SSD
Case: Corsair 4000D Airflow
CPU Cooler: Thermalright Peerless Assassin 120

Fast forward four weeks. I haven’t played a single minute, but my machine is now indexing 200 GB of email archives and facing a serious performance bottleneck I’ll get to later. That “gaming” machine has been humming away, but not rendering virtual worlds. It’s been training, transcribing, and thinking.

I’m writing this post simply because I am so enthusiastic about local AI. I’ve found that local models are surprisingly powerful for specific use cases. Of course, they aren’t going to replace Gemini or Claude for coding, but for many other applications, they work incredibly well. Lately, I’ve been so obsessed with this that I’m sleeping significantly less and spending all my free hours working on it.

2. The Rocky Road to a Working Setup #

Before I could even get to the fun AI stuff, I had to wrestle with the machine itself. I started with Pop!_OS, which is supposed to be a great out of the box solution that “just works”. However, it’s been a long time since I used Linux on the desktop; my experience is almost exclusively with servers. I quickly installed some of the wrong NVIDIA drivers and ended up debugging stuff in Grub. I got frustrated with the different commands I had to run to set up everything and realized that reproducing this system was going to be a massive pain. Since I’ve grown to love Nix on my Mac with Nix-Darwin, I decided to switch the whole system to NixOS. This has been an amazing decision. Even though there are many pain points with Nix, I think it is well worth it. For those interested, you can see the complete setup, including all the local AI services, in my NixOS configuration on GitHub.

3. The First Victory: `agent-cli` 🐍 #

With a stable system, I quickly got started with a few scripts. These soon evolved into my first real project of this adventure: agent-cli.

agent-cli is a collection of local-first, AI-powered command-line agents that run entirely on your machine. The core philosophy is privacy; your data never leaves your computer. It’s designed for seamless integration with system-wide hotkeys. I’m now using it constantly.

Instead of typing, I now dictate almost everything. A quick hotkey, and agent-cli transcribe turns my speech into text. Another hotkey, and agent-cli autocorrect cleans it up using a local LLM running on Ollama. It has genuinely streamlined my workflow. For example, I can pipe the tools together, like correcting text from my clipboard and then having it spoken aloud: agent-cli autocorrect | agent-cli speak.

The toolkit includes:

autocorrect: Fixes grammar and spelling.
transcribe: Uses a local Whisper model for speech-to-text.
speak: Converts text to speech with a local TTS engine.
voice-edit: A voice-powered clipboard assistant.
assistant: A hands-free voice assistant using a wake word.
chat: A conversational AI with tool-calling capabilities.

It’s been a fantastic success in my personal workflow, and it’s all open-source for you to try. Contributions and ideas welcome!

Once I trusted my toolchain, the obvious next step was to feed all my data into it.

4. The Grand Ambition: `AIBrain` 🧠 #

My second package, AIBrain, is a much larger endeavor. The vision is to create a “life-OS”—a private, local AI that processes all my personal data (emails, calendar, files, photos, messages, browser history, location data) to generate summaries and answer questions, eventually allowing for queries like:

aibrain ask "When did I get into landscape photography?"
aibrain ask "How many countries did I visit between 2015-2025?"

This project led me to explore the landscape of agentic frameworks. I started with CrewAI, but I quickly found that despite the hype and funding, it had some painful problems (specifically this issue where things just fail without any helpful error messages). I decided to switch to LangGraph, which felt more robust. I also chose to not use PydanticAI (which I used in agent-cli) because its Ollama support is just a wrapper around the OpenAI-compatible API, which doesn’t expose all the useful options (I even opened a PR in Ollama to make its OpenAI compatible API more feature-complete, but it has not been merged yet).

The core infrastructure of AIBrain is ready. It can index emails, calendar events, and files in various formats (PDF, Excel, PowerPoint, images). However, I’ve hit a significant challenge.

5. Conclusion: The Journey Continues #

This past month has been a whirlwind. I set out to play games and ended up with two open-source AI packages and a much deeper appreciation for the power sitting in a consumer-grade GPU. It’s incredible what you can achieve with local hardware today.

agent-cli is a finished, polished tool that I use daily. AIBrain is a much bigger dream, and I’m still figuring out how to solve the performance puzzle to make it truly practical. Next up: smarter chunking with LangGraph, vector-DB swap-outs, and GPU scheduling tricks.

This experience has reinforced my passion for local-first software and open-source development. The future of personal, private AI is being built right now, not just in large corporate labs, but in the homes of hobbyists tinkering with their gaming rigs.

⭐ If this resonates, star the repos & drop issues/questions.

And who knows, maybe I’ll even find the time to play ‘The Last of Us’.

Open-sourcing my dotfiles: a practical, cross-platform terminal setup 🏠

Sat, 05 Apr 2025 00:00:00 +0000

Introduction #

Many of us spend a significant amount of time in the terminal. Over the years, I’ve found that investing in a well-organized and consistent command-line environment pays dividends in productivity and, frankly, makes the daily grind more enjoyable. After refining my personal setup across more than 10 different machines – ranging from my primary MacBooks to Linux servers (x86/ARM), Raspberry Pis in my homelab, cloud VMs, and even my iPhone via iSH – I’ve decided it’s time to share it publicly. The need for a consistent experience across such diverse hardware and operating systems was a major driving force behind this setup’s evolution.

Today, I’m open sourcing my complete dotfiles repository 🎉. This isn’t about presenting a “perfect” solution, but rather sharing a practical system that has evolved to handle real-world needs like cross-platform consistency, easy setup on new machines, and integrating modern CLI tools effectively. If you’re looking for ideas to streamline your own terminal workflow, I hope you find something useful here.

Table of contents

Why Open Source Now? #

I have maintained my dotfiles for many years in a private repository. Sharing this setup feels like a natural step for a few reasons:

Sharing Solutions: This setup incorporates solutions to problems I’ve wrestled with, like managing binaries without sudo (leading to my dotbins tool), achieving consistent SSH agent behavior, or getting Python environments to activate seamlessly with direnv.
Giving Back: I’ve learned a lot from countless other dotfiles repos and articles shared by the community. It feels right to contribute my own approach.
Transparency & Learning: Open sourcing allows others to see how different pieces fit together and perhaps adapt ideas for their own configurations.

However, the driving force was the recent creation of my dotbins tool and honestly, I just want to share “my way” of doing things.

Core Ideas & Highlights #

My setup is built around a few key principles aimed at practicality and efficiency:

1. Cross-Platform & Shell Agnostic #

It’s designed to work reliably on macOS (aarch64) and various Linux distros (x86_64, aarch64). While Zsh is my preference (leveraging Oh-My-Zsh), the core configurations in configs/shell/ are sourced by both .zshrc and .bash_profile, ensuring basic compatibility.

2. Modularity for Sanity #

Instead of one giant config file, the shell setup is broken down logically:

configs/shell/
├── 00_prefer_zsh.sh # Switches Bash users to Zsh if available
├── 10_aliases.sh # Common aliases
├── 20_exports.sh # Environment variables
├── 30_misc.sh # Dotbins init, secrets sourcing
├── 40_keychain.sh # SSH agent setup (Keychain/1Password)
├── 50_python.sh # Python env helpers (conda, uv, direnv)
# ... and others for Zsh specifics, SLURM, etc.
└── main.sh # Sources the relevant files above

This makes it much easier to understand, maintain, and debug specific parts of the configuration. My actual .zshrc and .bash_profile just source main.sh.

3. Automation via Dotbot #

A core goal here is a true ./install and done setup. Dotbot is key to this automation. Setting up a new machine or syncing changes is streamlined using this tool. The install.conf.yaml file defines which config files get symlinked where, and runs initial setup commands. This includes updating submodules and, importantly, using uv tool install to install a curated list of essential Python CLI tools (ruff, pre-commit, dotbins itself, etc.) globally, ensuring they’re immediately available after installation. For remote machines, scripts/sync-dotfiles.sh handles pulling updates and optionally re-running the install.

4. Hassle-Free CLI Tools with `dotbins` #

Modern CLI tools are fantastic, but installing them everywhere, especially without sudo, can be a pain. I built dotbins to solve this. It downloads pre-compiled binaries for specified tools directly from GitHub releases, organizing them by platform/architecture.

# Snippet from ~/.dotbins/dotbins.yaml
tools:
 delta: dandavison/delta # Git diff tool
 eza: eza-community/eza # Modern 'ls'
 zoxide: ajeetdsouza/zoxide # Smarter 'cd'
 starship: starship/starship # Shell prompt
 atuin: atuinsh/atuin # Shell history sync
 # ... plus tools with shell integration code

The shell setup automatically adds the correct binary path and runs any needed initialization. More details in my dotbins post.

5. Sensible SSH Key Management #

Using Funtoo Keychain, often integrated with the 1Password CLI for passphrase retrieval, means I typically only deal with my SSH key passphrase once per login session. This setup is detailed here.

6. (macOS) Declarative Setup with Nix-Darwin #

On my Macs, I use Nix-Darwin to manage system settings and even Homebrew packages declaratively (configs/nix-darwin/). Running nixswitch applies the entire configuration, making macOS setups highly reproducible.

A Note on Alternatives & Design Choices #

You might wonder why I haven’t adopted certain popular tools or approaches. Here’s some rationale behind the choices made in this setup:

Why not fish shell? While fish offers many appealing modern features (and its Rust rewrite is intriguing!), a core requirement for my setup is broad compatibility. I need my core shell environment to function reliably even on minimal Linux systems (servers, containers, HPC nodes) where bash is often the only guarantee. For this reason, I use zsh as a powerful, yet largely POSIX-compatible, middle ground that works well across my diverse environments without requiring a non-standard shell installation everywhere.
Why iTerm2 on macOS? I’ve experimented with newer terminals like WezTerm, Ghostty, Kitty, and Alacritty. Many offer benefits like impressive speed and GPU rendering. However, I consistently return to iTerm2.
- Criticisms & Rebuttals: iTerm2 is often criticized for being “bloated” or “slow,” and historically, its settings weren’t easily version controllable. Frankly, on modern hardware, any perceived slowness is negligible for my use cases. More importantly, iTerm2 does allow its profiles to be saved as JSON (see my Profiles.json in this repo), making the configuration easily version controlled via dotfiles.
- The Killer Feature: The primary reason I stick with iTerm2 is its robust Semantic History feature. The ability to Cmd-Click URLs/filenames in terminal output – even complex ones with line numbers like src/my_module/file.py:123 – and have them open directly in VS Code at the correct line is indispensable for my debugging and development workflow. I haven’t found this replicated with the same reliability and ease of configuration elsewhere.
- Other Features: I also like simple features selecting text and (without ⌘+C!) pasting it right back into the terminal, and the window and tab management features.
- Ghostty Example: I recently tried Ghostty and liked many aspects, but quickly ran into limitations that highlighted my reliance on iTerm2 features, such as the lack of built-in text search, scrollbars, and crucially, the clickable file paths with line numbers (as discussed here).
Why Dotbot/Git over chezmoi? Chezmoi is a very popular and powerful dotfiles manager, often praised for its templating and management features. However, I prefer the directness of using git for version control and Dotbot for simple symlinking. My setup is the Git repository, which feels intuitive. Crucially, I rely heavily on Git submodules (perhaps Git’s least loved feature 🤔) to manage external tools and plugins directly within my dotfiles repo. This submodule-centric approach integrates seamlessly with a standard Git workflow, which made Dotbot a more natural fit for me than chezmoi’s model.
No sudo Required: A key design principle is that the installation process via ./install (Dotbot symlinking, uv tool install, dotbins fetching binaries) operates entirely within the user’s home directory. No sudo access is needed to get the core environment up and running. This makes the setup viable in restricted environments like HPC clusters, shared servers, or locked-down corporate machines where admin rights aren’t available.

A Look Inside: Structure #

The repository is organized to keep things separated logically:

.
├── configs/ # Configs (atuin, bash, git, nix, shell, zsh...)
├── install # Main installation script (runs dotbot)
├── install.conf.yaml # Dotbot: Links configs, runs setup commands
├── scripts/ # Utility scripts (syncing, backups, helpers)
├── submodules/ # External tools managed as submodules (dotbot, dotbins, plugins...)
└── README.md # Detailed overview

Getting Started #

If you want to try this setup or adapt parts of it:

Prerequisites: git is essential. SSH access to GitHub is needed if you fork and want to manage the private secrets submodule or other private submodules.

Clone:

# Clone recursively to get submodules
git clone --recurse-submodules -j8 git@github.com:basnijholt/dotfiles.git
cd dotfiles

Install:
```
./install
```
This single command runs Dotbot, which handles creating configuration symlinks, updating Git submodules, and installing numerous Python tools via uv (as defined in install.conf.yaml). Combined with dotbins automatically fetching other pre-compiled binaries, your environment should be remarkably complete after this step. Restart your shell after it finishes.
⚠️ Important: Customize!
- Fork the repository first! Don’t use my configuration directly, especially configs/git/gitconfig.
- Update configs/git/gitconfig with your name and email.
- Review install.conf.yaml – remove links or shell commands you don’t need. You can see the full list of Python tools installed via uv here.
- Modify configs/shell/ files to suit your workflow.
- Adjust the dotbins configuration (submodules/dotbins/dotbins.yaml) to include your favorite tools.

A Note on Secrets #

Sensitive information (API keys, etc.) is not stored directly in the public repository. I use a private Git repository included as a submodule (secrets/). This requires SSH authentication. Within that private repo, I use gpg and git-secret to encrypt sensitive files, adding another layer of security. You’ll need your own strategy for managing secrets, whether it’s a similar private repo, environment variables, or a dedicated secrets manager.

Conclusion #

This dotfiles setup represents my ongoing effort to build a productive, consistent, and enjoyable terminal environment across a diverse range of machines – from personal laptops to homelab servers and cloud instances. It solves real problems I’ve encountered in maintaining that consistency. By sharing it, I hope to offer some practical ideas and perhaps save others some time in crafting their own ideal setup.

Feel free to explore the repository, borrow what you find useful, and adapt it to your needs. If you find it helpful, consider giving it a star! If you have suggestions or find issues, contributions are welcome!

Happy terminal tinkering!

Further Reading & Links:

My Dotfiles Repository on GitHub
Blog Post: My Homelab Setup
Blog Post: Be a Ninja in the Terminal 🥷
Blog Post: dotbins: Managing Binary Tools in Your Dotfiles 🧰
Blog Post: Combining Keychain and 1Password CLI for SSH Agent Management
Dotbot
Dotbins
Git Secret
iTerm2

dotbins: managing binary tools in your dotfiles 🧰

Tue, 11 Mar 2025 00:00:00 +0000

In my previous post about terminal productivity, I shared a setup combining tools like zsh, oh-my-zsh, zsh-z, and various plugins to create a highly efficient command-line environment. While that setup served me well for years, I’ve recently encountered a challenge: incorporating modern, compiled CLI tools across all my environments without administrative privileges.

Today, I’m excited to introduce dotbins - a solution I created to solve this exact problem.

The Modern CLI Tools Problem #

Over the past few years, we’ve seen an explosion of incredible, modern CLI tools written in languages like Rust and Go. Tools like:

zoxide (a smarter, faster alternative to zsh-z)
bat (a cat replacement with syntax highlighting)
eza (a modern ls alternative)
delta (a better diff viewer for Git)
fzf (a fuzzy finder for your terminal)
ripgrep (a faster, better grep)
atuin (a shell history with search and sync)

These tools significantly enhance terminal productivity, but they come with a catch: they’re compiled binaries, not simple scripts. While my previous setup worked well because all the tools were basic shell scripts I could include as submodules in my dotfiles repository, these modern alternatives require installation.

This became frustrating when working on:

Remote systems where I lacked admin/sudo permissions
Machines that I use only temporarily
Systems where I didn’t want to install package managers

I’d spend time carefully setting up my dotfiles with all my configurations, only to find that the actual tools they relied on weren’t available.

Enter `dotbins` 🧰 #

dotbins was born out of this frustration. It’s a utility that manages pre-compiled binaries for CLI tools across multiple platforms and architectures, right in your dotfiles repository.

The key insight: track pre-compiled binaries in a separate Git repository (using Git LFS for efficiency), include this repository as a submodule in your dotfiles, and ensure all your essential tools are immediately available on any system.

No package manager, no sudo, no problem.

How `dotbins` Works #

dotbins handles several critical tasks:

Downloads binaries directly from GitHub releases for your selected tools
Organizes them by platform (macOS, Linux) and architecture (amd64, arm64)
Tracks installed versions and update timestamps
Extracts binaries from archives in various formats
Integrates seamlessly with your shell via a simple PATH addition

The configuration is straightforward - a YAML file where you define which tools you want and how to get them:

tools:
 ripgrep:
 repo: BurntSushi/ripgrep
 extract_binary: true
 binary_name: rg
 binary_path: ripgrep-*/rg
 asset_patterns:
 linux: ripgrep-{version}-{arch}-unknown-linux-musl.tar.gz
 macos: ripgrep-{version}-{arch}-apple-darwin.tar.gz
 arch_map:
 amd64: x86_64
 arm64: aarch64

My Workflow: A Two-Repository Approach #

My approach uses two repositories:

Private dotfiles repository containing all my configurations
Public mydotbins repository containing all the binaries

I include mydotbins as a submodule in my dotfiles repository. This separation keeps large binary files out of my main dotfiles repository and allows me to share the binary collection publicly while keeping my personal configurations private.

When I clone my dotfiles on a new system, I get not just my configuration files, but also all the CLI tools I depend on for productivity.

Modern Alternatives to My Previous Setup #

With dotbins, I’ve been able to upgrade several tools from my previous setup:

Old Tool	Modern Alternative	Advantage
`zsh-z`	`zoxide`	Faster, smarter, works across shells
`cat`	`bat`	Syntax highlighting, Git integration
`ls`	`eza`	Better formatting, Git integration
`grep`	`ripgrep`	Much faster, respects `.gitignore`
Control + R	`atuin`	Shell history with search and sync
Default Git diff	`delta`	Syntax highlighting, better visual diffs
N/A	`fzf`	Fuzzy finding makes everything better
N/A	`atuin`	Shell history with search and sync

The best part? All of these are now automatically available on every machine where I clone my dotfiles, without any additional installation steps.

Getting Started with `dotbins` #

If you’d like to adopt this approach, here’s how to get started:

Install dotbins:

pip install dotbins
# Or better yet, use uv:
uvx dotbins

Create a configuration file at ~/.config/dotbins/config.yaml:

tools_dir: ~/.mydotbins/tools

platforms:
 linux:
 - amd64
 - arm64
 macos:
 - arm64

tools:
 # Add your favorite tools here
 fzf:
 repo: junegunn/fzf
 extract_binary: true
 binary_name: fzf
 binary_path: fzf
 asset_patterns: fzf-{version}-{platform}_{arch}.tar.gz
 platform_map:
 macos: darwin

Initialize and download your tools:
```
dotbins init
dotbins update
```

Add the shell integration to your .zshrc or .bashrc:

# dotbins - Add platform-specific binaries to PATH
_os=$(uname -s | tr '[:upper:]' '[:lower:]')
[[ "$_os" == "darwin" ]] && _os="macos"

_arch=$(uname -m)
[[ "$_arch" == "x86_64" ]] && _arch="amd64"
[[ "$_arch" == "aarch64" || "$_arch" == "arm64" ]] && _arch="arm64"

export PATH="$HOME/.mydotbins/tools/$_os/$_arch/bin:$PATH"

(Optional) Track your binaries in a separate Git repository with Git LFS for efficiency

Finding New Tools to Add #

Not sure which pattern to use for a new tool? The analyze command is here to help:

dotbins analyze sharkdp/bat

This will suggest a configuration for the tool based on its GitHub release assets.

Conclusion: The Evolution of My Terminal Setup #

With dotbins, my terminal productivity setup has evolved beyond what I described in my previous post. I can now seamlessly incorporate the best modern CLI tools without worrying about installation or administrative privileges.

The beauty of this approach is its portability—I get a consistent, powerful environment on any machine where I clone my dotfiles.

If you’re a terminal power user who works across multiple environments, give dotbins a try. It might just be the missing piece in your dotfiles setup!

GPL for Python packaging ⚖️

Mon, 10 Feb 2025 00:00:00 +0000

Understanding GPL for Python Packaging #

Over the last 10 years–since I started working on and with open source projects–the GPL topic has frequently come up with friends and colleagues. I simply write this post as a reminder to myself and to have something concise and clear to link to later. Also, IANAL, so if you are relying on this post, please do your own research, I have included all the links I used to make this post.

The GNU General Public License (GPL) is widely used in the open-source world, but its implications can be unclear, especially regarding Python packaging. If you develop or distribute Python software, understanding GPL variants is crucial.

What is GPL? #

GPL is a strong copyleft license—meaning software using GPL-licensed code must also be released under the GPL. There are several key variants relevant to Python:

GPLv2 & GPLv3: These licenses require that software using GPL code (directly or indirectly) also be open-sourced under GPL upon distribution.(¹,²) If your Python application imports or depends on a GPL package, your code must adopt GPL licensing.
LGPL (Lesser GPL): LGPL is more permissive and is usually applied to libraries. It allows proprietary software to link or import the library without forcing the proprietary software itself to adopt LGPL.(³,⁴) You just need to ensure users can replace or modify the LGPL component.
AGPL (Affero GPL): AGPL is similar to GPLv3 but includes a critical extra clause: it applies even when users access the software remotely over a network (such as web services or APIs). If you use an AGPL-licensed Python library, your entire application must be open-sourced under AGPL, even if you’re only hosting it online.(⁵,⁶)

What Does “Linking” Mean in Python? #

GPL licenses often refer to “linking,” traditionally associated with compiled languages (e.g., C, C++). Python doesn’t link code in the traditional sense. However, it is generally agreed upon that importing a Python module counts as linking for licensing purposes.(¹,⁷) Therefore, directly importing a GPL-licensed Python package typically triggers the GPL’s copyleft requirements.

Why Does This Matter for Python Packaging? #

Python makes it easy to incorporate third-party libraries. But unintentionally using GPL-licensed libraries (especially GPL or AGPL) legally obligates you to open-source your proprietary code.

Direct Dependencies: If you directly import a GPL-licensed Python library, your software must be GPL-licensed upon distribution.(¹,²)
Indirect (Transitive) Dependencies: If any dependency in your Python project indirectly relies on GPL-licensed code, your entire software must also adopt GPL licensing upon distribution. Even a hidden, indirect GPL dependency triggers the GPL requirements.(⁸,⁹,¹⁰)

Recommendations #

Check Licenses Carefully: Always verify the licenses of both your direct and indirect dependencies to prevent unintended GPL licensing obligations.(¹¹,⁷)
Use Permissive or LGPL Licenses: When planning to keep your own software proprietary, prioritize libraries with permissive licenses (e.g., MIT, Apache, BSD) or LGPL-licensed libraries, as they allow for proprietary use without triggering GPL requirements.(³,⁴)
Separate GPL Code: If you must utilize GPL code, explicitly separate it from proprietary code. Using subprocess calls or isolated microservices is often recommended since it counts as “mere aggregation,” not linking, thus avoiding GPL obligations.(¹²,⁷)

By clearly understanding GPL licensing implications, you can confidently manage your Python project’s dependencies and safely distribute your software.

tuitorial: terminal-based interactive code tutorials 📚

Sat, 04 Jan 2025 00:00:00 +0000

While trying to demonstrate my pipefunc package (a tool for automating computational pipelines), I hit a common presentation problem: how do you effectively walk through code without endless repetition?

Traditional presentation tools like PowerPoint force you to copy-paste the same code snippets multiple times just to highlight different parts. Jupyter notebooks are great for self-paced learning but clunky for live presentations (too much text that the viewer will try to read). I needed something that would let me define code once and create multiple views highlighting different aspects.

So, during the holiday season, I did what any reasonable developer would do: procrastinated on my actual work and built a new tool instead!

What is tuitorial? #

tuitorial is a Python package that lets you create interactive, terminal-based code tutorials where you define the code ONCE, then create steps that highlight different parts based on rules (like regex patterns or line numbers). No more copy-paste presentations!

Key Features #

Write code once: Define your code once, then create multiple views highlighting different aspects
Rich highlighting options: From simple literal matches to complex regex patterns
Interactive navigation: Intuitive keyboard controls for stepping through tutorials
Beautiful terminal UI: Powered by Textual for a polished look
Flexible configuration: Choose between Python API or YAML format
Development mode: Live reloading for quick iterations

See It in Action #

Here’s a demo of tuitorial explaining pipefunc - a package that lets you create computational pipelines with automatic parallelization, caching, and dependency management:

Who Should Use This? #

While tuitorial isn’t for everyone, it’s perfect for:

Developers giving technical presentations
Teachers explaining code concepts
Teams creating interactive documentation
Anyone who loves terminal-based tools

Getting Started #

pip install tuitorial

Check out the documentation for examples and detailed usage instructions.

Final Thoughts #

Building tuitorial was a lot of fun! While it may not replace PowerPoint for your next business presentation, it offers a unique approach to code demonstrations that I hope others will find useful.

Try it out and let me know what you think!

Home Assistant Ecosystem 🏠

Tue, 24 Dec 2024 00:00:00 +0000

(See my intro post)

There are not enough days in this advent calendar to highlight all my projects. So today is a collection of IoT/Home Assistant-related packages. Each has its own story.

📖 Origin Stories & Technical Details #

My Home Assistant obsession began as described in Day 10. Many projects emerged from this hobby:

aiokef: To control my KEF speakers, I reverse-engineered network traffic and decoded raw byte sequences, diving deep into proprietary protocols to “speak” the speaker’s language.
miflora: When @ChristianKuehnel couldn’t maintain this plant sensor library anymore, he transferred it to me. A perfect example of open source collaboration, it continues to help users monitor plant health and demonstrates how projects can thrive through community handovers.
addon-otmonitor: This HA add-on packages OpenTherm Monitor for the OpenTherm Gateway (OTGW). Using Docker to simplify deployment, it’s become a powerful open-source alternative to Nest or Ecobee, giving full control over heating systems.
home-assistant-macbook-touch-bar: Remember that useless touch bar on the old MacBook? I transformed it into a mini Home Assistant control panel for lights, temperature, and more - a classic case of hardware hacking giving new life to abandoned technology.
python-kasa: To modernize the popular pyHS100 library for TP-Link devices, I converted it to use asyncio. With @rytilahti, we created the python-kasa organization through community collaboration. While I haven’t contributed much since its inception, it’s now the standard for controlling Kasa devices.

📊 Impact & Lessons #

These projects serve thousands of users while teaching valuable lessons:

Open source empowers us: from KEF speaker integration to plant monitoring
Reverse engineering unlocks potential: turning proprietary protocols into open solutions
Community drives success: projects like miflora and python-kasa thrive through collaboration
Innovation through repurposing: giving new life to hardware like the MacBook Touch Bar
Modern tech matters: Docker simplifies deployment, async code boosts performance

Want to explore these projects? Check them out on GitHub:

This concludes our Advent of Open Source! I hope you’ve enjoyed this journey through my projects as much as I’ve enjoyed sharing them. Happy holidays and happy coding!

#OpenSource #HomeAssistant #IoT #Python #SmartHome

pfapack 🔢

Mon, 23 Dec 2024 00:00:00 +0000

(See my intro post)

Ever needed to calculate the square root of the determinant of a skew-symmetric matrix? Probably not, but if you’re in quantum physics, you might have! This is called the Pfaffian. Today’s project, pfapack, is a Python package that provides efficient routines for computing it. The underlying algorithms and original code implementations were developed by my PhD co-promotor Michael Wimmer. I created the pfapack package to make this powerful tool easily accessible.

📖 Origin Story #

Working in quantum physics, I frequently need to compute the Pfaffian. Michael had not only developed the algorithms but also wrote highly optimized C, FORTRAN, and Python implementations, distributing them as a tar file on his website. To make it easier for researchers working in Python, I packaged his existing Python code, added wrappers for his C and FORTRAN implementations, and set up automated builds for PyPI and conda-forge to make it easily installable.

🔧 Technical Highlights #

Python Wrapper for Efficient Code: User-friendly Python interface to Wimmer’s optimized C and FORTRAN.
Multiple Algorithms: Supports both the Parlett-Reid and Householder methods.
Optimized for Performance: Leverages low-level optimizations for speed.
Conda and Pip Installable: Easy installation via conda-forge and PyPI.
Automated Wheel Builds: Uses pypa/cibuildwheel for streamlined, automated builds and releases.
Cross-Platform Compatibility: Works on Linux, macOS, and Windows (with some caveats).

📊 Impact #

Makes specialized mathematical algorithms readily available to Python users.
Simplifies the use of highly optimized code.
15 GitHub stars.
Used in research projects that require efficient Pfaffian computations, particularly in quantum physics.

🎯 Challenges and Solutions #

Bridging Languages: Wrapping C and FORTRAN for Python integration.
Automated Builds: Setting up automated builds for multiple platforms was complex.
Windows Compatibility: As always Windows support is a PITA; it currently requires MSYS2 and MinGW64.

💡 Lessons Learned #

Making specialized tools accessible broadens their impact.
Wrapping low-level code in Python can improve usability.
Automated builds are essential for maintainability.
pypa/cibuildwheel is awesome for cross-platform builds.

🙏 Credits #

All the credits for the underlying algorithms and original code implementations go to Michael Wimmer. I simply made it easier to distribute and use in Python.

Want to compute Pfaffians efficiently in Python? Check out pfapack on GitHub or install it via pip install pfapack or conda install -c conda-forge pfapack!

#OpenSource #Python #ScientificComputing #Math #Pfaffian #FORTRAN #C

tiller-streamlit 💰

Sun, 22 Dec 2024 00:00:00 +0000

(See my intro post)

Tracking personal finances is crucial, especially when working towards financial independence (see my WenFIRE post on Day 4). Today’s project is tiller-streamlit, a Streamlit app that visualizes your financial data from Tiller. I host it on my local network under money.local using Traefik for easy access.

📖 Origin Story #

Used to use Intuit Mint, but when they shut down, I needed an alternative with full data control.
Tiller automatically populates your financial data into a Google Sheet that you own forever.
With 20+ accounts, manual updates are tedious – Tiller automates it.
Combined Tiller’s data with Streamlit’s ease of use, creating a personal finance dashboard.

🔧 Technical Highlights #

Powered by Streamlit: Turns Python into a web app with minimal code.
Tiller Integration: Connects to Tiller’s Google Sheets for automated data retrieval.
Interactive Visualizations: Uses Plotly and Altair for dynamic charts.
Customizable Analysis: Filter by categories, time periods, and more.
Net Worth Tracking: Calculates and visualizes net worth over time.
Dockerized Deployment: Easy deployment with Docker, and served locally with Traefik.

📊 Impact #

Primarily for personal use, it has significantly improved my understanding of my finances.
Great way to learn Streamlit and explore its capabilities.
Visualizing spending patterns helps identify areas to cut back and make informed financial decisions on the path to financial independence.

🎯 Challenges and Solutions #

Learning Streamlit: Excellent documentation and community support made it a smooth process.
Data Wrangling: Transforming Tiller’s raw data into a format suitable for visualization.
Deployment: Docker and Traefik simplified local deployment, making it accessible on my home network.

💡 Lessons Learned #

Data Ownership Matters: Owning your financial data gives you control and flexibility.
Visualization is Key: Seeing your finances visually makes a huge difference.
Streamlit is Powerful: Simplifies web app development.
Automation is Essential: Tiller’s automatic data population makes the whole process sustainable.
Docker and Traefik Simplify Local Deployment: Making it easy to access the app on my home network.

🔮 Future Plans #

Budgeting Features: Integrate budget tracking and forecasting.
Goal Setting: Set financial goals and track progress.
Investment Tracking: Incorporate investment data for a complete picture.

Want to visualize your own finances with Tiller and Streamlit? Check out tiller-streamlit on GitHub!

#OpenSource #Python #Streamlit #PersonalFinance #DataVisualization #Tiller #Traefik #Docker

Interactive Graph Visualization 🕸️

Sat, 21 Dec 2024 00:00:00 +0000

(See my intro post)

After creating pipefunc (Day 20), I wanted a way to visualize its (possibly large and complex) computational graphs interactively in Jupyter notebooks. What started as a simple visualization PR evolved into two standalone packages: graphviz-anywidget (Python) and graphvizsvg (JavaScript) - which unexpectedly introduced me to JavaScript development!

📖 Origin Story #

While working on pipefunc’s visualization features, I discovered that existing solutions didn’t quite meet my needs. However, I found several components that would solve my issue:

AnyWidget (interactive GraphViz in Jupyter)
@hpcc-js/wasm-graphviz (GraphViz in WASM)
d3-graphviz (interactive GraphViz in D3)
jquery.graphviz.svg (GraphViz SVG manipulation)

AnyWidget would work with ESM modules, however, I had no clue what that even was. The jquery.graphviz.svg package wasn’t one and hadn’t been maintained in 8 years.

With AI as my JavaScript mentor, I first rewrote jquery.graphviz.svg into a modern ESM module (graphvizsvg), adding comprehensive tests that uncovered bugs in the original. Then, using AnyWidget, I created graphviz-anywidget to connect everything together - combining the WASM-powered d3-graphviz with the interactive features from graphvizsvg into a seamless Python package.

To my surprise, I found JavaScript’s development tooling remarkably sophisticated - especially npm, which handles everything from linting to testing to bundling to publishing. Something we’re still missing in Python!

🔧 Technical Highlights #

graphviz-anywidget:

Interactive Graphviz visualization in Jupyter
WASM-powered graph rendering
Directional graph traversal
Node and edge highlighting
Works in JupyterLab, Notebook, and VS Code

graphvizsvg:

Modern ESM module for interactive SVG visualization
Automatic color transitions
Bi-directional graph traversal
Comprehensive test coverage
My first npm package!

📊 Impact #

Enhances pipefunc’s visualization capabilities
Modernizes legacy jQuery code for modern web development
Proves that diving into new technologies can yield useful tools

🎯 Challenges and Solutions #

Learning JavaScript/TypeScript from scratch
Making WASM work in Jupyter
Getting it to work in VS Code

💡 Lessons Learned #

Don’t let preconceptions limit your tech choices
Modern JavaScript development is actually enjoyable
AI can be an excellent programming mentor
Good visualization makes complex data accessible
Breaking features into separate packages increases reusability
Test coverage helps find bugs in even well-used code

Want to visualize graphs interactively? Check out graphviz-anywidget and graphvizsvg!

#OpenSource #JavaScript #Python #DataVisualization #WebDev

pipefunc 🕸️

Fri, 20 Dec 2024 00:00:00 +0000

(See my intro post)

Of all the projects I’m sharing this month, this one that started as a passion project excites me the most!

📖 Origin Story #

Sometimes the best projects are born from the most unexpected moments. More than 1½ year ago, while on parental leave with my twin boys, I found myself with small pockets of time during naps to work on a problem that had been bothering me for years: the tedious bookkeeping required in complex computational workflows. Every scientific computation project seemed to reinvent the same patterns - managing function dependencies, parameter sweeps, result caching, parallelization, and a lot of boilerplate to combine the resulting data. I wanted something that would let scientists focus on their science, not on pipeline management.

Example of a pipeline generated by PipeFunc

🔧 Technical Highlights #

Automatic DAG construction via very simple and lightweight syntax
N-dimensional parameter sweeps with automatic parallelization
Visual pipeline representation using NetworkX
Resource profiling (CPU, memory, time)
Type validation between pipeline stages
Ultra-fast: only 15 µs overhead per function
Flexible caching strategies (memory, disk, cloud)
Integration with scientific computing tools:
- NetworkX for graph algorithms
- NumPy for multi-dimensional arrays
- Xarray for labeled arrays
- Zarr for distributed storage
- Adaptive for parallel computing

📊 Impact #

230 GitHub stars
700+ tests with 100% coverage
Fully typed codebase
Comprehensive documentation
Tested on real workflow on SLURM cluster
Covered on Pycoder’s Weekly with >100k subscribers

🎯 Challenges and Solutions #

Balancing simplicity with power
Making complex workflows intuitive
Handling distributed computing edge cases
Ensuring type safety across the pipeline
Optimizing performance without sacrificing features

💡 Lessons Learned #

Sometimes the best time to code is during baby naps
Complex problems can have elegant solutions
Scientific computing needs better tooling
Good abstractions make hard things easy
Type hints and tests prevent headaches

🔮 Future Plans #

The journey is far from over. Plans include:

Enhanced cloud computing support
More interactive visualization options
Interactive pipeline debugging tools
Expanded parameter sweep capabilities

Want to simplify your computational workflows? Check out pipefunc on GitHub or read the documentation!

#OpenSource #Python #DataScience #ScientificComputing #Programming

fileup 📤

Thu, 19 Dec 2024 00:00:00 +0000

(See my intro post)

Sometimes the best tools are the ones you build for yourself and keep using for years. Today’s project is fileup, a tiny command-line utility that’s been making my life easier for 7 years - because sharing files shouldn’t require leaving the terminal!

📖 Origin Story #

Back in 2017, I found myself repeatedly going through the same tedious process: needing to share a file, opening a browser, navigating to a file sharing service, waiting for uploads, and copying URLs. As someone who lives in the terminal, this felt inefficient. I wanted something as simple as fu filename that would handle everything and put the URL in my clipboard. Seven years and countless file shares later, it’s still one of my most-used tools.

🔧 Technical Highlights #

Supports both FTP and SCP uploads
Smart URL generation:
- Jupyter notebooks → nbviewer links
- Images → markdown-formatted links
- Regular files → direct URLs
Automatic file expiration and cleanup
Zero dependencies - uses only Python standard library
Clipboard integration (macOS)
Simple INI configuration
Works as both a standalone script or installed package

📊 Impact #

This is one of those tools where GitHub stars (currently 0!) don’t tell the whole story:

Used almost daily for 7 years
Shared thousands of files
Saved countless minutes of browser interactions
Proves that utility trumps popularity in open source

💡 Lessons Learned #

Longevity comes from solving a real, persistent need
A tool doesn’t need to be revolutionary to be useful
Zero dependencies mean zero maintenance headaches
Sometimes the impact of a tool isn’t measured in stars
Simple tools that remove friction are worth maintaining

Want to share files from your terminal? Check out fileup on GitHub!

#OpenSource #Python #DevTools #CommandLine #Programming

Psychedelic Data Science 🍄

Wed, 18 Dec 2024 00:00:00 +0000

(See my intro post)

📝 Note: Running out of awesome projects and I want to save the best for last, so today just something fun.

While preparing for this advent calendar, I browsed through my 382 GitHub repositories and rediscovered this time capsule from 8 years ago. It explores the language of psychedelic experiences through data science - with an interesting hypothesis: do psychedelic experiences generate richer vocabulary compared to other substance reports?

📖 Origin Story #

Back in 2015, when I was still “young” (before back pain and two-day hangovers became a thing), I was learning data science and natural language processing. I had an amusing hypothesis: surely people describing their psychedelic experiences would use richer vocabulary than those writing about stimulants - I mean, who hasn’t pondered the linguistic complexity of “everything is connected” versus “I cleaned my entire apartment at 4 AM”? Erowid.org, with its thousands of detailed first-person narratives across different substances, provided the perfect dataset to test this theory.

🔧 Technical Highlights #

Natural language processing of experience reports
Vocabulary richness analysis across substance categories
TF-IDF vectorization for text analysis
Support Vector Machine classification of experience types
Web scraping with BeautifulSoup
K-means clustering for discovering common themes
Word cloud generation to visualize vocabulary differences

📊 Impact #

A learning project that helped understand:
- How different experiences shape language use
- Processing subjective experience narratives
- Document classification techniques
- The challenges of quantifying vocabulary richness
10 GitHub stars

🎯 Challenges and Solutions #

Implementing respectful web scraping
Controlling for report length and education level
Creating meaningful metrics for vocabulary richness
Visualizing linguistic patterns across categories

💡 Lessons Learned #

Putting things on GitHub means it’s less likely forgotten things get lost
Early data science projects often reveal our initial fascinations
Web scraping requires both technical skill and ethical consideration
Text analysis tools have evolved dramatically since 2015
Sometimes the most interesting projects are the ones you almost forgot about

Want to explore this intersection of psychedelics, language, and data science? Check out the project on GitHub!

#OpenSource #Python #DataScience #NLP #MachineLearning

Adaptive Scheduler 🚀

Tue, 17 Dec 2024 00:00:00 +0000

(See my intro post)

Ever tried to efficiently run 100,000 cores from a Jupyter notebook? No? Well, I have, and it led to some interesting discoveries about the limits of parallel computing tools.

📖 Origin Story #

During my 2018 internship at Microsoft Quantum, we faced a unique challenge: our adaptive sampling algorithms needed to run on massive computing clusters (50,000+ cores), but existing tools couldn’t handle it efficiently.

The problem was interesting: traditional parallel computing tools like Dask rely on a central scheduler process. Imagine 100,000 cores, each finishing a task every 10 seconds. That means every 10 microseconds, a core needs new work! With typical scheduler overhead being 1-50 milliseconds, workers would spend 99% of their time waiting rather than computing.

Usually, you’d solve this by batching work ahead of time. But with adaptive sampling (yesterday’s project), that’s impossible - you need the results of previous calculations to know what to compute next. It was like trying to conduct an orchestra where each musician needs personal instructions every few seconds!

🔧 Technical Highlights #

We created a solution that:

Acts as a meta-scheduler, launching multiple sub-schedulers (Dask, ipyparallel, mpi4py, etc.)
Minimizes communication between scheduling layers
Handles job management through a simple database
Supports automatic fault tolerance and data saving
Works with any cluster scheduler (SLURM, PBS)
Provides real-time progress tracking in Jupyter notebooks
Scales to 50,000+ cores without breaking a sweat

📊 Impact #

Used extensively for real quantum device simulations
26 GitHub stars (but don’t let that fool you - it’s highly specialized!)
Enables interactive supercomputing from a simple Jupyter notebook
Likely ran for many millions of core-hours across various projects
Actively maintained with 61 releases since 2018, proving its ongoing value

🎯 Challenges We Solved #

Scheduler overhead killing performance at scale
Data locality and fault tolerance
Real-time monitoring of massive parallel jobs
Making supercomputing accessible through notebooks
Automatic job recovery after crashes (e.g., when using spot VMs or Heisenbugs)

💡 Lessons Learned #

Sometimes you need to think outside the box
The best tools hide complexity behind simple interfaces
Real-time feedback is crucial, even for massive computations
When scaling up 1000x, you often need a completely different approach
Making things “just work” from a notebook is worth the effort

Want to run massive parallel computations efficiently? Check out Adaptive Scheduler on GitHub!

#OpenSource #Python #HPC #QuantumComputing #ParallelComputing

Adaptive 📈

Mon, 16 Dec 2024 00:00:00 +0000

(See my intro post)

During my PhD, I was running quantum transport simulations on our 800-core computational cluster. Traditional parameter sweeps using dense grids were hitting the cluster’s limits - wasting precious compute time on uninteresting regions while potentially missing important features. Most parameter spaces we explored were “boring” with occasional interesting regions that required higher sampling density.

📖 Origin Story #

Initially, in 2016, I had a collection of one-off adaptive sampling scripts. Together with Joseph Weston and the support of my PhD advisor Anton Akhmerov, we turned it into a full-fledged Python package “Adaptive”. What began as an internal tool to make our cluster usage more efficient slowly gained traction in the wider scientific computing community.

🔧 Technical Highlights #

Multiple adaptive sampling strategies (1D, 2D, ND, averaging stochastic functions)
Parallel execution support (local, MPI clusters, distributed systems)
Live plotting in Jupyter notebooks with real-time feedback
Customizable loss functions for different sampling priorities
Minimal dependencies

📊 Impact & Applications #

1164 GitHub stars and thousands of daily downloads
Cited in 20+ scientific publications
Dependency of many packages, most notably: Orange Quantum System’s Quantify software for controlling real quantum computers!

Used in cutting-edge research across fields:

Quantum Computing: Simulating and controlling superconducting qubits and trapped ion systems
Quantum Physics: Exploring topological quantum systems and novel materials
Materials Science: Studying graphene and other 2D materials
Engineering:
- Optimizing radar system performance
- Fluid dynamics simulations
Chemistry: Molecular modeling and vibrational spectroscopy
Most Unexpected Use: Found in a paper on predicting energy usage of wartime bungalows!

This range of applications shows how a tool built for quantum transport simulations can find surprising uses across disciplines, from fundamental physics to everyday buildings.

🎯 Challenges and Solutions #

Making parallel execution truly scalable while maintaining sampling intelligence
Creating intuitive visualization tools for complex parameter spaces
Handling stochastic functions and noisy data

💡 Lessons Learned #

Building a user base takes active effort - giving talks and engaging online made all the difference
Good documentation converts interested users into regular contributors
This was my first open source package and learned all about packaging, testing, and CI/CD

Want smarter parameter space exploration? Check out Adaptive on GitHub or try our interactive tutorial!

#OpenSource #Python #ScientificComputing #ParallelComputing #Programming

clip-files 📋

Sun, 15 Dec 2024 00:00:00 +0000

(See my intro post)

Sometimes the most useful tools are born from daily frustrations. When working with AI assistants like ChatGPT or Claude, I found myself constantly copying files to share context. After doing this manually dozens of times, I created a tool to automate it.

📖 Origin Story #

While contributing to open source, I frequently like to share entire (or large parts of) codebases with AI assistants for context or code review. Since the code is open source anyway, there’s no reason not to share the full context! But manually copying files, adding their paths for context, and ensuring I didn’t exceed token limits was tedious. Instead of continuing this manual process, I spent an evening creating clip-files - and have used it multiple times daily ever since.

In fact, I’m using it right now! The command (shown below) lets me share this entire advent calendar series with AI assistants for proofreading.

clip-files --initial-file ai.md --files introduction.md day*.md

🔧 Technical Highlights #

Uses tiktoken for accurate GPT token counting
Supports both directory traversal and specific file selection
Automatically generates a file index for reference
Allows custom initial instructions via file
Preserves file paths in output for context
Clean, typed, and documented codebase

📊 Impact #

While this tool has no GitHub stars (I haven’t promoted it), its real impact is personal - I use it multiple times daily for:

Sharing entire open source codebases with AI assistants
Getting comprehensive code reviews
Discussing bug fixes with full context
Documentation improvements
Open source contributions

The tool’s real value isn’t in its complexity (it’s just ~250 lines of code) but in how it removes friction from open source development. When working with open code, we might as well share all the context we can - and this tool makes that effortless.

🎯 Challenges and Solutions #

Maintaining consistent formatting across different input methods
Calculating accurate token counts for different components
Providing meaningful error messages for invalid inputs
Structuring output to be AI-assistant friendly

💡 Lessons Learned #

When working with open source code, sharing full context is valuable
Simple command-line tools can significantly improve daily workflows
Consistent formatting matters when working with AI assistants
Sometimes a 250-line tool can save hours of manual work

Want to make sharing code with AI assistants easier? Check out clip-files on GitHub!

#OpenSource #Python #DevTools #AI #Programming

PhD Thesis Cover Design 🎨

Sat, 14 Dec 2024 00:00:00 +0000

(See my intro post)

When most people think of open source, they think of software. But what about open-sourcing your PhD thesis and creating a generative art system for its cover?

📖 Origin Story #

With my PhD defense approaching and needing around 100 copies of my thesis, I faced a design challenge. As someone more comfortable with Python than Photoshop, I turned what started as a simple visualization idea into a full-blown generative art project with machine learning-based clustering.

Multiple printed copies of the thesis

🔧 Technical Highlights #

Generated 3,671 unique covers from quantum physics simulation data
Used VGG16 neural network to extract features from covers
Implemented K-means clustering to group similar designs
Created interactive IPywidgets for design selection
Built a Binder app for real-time color scheme adjustment
Added unique edition numbers (1/120, 2/120, etc.)
Made both thesis and cover design code fully open source

The project combines:

Adaptive sampling for physics simulations
Neural networks for image feature extraction
Interactive visualization tools
Parallel processing for batch generation
Version control for scientific writing

📊 Impact #

Thesis repository: 14 GitHub stars
Cover design repository: 36 GitHub stars
Real-world adoption: Dr. Tomas Pippia from TU Delft used the code to create his own thesis cover
~100 unique printed copies, each with its own generated cover and edition number

🎯 Challenges and Solutions #

Managing 3,671 unique PDF files and their conversions
Creating a clustering system for visually similar designs
Building interactive tools for non-technical collaborators
Ensuring consistent print quality across designs
Balancing artistic appeal with scientific relevance

💡 Lessons Learned #

Open source isn’t just about code - it’s about sharing knowledge
Python can be a powerful tool for creative projects
Machine learning can help solve unexpected problems
Good visualization requires both technical skill and artistic sense
Interactive tools make collaboration with non-programmers easier

📚 Fun Fact #

Due to COVID restrictions, I defended my thesis without any guests present. The silver lining? I still have about 100 beautifully unique copies at home, each with a different generated cover and edition number. If you’d like a physical copy of this piece of quantum physics meets generative art, just let me know!

Want to create your own thesis cover or see how I wrote mine? Check out the thesis cover project and thesis source!

#OpenSource #PhD #Python #MachineLearning #DataVisualization

UniDep 🧬

Fri, 13 Dec 2024 00:00:00 +0000

(See my intro post)

Ever tried to set up a Python project that needs both pip and conda packages? Then you know the pain of maintaining multiple requirement files. UniDep was born from years of frustration with this exact problem.

📖 Origin Story #

While working on large monorepos with hundreds of dependencies, I kept running into the same issue: maintaining separate files for conda (environment.yml), pip (requirements.txt), and Python packaging (pyproject.toml). Coming from languages like Rust, where package management is a joy, Python’s fragmented ecosystem can feel overwhelming, especially to newcomers (obligatory xkcd.com/1987).

What started as a simple tool to avoid duplicate dependency definitions turned into something much more powerful. In enterprise environments, it’s common to find monorepos with over 1000 dependencies spread across dozens of packages. Setting up these environments traditionally involves following lengthy setup guides, installing packages in the correct order, and hoping nothing breaks.

Then came the “aha” moment - what if we could install everything with a single command? After implementing UniDep, those complex setup guides became a one-liner: unidep install-all -e. It installs all dependencies and sets up every package in the monorepo in editable mode. What used to take hours now takes minutes.

The difficulty of managing pip and conda

🔧 Technical Highlights #

Single source of truth for all dependencies
Supports both requirements.yaml and pyproject.toml
Handles platform-specific dependencies
Generates conda-lock files both for entire monorepos and fully consistent lock files for its individual packages
Works with pip, conda, and mamba
Monorepo-friendly with local dependency support
Integrates with setuptools and hatchling
≥99% test coverage, fully-typed

📊 Impact #

221 GitHub stars
Featured on Python Bytes podcast
Saves countless hours of dependency management
Makes complex project setups accessible
Actively maintained with 70 releases

🎯 Challenges and Solutions #

Different package naming between pip and conda
Platform-specific dependencies
Cross-platform compatibility (Linux, Windows, MacOS)
Supporting pip-only workflows

💡 Lessons Learned #

Good developer experience is worth the effort
Sometimes you need to build a bridge between existing tools
The best tools make hard things easy
Dependency resolution is hard but can be simple for users

🔮 Future Plans #

Adding Pixi support - allowing seamless migration to Pixi without changing config files
Eventually, Pixi might make UniDep obsolete (and that’s okay!)
For now, UniDep bridges the gap between pip and conda, making life easier for developers

Want simpler dependency management? Check out UniDep on GitHub!

#OpenSource #Python #DevTools #Programming #PackageManagement #Conda

instacron 📸

Thu, 12 Dec 2024 00:00:00 +0000

(See my intro post)

Ever found yourself with beautiful photos but too lazy to post them? Instead of changing my habits, I did what any developer would do: spent way more time automating the process than it would have taken to post manually.

📖 Origin Story #

Back in 2017, I had hundreds of landscape photos from traveling through South America that I wanted to share on Instagram. The solution? Write a Python script that would randomly select photos and post them automatically, complete with philosophical quotes randomly selected from Bukowski, Einstein, or Dostoevsky because… it seemed to be the default of all “influencers” at the time. Nothing says “authentic travel experience” like an auto-generated Bukowski quote about drinking next to your serene mountain photo!

Instacron Example Post

🔧 Technical Highlights #

Randomly selects photos from a directory
Adds location data from EXIF metadata
Generates captions with random philosophical quotes
Adds two random emojis to match the “mood”
Automatically generates relevant hashtags
Tracks posting frequency
Uses cron for scheduled posting

📊 Impact #

21 GitHub stars
4143 Instagram followers
Successfully posted hundreds of photos
Generated some concerned DMs (more on that below!)

🎯 Challenges and Solutions #

Instagram’s ever-changing API
Handling rate limits and restrictions
Ensuring photos weren’t posted multiple times
Making captions interesting without human input
The delicate art of random emoji selection

😅 Funny Story #

The random quote and emoji selector once created an unexpectedly dramatic post. Picture this: a beautiful landscape photo paired with a deeply philosophical quote about solitude, and topped with a broken heart emoji (💔). Within hours, I started receiving concerned DMs from friends asking if everything was okay and whether my relationship had ended!

I had to explain that no, I wasn’t going through a breakup - my bot just had a flair for the dramatic! These occasional mismatches made the whole thing more entertaining.

💡 Lessons Learned #

Sometimes the best projects come from pure laziness
Automation doesn’t always save time, but it’s fun
Never underestimate the power of a misplaced emoji to trigger concerned messages
Some followers actually care about you (even if they’re worried about your bot-generated content)

While I haven’t used this project in 6 years (Instagram’s API changes eventually won), it remains a testament to the lengths we’ll go to avoid repetitive tasks. Check out instacron on GitHub!

#OpenSource #Python #Automation #Photography #Instagram

conda-forge Contributions 🐍

Wed, 11 Dec 2024 00:00:00 +0000

(See my intro post)

Unlike other projects in this advent calendar, I want to celebrate being part of something much bigger: the conda-forge community, where thousands of volunteers maintain the packages that power scientific Python.

📖 Origin Story #

I started with conda-forge in 2016 during my PhD work with Kwant, a quantum transport simulator. Installing it was a nightmare - it required system-level numerical libraries like MUMPS and Scotch which required a special config file to link. When I discovered conda-forge and its mission to make scientific software installation painless, I knew this was the solution!

The humble work of conda-forge maintainers

🔧 Technical Highlights #

Over the past 8 years, I’ve maintained over 40 build recipes, including:

Major scientific packages like VTK, MUMPS, and Scotch
Quantum physics tools like Qsim, Qcodes, and Kwant
Visualization libraries like HoloViews
Plus all the packages I’ve authored myself

The real magic of conda-forge is its infrastructure:

Automated builds across Linux, macOS, and Windows
Strict dependency version management
Comprehensive CI/CD pipelines
Community-driven quality control

📊 Impact #

What makes conda-forge truly special is how initial contributions blossom into collaborative efforts. I’ve experienced this firsthand: after creating the initial MUMPS feedstock, 25 other contributors joined in, each bringing their unique expertise.

A recent experience also illustrates this: I added CUDA support to both Google’s Qsim and IBM’s Cirq packages. Shortly after, Leo Fang, an engineer from NVIDIA who knows CUDA far better than I do, stepped up and made significant improvements. This is the beauty of open source - experts naturally gravitate to where they can make the biggest impact.

This collaborative approach solves a problem I’ve encountered at several companies: the tendency to maintain complicated build systems internally with custom hacks. Instead of each organization reinventing the wheel, conda-forge provides a shared platform where:

Maintenance burden is distributed
Expert knowledge flows freely
Build practices are standardized
Infrastructure is public and reusable

🎯 Challenges and Solutions #

Keeping up with upstream changes
Managing complex dependency trees
Cross-platform compatibility
Coordinating with upstream maintainers

💡 Lessons Learned #

Community effort beats solo work for infrastructure
Automation is crucial for reliability
Small contributions compound over time
Being part of something bigger is rewarding

Want to contribute to scientific Python? Check out conda-forge and the staged-recipes repository!

#OpenSource #Python #Scientific #Programming #Community

Home Assistant Config 🏠

Tue, 10 Dec 2024 00:00:00 +0000

(See my intro post)

Funny how things work out - initially, I didn’t care for home automation at all. But when in 2020 I discovered Home Assistant was written in Python, my favorite programming language, I suddenly found a new hobby. Over the years, I’ve built a comprehensive setup with over 137 automations (and counting!). These automations are triggered by everything from simple motion sensors to complex patterns of conditions and sensor states, creating a home that responds intelligently to our needs.

📖 Origin Story #

What started with basic light controls evolved into a complete home automation system. In the beginning, my wife was continuously annoyed by lights turning on at the wrong moment or not at all. However, as I debugged and refined the system, things started working exactly as expected, and she began to really appreciate it. When we moved from The Netherlands to the US in 2022 (and two more times since), we felt like we were back in the stone age having to manually control lights. The annoyance had shifted from buggy automations to not having Home Assistant fully installed yet!

Unfortunately, I’ve been less active lately with my Home Assistant setup because so many other projects draw my attention. One of these “projects” is my 1.5-year-old twin boys, who now have their own room with specialized automations, including 100% local cameras with ML pattern detection for monitoring without compromising privacy.

The evolution of home automation

🔧 Technical Highlights #

137 documented automations with auto-generated documentation
Presence detection in every room
Adaptive lighting throughout the house
Privacy-focused baby monitoring
Fully local processing
2,432 commits of continuous improvement

📊 Impact #

1,747 GitHub stars
185 forks
Used as reference by countless Home Assistant enthusiasts
Featured in Home Assistant community
Spawned several spin-off projects (like Adaptive Lighting from Day 2!)

💡 Lessons Learned #

Start small, expand gradually
Privacy and local processing matter
Automated documentation stays accurate
Home automation is never “finished”
Sometimes life (like twins!) brings new automation challenges

Want to explore my home automation setup? Check out the full config on GitHub!

#OpenSource #HomeAssistant #SmartHome #IoT #Python

yaml2bib 📚

Mon, 09 Dec 2024 00:00:00 +0000

(See my intro post)

Every academic writing in LaTeX knows the pain: managing BibTeX files with hundreds of citations, each potentially formatted slightly differently, with inconsistent journal abbreviations, and duplicated entries across chapters. While procrastinating on writing my PhD thesis, I became obsessed with solving this universal academic headache.

📖 Origin Story #

When writing a PhD thesis with multiple chapters that share citations, maintaining consistency is crucial but tedious. Different chapters might cite the same paper but with slightly different BibTeX entries - one using the full journal name, another using abbreviations, or worse, having slightly different titles or author lists. Rather than manually standardizing ~350 citations, I created yaml2bib: give it a list of DOIs in YAML format, and it generates a perfect BibTeX file with consistent journal abbreviations and formatting.

The pain of manual BibTeX management

🔧 Technical Highlights #

Fetches citation data from CrossRef using DOIs
Ensures consistent journal name abbreviations
Caches API responses to avoid repeated queries
Supports custom text replacements
Combines multiple YAML sources
Works as both CLI tool and Python library
Zero manual citation formatting needed

📊 Impact #

While this tool has only 11 GitHub stars, it saved me countless hours during thesis writing and helped ensure professional consistency in my citations. It’s particularly useful for:

Large academic documents with many citations
Multi-chapter works sharing references
Collaborative papers needing citation standardization
Anyone tired of manually formatting BibTeX entries

💡 Lessons Learned #

Procrastination can be productive if channeled right (story of my life…)
A single source of truth prevents inconsistencies
Good tools make you care about details you’d otherwise skip
Every LaTeX user has fought with BibTeX at some point

Want perfectly consistent citations? Check out yaml2bib on GitHub!

#OpenSource #Python #Academia #LaTeX #Research

Home Assistant Stream Deck YAML 🎮

Sun, 08 Dec 2024 00:00:00 +0000

(See my intro post)

What started as a personal hack to control my home (temperature, lights, TV, music) with a gifted Stream Deck evolved into something bigger. This project became my first real exploration of AI-assisted development, showing me how much faster I could work with AI as a tool. With 250+ stars and 9 contributors adding significant features, it’s grown beyond my initial vision.

📖 Origin Story #

While the Stream Deck’s official software is great for streamers, it doesn’t support Linux and its Home Assistant integration is not very programmable. After creating a simple solution using python-elgato-streamdeck, I realized others might be interested. Using AI as a development partner changed my workflow - it helped write tests, reviewed code, and generated use cases I hadn’t thought of. What really surprised me was asking AI to brainstorm example configurations - it generated over 30 creative use cases with complete code examples, which I then turned into unit tests. These tests now automatically generate the documentation using markdown-code-runner (from Day 5).

🔧 Technical Highlights #

YAML configuration with Jinja2 templating
Supports all Stream Deck models, including the Plus with dials
Cross-platform (Linux, macOS, Windows)
30+ example configurations (AI-generated, then human-refined)
Documentation auto-generated from code and unit tests
Available as a Home Assistant add-on
Community-contributed features like touchscreen support and dial controls

💡 Lessons Learned #

AI can significantly speed up development
Faster development enables broader project scope
Good examples make the best documentation
Tools building upon tools multiply productivity
Community contributions can take a project in exciting new directions

Want to control Home Assistant with a Stream Deck? Check out the project on GitHub!

#OpenSource #HomeAssistant #SmartHome #Python #AI

numthreads 🧵

Sat, 07 Dec 2024 00:00:00 +0000

(See my intro post)

Sometimes the smallest tools solve the most persistent problems. Today’s project is about taming automatic parallelization in scientific computing - a deceptively simple challenge that has cost countless CPU hours.

📖 Origin Story #

While working on high-performance computing clusters, I frequently encountered a counterintuitive problem: code running slower on multiple CPU cores than on a single one. Many scientific libraries (NumPy, SciPy) automatically parallelize operations, which sounds great but can actually harm performance when you’re already parallelizing at a higher level. After repeatedly explaining to colleagues why they needed to set various environment variables to disable this behavior, I created numthreads to solve it once and for all.

Overenthusiastic threading

🔧 Technical Highlights #

Controls thread count for major numerical libraries:
- OpenBLAS
- Intel’s Math Kernel Library (MKL)
- OpenMP
- NumExpr
- Accelerate
Zero dependencies
Tiny (≤7KB) yet solves a real problem
Both CLI and Python API

📊 Impact #

Over my scientific computing career, I’ve encountered this threading issue dozens of times. Since creating this package a year ago, I’ve helped at least 5 different researchers speed up their workflows, sometimes by orders of magnitude. The beauty lies in its simplicity - the fix is often as simple as:

eval $(numthreads 1)

💡 Lessons Learned #

The simplest solutions are often the best
More cores doesn’t always mean faster code
If you find yourself repeating the same instructions, write a tool
Even a 7KB package can save hours of computing time

Want better control over your numerical computations? Check out numthreads on GitHub!

#OpenSource #Python #HPC #ScientificComputing #Programming

Open Science Publications 🔬

Fri, 06 Dec 2024 00:00:00 +0000

(See my intro post)

Today’s post is about something I have strong opinions on: making scientific research reproducible. While many researchers talk about open science, actually making your work reproducible for anyone requires significant effort.

📖 Origin Story #

During my Ph.D. and subsequent research, I noticed a frustrating pattern in scientific publications: claims of “code available upon request” that often led nowhere, or code snippets that wouldn’t run without substantial modification. I made an effort that my publications would be different – each includes complete, runnable code that reproduces every figure and result.

🔧 Technical Highlights #

Multiple repositories covering quantum physics experiments and simulations:
- orbitalfield - “Orbital effect of magnetic field on the Majorana phase diagram” (94 citations)
- supercurrent-majorana-nanowire - “Supercurrent interference in few-mode nanowire Josephson junctions” (78 citations)
- zigzag-majoranas - “Enhanced proximity effect in zigzag-shaped Majorana Josephson junctions” (56 citations)
- azure-quantum-tgp - “Protocol to identify a topological superconducting phase in a three-terminal device” (52 citations)
- spin-orbit-nanowires - “Spin-orbit protection of induced superconductivity in Majorana nanowires” (81 citations)

🔄 Evolution of Best Practices #

What I consider best practices has evolved over time. Today, I would:

Use Pixi for universal lock files across operating systems and programming languages
Provide a minimal Docker container that just installs the pixi lock file
Create self-documenting Jupyter notebooks that reproduce every result
Include clear figure-to-code mapping for paper reproducibility

🎯 Challenges and Solutions #

Balancing code cleanliness with research deadlines
Managing large datasets efficiently
Ensuring long-term reproducibility
Making complex physics simulations accessible

💡 Lessons Learned #

Clean code takes time but saves more in the long run
Documentation is as crucial as the code itself
Lock files are essential for true reproducibility
Making code public improves its quality

Want to explore quantum physics simulations? Check out the repositories above, each linked to their corresponding papers with full reproduction instructions.

#OpenSource #OpenScience #Physics #QuantumComputing #Python

markdown-code-runner 📝

Thu, 05 Dec 2024 00:00:00 +0000

(See my intro post)

Documentation should be as close to the code as possible - that’s the principle of “information locality.” But how do you keep code examples and their outputs in sync? Enter markdown-code-runner, a tool that executes code blocks within Markdown files and updates their output in-place!

📖 Origin Story #

While maintaining various open source and work projects, I found myself constantly updating README or Wiki files with new command outputs, updated tables, and fresh examples. This manual process was error-prone and tedious. Instead of using external templating files or more advanced documentation generators like Sphinx and Quarto (which are often overkill for single-page projects), I wanted something simpler: code and its output living together in the same Markdown file, always in sync.

🔧 Technical Highlights #

Executes code blocks (Python and Bash) within Markdown files
Updates outputs in-place while preserving the original file structure
Supports hidden code blocks for generating content without showing the code
Works with any language by using file code blocks and bash execution
Zero external dependencies
GitHub Actions integration for automatic README updates
Preserves Markdown spec compatibility by hiding code in HTML comments ()

📊 Impact #

97 GitHub stars
Used in many of my other projects for auto-generating:
- Command-line help texts
- API documentation
- Example outputs
- Data tables
Helps maintain “information locality” - everything needed is in one file
Enables dynamic documentation that stays up-to-date automatically

🎯 Challenges and Solutions #

Parsing Markdown without breaking its structure
Supporting multiple programming languages
Making it work seamlessly with GitHub Actions
Handling complex outputs (tables, images, etc.)
Maintaining backward compatibility with existing Markdown files

💡 Lessons Learned #

Documentation is best when it’s close to what it documents
Automation should be invisible - the tool shouldn’t change how you write Markdown
Sometimes the simplest solution (using HTML comments) is the best
Good documentation tools should make maintaining docs easier, not harder
Auto-generated content should be clearly marked as such

Want to keep your documentation always in sync? Check out markdown-code-runner on GitHub!

#OpenSource #Python #Documentation #DevTools #Programming

WenFire: When Could I retire?! 🔥

Wed, 04 Dec 2024 00:00:00 +0000

(See my intro post)

While I absolutely love my job, I believe I’ll love it even more when my family’s livelihood doesn’t depend on it. That’s the dream of financial independence - doing what you love because you want to, not because you have to. This led me to create WenFire, a financial independence calculator that helps answer the eternal questions: “When can I retire?” and “How many days of extra work will that new iPhone or car cost me?”

📖 Origin Story #

There are many retirement calculators out there, but they all made assumptions I didn’t quite agree with (and I’m sure others won’t agree with my assumptions either!). I wanted something that matched my specific views on salary growth and investment returns. Plus, I had been itching to learn more about building web applications, so this project let me explore FastAPI, htmx, and Vega-Lite while solving a personal need.

🔧 Technical Highlights #

Built with FastAPI and Bootstrap
Interactive visualizations using Vega-Lite
Responsive and mobile-friendly design
Customizable assumptions for:
- Investment growth
- Inflation rates
- Salary increases
- Safe withdrawal rates
Allows parameter changes at certain dates
Calculate retirement impact of one-time expenses
All parameters are encoded in the URL for easy sharing

📊 Impact #

While this project only has 3 GitHub stars, its real value is personal - it helps me track my own journey to financial independence. It’s also been a great learning experience in web development, an area where I had little prior experience.

🎯 Challenges and Solutions #

Learning web development from scratch
Creating intuitive visualizations for financial data
Balancing simplicity with customization options
Making reasonable default assumptions
Ensuring mobile responsiveness

💡 Lessons Learned #

Financial modeling requires careful consideration of assumptions
Web development is a different beast from scientific computing
Sometimes the best way to learn new tech is to solve a personal problem
The best calculator is the one that matches your own assumptions

Want to calculate your path to financial independence? Try it at wenfire.nijho.lt or check out the source code!

#OpenSource #Python #FinancialIndependence #WebDev #FIRE

rsync-time-machine.py 🕒

Tue, 03 Dec 2024 00:00:00 +0000

(See my intro post)

Sometimes the best open source projects start with “I can do better than this.” That’s exactly what happened when I looked at laurent22/rsync-time-backup, a popular 600-line Bash script for Time Machine-style backups. While it worked, it had known bugs and was tricky to maintain due to Bash’s limitations. It also lacked tests, type hints (bash duh…), and proper error handling. So, I did what any reasonable developer would do: rewrote it in Python: rsync-time-machine.py! 🐍

📖 Origin Story #

I needed reliable backups that worked across platforms and filesystems, unlike Apple’s Time Machine. While many excellent backup tools exist, I was drawn to the simplicity of this approach: it just creates folders named YYYY-MM-DD-HH-MM-SS containing your files. No special tools needed for restoring or browsing - just your regular file explorer! I created a fully tested, typed, and documented Python port that maintains compatibility with the original while adding modern development practices.

🔧 Technical Highlights #

Creates incremental backups using hard links (saving space while keeping full snapshots)
Works on Linux, macOS, and Windows (via WSL or Cygwin)
Supports local and remote (SSH) backups
Smart backup expiration strategy
Built-in safety checks and locking mechanism
Pretty terminal output
Absolutely zero dependencies beyond Python itself - it just works!
Usable as a standalone .py script or pip installable package
100% test coverage

📊 Impact #

The project reached the front page of Y Combinator’s Hacker News, causing its popularity to explode:

381 GitHub stars
16 forks
6 contributors
Featured on Real Python podcast
Active discussion on Reddit’s r/commandline

🎯 Challenges and Solutions #

Maintaining compatibility with the original Bash script while improving the codebase
Making it work on Windows through WSL/Cygwin (surprisingly tricky!)
Handling various edge cases in filesystem operations
Implementing a robust backup expiration strategy
Adding comprehensive test coverage for file operations
Keeping the codebase dependency-free while maintaining functionality

💡 Lessons Learned #

Sometimes a rewrite is worth it, especially when adding modern development practices
Good documentation and test coverage are crucial for backup tools
The Python community appreciates well-structured ports of useful tools
Zero dependencies means zero headaches for users
Cross-platform compatibility (especially Windows) requires careful consideration
Simple, transparent solutions (like regular folders) can be better than complex ones

Want reliable, cross-platform Time Machine-style backups? Check out the project on GitHub!

#OpenSource #Python #Backups #DevTools #Programming

Adaptive Lighting 💡

Mon, 02 Dec 2024 00:00:00 +0000

(See my intro post)

Unlike yesterday’s Calendar of Life project, today we’re looking at one of my most popular contributions. It’s one of several Home Assistant and home automation related projects (Day 8, Day 10, Day 24) I’ll be sharing this month. While my coding journey started in scientific computing with physics simulations, discovering how to control my home environment through code sparked a new obsession. Home Assistant, currently the #1 open source project on GitHub, is the brain of my smart home and lets you control and automate everything from lights to thermostats, completely locally and privacy-focused.

Keep your lighting in sync with the sun, they said. It’ll be simple, they said…

📖 Origin Story #

Back in 2020, inspired by @claytonjn’s circadian_lighting Home Assistant component, I wanted to create a more comprehensive solution for automatically adjusting lights based on the time of day. What started as a contribution attempt to Home Assistant Core evolved into its own custom component when the PR wasn’t merged - handling all the edge cases made the code too complex for core. The standalone component gave us the freedom to implement features properly, becoming one of Home Assistant’s most installed custom integrations.

🔧 Technical Highlights #

While the concept is simple, making it work reliably is… interesting:

Handles unreliable Zigbee networks and flaky WiFi connections
Manages different light brands’ quirks (looking at you, IKEA bulbs 👀)
Provides smooth transitions between color temperatures
Detects manual overrides without disrupting user control
Supports sleep modes for bedtime routines
Configurable via YAML or the UI (only integration to support this!)

The integration has 38 parameters to fine-tune your lighting. Try our WebAssembly simulator to visualize your settings!

📊 Impact #

2000+ GitHub stars
103 contributors
512 issues
Tens of thousands of active users
Available in 20+ languages
One of the most installed custom integrations
Featured in several YouTube videos and podcasts
Dedicated parameter visualization web app

🎯 Challenges We Solved #

Lights randomly turning on (bulbs falsely reporting state)
Network congestion (solved with Zigbee grouping)
Different brands interpreting colors differently
Handling manual overrides gracefully

💡 Lessons Learned #

“It works on my setup” is just the beginning
Users surprise you (like using it for plants, or above the polar circle!)
Edge cases multiply quickly
Documentation is as important as code
Open source thrives on community effort

Want your lights to follow the sun? Check out the project on GitHub and try the simulator!

#OpenSource #HomeAssistant #SmartHome #IoT #Python

Calendar of Life 📅

Sun, 01 Dec 2024 00:00:00 +0000

(See my intro post.)

Visualizing the finite weeks of our lives, because apparently, I needed another reminder of my mortality!

📖 Origin Story #

You know how sometimes you’re just casually browsing the internet, not looking to have an existential crisis? Well, that’s exactly what happened when I stumbled upon Tim Urban’s Wait But Why post “Your Life in Weeks” and saw Kurzgesagt’s “Calendar of Your Life” poster. Instead of just feeling mildly anxious about the finite nature of existence like a normal person, I decided to cope by writing some Python code. Because that’s what we do, right?

🔧 Technical Highlights #

The project uses matplotlib to create a grid where:

Each row represents one year (up to 80 years, optimistically speaking!)
Each column represents one week (52 weeks per year)
Different colors show different life stages (early childhood, school, university, etc.)
The current week blinks in the animated version, just in case you needed a more urgent reminder of time passing
Supports both dark and light modes, because existential dread comes in all themes

One interesting technical detail is handling the fact that 52 weeks isn’t exactly one year. The code uses a small correction factor (days_per_week = 365.25 / 52) to ensure the visualization stays accurate over many years. Yes, I made sure your existential crisis would be mathematically precise.

📊 Impact #

With its whopping 5 GitHub stars, this project clearly hasn’t taken the world by storm. But hey, sometimes the best tools are the ones we make for ourselves, right?

🎯 Challenges and Solutions #

The main challenges were (this was actually a very simple one):

Accurately mapping life events to week numbers (turns out life doesn’t fit neatly into boxes)
Creating smooth animations for the current week indicator (because a blinking dot really drives home the whole “time is passing” thing)
Handling the 52 vs 52.18 weeks per year discrepancy (thanks, Earth’s orbit)
Making the visualization work well in both dark and light modes (for viewing your life calendar at any time of day)

💡 Lessons Learned #

This project taught me that sometimes the most impactful tools are the simplest ones. Sure, it’s just a bunch of dots on a grid, but each dot represents a week of life - past, present, or future. It’s a humbling reminder that while we can’t add more dots to our grid, we can try to make each one count.

Want to contemplate your own mortality in a more organized way? Check out the project on GitHub!

#OpenSource #Python #DataVisualization #Programming

Open-Source | Bas Nijholt

Roll your own, fork the rest 🍴

Introduction: a follow-up to something I wrote #

1. Stars measure interest, not usage #

2. A popular protocol is not a popular library #

3. I checked the rule against my own code #

4. Roll your own: the library gives you the easy 10% #

5. Fork your own: when the problem is hard #

Agno: patches instead of a fork #

6. I am not dunking on open source, including mine #

7. My rule for the next uv add #

Friend-to-friend ZFS backups, version two

Why ZFS #

What we wanted #

ZFS already had most of it #

Rehearsing the permissions in a VM #

A gate that speaks syncoid #

Zones: a second wall in the kernel #

Who stops what #

What it cannot hide #

Setting it up #

Knowing when it stops working #

Restoring #

The first real push #

Tested like everything else #

AI scope creep or useful? #

References #

MindRoom: AI agents that live in Matrix and work everywhere 🧠

1. The problem: your AI is trapped in apps #

2. What is MindRoom? #

3. How it actually works #

4. Building on Matrix: the good and the tricky #

5. Memory that follows you #

6. 100+ built-in tool integrations #

7. Teams: agents that collaborate #

8. Hot-reload: change config and plugins without downtime #

9. Voice, scheduling, and other features #

10. The obsession, the SaaS dream, and the burnout #

11. OpenClaw and why it matters #

12. What’s next #

Links and resources #

Auto-installing extras at runtime so users never have to think about dependencies

1. From one command to a dependency maze #

2. Why “just use extras” breaks down #

3. The decorator #

4. Checking without importing #

5. The metadata bridge #

6. Three environments, three strategies #

A) uv tool install — the persistent environment #

B) uvx — the ephemeral environment #

C) Regular virtualenv, pipx, or system install #

7. Preventing infinite re-execution loops #

8. What users actually see #

9. Keeping everything in sync #

10. Why uv made this practical #

11. Tradeoffs #

12. Not dependency injection #

13. Conclusion #

Parallel agentic coding made trivial with `agent-cli dev`

1. The “just use worktrees” problem #

2. Why parallel development matters for agentic coding #

3. One command to rule them all #

4. It knows your stack #

5. Terminal magic #

6. Spawning agents with prompts #

7. Teaching Claude to spawn agents #

8. My actual workflow #

9. Managing environments #

10. Getting started #

Conclusion #

Links #

SOTA RAG & Memory without the database: Files, Git, and simple folders

1. The amnesia problem #

2. Learning from failure: AI Journal #

3. How I studied SOTA: clone, read, re-implement #

4. The dependency problem: why ONNX over PyTorch #

5. RAG: just let me grep it (kind of) #

The architecture: OpenAI compatibility #

Two-stage retrieval: the SOTA approach #

6. Memory: files over databases #

7. My rule for the next `uv add` #

A) `uv tool install` — the persistent environment #

B) `uvx` — the ephemeral environment #

C) Regular virtualenv, `pipx`, or system install #