Software Development | 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. ↩︎

Why Docker isn't an AI-safe sandbox anymore, and how I fixed it in MindRoom 🔒

Sun, 18 Oct 2026 00:00:00 +0000

For years, a Docker container was my default answer to “where do I run this?” I never thought it was a perfect sandbox. It was good enough, because getting out of one usually meant finding a specific kind of bug in the Linux kernel itself, and those were hard to find.¹

AI models have become very good at finding security bugs, including in Linux. Anthropic and OpenAI now keep their strongest security models, Claude Mythos and Daybreak Blue, behind identity checks and vetting. Open-weight models, which anyone can download and run, come with no such rules, and they trail the closed ones by only six to seven months. Once there is an open model as good as Mythos, anyone can strip out its refusals with a tool like Heretic (people call this abliteration) and point it at the Linux kernel. The security company DepthFirst used its own model to find a way out of a container and titled the write-up Containers Are No Longer a Security Boundary.

I care about this because running untrusted code in containers is exactly what MindRoom, my open-source system for AI agents that live in Matrix chat rooms, does. Every agent can get its own Docker worker, and its shell, file, Python, and browser tools run there. It can install anything, start background processes, and drive a real browser. And as I wrote in my ZFS post, I run coding agents in YOLO mode, exclusively. I do not review the commands they run, I look at the results.

So both sides changed at once. The code inside the container is now written by an AI, and the bugs that let it out are now found by an AI. A video from the Low Level channel asking whether containers are still safe made me sit down and rethink my setup.

I am not an expert in any of this. I have used containers, KVM, and hypervisors for years, including Proxmox before I moved to NixOS, but I never deeply understood what happens underneath. Building this forced me to learn it, and writing this post is my exercise in understanding it all. All of this is very complicated (as is everything new), and I am still learning. I am sure I skip over a lot and simplify the rest; what is here are the parts that helped me understand it. I thought it would be nice to share.

Table of contents

What the kernel actually does #

When people talk about Linux, they usually mean an operating system like Ubuntu, Fedora, or NixOS. Those differ in almost everything you see: package managers, desktops, config files. What they all have in common is the kernel, the part Linus Torvalds started in 1991 and still leads today. Strictly speaking, that kernel is the only part called Linux.

The kernel is the one program on a Linux machine that talks to the hardware directly. Everything else, your shell, Python, Chrome, Docker, runs on top of it and has to ask it for things. Open this file. Give me some memory. Send this packet. Start a new process. Those requests are called system calls, or syscalls for short.

There is one kernel per machine, and it decides who is allowed to do what. That makes it the most trusted code on the system. Most kernel bugs only crash the machine or cause glitches. But some let a normal program become root, the admin account, or even run its own code inside the kernel. At that point it can do anything on the machine, including leaving any container it was in.

A container is a process in a costume #

When you docker run -it ubuntu, you get a root shell in what feels like a fresh computer. Under the hood it is one ordinary process. The kernel dresses it up using three features:

Namespaces decide what the process can see. It gets its own list of processes (where it is process number 1), its own filesystem, and its own network. Root inside is still root on the host, with most of its powers taken away.²
cgroups decide how much it can use: CPU, memory, number of processes.
seccomp decides which syscalls it may make at all. It is a filter that blocks the ones a normal program never needs.

There is no second kernel. Every syscall from inside a container lands in the same kernel as every other container and the host itself. The kernel enforces the isolation, and it is also what gets attacked.

For most uses that is fine. Usually you put fixed software in a container: a database, a web app, some self-hosted service. You know where that code comes from, you keep your kernel patched, and that is good enough.

An AI agent is different. It writes new code on the spot and runs it, and nobody knows in advance what that code will do.

Since root in a container is root on the host, anyone who can use Docker can start a container as root and mount any folder from the host into it. They can then read and change every file in that folder, including files their own account may not open. Docker’s own documentation says the docker group grants root-level privileges. I knew that in theory, but it only clicked when I watched an AI agent do it on a machine where I had no root, only Docker access. It needed to change files it was not allowed to touch, so it started a small container, mounted their folder, and edited them from inside. No kernel bug needed.

Why kernel bugs are a bigger problem now #

Kernel bugs that let a normal program take over the whole machine used to take skilled people weeks or months to find and exploit. The famous ones, like Dirty COW in 2016, made the news every year or two, you patched, and that was it.

AI is speeding this up, and the DepthFirst write-up I mentioned is a good example. Their model found a bug in the kernel code for Unix sockets, which programs on the same machine use to talk to each other. The kernel freed a piece of memory and then kept using it, a so-called use-after-free, and from inside a container that was enough to get out. Their conclusion is that you should assume attackers can escape containers at will.

Blocking more syscalls, or taking more powers away from root, helps a little. But it only narrows which parts of the shared kernel a container can reach. This bug sat in Unix sockets, which almost every program uses, including the browser the agent drives, so blocking them would break the agent.

Now put an AI agent in that container. It reads web pages and repositories written by strangers, and one of those could talk it into running an exploit. On a MindRoom server, getting out of a worker means getting onto the machine that runs MindRoom itself. That is where the API keys, Matrix logins, and stored credentials live, which the workers are built to never see.

So I asked a model to break out #

Before changing anything, I wanted to know how real this was for my own setup. I gave a MindRoom agent Daybreak Blue and asked it to escape its worker container using known kernel vulnerabilities. Daybreak Blue is OpenAI’s security model for verified users, so it does the offensive security work that other models refuse.

It did not get out, which was reassuring. But it only tried known bugs. A kernel a few weeks behind on patches, or a bug nobody has published yet, would be a different story. So the attempt tells me the easy path was closed that day, and not much more.

Stronger walls: virtual machines #

The classic answer is a virtual machine. A container shares the host’s kernel, but a VM brings its own, and this is where the hardware comes in. Modern CPUs have a virtualization mode built in, called VT-x on Intel and AMD-V on AMD. In that mode, a second kernel, the guest kernel, runs directly on the real CPU and believes it is in charge, while the CPU quietly limits it. When the guest tries something it may not do on its own, like talking to a disk or a network card, the CPU pauses the guest and hands control to the host. This is called a VM exit. Despite the name, nothing escapes and nothing crashes. The host handles the request, for example by pretending to be that disk, and then resumes the guest where it stopped. From the guest’s point of view, the instruction simply finished.

Memory is fenced off too. The host gives the CPU a separate map of which real memory each guest may use, and the CPU checks every memory access against it. So even a guest kernel with full privileges cannot touch the host’s memory.

The CPU only provides the mechanism. The software that sets the rules and handles the VM exits is called the hypervisor. “Hypervisor” is a role, not one program, and on Linux it is two pieces:

KVM, a module in the Linux kernel, uses the CPU’s virtualization mode to run the guest, keeps that memory map, and catches its VM exits. It shows up as the device /dev/kvm.
A VMM (virtual machine monitor), a normal program on top, sets up the VM and handles the exits that KVM passes up, for example by pretending to be the guest’s disk and network card. QEMU, Firecracker, and Cloud Hypervisor are three VMMs you can pick from.

Proxmox, which I mentioned above, is KVM plus QEMU. AWS Lambda is KVM plus Firecracker.

Code in a VM talks to its own guest kernel. To reach the host, it usually has to break that kernel first and then the hypervisor.³ That is still possible. Google Project Zero turned a bug in how KVM runs VMs inside VMs on AMD into a full escape in 2021. Google’s kvmCTF pays up to $250,000 for a new one. And this year, one researcher, Hyunwoo Kim, published three KVM escapes, one of them hidden in KVM since 2010.

The difference between a container and a VM is how much code an attacker can reach, and that gap is large. On x86 (the Intel and AMD chips in most PCs and servers), Linux has about 370 syscalls, and Docker’s default seccomp filter blocks a few dozen of them. Behind the rest sit the kernel’s filesystems, networking, memory management, and core code: about 3.8 million lines, even without counting drivers. Not all of that is reachable from a container, but a lot of it is. KVM on x86 is about 114,000 lines. On top of KVM comes the VMM, but only the few devices it fakes for the guest. Most QEMU escapes came from its many emulated devices, which is why Firecracker and Cloud Hypervisor keep that list short.

Google’s bug bounties point the same way. kernelCTF pays $71,337 for each new kernel exploit that turns a normal user into root, and Google’s public repository holds exploits for 93 different kernel bugs. kvmCTF pays more than three times as much, and the same repository holds one KVM exploit, which crashes the host instead of escaping it. kvmCTF started a year later, but the gap is still big. Most of those kernel exploits would not work as written from a default container, because they first use a feature Docker blocks. Still, they show how many exploitable bugs sit behind the syscalls.

Kata Containers and gVisor #

Regular VMs are heavy. They boot a full operating system and tend to use a lot of memory. A microVM is a stripped-down VM meant to run one workload and start quickly. That still leaves a practical problem. MindRoom, like most tools, speaks Docker: it hands Docker an image and some folders to mount, and gets a running container back. A VM does not take a Docker image. Switching to VMs would normally mean building disk images, booting them, and wiring up files and networking myself.

Docker does not start containers by itself, though. It takes care of images, networks, and volumes, and then hands the actual start to a small program called a runtime. The default runtime, runc, does what I described earlier: it starts a process on the host kernel with namespaces, cgroups, and seccomp. But you can tell Docker to use a different runtime.

Kata Containers is such a runtime, and it starts a microVM instead. It picks one of the VMMs above (my test used QEMU), boots a small guest kernel, and starts the container inside it.⁴ Docker, and MindRoom, still see an ordinary container.

gVisor, from Google, takes a different route, and it is not a VM. It is a reimplementation of the Linux kernel, written in Go, that runs as a normal program on the host. Go manages memory for the programmer, so the use-after-free mistake behind the DepthFirst escape is much harder to make in gVisor. The worker’s syscalls go to gVisor instead of the host kernel, and gVisor itself only makes a small, filtered set of host syscalls. That is the hardening idea taken all the way: gVisor answers the agent’s syscalls itself, so the filter on the host can be much stricter than Docker’s. It needs no /dev/kvm, so it also runs inside cloud VMs that cannot start VMs of their own.⁵ My test machine, an ARM server (with the kind of chip phones use) running NixOS, had no /dev/kvm, which is why I tried gVisor first. Its runtime is called runsc, and it plugs into Docker the same way.

The three options side by side.

Or as a table:

Isolation	What worker code talks to	Needs KVM	Usual escape route
Plain Docker (`runc`)	The host kernel, filtered by seccomp	No	A host kernel bug
gVisor (`runsc`)	gVisor’s own kernel, written in Go	No	A gVisor bug, then a host kernel bug through its small filtered surface
Kata Containers	Its own guest kernel in a microVM	Yes	A guest kernel bug, then a hypervisor bug

Each option also changes how much code on the host an escape can pick its bug from.

Lines of code on the host that deal with what the agent’s code asks for, counted with tokei, comments and blank lines included. For Docker, the core of Linux without drivers; for gVisor, its kernel and network stack without tests; for Kata, KVM alone, without the VMM and Kata’s other helpers. Not all of it is reachable. Hover for exact numbers.

The PR: six lines #

The change is PR #2886, which is now merged. It adds one setting, MINDROOM_DOCKER_WORKER_RUNTIME, and MindRoom passes its value to Docker as the runtime whenever it starts a worker. That is six lines of source code, plus 62 lines of tests and some docs. Changing the setting recreates each worker the next time it is used, and leaving it unset keeps everything as it was.

For gVisor, setting it up is two steps: register the runtime in Docker’s /etc/docker/daemon.json and restart Docker, then point MindRoom at it.

{
 "runtimes": {
 "runsc": { "path": "/usr/local/bin/runsc" }
 }
}

MINDROOM_DOCKER_WORKER_RUNTIME=runsc

Kata needs no entry in that file: once it is installed, MINDROOM_DOCKER_WORKER_RUNTIME=io.containerd.kata.v2 is enough. The full setup, and a few catches for each runtime, are in the MindRoom docs.

The six lines are short because everything else already existed. gVisor and Kata do the isolating. Docker already gives each worker its folders, its credentials, and its network, and it already knows how to hand a container to a different runtime. On the MindRoom side, the hard part happened months earlier, when agent tools moved out of the main process into dedicated workers with explicit mounts and credentials. Once every worker is a single call to Docker’s containers.run, swapping what runs underneath it is one argument. For comparison, Claude Opus estimated that building a microVM backend into MindRoom itself would take 2,500 to 4,000 lines.

What it costs #

I tested both runtimes with a real agent in a Matrix room: gVisor on that ARM server, and Kata in a throwaway VM on my desktop. Shell, Python, git, background processes, and the browser all worked, without any MindRoom code change. My Kata numbers below come from a VM inside a VM, so bare-metal numbers will differ.

Configuration is the cheap part: one environment variable, plus one entry in Docker’s config for gVisor. The other costs are the usual trade-offs between containers and VMs:

Computation. Code that only calculates, without asking the kernel for anything, runs at full speed with both. gVisor lets those instructions run directly on the CPU, according to its performance guide. A Kata guest runs on the CPU in its virtualization mode, and in AWS’s paper on Firecracker, the CPU overhead was negligible.
Syscalls, disk, and network. The cost starts when a program does ask the kernel for something. Under gVisor, every syscall takes a detour through gVisor’s kernel, so programs that make many small syscalls, like ones that open thousands of small files, slow down the most. Under Kata, disk and network go through the VMM’s fake devices. In that same paper from 2020, a Firecracker guest reached 15 Gbit/s of network traffic where the host reached 44.
Startup. gVisor only has to start a program, so it starts quickly. Kata has to boot a kernel first, and my worker took about 10 seconds to start instead of about 3. Booting a VM can be much faster than that: Firecracker boots a minimal one in about 125 ms.
Memory. gVisor adds a small, mostly fixed amount per sandbox. Each Kata VM runs a second kernel plus the VMM, which alone takes about 3 MB with Firecracker and 131 MB with QEMU. Kata gives each worker VM 2 GiB by default, and /tmp lives in that RAM. The host only hands out memory the guest actually touches, so my idle worker used under 0.8 GiB of host memory. Raising the VM size costs little until a worker needs it. But a VM cannot grow past its size the way a container can, and memory the guest has used, for example to keep recently read files in its cache, mostly stays with the VM.
Compatibility. gVisor reimplements Linux, and its docs say there will always be unimplemented features and bugs, so now and then a program will not work. Kata runs a real Linux kernel, so programs behave as usual, with a few catches. For example, a file lock held on the host does not block the worker, because the lock lives in the guest kernel.

What this does not fix #

A stronger sandbox protects the host. It does nothing about the tokens and network access you give the worker. An agent needs no kernel exploit to misuse a token that can push to your repositories, or to poke at every device on your home network. Scoped credentials and a firewall allowlist protect you at least as much, and MindRoom handles both separately: Agent Keys let agents use API keys without ever seeing them, and Approved Egress limits which servers a worker on Kubernetes can reach.

gVisor has had its own bugs, and it still talks to the host kernel, just through a much smaller door. KVM has bugs too, as this year’s escapes show. Both walls make an escape far harder, and neither makes it impossible.

Conclusion #

Once I started reading about this, I kept running into people saying containers were never a security boundary. That is true, and for years I did not worry about it. With AI finding kernel bugs faster and agents running code nobody reads, I do now.

No sandbox is perfectly safe, though. In a conversation with Dwarkesh Patel, Noam Brown doubted that even computers with no network connection at all would be enough to contain an AI. He pointed to studies where two such computers next to each other talk through heat: one runs its CPU hot, and the other picks up the change with its temperature sensor. Every option in this post trades some speed or memory for safety. How far to go depends on your own risk tolerance and how paranoid you are. MindRoom can now move its agents off the shared kernel with one environment variable. I do not use it myself yet, but if you are more paranoid than I am, it is there.

The other way out is a bug in the program that starts the container. In 2024, CVE-2024-21626 in runc, the program Docker uses for that, leaked a handle to a host folder into new containers, so a malicious image could reach the host’s files without any kernel bug. ↩︎
Docker can map the container’s root to an ordinary user on the host with user namespace remapping, or run without root altogether in rootless mode, but neither is the default. Rootless mode would have stopped the agent in my Docker story, because Docker then has only my own rights. Remapping would not, because anyone who can use Docker can turn it off for a single container. Neither helps against a kernel bug, because code running inside the kernel is above every user. ↩︎
A bug in the VMM’s fake devices, or in other VMM code that handles the guest’s traffic, can skip the first step, because a normal program in the guest can feed that code data through the network or a shared folder. CVE-2020-8608, a buffer overflow in QEMU’s user-mode networking, could be triggered that way with crafted network traffic. ↩︎
Like runc for Docker, Kata’s own programs on the host are a way out too. In 2020, one bug (CVE-2020-2023) let a container take over the guest without a kernel bug, and a second (CVE-2020-2026) then let the guest trick the Kata runtime on the host into mounting files over any host path. Neither needed a KVM bug. virtiofsd, the program that shares folders with the guest, also runs on the host and handles the guest’s file requests. ↩︎
gVisor can use KVM too, as an option. By default it catches the agent’s syscalls without it, which is the setup this post describes. With KVM switched on, gVisor runs the agent’s code in the CPU’s virtualization mode so catching syscalls is faster, but gVisor’s own kernel still answers them, and there is no guest Linux and no fake devices. gVisor recommends that mode only on bare metal; inside a VM the default is usually faster. ↩︎

Giving models the tools they were trained with can make them worse

Sun, 11 Oct 2026 00:00:00 +0000

A few nights ago, lying in bed, I had what felt like a galaxy-brain idea. I dictated it into my watch so I would still remember it in the morning.

Every frontier model learns to solve coding tasks with tools through reinforcement learning (RL), and I assume that training happens inside its vendor’s own coding agent: Anthropic’s models in Claude Code, and OpenAI’s models in Codex. That is a big assumption, since the labs do not publish their training environments, but it makes business sense: they sell those agents, so they have every reason to make their models work best in them. Every other harness, like pi, opencode, or my own MindRoom, gives the model a set of tools of its own design for running commands and editing files. The models are usually smart enough to figure those out, but not always. Sometimes a model assumes an edit tool works like the one it was trained with, and uses it wrong. This summer, that happened to Claude Opus 4.8 in pi, which I come back to below.

