Building Piclaw on Top of an Opinionated Coding Agent - Tao of Mac
Rui Carmo
Tao of Mac
Aug 21st 2026 · 15 min read
·<br>#agents #ai #architecture #arm64 #bun #pi #piclaw #typescript
Building Piclaw on Top of an Opinionated Coding Agent
I’ve spent the better part of six months building piclaw–my personal AI assistant, workspace and, occasionally, agent swarm–on top of Mario Zechner’s pi engine, and I think it’s time to write about not just my motivation but also how I feel about having invested that much time into the whole thing.
This is important (at least to me) because pi is an excellent coding agent with a very clear point of view about how things should work. The internals are concise, well structured and easy to follow, with the brilliant twist that extensions can literally take over the entire thing–to the point where you can pretty much rewrite the entire agent loop (however you care to define loop these days).
Building a different kind of UI on top of it has been educational, very rewarding and occasionally maddening, and I’ve reached the point where I need to write down what I’ve learned and a lot of the underlying rationale–partly because I just want to use the thing now and move on, and partly because there’s a lot buried in the project documentation itself (there are a lot of whats and hows, but relatively few whys).
Why pi?
The key thing that captivated me is that pi is, in effect, a self-modifying agent harness.
Yes, self-modifying. Like… a virus. I like to think that its virality (however you cast it) is one of the unstated reasons it has found its way into a lot of projects lately, but let’s skip that bit and just reframe “self-modifying” as both self-improving and self-evolving without dipping too much into the penny arcade theatrics of AGI.
I’ve come to the point where I think that even without agency, self-modifying harnesses like pi are way more powerful than just about anything we’re getting from megacorps, because they can morph into your own completely personalised environment–which is what piclaw became for me.
When I started out fooling around with what eventually became steward, the field of open coding agents was a mess of half-finished Python scripts and VS Code forks, and pi stood out because it was opinionated in the right ways: TypeScript as the runtime, a clean turn-based conversation model, good terminal UX and–critically–a willingness to evolve quickly. Mario Zechner made strong choices about tool calling, context management and model interaction, and they were essentially the right ones.
And if you take the essential bit literally, the thing pi got most right was restraint. Or, if you have been following the philosophical debate about AI use, taste.
At the risk of reiterating the basics most people already know about pi, it starts with a small, carefully chosen set of built-in tools–file I/O, shell, search and editing–and leaves the LLM to fend for itself in UNIX land, which gives it tremendous power and flexibility.
Compare that with what AI lab harnesses are becoming: sprawling collections of specialised tools, bespoke UI panels, inline diffs, notebook integrations, code review modes and whatever else someone thought of that quarter week. Every one of those features eats context, adds latency and makes prompts longer–which means the model has less room to think about your actual problem.
pi starts from the other end: give the model the minimum surface it needs to be effective and spend the rest of the token budget on the actual problems at hand. The introspection is excellent too–you can see what the model is doing, which tools it is calling and what the context looks like at any point. No magic, no hidden system prompts, no mystery. That transparency is worth more to me than feature polish, because it means I can debug things when they go wrong.
I didn’t necessarily want just a coding agent, though, and after a while, I realised I didn’t even want to run it in a terminal. I wanted an extensible agent that could run headless, manage my homelab, edit my wiki, file links, take notes, run scheduled tasks, and generally be useful in ways that might only occasionally have to do with writing code.
pi’s small tool surface and clean turn model were close enough to what I needed that building on top of it seemed faster than starting from scratch.
Escaping The Terminal
As I’ve written many times before, I don’t run coding agents locally–that’s why I spent quite some time coming up with things like agentbox and webterm to run them in remote machines.
But the biggest departure from pi came from using it inside vibes, which started out as a generic web UI that I could use from my phone. And with my mobile background, it was pretty obvious (at least to me) that a highly optimised web UI was vastly better than using WhatsApp or Telegram as a bridge–not only could I make it much more secure over Tailscale (without any middlemen), but I could build a...