So the idea was simple: in MindRoom, give each model the same shell and file-editing tools as its native harness, and switch them automatically depending on which model is answering. Claude would see Claude Code’s Bash, Read, Edit, and Write. GPT would see Codex’s exec_command and apply_patch. And because the smallest agents do surprisingly well, I would go one step further: a minimal agent whose only tool is the shell each model knows from its training.

I was beyond excited. I could not really share that excitement locally, because my wife did not care, so I am sharing it with the internet instead.

Then I measured it against MindRoom’s own tools, and the familiar ones did not make the models more efficient. With only Codex’s tools, GPT-6 Astra did 84% more work, taking more steps and reading and writing more along the way, and used 59% more tokens. With Claude Code’s tools, Claude Sonnet 5.5 did 15% more work, and Claude only came out a few tokens cheaper because the descriptions I wrote for those tools are slightly shorter than MindRoom’s. Only one model clearly worked more efficiently with its own tools: Claude Opus 4.8, the model from the pi story. The models seem to generalize beyond the environment they were trained in, and what still matters is how much the agent sends with every request.

What I found

Compared with MindRoom’s own tools, the familiar ones did not make the models more efficient: with only Codex’s tools, GPT-6 Astra and Sol did 60 to 84% more work and used 43 to 59% more tokens.
With Claude Code’s tools, Claude Sonnet 5.5 did 15% more work and Opus 5.5 about the same; they only came out a few tokens cheaper because the descriptions I wrote for those tools are shorter than MindRoom’s.
Only Claude Opus 4.8, the model whose edits kept failing in pi, clearly worked more efficiently with its own tools.
What matters is how much the agent sends with every request: a minimal agent with one shell tool and a 12-line prompt used 58 to 76% fewer tokens than the same agent in standard mode on these short tasks.
Giving that minimal agent each model’s own shell tool did not make it better.

Table of contents

What a harness is #

“Harness” gets thrown around a lot, but there is no magic in it. Every coding agent talks to the model the same way: each request contains a system prompt, the definition of every tool the model may call, and the conversation so far. When the model answers with a tool call, the harness runs the tool, adds the result to the conversation, and sends everything again.

What a coding agent sends with every step. The light parts are the same every time; only the conversation grows.

So from the model’s side, a harness is three things: its system prompt, its tool definitions, and what comes back when a tool runs. The first two are just text, so they are easy to copy, and the tool definitions are effectively the harness’s API: change them, and the model sees a different harness. The third is code, which takes more work to copy.

Because every request resends everything, a task’s tokens come in two parts. The fixed part is what the agent sends before anything happens: its system prompt, its tool definitions, and the task, which every request resends. The work is everything the steps add on top: the model’s replies, the tool results, and the growing conversation that every later request resends too. When I say below that a model did more work, I mean that second part.

Why I believed it #

Two things convinced me: how well the smallest agents do, and what goes wrong when a model meets unfamiliar tools.

Smaller agents do better #

Pi made its name by being small. When Mario Zechner introduced pi last November, its system prompt and tool definitions together came in below 1,000 tokens, and it had four tools: read, write, edit, and bash. He also wrote that “pi does not and will not support MCP”, the Model Context Protocol through which most agents load outside tools. And he pointed to Terminus 2, a minimal agent from the Terminal-Bench team, which was “holding its own against agents with far more sophisticated tooling”.

In August, DeepSeek released DeepSeek Harness, which was all over Hacker News and the local AI subreddits I read. Its standard setup comes with a full set of tools. But for benchmarks, DeepSeek points to its minimal profile. In early September, that profile had exactly one tool, a persistent bash, and a one-line system prompt: “You are a helpful software engineer assistant.” (Ten days later, it already had a second tool, working_directory; staying that small seems to be hard.) That is what inspired the minimal mode I added to MindRoom in September, which gives an agent a short prompt and a single bash tool.

Models should know their own tools best #

The case that got me thinking about this was Claude Opus 4.8 in pi. In July, a pi user reported that about 20% of its edits failed in some sessions. Pi’s edit tool takes a list of replacements, and Opus 4.8 kept adding made-up fields to them, like in_file, matchCase, or newText2. Claude Sonnet 5 did it too, while Opus 4.7 and older Claude models never did in the same tests.

Armin Ronacher, one of pi’s maintainers, dug into it and compared it with what Claude Code does with the tool calls it receives. It turns out that Claude Code quietly repairs a lot of them:

It accepts several names for the same argument, like old_str and old_string.
It parses an argument that arrives as a string when it should be an object.
It fixes broken \uXXXX escapes in strings.
It drops fields it does not know.
When it cannot parse a call at all, it asks the model to try again.

His hypothesis is that RL itself might be the cause. If a model is trained in a harness that absorbs these mistakes, a slightly wrong tool call still completes the task and still gets rewarded, so nothing teaches the model not to make it. Pi now ignores unknown fields too, just like Claude Code.¹

Then pi itself strayed from its minimal roots. Pi 1.0 came out on October 1 and added MCP after all. The Register called it a 180. On Hacker News and r/LocalLLaMA, people worried that “Pi’s days as a nice minimal agent TUI are numbered”. What struck me was how the maintainers explained it. Armin Ronacher wrote that the models “are trained on their respective harnesses and we’re not here to fight their behavior”, and Mario Zechner that “we follow what the models are trained on”. That is exactly the native-tools half of my plan.

My plan combined both: a minimal agent, with each model’s native shell as its only tool. Terminal-Bench also said something I chose to ignore: agents like Terminus 2 do well with tools no model was trained on. I did not believe that part. In opencode and pi, I had repeatedly seen models get the edit tool wrong, so I assumed the benchmarks did not carry over to real work. My belief that a model works best in the harness it was trained in was that strong: I expected the native tools to help, and to help most in a minimal agent with nothing but a shell.

What I built #

MindRoom is my open-source platform for AI agents that live in Matrix chat rooms, where several agents can work together. Its agents get shell and file tools under MindRoom’s own names, like run_shell_command, read_file, and edit_file. In this pull request, I added what I call tool dialects, which show a model those tools in the shape of the coding agent it was trained in.

Model	Sees	Instead of
Claude	`Bash`, `BashOutput`, `KillShell`, `Read`, `Edit`, and `Write`, as in Claude Code	`run_shell_command`, `check_shell_command`, `kill_shell_command`, `read_file`, `edit_file`, and `write_file`
GPT	`exec_command`, `write_stdin`, and a freeform `apply_patch` that takes the patch as plain text, as in Codex, and a `kill_shell_command` that takes Codex’s `session_id`	`run_shell_command`, `check_shell_command`, `kill_shell_command`, `edit_file`, and `write_file`

Inside MindRoom, nothing changes: approvals, hooks, and the stored history keep MindRoom’s names, and the translation only happens on the way to and from the model. That gives MindRoom a property I like a lot: a conversation can switch from Claude to GPT halfway through, and each model sees the earlier tool calls in its own shape, as if it had made them in its own harness.

Matching the native harness exactly turned out to be a stretch, though. Codex has no tool for reading files, so in the pull request, GPT keeps MindRoom’s read_file, and both keep MindRoom’s grep, find_files, and ls, which makes each native set a mix. For the main comparison, I removed those extra tools, so each model saw only the tools of its own harness. The tools have the same names and arguments as in Claude Code and Codex, but I wrote short descriptions of my own, because Claude Code’s are not openly licensed. What they return is MindRoom’s output, and the system prompt is MindRoom’s too. So keep in mind for everything below: I tested the names and shapes of the tools, not the whole harness.

How the translation works

Codex’s apply_patch is freeform: the model writes the patch as plain text instead of JSON arguments. I ported Codex’s patch parser and the code that applies patches, together with Codex’s own test cases, so a patch from a Codex-trained model applies exactly as it would in Codex. Its description comes from Codex too, which is openly licensed.
A switched model sees earlier calls in its own shape only for the tools its own harness also has, like the shell: an edit made with Claude Code’s Edit stays an edit_file call for GPT, which has no matching tool.
An earlier version of the pull request also rewrote every tool result to look like the native one. That was a lot of fragile code, so I removed it before I measured anything.

How I measured it #

I used 12 terminal tasks from an evaluation suite I built for MindRoom, like writing a report from a CSV file, finding the commit that broke a check, or fixing failing tests.² A hidden check graded each result, and every setup ran every task three times. Almost every run passed, so the interesting number is how many tokens the agent needed to get there, cached input included, and cheaper in what follows means fewer tokens.³ The tool comparisons ran through MindRoom’s OpenAI-compatible API; minimal mode, which only works in chat, ran through Matrix. I tested five current models, Claude Opus 5.5 and Sonnet 5.5, and GPT-6 Astra, GPT-6.1 Sol, and GPT-6 Luna, and later five older ones. The current Claude models ran with adaptive thinking, where the model decides when to think. I called the GPT models from MindRoom through OpenAI’s Codex backend, the endpoint the Codex CLI uses, so no run used Codex itself; with no reasoning effort set, the backend picks one.

Details of the setup

A small harness sent each task to MindRoom’s OpenAI-compatible API as a new conversation, and a hidden check graded the result in a separate container without network access. Every task ran three times per configuration, so each number in this post comes from 36 runs.
The agent’s commands ran in a Docker container, the way MindRoom runs agents it does not fully trust.
With adaptive thinking, the current Claude models thought before 15 to 25% of their replies, with MindRoom’s tools and with the native ones.
I ran the GPT models through OpenAI’s Codex backend, the endpoint the Codex CLI uses, and sent no reasoning effort, so the backend picked one. The GPT-6 models barely reasoned on these tasks: in those runs, only 4 to 12% of their requests had any reasoning tokens, and then 7 to 234 of them.

Native tools don’t make today’s models more efficient #

To make the comparison fair, I gave each model only the tools of its own harness, against MindRoom’s matching set.⁴ For Claude, that is a shell and tools to read, edit, and write files; for GPT, a shell and Codex’s apply_patch, against MindRoom’s tools to edit and write files.

Change in tokens per task when each model uses its native harness tools instead of MindRoom’s, with 95% confidence intervals: with only the harness’s own tools against MindRoom’s matching set, and with the mixed set in the pull request. Hover for values.

Claude got 6 to 13% cheaper with Claude Code’s tools, but only because the definitions I wrote for them are about 480 tokens shorter than MindRoom’s, and every request resends them; the tools themselves saved nothing, and Sonnet 5.5 even did 15% more work with them. It never even touched the file tools: Opus 5.5 and Sonnet 5.5 did everything in the shell, with either set.

GPT-6 Astra and Sol got much more expensive, while Luna barely changed. With only Codex’s tools, GPT-6 Astra did 84% more work and used 59% more tokens. It called apply_patch 30 times, as a separate step for edits it otherwise made inside its shell commands, and every extra step resends the whole conversation so far. I expected the opposite: these are the tools I assumed these models were trained on, so I thought they would need fewer and more confident steps. The mixed set, the lighter rows, points the same way.

The tool mistakes I wanted to prevent did not happen with MindRoom’s tools at all: with its matching set, none of the five models made a single tool error. The only errors came from the mixed set: next to Codex’s tools, Luna had to guess how MindRoom’s read_file resolves paths, and got it wrong seven times.

The numbers behind this section

Fixed part and work. Every request to a model sends the whole conversation so far, plus the definition of every tool the model can use. So I split each task’s tokens in two. The fixed part is the first request’s input, which holds the system prompt, the tool definitions, and the task, times the number of requests. The work is everything else: tool results and the model’s replies, counted again with every later request that resends them, so it also grows with the number of steps. Providers cache most of the fixed part between requests and charge much less for cached input, so it costs less than its share of the tokens suggests.

Only the harness’s own tools. With Claude Code’s tools, Opus 5.5 used 13% fewer tokens [95% CI −19 to −6%] and Sonnet 5.5 6% fewer [−10 to −1%]. Both came from the definitions: the Claude Code-style set I wrote is about 480 tokens shorter, while the work on top of it grew by 7% [−7 to +23%] and 15% [+7 to +25%]. With Codex’s tools, GPT-6 Astra used 59% more tokens [+53 to +65%] and GPT-6.1 Sol 43% more [+33 to +52%]. They called apply_patch 30 and 22 times, where with MindRoom’s tools they made only 3 and 6 calls to the file tools, so they needed 4.7 and 4.4 requests per task instead of 3.5 and 3.6 and did 84% [+73 to +96%] and 60% [+44 to +76%] more work. GPT-6 Luna used about the same with either set, +3% [−8 to +15%], and called apply_patch only 8 times. The pass rates stayed within one or two runs of each other, and no model made a tool error with either set.

The mixed set, as it is in the pull request.

Change in tokens per task when each model uses its native harness tools instead of MindRoom’s, with 95% confidence intervals. The second row caps the native shell output at the last 100 lines, MindRoom’s shell default. Hover for values.

With Claude Code’s tools, both Claude models used about 9% fewer tokens. With Codex’s tools, GPT-6 Astra used 31% more tokens and GPT-6.1 Sol 19% more. An earlier run of the same experiment, before some unrelated fixes in the pull request, gave almost the same numbers: 33% more for Astra and 15% more for Sol. For GPT-6 Luna, the difference was too small to tell apart from noise. The pass rates barely moved: Opus, Sonnet, and Sol passed all 36 runs with either set of tools, and Astra failed one run in some configurations. Luna passed 33 runs with MindRoom’s tools and 35 with Codex’s; in the earlier run it was the other way around, 35 against 32, so I would not read anything into it either.

It is not the longer output. MindRoom’s own shell tool returns the last 100 lines of a command’s output by default. For the native tools, I returned everything up to 50 KiB, because that is closer to what Claude Code and Codex do. So I ran everything again with the native tools capped at the same 100 lines, the second row in the chart above. The cap barely changes anything: Astra still uses 26% more tokens, Sol 15% more, and the Claude models still save about 8%. The models hardly ever print more than 100 lines anyway: in the uncapped run, 3 of Astra’s 91 shell results and 3 of Sol’s 93 were longer than that, and none of Claude’s 220.

Where the tokens went with the mixed set.

Tokens per task with MindRoom’s shell and file tools and with the native ones, split into the fixed part (light) and the work the model did on top of it (dark). Hover for the number of requests.

Claude did not work any differently with Claude Code’s tools. It never called a file tool with either set, did everything in the shell, and made about the same number of requests. Its work changed by 5% or less, and almost all of its savings come from the fixed part: the Claude Code-style definitions I wrote are about 480 tokens shorter than MindRoom’s.

GPT did work differently. With Codex’s tools, Astra and Sol edited files with apply_patch 17 and 15 times, where with MindRoom’s tools they made only 3 and 5 calls to the file tools and did the rest from the shell. Each patch is a request of its own, which accounts for their 0.3 to 0.5 extra requests per task. They also did 51% and 24% more work. And Codex’s tools take about 130 more tokens to describe than MindRoom’s, because apply_patch costs about 270 more than edit_file and write_file together, so the fixed part grew as well.

The mistakes. None of the five models made a single tool error with MindRoom’s tools in its 36 runs. Partly, the models rarely needed the file tools: the Claude models never called one, and of the GPT models, only Luna used them often. The only model that made tool errors was Luna, and only with the Codex tools: 7 errors in 36 runs, all of them read_file calls with a path relative to the directory Luna had just given exec_command. The made-up fields in pi always appeared inside its nested list of replacements, where the model has to write the JSON for each replacement itself. MindRoom’s edit_file is flat, like Claude Code’s Edit: a path, the old text, and the new text. So I suspected that keeping the tools as simple as the native ones matters more than matching their exact names.

Older models: only Opus 4.8 did better with them #

The pi story made me wonder whether this used to be different, since Opus 4.8 struggled with pi’s edit tool while Opus 4.7 did not. So I ran the same comparisons on older models that are still available: Claude Opus 4.7, Opus 4.8, and Sonnet 5, and GPT-5.5 and GPT-5.6 Sol.

Change in tokens per task when the older models use their native harness tools instead of MindRoom’s, with 95% confidence intervals: with only the harness’s own tools against MindRoom’s matching set, and with the mixed set in the pull request. Opus 4.7 and 4.8 ran without thinking, Sonnet 5 with adaptive thinking, and GPT with the effort Codex picks. Hover for values.

With only each harness’s own tools, the older models did not prefer their native tools either, except for one. The exception is the model from the pi story: Opus 4.8 did 17% less work and used 19% fewer tokens with Claude Code’s tools, reading files through Bash instead of with a separate tool. With the mixed set, the older Claude models seemed to prefer Claude Code’s tools, using 22 to 36% fewer tokens, but that came from the extra tools the mixed set keeps from MindRoom, grep, find_files, and ls: next to MindRoom’s other tools, those made the older Claude models take more steps and read more, and next to Claude Code’s tools, the models hardly touched them. And on the pi story itself: Opus 4.8 and Sonnet 5, the two models that made up fields in pi, made 111 edits with MindRoom’s edit_file, which takes a single path, old text, and new text, and none of them failed.

With only each harness’s own tools, the GPT-5 models did about the same with either set, and unlike GPT-6 Astra and Sol, they barely used apply_patch. So reaching for its native editing tool, and paying for it, is new in that generation.

Of the ten models I tested, familiar tools clearly made only one more efficient, the one that started it. The others did as well or better with tools they were presumably not trained on: they seem to generalize beyond the environment they were trained in.

The numbers behind this section

Only the harness’s own tools. With Claude Code’s tools, Opus 4.7 used 3% fewer tokens [−12 to +6%], Opus 4.8 19% fewer [−26 to −11%], and Sonnet 5 7% fewer [−29 to +23%], a noisy result. Opus 4.8 did 17% less work [−29 to −4%] on top of the shorter definitions, while the other older models’ work changed by −5 to +13%, none of it clearly; Opus 4.8 called MindRoom’s read_file 27 times, but never Claude Code’s Read. With Codex’s tools, GPT-5.5 used 5% more [−5 to +16%] and GPT-5.6 Sol 3% more [−4 to +11%]; they called apply_patch only 3 and 9 times, where with MindRoom’s tools they made 20 and 16 calls to the file tools. The pass rates stayed within one or two runs of each other. None of the older models made a tool error with MindRoom’s matching set; with Codex’s, GPT-5.5 sent garbled working directories to exec_command 11 times.

Why the mixed set made them look different. The only difference between the two tests is that the mixed set adds MindRoom’s grep, find_files, and ls to both sides. Next to MindRoom’s other tools, the older Claude models called ls and grep 20, 9, and 3 times, took 0.3 to 0.9 more requests per task, and did 35 to 38% more work than without them. Next to Claude Code’s tools, they called them once in total.

The older models with the mixed set.

Change in tokens per task when each model uses its native harness tools instead of MindRoom’s, with 95% confidence intervals, oldest models first in each family. Each model’s reasoning mode is in parentheses: Opus 4.7 and 4.8 do not think, the other Claude models think adaptively, and GPT uses the effort Codex picks. Hover for values.

Opus 4.7, Opus 4.8, and Sonnet 5 used 22 to 36% fewer tokens with Claude Code’s tools. Unlike the 5.5 models, they also made fewer requests and did 26 to 45% less work on top of the fixed part. GPT-5.6 Sol used 15% fewer tokens with Codex’s tools and did 27% less work, and GPT-5.5 used about the same. One generation later, the GPT-6 models use up to 31% more with Codex’s tools, and the Claude 5.5 models mostly save what the shorter definitions save. The pass rates stayed within one or two runs of each other for every model.

How they used the file tools. With MindRoom’s tools, the older Claude models called read_file 24, 29, and 44 times; with Claude Code’s, they called Read only 3, 1, and 6 times and read files through Bash instead. GPT-5.6 Sol needed 9 patches where it had made 32 calls to edit_file and write_file. Opus 4.8 and Sonnet 5 made 37 and 21 calls to MindRoom’s flat edit_file, and none of them failed. That does not prove that pi’s nested list caused pi’s failures, because I never gave them a nested edit tool, but a flat one did not trigger them. Their few tool errors were different ones: Sonnet 5 twice polled a background command that did not exist, GPT-5.5 and GPT-5.6 Sol each had one edit whose old text did not match, and GPT-5.5 sent garbled working directories to Codex’s exec_command seven times.

Only the shell tools.

Change in tokens per task when the older models use their native harness tools instead of MindRoom’s, with 95% confidence intervals: with shell and file tools, and with only the shell tools. Opus 4.7 and 4.8 ran without thinking, Sonnet 5 with adaptive thinking, and GPT with the effort Codex picks. Hover for values.

The native set mixes a model’s own tools with some of MindRoom’s, such as grep, ls, and, for GPT, read_file, so I also ran the older models with only the shell tools, in MindRoom’s shape and in the native one. Opus 4.7 then used 10% fewer tokens with the native shell, GPT-5.6 Sol 6% fewer, and GPT-5.5 the same, and almost all of that came from shorter definitions. Opus 4.8 used 23% fewer tokens, made fewer requests, and did 16% less work. Sonnet 5’s result is too noisy to read: in one run, the native shell returned a 50 KB output early on, and resending it with every later request made that run cost 12 times the median; its median run used 9% fewer tokens with the native shell.

The reasoning settings. Opus 4.7 and 4.8 do not think unless you ask them to, and Sonnet 5 thought before 42% of its replies, against 15 to 25% for the 5.5 models at the same adaptive setting. The GPT-5 models reasoned before 59 to 76% of their requests, while the GPT-6 models reasoned before only 4 to 12%. With adaptive thinking and the mixed set, Opus 4.7 and 4.8 thought before 26 to 36% of their replies, and still used 35% and 20% fewer tokens with Claude Code’s tools. For that test, I set thinking to adaptive in the model’s extra_kwargs, since these models reject a fixed thinking budget.

I also ran one current model of each family, Claude Sonnet 5.5 and GPT-6 Astra, at low and at high reasoning effort. For Astra, I set reasoning_effort to low or high; for Sonnet 5.5, output_config.effort, which is how the Claude 5.5 models take a reasoning effort.

Change in tokens per task when Claude Sonnet 5.5 and GPT-6 Astra use their native harness tools instead of MindRoom’s, at each reasoning effort, with 95% confidence intervals. With no effort set, Sonnet uses adaptive thinking, and Astra the effort Codex picks. Hover for the tokens per task.

Both models passed all 36 runs at every effort with either set of tools, except for one run that Astra failed with MindRoom’s tools at its default effort. A higher effort made Codex’s tools worse for GPT. At high effort, Astra made 4.5 requests per task with Codex’s tools against 3.6 with MindRoom’s, and used 45% more tokens. Even at high effort, though, Astra reasoned before only 10 to 12% of its requests, against 4 to 7% at its default, far below the GPT-5 models. For Claude, the native tools stayed cheaper at every level, and saved the most at low effort, 19%, where Sonnet thought before only 3 to 4% of its replies. Sonnet thought about as often at its default as at high effort, so I would not read much into the difference between those two.

What does matter: what the agent sends #

My next guess was the other half of my plan, a smaller agent. Every request to the model resends the system prompt and the definition of every tool, so an agent with a shorter prompt and fewer tools sends less with every step.

Fewer tools #

Fewer tools did help. With only MindRoom’s shell tools and none of its file tools, the agent used about a third fewer tokens and passed about as many runs. A shell-only agent is also where I still expected the native tools to matter most, because every step goes through the one tool whose shape the model knows best. They did not: GPT used the same number of tokens with Codex’s shell tools, and Claude saved only what its shorter descriptions save.

The numbers behind this section

Change in tokens per task, with 95% confidence intervals: with only MindRoom’s shell tools instead of all of MindRoom’s tools, and with only the native shell tools instead of MindRoom’s. Hover for values.

With only MindRoom’s three shell tools, for running, checking, and stopping a command, and none of its file tools, the agent used 27 to 41% fewer tokens. It passed about as many runs: Luna passed 31 instead of 33, too small a difference to tell apart, and the other four models passed all 36.

For the native shape, I gave Claude only Claude Code’s Bash, BashOutput, and KillShell, and GPT only Codex’s exec_command and write_stdin, with MindRoom’s kill_shell_command in Codex’s style. For GPT, the total did not move: Astra, Sol, and Luna used the same number of tokens, within 2%, and made the same number of requests. Codex’s shell tools alone take about 130 fewer tokens to describe than MindRoom’s, and GPT spent about as much on extra work. Claude Sonnet 5.5 used 18% fewer tokens and Claude Opus 5.5 6% fewer, mostly because the Claude Code-style shell tools are shorter to describe than MindRoom’s.

Minimal mode: one shell tool and a 12-line prompt #

MindRoom’s minimal mode, modeled on DeepSeek’s minimal profile, takes this all the way. The agent gets a 12-line prompt and a single bash tool instead of its normal prompt and tools. Its instructions, skills, context files, and memory move behind a command-line program inside that shell, which it can call when it needs them. Minimal mode only works in chat, so I ran this comparison in Matrix conversations, against the same agent in standard mode with only its shell tools. A chat adds context about the room to every request, but even so, the minimal agent used 21 to 52% fewer tokens than the shell-only agent through MindRoom’s API.

The difference starts before the model does anything. For Claude Sonnet 5.5, the prompt and tool definitions sent with every request shrink from 4,285 tokens to 661.⁵

What every request carries besides the conversation: the system prompt and the tool definitions, in standard and in minimal mode, from each provider’s own token counts. Hover for values.

Tokens per task in Matrix conversations: the same agent with only MindRoom’s shell tools, in standard mode and in minimal mode with its single bash tool, split into the fixed part (light) and the work the model did on top of it (dark). Hover for values.

Each bar splits a task’s tokens into the fixed part, the prompt and tool definitions resent with every request, and the work the model did on top of it. The minimal agent used 58 to 76% fewer tokens than the same agent in standard mode with only its shell tools, for every model. Most of that is input the provider had cached and bills at a fraction of the price, so the bill shrinks less than the token count does: counting only uncached input and output, the minimal agent used 16 to 42% fewer tokens. And the model did not pay for it with extra work: the dark part of the bars stayed about the same or shrank, except for Luna’s. I had also hoped that the smaller agent would need less to do the task itself, but only GPT-6 Astra and Sol did, with slightly fewer steps and about a quarter less output; Claude worked exactly the same in both modes.

These tasks are short, three or four requests each, which is why the prompt weighs so much. I tried to make them harder so they would take more steps, but the models were so good that they only took about 50% more requests, and for the two models I tried, Claude Sonnet 5.5 and GPT-6 Astra, the pattern stayed the same: Sonnet did the same work in both modes, and Astra less in minimal mode. For the models that save steps, I see no reason why longer tasks would erase that gain: every step saved also saves resending the conversation, so on long tasks it counts for more. In a long session, the growing conversation dominates and the prompt’s share of the tokens shrinks, but its saving per request stays: about 3,600 tokens for Claude and 2,200 for GPT. And a real agent’s prompt carries far more instructions, skills, and memory than this test agent’s, so it saves more per request, although fetching them through the shell when needed costs requests of its own.

The numbers behind this section

Why Matrix. Minimal mode only works in chat conversations, so I ran it through Matrix, next to the same agent with only its shell tools in standard mode. Each run got a fresh chat room with only the agent, named coder, and MindRoom’s router, which handles commands like !mode; for minimal mode, I switched the room over with !mode coder minimal before sending the task. In a Matrix conversation, the agent also gets context about the room and the conversation, so it uses more tokens than through the API: on the same code, with only the shell tools, Claude Opus 5.5 used 22,192 tokens per task in Matrix against 12,904 through the API. That is why I compare minimal mode with standard mode in Matrix.

The prompt. In standard mode, the system prompt is 2,295 tokens for Claude Sonnet 5.5 and 1,463 for GPT-6 Astra, and the tool definitions, the shell tools and one for inviting MindRoom’s router, add another 1,990 and 867. In minimal mode, the system prompt is 152 and 97 tokens, and the single bash tool adds 509 and 72. This test agent’s standard prompt is about 100 lines only because its own configuration is one role line and one instruction; a real agent’s prompt also carries its instructions, skills, context files, and memory, and can run to hundreds of lines, while its minimal prompt stays at 12. The model receives all of that, plus the task and the room’s context, again with every request, so it adds up: in standard mode, about 80% of all tokens were this fixed part.

The result. Its first request dropped from about 4,600 to 1,000 input tokens for Claude, and from about 2,600 to 410 for GPT. Counting only the uncached input and the output, the minimal agent used 16 to 42% fewer tokens. Even with the extra context of a Matrix conversation, it used fewer tokens than the agent with only MindRoom’s shell tools through the API on the same code: 21 to 52% fewer.

Is that a fair comparison? A shorter prompt saves tokens even if the model then has to work harder, so the real question is whether it had to. Mostly, it did not: the work stayed the same for both Claude models (1% and 3% less), and went down for Astra and Sol (38% and 13% less), which also needed fewer requests, about 3.0 per task instead of 3.3 to 3.4. Luna is the exception: it made more requests and did 40% more work in minimal mode, but the shorter prompt still more than paid for that. Counted per task without the resent conversation, the Claude models wrote and added to the conversation the same in both modes, Astra and Sol wrote about a quarter less and needed 0.2 to 0.4 fewer requests, and Luna added 33% more, mostly longer command output. Three of the five models failed one more run in minimal mode, mostly on the same script-writing task that other configurations also miss now and then. That is too small to tell apart here, but I will keep an eye on it with harder tasks.

Minimal mode with each model’s native shell tool #

That leaves the combination I had in mind from the start: the minimal agent, with each model’s native shell tool as its only tool. I patched minimal mode so that its single tool appears as Claude Code’s Bash for Claude and as Codex’s exec_command for GPT, with the same 12-line prompt.⁶

Change in tokens per task in minimal mode when its single tool is the model’s native shell tool, Claude Code’s Bash or Codex’s exec_command, instead of MindRoom’s bash, with 95% confidence intervals. The second row cuts the native tool’s output to the last 100 lines, MindRoom’s bash default. Hover for values.

It did not make the minimal agent better for any model. For Claude, it made little difference: Sonnet used about the same, and Opus a little more. For GPT, it was clearly worse, mostly because exec_command hands back a command’s whole output, and in an agent that sends so little else, a few long outputs weigh a lot. With its output cut to 100 lines, bash’s default and the light rows in the chart, only Sol still clearly used more; Astra’s and Luna’s smaller increases could be chance.

So the whole effect of the combination came from its minimal half: models that were trained with a carefully designed set of tools did best with one tool and almost no prompt, and the tool’s native shape did not make it better.

The numbers behind this section

The single native tool only runs commands, but no current model ever polled or stopped a command in any of these runs, so it lacked nothing they used. I ran it next to minimal mode with MindRoom’s own bash on the same code, and once more with the native tool’s output cut to the last 100 lines. That is bash’s default, which the GPT models set themselves on every call, more often lower than higher; in the end, the capped native tool and bash returned about as much, except for Astra, whose bash results were twice as long.

For Claude, Sonnet used 4% fewer tokens with the native tool and Opus 7% more. For GPT, it was 34 to 46% more tokens, mostly because exec_command returns a command’s whole output, so the models read 39 to 50 lines per result instead of 20 to 36. Cut to 100 lines, the native tool cost GPT 5 to 15% more, but only Sol’s increase is clearly more than chance; part of it is the definition, which takes about 90 more tokens than bash on every request. In minimal mode, the agent sends so little else that a few long outputs weigh much more than through the API: the cap cut Astra’s tokens by about 20% here, against 4% there. Claude rarely printed more than 100 lines, so I would not read anything into the gap between its two native rows. The pass rates differed by at most a few runs, too few to tell apart.

What this does and does not show #

I tested the names and arguments of the tools, not whole harnesses. Claude Code and Codex also have their own tool descriptions, system prompts, and output formats, Codex has an interactive terminal, and RL trains all of that together. The full harness might still help today’s models; matching only the tools did not.
The tasks are easy and short: 97% of all runs passed, with three to seven requests per task on average. Harder, longer tasks might separate the tool sets on success, not only on cost.
With 36 runs per configuration, a 15 to 30% difference in tokens is clear, but a difference of one or two passed runs is not.
I tune MindRoom’s agent setup on other tasks from the same 12 families, and a note on working habits from that tuning sits in the shell tool’s description. Both tool sets carry the same note, so it should not favor either.
The confidence intervals cover run-to-run variation on these 12 tasks, not the choice of tasks. Resampling the tasks as well widens them: GPT-6 Astra’s +59%, for example, becomes +38 to +81%, and Sonnet 5.5’s 6% saving becomes indistinguishable from none. Astra and Sol still used more tokens with Codex’s tools on every one of the 12 tasks, and the minimal agent used fewer on every task, for every model.
Most runs used each model’s standard reasoning mode, which differs between generations: adaptive thinking for Sonnet 5 and the 5.5 models, none for Opus 4.7 and 4.8, and the effort Codex picks for GPT. I tried other settings on four models: two current ones at low and high effort, and Opus 4.7 and 4.8 with adaptive thinking. The pattern held at every effort: Astra used 27 to 45% more tokens with Codex’s tools, and Sonnet 5.5 stayed slightly cheaper with Claude Code’s.

What happens to the pull request #

The pull request is still unmerged, and given these results, I am not sure I will merge it at all. For today’s models, the native tools either cost more, as Codex’s did for GPT-6 Astra and Sol, or, as Claude Code’s did for Claude, only saved the few tokens of the shorter descriptions I wrote for them, which MindRoom’s own tools could get too. The one model that clearly did better with its own tools, Claude Opus 4.8, is a generation behind. What I will do is use minimal mode a lot more, with MindRoom’s own bash.

Why this excites me #

Half of my plan was wrong, and I am happy about that. The minimal-harness, DeepSeek-style half held up; the native-tools half did not. The benchmarks I did not believe were right, at least for these models. It suggests that these models generalize much better than I gave them credit for. They were trained with one specific set of tools, and on these tasks they did just as well with tools they had presumably never seen in training, as long as those tools were simple, like an edit tool that takes one path, the old text, and the new text. Only Opus 4.8, the model that started all this, still did better with its native tools. What matters more than familiarity is how much the agent sends with every request: the prompt and the definition of every tool.

It also changes how I think about who gets to build the best agents. If models only worked well in the harness they were trained in, the labs would own the best agents by default. Instead, at least the skill of using unfamiliar tools seems to carry over to other harnesses. I suspect the same holds one level up, for how several agents work together. The labs presumably train their models in their own harness, but if what the models learn transfers this well, a harness built outside the labs, like MindRoom, could get just as good at letting agents collaborate. That is still a hunch, and testing it is what I want to do next.

Appendix: how I measured, and the numbers behind the charts #

All scripts, the tasks, and one row per trial, with its reasoning setting, are on GitHub next to this post’s source.

Show the setup and every configuration

Setup

Each configuration ran as a separate MindRoom instance with one agent and a fresh Docker container for its commands. The model, the tools, and everything else were fixed in that instance’s configuration.
The tool comparisons ran through MindRoom’s OpenAI-compatible API on the pull request at commit d73aafb51: the matching sets, the mixed sets with whole and with 100-line output, and both shell-only setups. The capped run changed only the output limit of the native shell tools.
The minimal-mode runs and their standard-mode comparison ran through Matrix on MindRoom’s main branch at release v2026.10.228, whose shell tools lack two arguments the pull request added, a working directory and a wait. A shell-only run through the API on that release used within 3% of the pull request’s tokens for every model except Luna, which used 8% fewer.
The combination ran through Matrix on the pull request with an experiment patch that shows minimal mode’s single tool in the model’s own dialect. On that code, minimal mode with MindRoom’s bash used within 10% of its tokens on main for every model.
Tokens per task are the input and output tokens of every model request in that task, from MindRoom’s per-request usage logs. The work is what is left after subtracting the fixed part, the first request’s input times the number of requests.
The confidence intervals come from resampling the three runs of each task 5,000 times, keeping the mix of tasks fixed.

Each cell shows passed runs out of 36, then tokens per task; the work columns show how much the work changed with the native tools.

Matching sets: each harness’s own tools against MindRoom’s matching set (pull request, through MindRoom’s API)

Model	Reasoning	MindRoom’s set	Harness’s own set	Work with the harness’s set
Claude Opus 5.5	adaptive thinking	36/36 · 15,661	35/36 · 13,628 (−13%)	+7%
Claude Sonnet 5.5	adaptive thinking	36/36 · 14,606	36/36 · 13,764 (−6%)	+15%
GPT-6 Astra	Codex’s choice	36/36 · 7,041	36/36 · 11,206 (+59%)	+84%
GPT-6.1 Sol	Codex’s choice	36/36 · 7,292	36/36 · 10,417 (+43%)	+60%
GPT-6 Luna	Codex’s choice	35/36 · 8,425	34/36 · 8,638 (+3%)	−5%
Claude Opus 4.7	no thinking	34/36 · 24,398	33/36 · 23,564 (−3%)	+13%
Claude Opus 4.8	no thinking	33/36 · 24,103	34/36 · 19,593 (−19%)	−17%
Claude Sonnet 5	adaptive thinking	33/36 · 29,781	35/36 · 27,833 (−7%)	+9%
GPT-5.5	Codex’s choice	35/36 · 10,819	35/36 · 11,353 (+5%)	+2%
GPT-5.6 Sol	Codex’s choice	36/36 · 10,624	34/36 · 10,991 (+3%)	−5%

For Claude, both sets have a shell and tools to read, edit, and write files; for GPT, a shell and Codex’s apply_patch against MindRoom’s tools to edit and write files. Neither has MindRoom’s grep, find_files, or ls.

Mixed sets: native tools against MindRoom’s tools (pull request, through MindRoom’s API; Claude with adaptive thinking, GPT with the effort Codex picks)

Model	MindRoom’s tools	Native tools	Native tools, 100-line output	Work with native tools
Claude Opus 5.5	36/36 · 18,943	36/36 · 17,244 (−9%)	36/36 · 17,410 (−8%)	+5%
Claude Sonnet 5.5	36/36 · 17,765	36/36 · 16,237 (−9%)	36/36 · 16,399 (−8%)	−4%
GPT-6 Astra	35/36 · 8,250	36/36 · 10,807 (+31%)	35/36 · 10,399 (+26%)	+51%
GPT-6.1 Sol	36/36 · 8,873	36/36 · 10,534 (+19%)	36/36 · 10,239 (+15%)	+24%
GPT-6 Luna	33/36 · 12,003	35/36 · 11,532 (−4%)	36/36 · 10,816 (−10%)	+15%

Older models, mixed sets: native tools against MindRoom’s tools (pull request, through MindRoom’s API)

Model	Reasoning	MindRoom’s tools	Native tools	Work with native tools
Claude Opus 4.7	no thinking	34/36 · 33,140	33/36 · 25,793 (−22%)	−26%
Claude Opus 4.8	no thinking	33/36 · 32,219	34/36 · 23,843 (−26%)	−32%
Claude Sonnet 5	adaptive thinking	33/36 · 42,349	34/36 · 27,120 (−36%)	−45%
GPT-5.5	Codex’s choice	34/36 · 15,007	36/36 · 14,419 (−4%)	−11%
GPT-5.6 Sol	Codex’s choice	36/36 · 15,062	35/36 · 12,809 (−15%)	−27%

Older models, only the shell tools: native shape against MindRoom’s (pull request, through MindRoom’s API; Opus 4.7 and 4.8 without thinking, Sonnet 5 with adaptive thinking, GPT with the effort Codex picks)

Model	MindRoom’s shell	Native shell
Claude Opus 4.7	33/36 · 17,518	33/36 · 15,714 (−10%)
Claude Opus 4.8	35/36 · 19,183	33/36 · 14,686 (−23%)
Claude Sonnet 5	33/36 · 22,624	33/36 · 28,354 (+25%)
GPT-5.5	36/36 · 9,056	36/36 · 9,046 (0%)
GPT-5.6 Sol	36/36 · 9,171	34/36 · 8,658 (−6%)

Sonnet 5’s native mean comes from one run that cost 271,106 tokens, after a 50 KB command output; its median is 9% lower with the native shell.

Opus 4.7 and 4.8 with adaptive thinking, mixed sets: native tools against MindRoom’s tools (pull request, through MindRoom’s API)

Model	Thinking replies	MindRoom’s tools	Native tools
Claude Opus 4.7	26% and 31%	35/36 · 35,610	33/36 · 23,090 (−35%)
Claude Opus 4.8	36% and 30%	33/36 · 25,269	33/36 · 20,130 (−20%)

Reasoning effort, mixed sets: native tools against MindRoom’s tools (pull request, through MindRoom’s API)

Model	Reasoning effort	MindRoom’s tools	Native tools
Claude Sonnet 5.5	low	36/36 · 15,154	36/36 · 12,330 (−19%)
Claude Sonnet 5.5	default	36/36 · 17,765	36/36 · 16,237 (−9%)
Claude Sonnet 5.5	high	36/36 · 18,286	36/36 · 15,630 (−15%)
GPT-6 Astra	low	36/36 · 8,361	36/36 · 10,627 (+27%)
GPT-6 Astra	default	35/36 · 8,250	36/36 · 10,807 (+31%)
GPT-6 Astra	high	36/36 · 8,934	36/36 · 12,918 (+45%)

Only the shell tools (pull request, through MindRoom’s API; Claude with adaptive thinking, GPT with the effort Codex picks)

Model	All of MindRoom’s tools	MindRoom’s shell only	Native shell only
Claude Opus 5.5	36/36 · 18,943	36/36 · 12,926 (−32%)	36/36 · 12,202 (−6%)
Claude Sonnet 5.5	36/36 · 17,765	36/36 · 12,455 (−30%)	36/36 · 10,168 (−18%)
GPT-6 Astra	35/36 · 8,250	36/36 · 6,025 (−27%)	36/36 · 6,052 (0%)
GPT-6.1 Sol	36/36 · 8,873	36/36 · 6,195 (−30%)	36/36 · 6,177 (0%)
GPT-6 Luna	33/36 · 12,003	31/36 · 7,118 (−41%)	34/36 · 7,018 (−1%)

MindRoom’s shell alone is compared with all of MindRoom’s tools, and the native shell with MindRoom’s shell.

Minimal mode against standard mode (main branch, through Matrix, shell tools only; Claude with adaptive thinking, GPT with the effort Codex picks)

Model	Standard mode	Minimal mode
Claude Opus 5.5	36/36 · 22,192	36/36 · 8,030 (−64%)
Claude Sonnet 5.5	35/36 · 22,448	34/36 · 7,828 (−65%)
GPT-6 Astra	36/36 · 11,429	36/36 · 2,798 (−76%)
GPT-6.1 Sol	36/36 · 11,070	35/36 · 3,370 (−70%)
GPT-6 Luna	35/36 · 12,568	34/36 · 5,219 (−58%)

Minimal mode: the native tool against MindRoom’s bash (pull request with the experiment patch, through Matrix; Claude with adaptive thinking, GPT with the effort Codex picks)

Model	MindRoom’s `bash`	Native tool	Native tool, 100-line output
Claude Opus 5.5	36/36 · 8,058	36/36 · 8,654 (+7%)	36/36 · 9,123 (+13%)
Claude Sonnet 5.5	34/36 · 7,787	34/36 · 7,514 (−4%)	34/36 · 8,000 (+3%)
GPT-6 Astra	35/36 · 3,071	36/36 · 4,173 (+36%)	36/36 · 3,359 (+9%)
GPT-6.1 Sol	34/36 · 3,103	33/36 · 4,150 (+34%)	36/36 · 3,575 (+15%)
GPT-6 Luna	34/36 · 4,697	34/36 · 6,849 (+46%)	32/36 · 4,926 (+5%)

One of Luna’s runs with the whole native output counts for passes but not for tokens: the provider reported no usage for one of its requests.

Armin also found that Anthropic’s strict tool mode, which restricts the model’s output to the tool’s schema, made these failures disappear in his tests. Pi later turned it on for Claude models, and a pi user then linked a different problem to it: in that user’s logs, 9.5% of Claude’s edits had mangled \u escapes for non-ASCII text, such as Korean, with strict mode on, and 1.5% with it off. ↩︎
The 12 tasks come from 12 families: a CSV report, finding the commit that broke a check, renaming an API across a package, counting errors in log files, fixing failing tests, finding files, extracting fields from JSON, writing a shell script, editing a configuration file, counting matching lines in very long command output, unpacking nested archives, and deduplicating and merging data files. I tune MindRoom’s agent setup on other instances of these families, and these 12 were held out from that. ↩︎
Claude and GPT count tokens differently, so compare the numbers within one model, not across models. Cached input counts in full here, although providers bill it at a fraction of the price, so a bill changes less than the token count. ↩︎
MindRoom’s toolkits accept exclude_tools, so both sets drop MindRoom’s grep, find_files, and ls, and for GPT also read_file, since Codex reads files through the shell. Both keep their shell’s tools for checking on and stopping a background command, which no model used in the matching-set runs. ↩︎
Anthropic adds its own instructions for tool use to every request that has tools, which is why MindRoom’s single bash tool costs Claude 509 tokens. I measured all of these numbers by sending each part on its own and reading the input tokens the provider reported. ↩︎
The patch is with this post’s reproduction scripts. It shows minimal mode’s single tool as MindRoom’s canonical run function, which the tool dialect then presents as Bash or exec_command; nothing else about minimal mode changes. ↩︎

Exploring the Jev hype in MindRoom

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

Last week, every AI newsletter I get was full of Jev, a new model from TypeSafe. So were several subreddits. I am a permanent lurker on r/LocalLLaMA, and even though it is about local models, every other post seemed to be about Jev. There were local clones like mini-jev and von, CLI wrappers like jev-cli, and even someone on Hacker News claiming they had built the same thing a year earlier.

I tried Jev in MindRoom, my open-source agent platform on Matrix, and less than two days later it was making three decisions there.

Update 2026-10-07: OpenAI released the Decisions API today, its own take on the same idea, and MindRoom now supports it as a third backend; see below.

What a System One model is #

The name comes from Daniel Kahneman’s Thinking, Fast and Slow, where System 1 is fast, intuitive thinking and System 2 is slow and deliberate. A System One model does not generate text. You send it a state, for example a chat log, plus typed questions, and it returns probabilities:

Type	Question	Answer
Noul	Yes or no	Probability of yes
Choice	Pick one of up to 255 options	Chosen option plus the full distribution
Score	Rate against a rubric of 2 to 10 levels	Probability-weighted value

TypeSafe claims 70 to 500 ms end to end and $0.042 per million input tokens, with output tokens free. They also write “we can’t prove it isn’t subsidized.” Either way, it is incredibly cheap and incredibly fast.

Adaptive participation #

In MindRoom, a conversation can have several humans, several agents, or both. When I talk to a single agent, it simply replies, and I don’t need to tag it. Once another person joins and writes something, the agent cannot tell whether the message was meant for it or for the other person. Nothing decided that, so the agent stayed quiet unless explicitly tagged. That confused several users.

So I recently added adaptive participation: an agent that has already replied in a thread decides on its own whether to answer an untagged message. I first used an LLM as the judge, GPT-5.6 Luna on low reasoning. A yes-or-no question like “should this agent respond?” is exactly what Jev is for, so it became the second backend. Compared with Luna, it is about ten times cheaper and ten times faster, and if I believe the benchmarks, it is also smarter.

“Thanks” should not stop the agent #

The next thing I used Jev for was interruptions. When I send a message while an agent is still replying, MindRoom injects a notice at the next tool call telling the agent to stop and wrap up, because there is a new message. But often I, and other users, would watch the agent start working and then write “looks good” or “thanks.” The agent would stop early and continue in the next turn, which is both wasteful and counterintuitive.

Now a judgment decides whether the new message needs the interruption, which the docs call mid-turn coalescing. If it does not, the agent reacts with 👀, finishes its reply, and handles the message afterwards.

This is also where I learned a lesson about evals. My first implementation worked at the code level but not functionally. My evals, based on real attempts inside MindRoom that had all failed plus synthetic cases from GPT-6 Astra, passed 5 out of 40 with Jev. The fix changed the question and gave the judge more context, and it went to 40 out of 40.

	Before: 5/40	After: 40/40
Question	“May the active task finish before the queued human messages are handled in a later turn?”	“Does any newly queued message require an immediate change to, pause of, or stop of the active task?”
When unclear	“Also false when context is incomplete, the relationship is unclear…”	“Mere relevance to the task does not make praise or thanks an interruption.”
Context	The request and the new messages	The same, plus the preceding conversation

The old question treated anything unclear as a reason to interrupt, and a bare “thanks” without the conversation around it always looks unclear.

Picking the responder #

The third decision is routing. When a message in a room with many agents does not mention anyone, MindRoom’s router picks who should answer. That used to be a free-text LLM prompt, “choose the most appropriate agent.” It is now a Jev Choice over the eligible agents, plus a no_fit option, as described in the router docs. A confident no_fit asks the user to mention an agent instead of guessing, and anything uncertain falls back to the existing LLM router.

One config line to switch #

I built a very simple abstraction layer so I can swap Jev for an LLM without changing any code. Every decision is one question with criteria for true and false:

MID_TURN_QUESTION = JudgmentQuestion(
 id="interrupt_current_turn",
 instructions="Does any newly queued message require an immediate change to, pause of, or stop of the active task?",
 when_true="A new message requests stopping or pausing the active task, corrects it, ...",
 when_false="The messages acknowledge progress, express thanks, ask to continue unchanged, ...",
)

Jev receives it as a Noul question and returns a probability, which MindRoom compares with a threshold. An LLM receives the same question and context and must return {"decision": true} or {"decision": false}. Switching is a configuration change:

agents:
 helper:
 mid_turn:
 defer_reaction: "👀"
 judgment:
 provider: typesafe  # or: provider: llm, model: fast
 threshold: 0.8

Both backends log their decisions and latency, so I can compare them on real traffic. The code is in src/mindroom/judgment/, and the backends are documented under participation judgment backends.

A third backend: OpenAI Decisions #

On October 7, OpenAI released its own version of the idea, the Decisions API, currently in public beta. The question types match Jev’s: a predicate is a Noul, and choice and score keep their names. It serves a single model, gpt-6-luna, and OpenAI says it returns answers “about 10x faster than the Responses API.” Input costs $0.10 per million tokens and output is free, so it lists at about 2.4 times Jev’s price.

Thanks to the abstraction layer, adding it took one PR, merged the same day, and it works for all three decisions, including the router’s Choice:

judgment:
 provider: openai_decisions
 threshold: 0.8

From MindRoom’s side, only the wire format differs. The endpoint accepts only user messages, so MindRoom sends each chat message as its own user message, prefixed with its role, like assistant: .... Decisions can also answer with a refusal, which MindRoom treats as an abstention, so the usual fallback applies.

I tested it against the live API through MindRoom’s own code, with the same questions Jev gets. For participation, it gave 0.99 to replying to a direct question and 0.0 while two humans were talking to each other. Mid-turn, “Thanks, looks great so far!” got 0.0 for interrupting and “Stop, keep MySQL…” got 1.0. The router sent a pandas bug to code and a meeting request to calendar, both with confidence 1.0. A nonsense request got only 0.62, below the 0.8 threshold, so the normal LLM router took over. Each call took 130 to 280 ms. I have not compared it with Jev on real traffic yet, but both log the same outcome fields, so that only takes a config change.

Named after Jevons #

I only read why TypeSafe named it Jev after building all this: they named it after William Stanley Jevons, who noticed that as steam engines burned coal more efficiently, demand for coal went up instead of down. This is known as the Jevons paradox. That was literally my experience. Most of what I built was perfectly possible with an LLM. I just never built it, because I am somewhat cost- and latency-minded. Once I implemented Jev for one decision, I came up with use case after use case.

One I already built is a plugin, Response Audit JEV. Right after an agent replies, Jev checks the answer against the request and the tool calls the agent actually made, for example whether things are properly cited. If a check flags a problem, the plugin posts one follow-up in the thread that tags the agent and asks for a correction. Because Jev is so fast and cheap, running this after every reply costs almost nothing.

Right now I am full of ideas. For example, a model router. In MindRoom, an agent can switch to a different model mid-conversation with a tool call, and I can do the same with !model. Agents rarely do that without being told, though. So I default to a very expensive model, and I only save money when I remember to switch to a cheap one for something simple. Jev could run on every message and decide whether it needs the capable model or not. That works in both directions, up to a capable model or down to a cheap one. The perfect moment to switch is when the prompt cache has expired. A prompt cache belongs to one model, so switching normally means sending the entire context again at full price. Once the cache has expired, I pay that price anyway, so switching costs nothing extra.

Removing the guardrails and letting my coding agents loose

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

I have run coding agents in YOLO mode since I started using them in May 2025. I think it is the only way to parallelize work. Sometimes I have ten agents running at the same time, and clicking “approve” on every command they run would make that impossible.

What makes me comfortable with it is that models tend to do what you ask, and that you can keep them in an environment where they cannot do much harm. I don’t keep secrets within their reach, and above all I have very good backups. The last piece is a small set of hooks that block the few things I never want an agent to do on its own.

Why hooks and not AGENTS.md #

My system prompt has always told agents not to force-push or merge PRs. Some of them did it anyway.

The first time I really noticed was with Gemini 3 Pro in November 2025, which merged my PR and force-pushed to main. It happened a couple more times in the weeks after, as I parallelized more and asked more of the models. Three weeks later I had hooks for Claude Code and Gemini CLI that block these commands before they run. Codex did not support hooks yet. To my surprise, it did not need them: OpenAI’s models are extremely good at following instructions, and Codex never ignored an explicit rule in my AGENTS.md. Codex supports hooks by now, so it runs the same ones as the others.

Claude has been worse at following rules, and Gemini far worse still: absolutely dogshit. I only try Gemini now and then, and I have been disappointed every time. By now I don’t even try the latest Google models anymore.

I don’t think agents are ever purposely malicious. They try to do what you asked, but they can misinterpret it, and then they force-push or merge something. A rule in a Markdown file is a hope; a hook actually stops the command. Not that a hook would stop a malicious agent: it could put the blocked command in a Bash script and run that instead. What the hook does is tell the agent why I don’t want it, because every block comes with a short explanation:

git add -A is not allowed - add files explicitly to avoid adding unrelated untracked files

The models are well aligned, so once they know my intention, they respect it.

What I block #

All hooks live in my dotfiles, and I deliberately kept them simple. The detection logic is one Python module, git_guard.py, and the Claude Code, Codex, and Gemini CLI hooks all import it.

git commit --amend and git push --force. The unit I review is a PR. When I review a PR, I know I have reviewed it up to a certain commit, and later I only look at the diff of the new commits. Rewriting history breaks that.

Pushing to main. Everything happens in PRs. Inside a PR I don’t care how messy the history gets. I want the agent to push very often, so no work gets lost, and every commit has to be green, so each one is a snapshot I can go back to. The agent maintains its own development of the feature, and I have not written a commit message myself in a long time. When the PR is done, I squash merge it.

gh pr merge. The merge comes after my review, so it is mine to do.

git add -A. I often have unrelated untracked or unstaged files lying around. I work in many open source repositories, and some of those files should not be public, like deployment plans. This is the only block without an override.

sleep. This one is for Claude, and Opus 5 specifically, which I hate with a passion. It would run tests in the background and then sleep 300, badly overestimating how long the tests take, when a blocking tool call returns exactly when they finish.

The override #

Over time the models got more capable. I could parallelize more, and I trusted them to work on their own for longer. I noticed I was spending a significant fraction of my time clicking buttons and doing operations I had forbidden the agent to do, only to end up doing them myself.

So in July I added an override. When a hook blocks a command, the agent gets this hint:

If (and only if) the user has explicitly approved this exact action,
re-run the command prefixed with EXPLICITLY_USER_APPROVED_HOOK_OVERRIDE=1 to override this block.

Nothing checks whether I actually approved it. It is a soft gate, but it works because the agent now has to write down, in the command itself, that I approved the action. When it runs into the block without my approval, it becomes obvious to the agent that it has to ask me first.

git add -A stays hard-blocked, and a chained command cannot carry an override past it: EXPLICITLY_USER_APPROVED_HOOK_OVERRIDE=1 git commit --amend && git add -A is still rejected.

When the override was used without approval #

It has happened, mostly with GPT-5.6 Sol, which I used a lot at the time.

It used to be that you had to keep your context window short, because auto-compaction was lossy and produced poor summaries. Since around GPT-5.3, compaction works well enough that I keep a session going for as long as I am working on the same feature. So I would ask the agent to merge a PR early on, start a follow-up PR in the same session, and after a compaction the agent concluded that it should merge the new PR too. It did, without my approval.

The other case was my pr-review skill, by far my favorite skill that I wrote myself. I would tell the agent to run it and squash merge the PR only if the review approved it. A few times, the review found problems, the agent fixed them, and then it merged. What I meant was: merge if it is approved right away, and otherwise wait for me. Now I spell that out and end with “otherwise, wait for my instructions.”

Working from my phone #

The override matters most when I am away from my computer. On a month-long trip visiting family in Europe, I worked only from my phone, using my mobile coding workflow. Typing commands in a terminal on a phone is inconvenient, so I would rather say what I want and let the agent do it, including the merge. I have also built end-to-end encrypted voice calls to my agents over Matrix with MindRoom, and I am moving more toward that kind of voice-driven workflow.

Not much has changed #

I recently reread my first post on agentic coding from August 2025, and very little in it is outdated. The models are more capable, and I give them much larger scopes, but the way I work is mostly the same. The hooks are the main thing I added, and the override is how I loosened them again.

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).

Gemini 3 Pro: First Impressions

Wed, 19 Nov 2025 00:00:00 +0000

I’m a huge fan of agentic coding. I have the maximum subscriptions for both Claude and ChatGPT Pro, and since writing my agentic coding post, I mostly moved from Claude Code to Codex CLI with GPT-5 for my work that requires more complex reasoning. Using Claude Code often feels frustrating in comparison now.

I also frequently pit them against each other, drafting parallel plans with each tool (I’ve done this at least 50 times). The verdict is consistent. Claude Code, without exception, says that GPT‑5’s solution is superior, admitting it is more elegant and robust. Claude also misses bugs during PR reviews that GPT-5 catches immediately.

That said, Claude Code is significantly faster, which makes it my go-to for simple refactors. I also prefer its writing style for conversational answers and documentation.

But looking at the charts on Artificial Analysis, the new Gemini 3 Pro looks truly impressive. It’s at the top of nearly every benchmark. I’m excited for Gemini to potentially take over some of GPT‑5’s workload, so when Gemini 3 Pro Preview came out yesterday, I had to try it.

The good: raw power #

First off, the model is quite powerful. Last night, I built a complex new feature for my agent-cli project in just two hours: a RAG (Retrieval-Augmented Generation) proxy server.

This tool acts as a middleware that sits between any OpenAI-compatible client and server (like Ollama or vLLM). The server watches a specific folder, automatically indexes any PDF, Markdown, or text files into a local ChromaDB vector store, and injects relevant context into your prompts transparently. You can see the full implementation in PR #79.

It even handles dynamic re-indexing when I drop new files in! The speed and code quality for this task were genuinely impressive, and it handled the complexity of the RAG integration surprisingly well.

The bad: panic attacks and infinite loops #

However, the experience wasn’t without its “personality quirks.” Twice, Gemini got stuck in a loop saying “Should I? I should” over and over again. Or the following also happened:

It also has a bad habit of amending commits multiple times and force-pushing them. For me the Git history is a critical source of truth, and I don’t like rewriting it because I might just have reviewed those commits already.

The interface friction #

I also found the Gemini CLI interface frustrating. Basic tasks like selecting text or scrolling up are surprisingly difficult. I’m not sure why they chose this design or why they feel the need to deviate from standard CLI behavior. It feels like unnecessary friction in an otherwise promising tool.

Proofreading this post #

I also asked Gemini to proofread this very blog post. It made some suggestions—some I liked, others I didn’t, so I reverted the ones I didn’t want. But in every single subsequent iteration, it would forcefully re-apply its rejected changes, adding emojis I had removed or rewriting sentences I had explicitly restored.

The “main branch” incident #

Another scary moment: I asked if the PR was ready to be merged into main, and it went ahead and checked out the main branch and merged everything locally. If I hadn’t stopped it, I’m pretty sure it would have pushed the changes to the main branch directly as well. I tend to use “yolo mode” for agentic coding because I feel like Git has my back, but this feels like a dangerous path to go down.

And indeed, while writing this post, it actually happened. Gemini merged my pull request without my permission.

My prompt was > should the README reflect this? and before that I asked to review the PR.

When I asked why it merged it, it instantly force-pushed to main again!

Artifacts and existential crises #

Also, when it commits, it just adds all files, including debugging logs and build artifacts. When it realizes its mistake, it tries to fix it. But if I try to help at the same time (like removing the files myself while it’s thinking), it gets extremely confused.

It spirals into an existential crisis, claiming that I committed the file but now “it is gone.” “What is going on?” it asks, spending a lot of tokens (and time) looking at git reflogs and questioning its own existence. Even when I stop it and explicitly say that I deleted the file and to please continue, it completely ignores me and continues its panic attack. I experienced this pattern of ignoring instructions multiple times.

Conclusion #

Gemini 3 Pro shows massive potential. The raw coding ability is there, and building a clean RAG proxy in two hours is great! But the agentic behavior needs some serious work: the loops, the force pushes, ignoring instructions, and the confusion when reality doesn’t match its internal state.

This is just day one, so I’m confident many of these issues will get ironed out. I don’t love the interface, but given that gemini-cli is open source with ≈400 contributors, I expect rapid improvements, especially now that the model is finally good with agentic workflows!

Coding from my phone 📱

Mon, 20 Oct 2025 00:00:00 +0000

I am dictating this post at ten kilometers altitude on a flight home from Mexico, Blink Shell open on my iPhone, while an agentic assistant on my NixOS machine writes an initial draft for this post. Admittedly, I’m a little addicted to agentic coding: when an idea pops up, I want to jump on it right away—even if that means doing it from a cramped seat in the sky. This is the workflow I’ve arrived at after trying many alternatives, it extends my agentic coding write-up and the self-hosted AI obsession in my local AI journey. It’s my backup plan for those moments when a computer simply isn’t nearby—the rest of the time I’m still at a keyboard like any other developer. This is in no way a replacement for a proper computer/laptop workflow but gets the job done when needed. It’s a personal, mostly open-source stack built around agent-cli—my local-first voice layer. Here’s how it works: I speak into my phone, the audio goes to FasterWhisper for transcription, Ollama cleans up the text, and it lands on my clipboard ready to paste. My iOS Shortcut handles this through a small HTTP interface that agent-cli exposes. The coding agent itself still uses the best proprietary model I can access.

Table of contents

1. Why Phone Coding Works Now #

For years I used iSH (a full Alpine Linux emulator) with SSH to hop into servers from my phone, but dropped connections were a constant frustration (Mosh fixes this, more on that later). Because coding on a phone keyboard is terrible, I kept it to tiny configuration tweaks or one-off fixes of a few characters. Agentic tools changed that: with a CLI coding agent, I don’t need to type the code—I describe the change, review the patch, and run it. That made meaningful work on the phone possible for the first time, for those moments when a computer isn’t around.

I tried VS Code in the browser, bounced between iSH and Terminus for SSH, and even lived inside a handful of in-browser terminal clients. I also spent time with mobile companions like Happy and Omnara, both designed to mirror Claude Code sessions on the phone, but they still felt like extra steps between me and my actual terminal. That friction pushed me toward a phone‑ready, self‑hosted workflow that still gives me raw SSH access to my own machine when the computer is out of reach.

This post is based on the way I develop software today. Your mileage may vary, but if you also care about privacy, open tooling, and reproducible environments, I think there are useful pieces here.

2. Constraints and Trade-offs #

This setup grew organically over time. What emerged are less strict requirements and more happy accidents that turned into core benefits:

Single trust boundary: Only the model provider (OpenAI) sees code context; audio and automation stay local, and I avoid any additional third‑party relays.
Resilient sessions: Connections should survive sleep and spotty networks.
Voice-friendly: Dictation should be accurate enough that I can trust it.
Reproducible config: The entire stack must live in my dotfiles and NixOS configuration.

To give you a sense of what I tried, here is the short comparison that convinced me to roll my own:

Approach	Pros	Why I moved on
VS Code in the browser	Familiar editor UI	Needs a steady connection and still lives outside my dotfiles comfort zone
iSH / Terminus SSH	Works without extra infrastructure	Laggy, no Mosh, and awkward keybindings
In-browser terminals	Instant access from anywhere	Poor copy/paste ergonomics and flaky mobile keyboards
Happy (Claude Code companion)	Push notifications, encrypted mobile UI for Claude Code	Requires wrapping every session with a separate CLI and still abstracts away my shell, and was quite buggy for me
Omnara (agent command center)	Centralizes Claude Code/Codex sessions with terminal replay	Proxies via their servers; I already trust OpenAI for the model and don’t want another third‑party handling my code

The stack below gives me the resilience of Mosh, the ergonomics of Zellij, and full control over the AI layer.

3. Layer 1: WireGuard From the Router #

WireGuard is a modern VPN that lets me securely access my home network from anywhere. I terminate WireGuard on my router so every device in the house (and on the road) can dial home with the same config. (If you want something easier to set up without opening ports, Tailscale is a more user-friendly option.)

Server: ASUS XT8 router with WireGuard enabled via the router UI.
Client: The WireGuard iOS app with On-Demand rules so the tunnel flips on whenever I am off trusted Wi-Fi.
DNS: All mobile sessions resolve through my home DNS, so git.nijho.lt and internal services resolve instantly.

This gives Blink a local-LAN address for my desktop nixos.

4. Layer 2: Blink Shell + Mosh for Durable Sessions #

What is Mosh? It’s like SSH, but it stays connected when the network changes or the phone sleeps, and it feels faster on bad connections.

Blink Shell is my daily driver on iOS because it pairs beautifully with Mosh and has great keyboard ergonomics.

I launch sessions using mosh bas@nixos -- zellij attach --create phone (Zellij is my terminal multiplexer—more on that in the next section).
Mosh smooths over spotty LTE and keeps my session alive when the phone sleeps.

Mosh keeps the session responsive across flaky networks and sleep.

5. Layer 3: Zellij Layouts #

I use Zellij as my terminal multiplexer for mobile work.

I stick to the defaults and use a couple of predefined layouts (e.g., a “phone” layout with editor + shell panes).

Ergonomics matter even more on a glass keyboard, so I lean on a few shell helpers:

zoxide means I can jump between repos with z foo instead of pecking long paths.
Single-character aliases like p for pytest and gs for git status live in configs/shell/10_aliases.sh, keeping command entry to a minimum.
Autocompletion plugins—zsh-autosuggestions and zsh-syntax-highlighting—are wired up in configs/shell/70_zsh_plugins.sh, so I get inline hints and colour cues while typing.

I break these tricks down in more depth in Terminal Ninja, explain how I sync them with my Dotfiles, and even package binaries like zoxide with Dotbins.

6. Layer 4: `agent-cli` Server #

agent-cli runs as a small server on my NixOS machine. In this workflow I only use transcribe from iOS Shortcuts: the phone records audio, the server transcribes and cleans it up, and I paste the text. (Agent-CLI has other features like autocorrect and chat, but I don’t use them for this workflow.) On this machine I run a long‑lived agent-cli user service (systemd) so Shortcuts can POST audio to it and get cleaned text back—ready to paste into Codex CLI. The service is defined in my dotfiles—see: configs/nixos/modules/user.nix (agent-cli service).

For more background on why I built it and how I use it in practice, see Local AI Journey (§3) and Agentic Coding.

The models and services run on the same box:

FasterWhisper via faster-whisper-server for high‑accuracy streaming transcription.
Ollama for on‑device rewrite/cleanup before sending prompts to the coding agent.

My iOS Shortcut dictation workflow is slower than Apple’s built-in dictation, but the accuracy is much better—and that matters more.

For the actual coding agent, I use a fork of Codex CLI with OpenAI’s gpt-5-codex-high model (here no open-source solution matches the frontier).

7. Layer 5: The iOS Shortcut Pipeline #

My iPhone’s Action Button runs a Shortcut that records audio and sends my voice to agent-cli on my NixOS machine for transcription and cleanup.

For the full recipe, see the iOS Shortcut Guide: agent-cli/iOS_Shortcut_Guide.md.

In short: I press the Action Button, the Shortcut records a snippet, sends it to agent-cli, and copies the cleaned text to my clipboard so I can paste it into Codex CLI.

The whole loop finishes fast enough that I can capture intent by voice and paste it into Codex CLI without typing.

8. Workflow in Practice #

Here’s the typical flow:

WireGuard auto-connects when I’m off home WiFi
Open Blink—my Mosh session is still alive from last time, Zellij panes intact
Dictate the change, paste into Codex CLI, review the agent’s response
Check diffs in an adjacent Zellij pane or different Blink tab with separate Mosh session
The agent commits and pushes to a branch, then opens a PR via gh for me to review and merge

On the phone, I aim for the smallest practical edits and initial implementations. Even on personal repos, I still open a PR—sometimes prompting alone gets me to a merge‑ready result. For open‑source with real users, I finish on the computer with a careful review and any final edits.

9. Conclusion and Further Reading #

This phone setup extends my Agentic Coding workflow to mobile. I connect to the same Zellij session on nixos, so when an idea hits, I pick up exactly where I left off—same environment, same context, no setup. Everything runs on my hardware (voice processing and automation) except the coding model itself. It’s the most effective mobile workflow I’ve had so far. It’s mostly open‑source not out of dogma, but because those tools are the best options for my needs. The one exception is the coding model: there’s no true open equivalent right now, and it makes no sense to buy 20× H100s just to self‑host a frontier model even if such a high quality model would be available open-source.

If you’re curious to dive deeper, here are a few related posts:

Agentic Coding
Dotfiles: A Practical, Cross-Platform Terminal Setup
Local AI Journey: RTX 3090 Edition
Terminal Ninja
Using LLMs Effectively (already outdated at this point!)

I’d love to hear what self-hosted tricks you’re using for mobile development—reach out if you adapt this stack or build something wild on top of it.

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’.

Confessions of an asymmetric hypocrite: on Python dependencies

Sun, 27 Apr 2025 00:00:00 +0000

Introduction: The Dependency Dilemma 🤔 #

I just listened to a podcast “Build software that lasts!” with Bert Hubert (a fellow Dutch), who prefers to reduce the number of dependencies to an absolute minimum (also see his related blog posts [1] and [2]). While I agree one shouldn’t use is-even as a dependency (is-odd is a better choice 😏), I think there is a lot of value in reducing the number of dependencies but also in using the right tool for the job and not continuously re-inventing the wheel. The podcast got me thinking about my own stance on dependencies and how I actively avoid introducing dependencies into my libraries while expecting (hoping 🤞) others to depend on my work.

Like many software developers, I’ve spent countless hours wrestling with dependencies. Dependency hell is easy to fall into, especially in dynamic languages like Python. Those moments where installing or updating one package breaks another, or where a tiny library pulls in hundreds of transitive dependencies, are frustratingly common. This frustration partly motivated me to create unidep, a tool aimed at simplifying dependency management across different Python tools like pip and conda.

But working on unidep and my other projects forces me to think about my own relationship with dependencies. I’ve realized I operate with what feels like an “asymmetric hypocrisy.” My standards for the libraries I publish are extremely strict regarding which external dependencies I consume. Yet, as an author of over 30 Python packages, I inherently produce dependencies, hoping others will adopt my work. And then, when building applications or CLIs, my caution often disappears entirely.

This post dives into that asymmetry. It’s about the different hats I wear: the minimalist library author (as a dependency consumer), the hopeful library author (as a dependency producer), and the pragmatic application developer. In this post, I’ll explain why I take these different approaches and why it’s really about the situation, not a contradiction.

Table of contents

1. The Library Author Hat 🎩 (as Dependency Consumer): Maximum Caution #

When I build and publish an open-source Python library – like Adaptive, pipefunc, or unidep – my primary focus shifts to the users who will depend on my code. My choices directly impact their projects. This responsibility means I have to be very careful about adding external dependencies:

Minimize and Scrutinize: Fewer dependencies mean fewer potential conflicts for users. I aggressively minimize the core runtime dependency list.
Favor Battle-Tested Dependencies: I strongly prefer dependencies that are already widely adopted and trusted by the community. (I have been called that person that always wants the latest and greatest, the truth is that I am a sucker for shiny new things but typically only adopt them once they are already quite popular.) Think numpy or cloudpickle. These are less likely to cause unexpected issues or disappear overnight.
Low Transitive Dependency Count: A key criterion is how many other packages a potential dependency pulls in. Ideally, I choose dependencies with zero or very few further dependencies. For example, in pipefunc, dependencies like numpy, networkx, and cloudpickle are good examples – they are popular and don’t rely on many other things.
Optional Dependencies for Heavy Features: If a feature really needs a large or less common dependency, I try making it a optional extra (project.optional-dependencies). Users opt-in only if they need that specific capability.
Avoid Pinning (Mostly): As mentioned before, hard version pins (==1.2.3) in libraries are usually harmful. Minimum versions (>=1.2) or safe upper bounds (<2.0) are preferred.
License Awareness: The license of a dependency matters immensely, especially regarding compatibility and obligations (GPL considerations).

The guiding principle is: Do not cause pain for your users. A library should integrate smoothly into diverse environments.

2. The Library Author Hat 🎩 (as Dependency Producer): The Paradox #

Here’s where the “hypocrisy” might seem to surface. While I’m cautious about consuming dependencies for my libraries, I am also the author of over 30 packages. I invest time and effort into these tools, naturally hoping they prove useful and that others will adopt them – making my libraries dependencies in their projects.

Is it hypocritical to be wary of adding dependencies while simultaneously creating them for others? Perhaps slightly, but it’s also the nature of contributing to an ecosystem. I try to handle this by strictly following the rules from Section 1 for my own libraries. If I expect others to rely on my code, I feel responsible to make that dependency as low-risk and stable as possible. I want my libraries to be the kind of well-behaved, minimal-friction dependencies that I myself would be comfortable adding.

3. The Application Developer / Contributor Hat 🧢: Practicality is Key #

When the context shifts to building an application – like a command-line tool, a web service, or a personal project – my rules become much less strict. The key differences are isolation (keeping things separate) and how far the effects reach.

Isolation Reduces Risk: Applications often run in controlled, isolated environments. Docker, conda/micromamba (Python Environment Jungle post), or simple venvs contain the dependencies. A conflict within the application’s environment doesn’t break the user’s entire system or other unrelated projects.
CLIs as a Prime Example: Many tools I’ve built are CLIs (like tuitorial or helpers within my dotfiles). These might have tens of dependencies. Because they are installed into isolated environments (often via uv, pipx, or within a dedicated conda env), this complexity is okay. The risk is contained.
Developer Tools Welcome: Productivity boosters like ruff, mypy, etc., are fair game as development dependencies (My Python Project Toolkit). They don’t impact the end-user runtime (if packaged properly), so I am much more lenient with dev tools.
Focus on Functionality: The goal is often to deliver features or solve a problem efficiently. Leveraging existing libraries, even those with dependencies, is usually faster and more robust than reimplementing complex logic. It usually makes more sense to use existing libraries.

In this context, the focus changes from minimizing external impact (libraries) to maximizing internal capability and maintainability within a controlled scope (applications).

4. Conclusion: Not Hypocrisy, but Context-Driven Strategy 🙏 #

My approach to dependencies is “it depends on the situation”. I’m stricter about dependencies for my libraries than for my applications or personal tools. I am cautious about adopting dependencies while actively producing them for others.

But I don’t see this as hypocrisy. It’s a practical approach based on different situations and goals:

Libraries (as Consumer): Focus on keeping the software community stable and making things easy for users. Be conservative.
Libraries (as Producer): Create software responsibly, following the same high standards you expect from others.
Applications: Focus on adding features and developing quickly within separate environments. Be pragmatic.

Understanding the different risks and goals for each situation helps make good decisions about dependencies. It’s about choosing the right trade-offs for the specific situation, whether you’re building a foundational block for the community or a specific tool for a controlled environment.

How do you handle dependencies across different types of projects? Do you find yourself navigating similar questions? Share your thoughts!

Functions over classes? Why I prefer a simpler, functional style in Python 🐍

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

Over years of building software, from scientific simulation tools like Adaptive and pipefunc to package management packages like unidep, I’ve found myself preferring a certain coding style: using small, focused functions more than large classes with complex internal state and deep inheritance hierarchies. This isn’t about dogma, but about a pragmatic approach that, in my experience, leads to code that is easier to understand, test, and maintain.

This post outlines why I lean towards this functional-inspired style in my Python projects, while still recognizing where classes are the right tool.

Table of contents

1. Taming Complexity: Avoiding the Over-Engineering Trap 🧠 #

One of the biggest challenges in software development is managing complexity. As systems grow, keeping track of how different parts interact and understanding the internal state of objects can become a lot to keep track of mentally (high cognitive load).

I’ve often observed a pattern, especially when developers first start using object-oriented programming: the tendency to use classes everywhere. This can lead to over-engineering – introducing many layers of inheritance, abstract base classes with only a single implementation, and generally creating complexity when simplicity would suffice. Thinking you’re being clever by building complex class structures can sometimes just be a form of overgeneralization that makes the code harder, not easier, to follow.

Classes, particularly those with many methods modifying internal attributes (self.x, self.y, etc.), require you to constantly hold their state in your head. When you call a method object.do_something(), the outcome might depend not just on the arguments you pass, but also on the object’s history – what methods were called before, and in what order? This hidden state can make reasoning about the code’s behavior difficult and debugging tricky.

Functions, particularly when kept small and focused, tend to be more explicit. Ideally, a function takes inputs and produces outputs, with minimal side effects (or ideally, none - making them pure functions). Its behavior is primarily determined by its arguments. This makes the code flow easier to follow: data comes in, transformation happens, data goes out. There’s less hidden context to juggle mentally.

2. The Power of Small, Focused Functions 🎯 #

This leads directly to the preference for small functions, each doing one thing well (adhering to the Single Responsibility Principle). When functions are concise and have a clear purpose:

Readability Improves: It’s easier to understand what a small, well-named function does quickly.
Reusability Increases: Small, focused functions are more likely to be reusable in different parts of the codebase or even in other projects.
Refactoring is Simpler: Modifying or replacing a small unit of logic is less risky than altering a large, complex method within a class.

This philosophy is something I actively apply. Looking at the codebase for unidep, for example, you’ll find many utility functions in modules like _dependencies_parsing.py or _conda_env.py, each handling a specific, well-defined task.

3. Keeping Classes Simple & Using Them Where They Fit 🛠️ #

So, where do classes fit in this picture?

Firstly, as simple data structures – think NamedTuples or dataclasses (preferably with frozen=True). Their main role is to group related data attributes together, providing a clear structure for passing information around. They hold data, but don’t typically manage complex state transitions.

# Example of a simple data class from unidep
from dataclasses import dataclass
from pathlib import Path

@dataclass(frozen=True) # Use frozen=True for immutability
class Spec:
 name: str
 which: Literal["conda", "pip"]
 pin: str | None = None
 # ... other simple attributes ...

# Used to pass structured data, not to manage complex state
def process_spec(spec: Spec) -> Path:
 # ... function logic using spec data ...
 pass

Secondly, and importantly, classes are excellent for defining user-facing APIs. For the end-user of a library, having a single object with easily discoverable methods (object.<tab>) is often a great user experience.

A good example from my own work is the pipefunc package. It provides two main classes, Pipeline and PipeFunc, which encapsulate the core functionality. Users interact primarily with these objects and their methods.

# Simplified example from pipefunc's user perspective
from pipefunc import Pipeline

pipeline = Pipeline(...)
pipeline.add(some_function, ...)
results = pipeline.run("output_node")

However, inside the methods of these API classes (Pipeline.run, Pipeline.add, etc.), the actual logic is often delegated to smaller, internal functions. The class acts as a clean interface or facade, orchestrating calls to these more focused, functional units. This gives the user a nice API while keeping the internal implementation modular and testable.

I also actively avoid deep inheritance hierarchies. Composition (having objects contain other objects) often provides a more flexible and explicit way to combine functionality without the tight coupling and complexity inheritance can introduce.

4. The Testability Advantage ✅ #

One of the most significant practical benefits of prioritizing functions and simple classes is testability. Small, pure (or mostly pure) functions are incredibly easy to test:

Provide known inputs.
Assert expected outputs.
Minimal setup or mocking is required because there’s no complex internal state to manage.

Even when testing the methods of the API classes (like Pipeline in pipefunc), the fact that they often delegate to well-tested internal functions simplifies the process. You focus on testing the orchestration and interaction logic at the class level, knowing the underlying functional units are already verified.

Testing classes with intricate internal state inherently involves more setup (instantiating the object, getting it into the right state before calling the method under test) and potentially more complex assertions to verify state changes. Aiming for more functional units significantly simplifies the testing process.

5. It’s About Pragmatism, Not Dogma 🙏 #

This isn’t a wholesale rejection of object-oriented programming. It’s about choosing the right tool for the job and prioritizing clarity, testability, and maintainability. Classes are fantastic tools, especially for building clear APIs and structuring data. Deep inheritance and complex state management, however, should be used carefully, not just because the language allows it.

For much of the work I do – building libraries, tools, and performing data analysis or simulations – I’ve found that prioritizing functions, keeping API classes focused, minimizing internal state, and avoiding deep inheritance leads to code that I find easier to write, understand, debug, and maintain in the long run. The reduction in cognitive load and the ease of testing are strong points for how I work.

If you often find yourself struggling with complex state management or tangled inheritance trees, perhaps consider if a simpler, more functional internal structure, potentially fronted by a clean class-based API, might bring some clarity and simplicity to your projects too.

Vibe coding worked—until the 15‑hour cleanup

Fri, 21 Mar 2025 00:00:00 +0000

I tried “vibe coding” for 3 hours, my application worked, but then I spent 15 hours fixing it #

That’s not an exaggeration—it’s really what happened.

Recently, I tried “Vibe coding,” a term coined by Andrej Karpathy, a prominent AI researcher, co-founder of OpenAI, and former AI lead at Tesla. In his viral tweet from February 2025, Karpathy described vibe coding as a programming approach where you “fully give in to the vibes, embrace exponentials, and forget that the code even exists.” It’s essentially about letting AI handle the coding based on natural language prompts without closely reviewing the generated code.

Intrigued by the hype, I decided to experiment with vibe coding using Cursor on a new Python project I called dotbins (check out my detailed write-up here)." Dotbins manages CLI tool binaries within Git repositories, automatically downloading the correct binary from GitHub for the user’s platform and architecture, significantly simplifying my dotfiles and bootstrapping process. I am super excited about this project but it is not what this post is about.

Initially, it was fun to get something working so quickly. Within just three hours, I had a functioning prototype—without carefully examining the code. But I had unknowingly created a monster—a true spaghetti monster! 🍝

Once I started reviewing the AI-generated code, I realized it was totally incomprehensible. The AI had implemented the most complicated and roundabout ways to achieve simple tasks. It introduced redundant checks for impossible conditions, irrelevant error handling, and execution paths that would never trigger. The code worked superficially, but beneath the surface, it was chaotic and nearly impossible to understand or maintain.

This realization turned three hours of fun into fifteen hours of meticulous debugging, refactoring, and cleaning up the mess. Essentially, I had to rewrite the entire project.

My main takeaway: AI-assisted coding, or “vibe coding,” is incredibly powerful for quick prototyping but dangerous when used without oversight. According to this recent Y Combinator discussion, many startup founders are building products almost entirely with AI-generated code, “vibing” the code, meaning they let the AI write the code and don’t review it. For writing a couple of hundred lines of code it likely works pretty well, but for anything more complex, it’s a recipe for disaster. Personally, I would never invest in, build upon, or use such products—they’re essentially constructing technical prisons for themselves.

AI is fantastic for inspiration, quick prototyping, writing code, and refactoring—but letting it run wild without careful human review can quickly lead to severe technical debt and hidden bugs.

Thanks for reading!

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!

Python environments that stuck: micromamba and uv 🐍

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

1. Introduction 🚀 #

Like many Python developers, I’ve spent considerable time trying different environment management tools to find what works best for me.

After exploring various options from virtualenv to Conda, I found that Conda-based solutions fit my needs well - mainly because they handle non-Python dependencies without much hassle.

While Conda itself can be slow when setting up environments, tools like Mamba and Pixi provide the same functionality with better performance.

In this post, I’ll share my experience with different Python environment tools and provide practical commands for setting up Python environments.

Table of contents

2. The Alternatives 🌟 #

Before we start look at this comparison tables for the most popular Python environment management tools.

I had to split the tables into two because of the number of columns.

Table 1: Python Environment Management Tools

Tool	Key Features	Native/3rd Party	Non-Python Deps
Pyenv	Python version management	3rd Party	❌
Pipenv	Package & env management	3rd Party	❌
Conda	Package & env management	3rd Party	✅
Mamba	Fast Conda replacement	3rd Party	✅
Micromamba	Lightweight Mamba	3rd Party	✅
Docker	Containerization	3rd Party	✅
Venv	Built-in env management	Native	❌
Virtualenv	Env management (pre-3.3)	3rd Party	❌
Homebrew	macOS/Linux package manager	3rd Party	✅
Pixi	Fast Conda alternative	3rd Party	✅
uv	Fast pip and venv replacement	3rd Party	❌
System Package Managers	OS-based package management	Native	✅

Table 2: Python Environment Management Tools

Tool	Ease of Use	Isolation	Cross-Platform Support	Community & Support	Performance
Pyenv	Medium	✅	Windows, macOS, Linux	Good	Good
Pipenv	Easy	✅	Windows, macOS, Linux	Good	Good
Conda	Easy	✅	Windows, macOS, Linux	Excellent	Average
Mamba	Easy	✅	Windows, macOS, Linux	Growing	Fast
Micromamba	Medium	✅	Windows, macOS, Linux	Growing	Fast
Docker	Hard	✅	Windows, macOS, Linux	Excellent	Good
Venv	Easy	✅	Windows, macOS, Linux	Excellent	Good
Virtualenv	Medium	✅	Windows, macOS, Linux	Good	Good
Homebrew	Easy	❌	macOS, Linux	Excellent	Good
Pixi	Easy	✅	Windows, macOS, Linux	Growing	Fast
uv	Easy	✅	Windows, macOS, Linux	Growing	Very Fast
System Package Managers	Easy	❌	Depends on OS	Depends on OS	Good

Now that we’ve seen the alternatives, let’s dive into setting up environments with the help of Conda and Mamba.

🐍 Pyenv #

A popular tool that enables you to easily manage multiple Python versions on a single system. It allows you to switch between different Python versions without interfering with system-level installations.

Setup Instructions

Install pyenv:
- macOS: brew install pyenv
- Ubuntu: curl https://pyenv.run | bash
Add the following lines to your shell configuration file (e.g., ~/.bashrc, ~/.zshrc):
```
export PATH="$HOME/.pyenv/bin:$PATH"
eval "$(pyenv init -)"
```
Restart your shell or run source ~/.bashrc (or source ~/.zshrc)
Install a specific Python version: pyenv install 3.8.5
Set the Python version for your project: pyenv local 3.8.5

📦 Pipenv #

A package management and virtual environment management tool that combines the functionality of pip and virtualenv. It streamlines the process of installing and managing packages within isolated environments.

Setup Instructions

Install pipenv: pip install --user pipenv
Change to your project directory: cd my_project
Initialize a new virtual environment: pipenv --python 3.8
Install packages: pipenv install <package_name>
Activate the environment: pipenv shell

🌐 Conda #

A cross-platform package manager and environment management tool, often used in conjunction with Anaconda and Miniconda. Conda simplifies the installation and management of packages and dependencies, especially for data science and machine learning projects.

Setup Instructions

Download and install Miniconda: https://github.com/conda-forge/miniforge#miniforge3
Create a new environment: conda create --name my_env python=3.8
Activate the environment: conda activate my_env
Install packages: conda install <package_name>

🚀 Mamba #

Mamba is a fast, drop-in replacement for Conda, designed to resolve and install packages more quickly. It uses the same Conda repositories and environment files, making it easy to switch between the two.

Setup Instructions

Install Mambaforge with Mamba pre-installed:

Download and install Mambaforge with Mamba for your platform: https://github.com/conda-forge/miniforge#mambaforge

Alternatively, you can install Mamba within an existing Conda environment:
```
conda install -c conda-forge mamba
```
Create a new environment with Mamba:
```
mamba create --name my_env python=3.8
```
Activate the environment:
```
mamba activate my_env
```

Install packages using Mamba:

mamba install <package_name> -c conda-forge

By using Mamba instead of Conda, you can significantly speed up environment resolution and package installation while still benefiting from the Conda ecosystem.

🌌 Micromamba #

Micromamba is a lightweight and fast alternative to the Mamba package manager. It is a statically linked C++ executable that doesn’t require a base environment or come with a default Python version. It supports a subset of Mamba and Conda commands and is designed to resolve and install packages quickly. For those who need Conda features, you can install Conda using Micromamba with micromamba install conda.

Setup Instructions

Download the appropriate Micromamba binary for your platform from the official repository.
Make the binary executable and move it to a directory in your PATH:
```
chmod +x micromamba mv micromamba /usr/local/bin/
```

Create a new environment with Micromamba:

micromamba create -n my_env python -c conda-forge

Activate the environment:
```
micromamba activate my_env
```

Install packages using Micromamba:

micromamba install <package_name> -c conda-forge

If you need Conda’s features, you can install Conda within your Micromamba environment:
```
micromamba install conda
```

For example, if you need nb_conda_kernels to use your Micromamba environment in JupyterLab:

micromamba install conda nb_conda_kernels

And you are set up!

Micromamba is the perfect solution for those who want a fast and lightweight package manager while still being able to access Conda’s features when needed.

🐳 Docker #

A containerization platform that allows you to create lightweight, portable environments called containers. With Docker, you can package your Python application along with its dependencies, ensuring consistent execution across different systems.

Setup Instructions

Install Docker: https://docs.docker.com/get-docker/

Create a Dockerfile in your project directory with the following contents:

FROM python:3.11
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "your_script.py"]

Build the Docker image: docker build -t my_project .
Run the Docker container: docker run my_project

🏞️ Venv #

A built-in Python module available since Python 3.3, which allows you to create lightweight virtual environments. Venv simplifies the process of creating isolated environments for different projects, ensuring that package dependencies don’t conflict with each other.

Setup Instructions

Create a new virtual environment: python3 -m venv my_env
Activate the environment:
- macOS/Linux: source my_env/bin/activate
- Windows: my_envScriptsactivate
Install packages: pip install <package_name>

🌐 Virtualenv #

Virtualenv is a third-party Python environment management tool that predates the built-in venv module. It allows you to create isolated environments for different projects, ensuring that package dependencies don’t conflict with each other. Virtualenv is compatible with Python 2.7 and later versions, whereas venv is only available since Python 3.3.

Setup Instructions

Install virtualenv: pip install virtualenv
Create a new virtual environment: virtualenv my_env
Activate the environment:
- macOS/Linux: source my_env/bin/activate
- Windows: my_env\Scripts\activate
Install packages: pip install <package_name>

🍺 Homebrew #

Homebrew is a popular package manager for macOS and Linux that simplifies the installation and management of software. Though it is not a dedicated Python environment management tool, it does offer support for installing and managing multiple Python versions alongside other software.

Homebrew can be useful for installing and managing Python versions for system-level usage, but it’s not the best choice for managing isolated project-specific dependencies. For project-specific dependency management, it’s recommended to use other tools like venv, virtualenv, or Conda in conjunction with Homebrew-installed Python.

Setup Instructions

Install Homebrew (if not already installed):
- macOS: Follow the instructions at https://brew.sh
- Linux: Follow the instructions at https://docs.brew.sh/Homebrew-on-Linux
Install a specific Python version:
```
brew install python@3.11
```
Add the installed Python version to your PATH by adding the following line to your shell configuration file (e.g., ~/.bashrc, ~/.zshrc):
```
export PATH="/usr/local/opt/python@3.11/bin:$PATH"
```
Restart your shell or run source ~/.bashrc (or source ~/.zshrc) to apply the changes.
Verify the Python version: python3.11 --version

Keep in mind that Homebrew is mainly for installing and managing software at the system level. To manage project-specific dependencies and create isolated environments, combine Homebrew with other tools like venv or virtualenv for better dependency management.

💻 System package managers #

Some operating systems have their own package managers (e.g., apt for Ubuntu, pacman for Arch Linux, or Homebrew for macOS) that can be used to install and manage Python environments. However, using system package managers may lead to conflicts with other system packages and is generally not recommended for managing project-specific dependencies.

I will skip the setup instructions for this one, as it is just not recommended to do this!

🌟 Pixi #

Pixi is a new package manager built in Rust that uses Conda-forge packages but aims to be significantly faster and simpler than Conda. It’s developed by prefix.dev (the team behind Mamba) and focuses on providing a more streamlined experience. It is inspired by tools like Cargo, nix, and npm and aims to provide a modern package management experience for Python developers.

Setup Instructions

Install pixi following instructions at prefix.dev
Initialize a new project:
```
pixi init my-project
cd my-project
```
Add dependencies:
```
pixi add python numpy pandas
```
Run Python in the environment:
```
pixi run python
```

Create and run tasks (defined in pixi.toml):

# Add a task
pixi task add hello "python hello_world.py"

# Run the task
pixi run hello

Start an interactive shell in the environment:
```
pixi shell
```

Pixi can also be used as a global installation tool:

# Install tools globally
pixi global install starship
pixi global install fish

# Create a named environment with multiple packages
pixi global install --environment data-science-env \
 --expose python --expose jupyter \
 python jupyter numpy pandas

Key features:

Fast package resolution and installation
Uses Conda-forge packages
Built-in task runner
Global package installation support
GitHub Actions integration with automatic caching
Simple and intuitive CLI

⚡ uv #

uv is an extremely fast Python package installer and resolver written in Rust. It can be used as a drop-in replacement for pip and can generate virtual environments. While it is quite new it is already being used by many developers due to its speed and ease of use. Besides being fast, it is awesome because it is a single binary that can be used to also bootstrap Python itself.

Setup Instructions

Install uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

Create a new virtual environment:
```
uv venv
```
Activate the environment:
- Unix/macOS: source .venv/bin/activate
- Windows: .venv\Scripts\activate
Install packages (much faster than pip):
```
uv pip install numpy pandas
```

It will automatically maintain a uv.lock file to ensure deterministic builds. Install this lock file with uv sync.

Key features of uv:

Up to 10x faster than pip
Built-in virtual environment support
Compatible with pip’s CLI interface
Global package caching
Deterministic builds

There is much more to uv, so check out the documentation for more details.

3. Conclusion 🏁 #

The choice you make for managing your Python environments ultimately depends on your use case. If you don’t have to frequently deal with non-Python dependencies, I would recommend using uv for its speed and simplicity. However, because I often work with projects that require non-Python dependencies, I’ve found that Micromamba is the perfect fit for me.

That being said, each tool has its own strengths and weaknesses, and it’s important to choose the one that works best for your specific needs. I hope this journey through Python environment management has been helpful and informative. Good luck in finding your perfect Python environment workflow! 🐍

4. Further Reading 📚 #

Here are some resources for further exploration:

Pyenv: Pyenv GitHub repository and documentation
Pipenv: Pipenv documentation
Conda: Conda documentation
Mamba: Mamba documentation
Micromamba: Micromamba documentation
venv: venv documentation
virtualenv: virtualenv documentation
Anaconda: Anaconda homepage
Miniconda: Miniconda documentation
Homebrew: Homebrew homepage
Pixi: Pixi documentation
uv: uv documentation

Discovering Git worktrees: a handy tool for multitasking 📚

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

Recently, I discovered a game-changer in Git that has streamlined my workflow: worktrees. This feature allows developers to handle multiple branches of a single repository simultaneously, eliminating the need for constant branch-switching or multiple clones. For example, I typically want to keep the main branch in one editor window and the feature branch in another to easily test changes. With Git worktrees, I essentially have two separate working directories for each branch, making it easier to manage changes and switch between tasks.

What is a Git Worktree?

A Git worktree provides additional working directories linked to the same repository. This means you can easily work on different branches in parallel without duplicating repositories, saving both space and effort.

Benefits of Git Worktrees

Parallel Development: Effortlessly switch between branches for urgent bug fixes or new feature developments.
Efficiency: It’s lightweight, sharing the Git directory, and integrates smoothly with existing workflows.

Quick Commands

Create a Worktree:
git worktree add <path-to-new-worktree> <branch-name>
List Worktrees:
git worktree list
Remove a Worktree:
git worktree remove <path-to-worktree>

Conclusion

Incorporating Git worktrees into your workflow enhances productivity and organization. Whether dealing with bug fixes or new features, worktrees help maintain a cleaner environment.

My favorite tools that keep my Python projects sane 🧰

Sat, 22 Apr 2023 00:00:00 +0000

🌟 1. Introduction #

As a passionate Python developer, I am always on the hunt for the best tools to streamline my development process and enhance the quality of my projects. Over time, I have discovered a set of tools that have become indispensable in my workflow, making my coding experience more efficient and enjoyable. Using the right developer tools for Python projects is crucial for maximizing productivity, ensuring code consistency, and maintaining high-quality code.

In this blog post, I will share these essential tools that I now use for every single new project. We will explore the benefits of each tool and discuss how they can help you supercharge your Python development. The tools covered in this post include pre-commit, Black, Ruff, Mypy, Versioningit, Pyproject.toml with PEP 621, Nox, pytest, GitHub Actions CI matrix, and Read the Docs, Sphinx, MyST-NB, and Jupytext notebooks for documentation. Let’s dive in and learn how to enhance your Python projects with these powerful tools!

Table of contents

🛠️ 2. Pre-commit #

One of the most common challenges developers face when working on a project, whether alone or in a team, is maintaining code quality and consistency. As projects grow, it becomes increasingly difficult to enforce coding standards and catch issues before they make their way into the codebase. This is where pre-commit comes in.

Pre-commit is a powerful tool that helps you manage and maintain code quality by automating checks before commits. It achieves this by setting up a series of hooks that run before each commit, ensuring that only code that meets your predefined standards is committed to the repository. By catching issues early, pre-commit helps you keep your code clean and consistent, making it easier to review and maintain.

One of the reasons pre-commit has gained widespread adoption is its flexibility and extensibility. You can choose from a vast range of built-in hooks, such as code formatters, linters, and security checkers, or even create your own custom hooks. This allows you to tailor pre-commit to the specific needs of your project, ensuring that it enforces the exact coding standards you require.

Using pre-commit is beneficial for both individual developers and teams. For solo developers, it helps maintain discipline and enforces coding standards, making it easier to onboard collaborators in the future. For teams, it streamlines the review process by catching issues before they are submitted for review, reducing the time spent on addressing code inconsistencies and style violations.

Let’s take a look at an example. Suppose your project follows the PEP 8 coding standard, and you want to ensure that all code committed to the repository adheres to these guidelines. You can configure pre-commit to run a PEP 8 linter, such as Flake8, before each commit. This way, any code that does not meet the PEP 8 standard will be flagged, and the commit will be blocked until the issues are resolved.

In summary, pre-commit is an invaluable tool for maintaining code quality and consistency in your Python projects. By automating checks before commits, it ensures that your codebase remains clean and adheres to your chosen standards, making your development process more efficient and enjoyable.

Adding pre-commit to your Python project is simple and straightforward. To get started, you’ll first need to install the pre-commit package using pip:

pip install pre-commit

Next, create a configuration file named .pre-commit-config.yaml in your project’s root directory. This file will define the hooks you want to run before each commit. For example, to use Black for code formatting and Flake8 for linting, your configuration file might look like this:

repos:
 - repo: https://github.com/psf/black
 rev: stable
 hooks:
 - id: black
 - repo: https://github.com/pycqa/flake8
 rev: master
 hooks:
 - id: flake8

Once you have set up the configuration file, run the following command to install the pre-commit hooks:

pre-commit install

Now, every time you attempt to make a commit, pre-commit will run the specified hooks. If any issues are found, the commit will be blocked, and you’ll be prompted to fix the problems before trying again. To run pre-commit manually on all files in your repository, use the following command:

pre-commit run --all-files

By incorporating pre-commit into your development process, you’ll be able to catch and fix issues before they make their way into your codebase, ensuring a consistent and high-quality Python project.

🎨 3. Black: auto-formatting for Python #

As a developer who has always been particular about coding style, I’ve had my fair share of discussions on the proper way to indent multiline statements and other formatting nuances. These conversations, although sometimes necessary, can take up valuable time that could be better spent on actual development. That’s where Black, the uncompromising code formatter, comes in and saves the day.

Adopting Black has made a significant impact on my development workflow. No more unnecessary discussions about formatting preferences; everyone on the team simply follows the rules set forth by Black. This consistency across the codebase not only makes the code more readable but also reduces the time spent on formatting debates.

One of the best aspects of Black is that you don’t need to worry about writing perfectly formatted code initially. You can write your code as quickly as you want, even if it’s poorly formatted, and then simply run Black to transform it into a beautifully formatted masterpiece. This can be a real time-saver, especially when working on large projects with many contributors.

To install Black, run the following command:

pip install black

You can then format your code by running Black in the terminal:

black your_file.py

Alternatively, you can use the VS Code command palette to run Black on the currently open file. However, the most efficient way to use Black is in combination with pre-commit, as mentioned in the previous section. This way, your code is automatically formatted every time you commit, ensuring a consistent codebase without any extra effort.

In summary, Black is an invaluable tool for enforcing consistent code formatting throughout your Python projects. By adopting it and integrating it with pre-commit, you can save time and focus on what truly matters: writing great code.

🚀 4. Ruff: the fastest Python linter and auto-formatter #

In the past, I’ve used several tools to maintain code quality, such as isort, pyupgrade, flake8, and pydocstyle. However, I’ve recently discovered a powerful new tool called Ruff), an extremely fast Python linter written in Rust. Ruff is not only capable of replacing all these tools but also executes much faster, which significantly improves the development workflow.

Ruff offers an impressive range of features and performance enhancements. Some of its standout features include:

10-100x faster than existing linters
Over 500 built-in rules
Autofix support for automatic error correction
Built-in caching to avoid re-analyzing unchanged files
First-party editor integrations for VS Code and more

Moreover, Ruff has gained widespread adoption in the Python community and is used in major open-source projects like Apache Airflow, FastAPI, Hugging Face, Pandas, and SciPy. The tool is backed by Astral, which provides active development and support.

One of the best aspects of Ruff is the native VS Code extension, which continuously scans your code and can fix problems as you write. This seamless integration makes it an indispensable part of any Python development workflow.

To install Ruff, simply run the following command:

pip install ruff

To use Ruff in your project, run the following command in the terminal:

ruff your_file.py

For the best experience, I highly recommend using Ruff in conjunction with pre-commit, as mentioned earlier. This ensures that your code is always linted and formatted before committing, maintaining a consistent and high-quality codebase.

In conclusion, Ruff is an incredibly fast and powerful Python linter that streamlines the development process by consolidating multiple tools into a single, efficient package. By adopting Ruff and integrating it with pre-commit, you can enjoy a more productive and enjoyable Python development experience.

🔍 5. Mypy: static type checking for Python (find bugs before they happen) #

As developers, we’re always looking for ways to improve the quality of our code and minimize the time spent on debugging. This is where Mypy comes in. Mypy is a powerful static type checker for Python, designed to catch potential runtime errors before they occur. By using Mypy, you can ensure that your code adheres to type hints and that it runs smoothly without unexpected issues.

Mypy offers several advantages to Python developers, including:

Early detection of potential type errors, preventing many common bugs
Improved code readability and self-documentation through type annotations
Easier refactoring and code maintenance, as type annotations provide clear contracts between functions and modules
Better collaboration and communication within teams, since type annotations make the code’s intent and expectations more explicit

Adding Mypy to an existing project may initially seem time-consuming and frustrating, as it might flag numerous issues that require attention. However, once you’ve addressed these concerns and properly set up Mypy, the benefits far outweigh the initial effort. In fact, the time you invest in fixing type-related issues will quickly be recovered as Mypy helps you prevent bugs and reduce debugging time.

For a long time, I too ignored Mypy and only typed my code without actually checking it with the tool. But after truly embracing Mypy and integrating it into my development process, I can confidently say that I will never go back. The value it brings to the table in terms of code quality, readability, and reliability is simply too great to ignore.

By proactively identifying and resolving type-related issues, Mypy not only saves you precious debugging time but also enhances the overall quality of your codebase. As you continue to rely on Mypy, you’ll find that it becomes an indispensable part of your Python development toolkit, ensuring that your projects remain robust and maintainable.

To start using Mypy in your project, first install it with the following command:

pip install mypy

Then, you can run Mypy on your Python files by executing the following command in your terminal:

mypy your_file.py

For even better integration, you can add Mypy as a pre-commit hook, ensuring that your code is always checked for type consistency before being committed. This further strengthens the code quality and helps prevent potential runtime errors.

In summary, incorporating Mypy into your Python development workflow adds an extra layer of safety and clarity, making it easier to write high-quality, reliable code. By combining Mypy with other tools like Ruff and pre-commit, you can create a robust development environment that promotes productivity and code quality.

🧪 6. Nox and pytest for testing: a powerful combination #

When developing software, it’s essential to ensure that your code is reliable and functions as expected. The key to achieving this goal is writing thorough tests, which not only help you identify issues early on but also prevent regressions in the future. While it’s often tempting to dive headfirst into coding, taking a step back and first writing tests for your solution can lead to more efficient and effective development. Even if this approach doesn’t come naturally, it’s crucial to write tests for every problem you encounter to keep your codebase stable and reliable.

In the realm of Python testing, Nox and pytest stand out as powerful tools that can greatly enhance your testing process. Nox is a versatile automation tool that simplifies running tests in multiple virtual environments, while pytest is a popular and feature-rich testing framework for Python. Together, these tools provide a formidable testing environment that simplifies test management and execution.

In the past, you may have used Tox, a tool that manages test environments with a text-based configuration file (e.g., in setup.cfg or pyproject.toml). While Tox has served developers well for many years, including myself, Nox offers a more flexible alternative. Instead of relying on a text-based configuration, Nox takes advantage of a Python configuration file, providing virtually limitless configurability. This added flexibility makes it easy to create complex test matrices with different versions and dependencies, and even accommodate special conditions using simple if statements. After happily using Tox for years, I discovered Nox and found that it elevated my testing workflow to a whole new level.

To get started with Nox and pytest, create a basic nox.py file and a sample test file for pytest. Here’s an example nox.py configuration:

import nox

@nox.session(python=["3.7", "3.8", "3.9"])
def tests(session):
 session.install("-r", "requirements.txt")
 session.install("-r", "test-requirements.txt")
 session.run("pytest")

And an example test file for pytest:

import pytest

def test_addition():
 assert 1 + 1 == 2

def test_subtraction():
 assert 3 - 1 == 2

Beyond basic testing functionality, pytest boasts powerful features such as fixtures, mocking and patching, and parameterization. Pytest fixtures enable you to create reusable resources for your tests, while mocking and patching allow you to replace parts of your system with fake objects, isolating your tests from external dependencies. Parameterization, implemented using pytest.mark.parametrize, enables running the same test with multiple sets of inputs and expected outputs.

In conclusion, leveraging Nox and pytest for testing offers numerous advantages for developers who strive to improve code reliability and automate their testing workflows. By harnessing Nox’s exceptional configurability and pytest’s extensive testing features, you’ll establish a robust testing environment that bolsters code quality and ensures optimal performance.

🏷️ 7. Versioningit: version management with Git tags #

(Optional, only related when making a Python package)

For developers seeking an automated and customizable package versioning solution, Versioningit offers a powerful yet flexible approach. It is a setuptools plugin that automatically determines your package’s version based on your version control repository’s tags. The real advantage of Versioningit lies in its ability to customize the version format and even override separate functions used for version extraction and calculation.

Versioningit makes your release workflow extremely simple, especially if you have set up an automated build and twine PyPI upload pipeline. To create a new release, you only need to tag a version, and then click on the “Release” button in GitHub.

One of the major advantages of Versioningit is its minimal boilerplate code compared to other tools like Versioneer. Additionally, the Python __version__ string works seamlessly with editable installs (pip install -e .), unlike setuptools_scm, which is a common issue faced by developers.

Over the years, I have explored many options for package versioning, including Versioneer, Miniver, setuptools_scm, bumpversion (or bump2version), and manually setting everything. Versioningit stands out due to its simplicity, customization options, and compatibility with various workflows.

Some key features of Versioningit include:

Support for Git, modern Git archives, and Mercurial
Customizable version formatting using template strings
Optional writing of the final version and other details to a file for loading at runtime
Custom setuptools commands for inserting the final version and other details into a source file at build time
Customizable functions for VCS querying, tag-to-version calculation, version bumping, version formatting, and writing the version to a file

To use Versioningit in your project, simply add it to your project’s pyproject.toml file in the build-system.requires key. Then, create a [tool.versioningit] table in your pyproject.toml file. You can get up and running with just the minimal configuration - an empty table.

Once you have a [tool.versioningit] table in your pyproject.toml and your repository has at least one tag, building your project with setuptools will automatically set your project’s version based on the latest tag in your Git repository. With Versioningit, you can customize the version format using placeholder strings, making it adaptable to your project’s specific needs.

In summary, Versioningit streamlines the package versioning process and simplifies the release workflow. By automating package versioning based on version control repository tags and providing extensive customization options, it helps make the management of package versions more efficient and less error-prone.

📝 8. Pyproject.toml and PEP 621: Configuration Consolidation #

The pyproject.toml file plays a crucial role in consolidating configurations and setup for various tools in a Python project, such as Black, Ruff, Mypy, Versioningit, Nox, and pytest. This adherence to PEP 621 standards streamlines the development process by providing a single source of truth for multiple tools, eliminating the need for additional configuration files like setup.cfg or setup.py.

By specifying packaging details directly in the pyproject.toml file, you can efficiently manage your project’s dependencies and metadata. For example, the Adaptive Scheduler package demonstrates this approach with a comprehensive pyproject.toml file containing all the necessary configurations.

(click to unfold):

[build-system]
build-backend = "setuptools.build_meta"
requires = ["setuptools", "wheel", "versioningit"]

[project]
name = "adaptive_scheduler"
description = "Run many `adaptive.Learner`s on many cores (>10k) using `mpi4py.futures`, `ipyparallel`, `dask-mpi`, or `process-pool`."
requires-python = ">=3.8"
dynamic = ["version"]
maintainers = [{ name = "Bas Nijholt", email = "bas@nijho.lt" }]
license = { text = "BSD-3" }
classifiers = [
 "Development Status :: 2 - Pre-Alpha",
 "Intended Audience :: Developers",
 "Intended Audience :: Science/Research",
 "License :: OSI Approved :: BSD License",
 "Operating System :: OS Independent",
 "Programming Language :: Python",
 "Programming Language :: Python :: 3",
 "Programming Language :: Python :: 3.8",
 "Programming Language :: Python :: 3.9",
 "Programming Language :: Python :: 3.10",
 "Programming Language :: Python :: 3.11",
 "Topic :: Scientific/Engineering",
 "Topic :: System :: Distributed Computing",
]
dependencies = [
 "adaptive >= 0.14.1",
 "cloudpickle",
 "dill",
 "ipyparallel",
 "ipywidgets",
 "itables",
 "jinja2",
 "loky",
 "numpy",
 "pandas",
 "psutil",
 "pyarrow",
 "pyzmq",
 "rich",
 "structlog",
 "tinydb",
 "toolz",
 "tqdm",
 "versioningit",
]
[project.optional-dependencies]
all = ["dask-mpi", "mpi4py"]
test = ["pytest", "pytest-asyncio", "coverage", "pytest-cov"]
docs = [
 "myst-nb",
 "sphinx_fontawesome",
 "sphinx",
 "furo",
 "myst-parser",
 "emoji",
]
[project.urls]
homepage = "https://adaptive-scheduler.readthedocs.io/"
documentation = "https://adaptive-scheduler.readthedocs.io/"
repository = "https://github.com/basnijholt/adaptive-scheduler"

[project.readme]
content-type = "text/x-rst"
file = "README.rst"

[project.scripts]
adaptive-scheduler-launcher = "adaptive_scheduler._server_support.launcher:main"

[tool.versioningit]

[tool.versioningit.onbuild]
build-file = "adaptive_scheduler/_version.py"
source-file = "adaptive_scheduler/_version.py"

[tool.setuptools.packages.find]
include = ["adaptive_scheduler.*", "adaptive_scheduler"]

[tool.pytest.ini_options]
addopts = """
 -vvv
 --cov=adaptive_scheduler
 --cov-report term
 --cov-report html
 --cov-report xml
 --cov-fail-under=35
 --asyncio-mode=auto
"""

[tool.coverage.report]
exclude_lines = [
 "pragma: no cover",
 "raise NotImplementedError",
 "if TYPE_CHECKING:",
 "if __name__ == .__main__.:",
]

[tool.black]
line_length = 88

[tool.ruff]
line-length = 150
target-version = "py38"
select = ["ALL"]
ignore = [
 "T20", # flake8-print
 "ANN101", # Missing type annotation for {name} in method
 "S101", # Use of assert detected
 "PD901", # df is a bad variable name. Be kinder to your future self.
 "ANN401", # Dynamically typed expressions (typing.Any) are disallowed in {name}
 "D402", # First line should not be the function's signature
 "PLW0603", # Using the global statement to update `X` is discouraged
 "D401", # First line of docstring should be in imperative mood
 "SLF001", # Private member accessed
]

[tool.ruff.per-file-ignores]
"tests/*" = ["SLF001"]
"tests/test_examples.py" = ["E501"]
".github/*" = ["INP001"]

[tool.ruff.mccabe]
max-complexity = 18

[tool.mypy]
python_version = "3.8"

(from here)

As seen in the example, the pyproject.toml file includes details about the build system, project metadata, dependencies, optional dependencies, URLs, and configurations for various tools such as Versioningit, setuptools, pytest, coverage, Black, Ruff, and Mypy. By consolidating these configurations, you can maintain a more organized and maintainable project, making it easier to understand and update settings for different tools.

In summary, the pyproject.toml file and adherence to PEP 621 provide a unified approach to configuring and setting up your Python project, making it easier to manage dependencies, metadata, and tool-specific settings. This streamlined process ultimately leads to a more efficient and maintainable development workflow.

🌐 9. GitHub Actions CI Matrix: Testing on Multiple Platforms and Auto Publishing to PyPI #

GitHub Actions is an excellent tool for automating workflows and improving code quality through continuous integration (CI). By using a CI matrix, you can test your code on multiple platforms and Python versions, ensuring that your package remains compatible and stable across different environments.

To set up a .github/workflows/nox.yaml file for GitHub Actions, you can use the following simplified example:

name: nox

on:
 pull_request:
 push:
 branches: [main]

jobs:
 test:
 runs-on: ${{ matrix.platform }}
 strategy:
 fail-fast: false
 matrix:
 platform: [ubuntu-latest, macos-latest, windows-latest]
 python-version: ["3.8", "3.9", "3.10", "3.11"]

 steps:
 - uses: actions/checkout@v2
 - name: Set up Python ${{ matrix.python-version }}
 uses: actions/setup-python@v2
 with:
 python-version: ${{ matrix.python-version }}
 - name: Install dependencies
 run: pip install nox
 - name: Test with nox
 run: nox -e py${{ matrix.python-version }}

This configuration file specifies the platforms and Python versions for testing, as well as the steps to set up the environment, install dependencies, and run tests using nox. With this simple configuration, you set up tests on MacOS, Windows, Linux, and multiple Python versions, ensuring that your package remains compatible across different environments.

Another essential part of the CI/CD process is deploying your Python package. You can use the .github/workflows/publish-package.yaml file to automate the package deployment to PyPI whenever a new release is published:

name: Upload Python Package

on:
 release:
 types: [published]

jobs:
 deploy:

 runs-on: ubuntu-latest

 steps:
 - uses: actions/checkout@v2
 - name: Set up Python
 uses: actions/setup-python@v2
 with:
 python-version: '3.x'
 - name: Install dependencies
 run: |
 python -m pip install --upgrade pip
 pip install setuptools wheel twine build
 - name: Build and publish
 env:
 TWINE_USERNAME: __token__
 TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
 run: |
 python -m build
 twine upload dist/*

This workflow sets up Python, installs necessary dependencies, builds the package, and publishes it to PyPI using Twine. The process integrates seamlessly with versioningit, ensuring that the published package has the correct version number based on the git history.

In summary, leveraging GitHub Actions for continuous integration and automated workflows enhances code quality and reliability, while also simplifying the development and deployment processes. By testing across various platforms and Python versions, and automating package deployment, you can be confident that your package is well-maintained and accessible to users.

📚 10. Read the Docs, Sphinx, MyST-NB, and Jupytext notebooks for documentation #

Documentation is crucial for any software project, as it helps users understand how to use the package and provides guidance for contributors. Read the Docs, Sphinx, MyST-NB, and Jupytext notebooks are powerful tools that, when combined, facilitate the creation and maintenance of high-quality documentation.

tl;dr: check out the Adaptive documentation for an example of how to use these tools to create a comprehensive documentation website.

Read the Docs is a documentation hosting platform that automatically builds, version controls, and hosts your documentation for free. It integrates well with Sphinx and GitHub, allowing your documentation to be updated whenever you push changes to your repository.

Sphinx is a documentation generator that can transform reStructuredText files, MyST files, or Jupyter notebooks into various output formats, such as HTML, LaTeX, or PDF. It is highly extensible, supporting custom themes and plugins, and can automatically generate API documentation from your Python code.

MyST-NB is an extension to Sphinx that enables it to parse Jupyter notebooks and execute the code cells during the build process. It uses the MyST (short for Markedly Structured Text) markdown parser, which adds support for Sphinx roles and directives, making it a powerful alternative to reStructuredText.

Jupytext notebooks is a Jupyter extension that enables you to save Jupyter notebooks in Markdown format (or other text-based formats) instead of the default JSON format. By using Jupytext notebooks, you can store your code, explanations, and visualizations as plain text, which is easier to version control and can be seamlessly integrated with MyST-NB and Sphinx.

With MyST-NB and Jupytext, you can write your documentation using Jupyter notebooks in Markdown format. This approach combines the benefits of Jupyter notebooks, such as interactive code execution and rich output, with the simplicity of Markdown and the powerful features of Sphinx. The result is a highly readable, user-friendly, and maintainable documentation that caters to both users and developers.

To get started with MyST-NB, you’ll need to install it using pip:

pip install myst-nb

Next, configure your Sphinx project to use MyST-NB by adding the following lines to your conf.py file:

extensions = [
 "myst_nb",
]

Now, Sphinx will be able to parse and execute your Jupyter notebooks during the documentation build process, integrating them seamlessly with your existing documentation.

In summary, using Read the Docs, Sphinx, MyST-NB, and Jupytext notebooks for your documentation enables you to create high-quality, interactive, and easily maintainable documentation that benefits your project’s users and contributors. This combination of tools ensures that your documentation remains up-to-date, easily navigable, and engaging, ultimately enhancing the overall experience for your project’s audience.

For a full example, see how I setup Adaptive’s documentation using Sphinx, MyST-NB, and Jupytext notebooks. readthedocs.yaml, docs/source/conf.py, and here is an example notebook that is used in the documentation: docs/source/tutorial/tutorial.Learner1D.md

🎉 11. Conclusion #

In conclusion, incorporating these powerful tools into your Python development workflow can significantly enhance your productivity and code quality. By adopting pre-commit, Black, Ruff, Mypy, Versioningit, Pyproject.toml with PEP 621, Nox, pytest, GitHub Actions CI matrix, and Read the Docs, Sphinx, MyST-NB, and Jupytext notebooks for documentation, you create a streamlined, efficient, and reliable development environment.

These tools help maintain code consistency, catch issues early, automate package versioning, simplify testing, consolidate configurations, and create high-quality documentation. By integrating them into your projects, you can focus on writing great code while ensuring that your work remains robust, maintainable, and accessible to users and contributors alike.

Don’t hesitate to explore these tools and incorporate them into your Python development toolkit. They can transform your development experience, making it more enjoyable and efficient, ultimately leading to higher-quality projects and happier developers. Happy coding!

Crafting unique Ph.D. thesis covers with Python 🎨

Sat, 04 Apr 2020 13:40:00 +0000

Originally posted on quantumtinkerer.tudelft.nl/blog/thesis-cover on 2020-04-04 13:40.

I will hand out around a hundred copies of my thesis to my defense committee, colleagues, and my family and friends. Let’s be honest, most people will probably not get further than attempting to read the summary and appreciating the cover. Four years of work has gone into generating the content of the thesis, so I figured, at least some thought has to go into the design of its cover. Unfortunately, I am by no means an expert on a graphical design or even competent enough to attempt to use any kind of graphic design software. But luckily for me, I do consider myself an expert in Python , and why not make the thesis design a fun process?

Initial Design: Adaptive Sampling and Data Visualization #

My vague plan was to somehow incorporate a plot resulting from a simulation run with Adaptive [source ], the software I wrote during my Ph.D. to adaptively sample functions in parallel and my proudest work. I even had a potential simulation result in mind that I would use for it, specifically, one that has been on the background of my good friend’s phone for some years and one that has earned me quite some internet points on Reddit. This plot (below) is one of the results of Chapter 4 of my thesis [source ] and this paper.

Your browser does not support the video tag.

I went back to the code that generates the plot and started hacking away in Matplotlib. Quickly, I realized that not only the plot above was going to look cool, but that many other data sets that I had also resulted in beautiful patterns. I hit the paradox of choice: I had a total of 3671 unique data sets (all for Majorana devices with either different parameter sweeps or different physical effects that were included in the model) and no idea how I was going to make a selection.

This is an early attempt (and rather ugly in hindsight)

I decided to postpone the choice of which data to use and just focus on how to plot the data first. I experimented with different colormaps, fading colormaps that gradually reveal the underlying triangulation better, and more. On a weekend night, after telling a friend I was with about my plans, we (as usually happens) started to program some of the ideas we came up with. We settled on a design where the triangulation would slowly fade from the top to bottom and where each triangle simultaneously transitioned from a solid color (the average of the values at its vertices) to densely interpolated values. See this Jupyter notebook which generated the final version of the cover. After we also chose a nice colormap (by simply creating the cover for each possible colormap,) the following was suggested: “You know what would be even cooler?! To make every cover unique.” Ten minutes later, I had started 3671 jobs on our computational cluster. When the files slowly started to appear on my computer (I have my local files synced with the cluster), we could not have been more excited. There were simply so many cool looking alternatives. Too many to manually select now, to be honest—a problem for later I thought.

Overcoming the Paradox of Choice: Clustering and Neural Networks #

Four months later, with the rest of my thesis completely done and about a day left on the deadline to submit my thesis, I found myself facing the selection problem I had successfully ignored for so long. There must be a smarter way to select the covers, I thought. Many of them look roughly similar (and some of them are even quite boring or not ecstatically pleasing), so it does not make sense to scroll through all of them. I could cluster them by similarity and then I would just have to choose the nicely looking clusters while being able to instantly discard many.

Finally, a good application to use neural networks!

I still had the 3671 covers in pdf format in some folder, so using the wonderful GNU Parallel, I converted and rasterized all of them to jpeg with

find . -iname \*pdf -print0 | parallel -0 sips -s format jpeg {} --out {.}.jpg

Then I used a pre-trained convolutional neural network model (VGG16) to extract features in a lower-dimensional representation. I fed the feature arrays to a K-Means clustering algorithm that sorted them in 80 clusters. To procrastinate a little more, I created an interactive widget using ipywidgets (see video below) to facilitate the selection process.

Your browser does not support the video tag.

These are the clusters that I selected in a grid

The selection process was done using this Jupyter notebook.

Finally, I copied the selected clusters into different folders and used the OS’s file explorer to manually select a few covers from each cluster.

Final Touches: Fine-Tuning Colors and Adding Edition Numbers #

Then I printed an initial version of my thesis, however, I wasn’t really happy with the colors.

To choose the right color scheme I got help from a non-tech savvy friend who went to art school. Due to the COVID-19 crisis, we couldn’t sit side by side, so I created this Binder “app” with sliders.

Your browser does not support the video tag.

Additionally, since all of them were different anyway, I gave them an identifier and added

edition n of 120

to the back.

These are a few examples of the final result (click on one of the images to open gallery view)

A few days later, this was delivered to my doorstep

And finally I mailed them to my Ph.D. committee

Now it’s time to start preparing for my defense at May 11, 2020 at 15:00!

Notes #

The data and code to generate all printed covers is available at basnijholt/thesis-cover
The simulation code that generates the data is available at basnijholt/spin-orbit-nanowires
The video of the Reddit post is generated using this code

Software Development | 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 #

Why Docker isn't an AI-safe sandbox anymore, and how I fixed it in MindRoom 🔒

What the kernel actually does #

A container is a process in a costume #

Why kernel bugs are a bigger problem now #

So I asked a model to break out #

Stronger walls: virtual machines #

Kata Containers and gVisor #

The PR: six lines #

What it costs #

What this does not fix #

Conclusion #

Giving models the tools they were trained with can make them worse

What a harness is #

Why I believed it #

Smaller agents do better #

Models should know their own tools best #

What I built #

How I measured it #

Native tools don’t make today’s models more efficient #

Older models: only Opus 4.8 did better with them #

What does matter: what the agent sends #

Fewer tools #

Minimal mode: one shell tool and a 12-line prompt #

Minimal mode with each model’s native shell tool #

What this does and does not show #

What happens to the pull request #

Why this excites me #

Appendix: how I measured, and the numbers behind the charts #

Exploring the Jev hype in MindRoom

What a System One model is #

Adaptive participation #

“Thanks” should not stop the agent #

Picking the responder #

One config line to switch #

A third backend: OpenAI Decisions #

Named after Jevons #

Removing the guardrails and letting my coding agents loose

Why hooks and not AGENTS.md #

What I block #

The override #

When the override was used without approval #

Working from my phone #

Not much has changed #

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 #

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 #

6. Layer 4: `agent-cli` Server #