Peter Steinberger

OpenClaw, OpenAI and the future

Sun, 15 Feb 2026 00:00:00 +0000

tl;dr: I’m joining OpenAI to work on bringing agents to everyone. OpenClaw will move to a foundation and stay open and independent.

The last month was a whirlwind, never would I have expected that my playground project would create such waves. The internet got weird again, and it’s been incredibly fun to see how my work inspired so many people around the world.

There’s an endless array of possibilities that opened up for me, countless people trying to push me into various directions, giving me advice, asking how they can invest or what I will do. Saying it’s overwhelming is an understatement.

When I started exploring AI, my goal was to have fun and inspire people. And here we are, the lobster is taking over the world. My next mission is to build an agent that even my mum can use. That’ll need a much broader change, a lot more thought on how to do it safely, and access to the very latest models and research.

Yes, I could totally see how OpenClaw could become a huge company. And no, it’s not really exciting for me. I’m a builder at heart. I did the whole creating-a-company game already, poured 13 years of my life into it and learned a lot. What I want is to change the world, not build a large company and teaming up with OpenAI is the fastest way to bring this to everyone.

I spent last week in San Francisco talking with the major labs, getting access to people and unreleased research, and it’s been inspiring on all fronts. I want to thank all the folks I talked to this week and am thankful for the opportunities.

It’s always been important to me that OpenClaw stays open source and given the freedom to flourish. Ultimately, I felt OpenAI was the best place to continue pushing on my vision and expand its reach. The more I talked with the people there, the clearer it became that we both share the same vision.

The community around OpenClaw is something magical and OpenAI has made strong commitments to enable me to dedicate my time to it and already sponsors the project. To get this into a proper structure I’m working on making it a foundation. It will stay a place for thinkers, hackers and people that want a way to own their data, with the goal of supporting even more models and companies.

Personally I’m super excited to join OpenAI, be part of the frontier of AI research and development, and continue building with all of you.

The claw is the law.

Shipping at Inference-Speed

Sun, 28 Dec 2025 11:00:00 +0000

What Changed Since May

It’s incredible how far “vibe coding” has come this year. Whereas in ~May I was amazed that some prompts produced code that worked out of the box, this is now my expectation. I can ship code now at a speed that seems unreal. I burned a lot of tokens since then. Time for an update.

It’s funny how these agents work. There’s been this argument a few weeks ago that one needs to write code in order to feel bad architecture and that using agents creates a disconnection - and I couldn’t disagree more. When you spend enough time with agents, you know exactly how long sth should take, and when codex comes back and hasn’t solved it in one shot, I already get suspicious.

The amount of software I can create is now mostly limited by inference time and hard thinking. And let’s be honest - most software does not require hard thinking. Most apps shove data from one form to another, maybe store it somewhere, and then show it to the user in some way or another. The simplest form is text, so by default, whatever I wanna build, it starts as CLI. Agents can call it directly and verify output - closing the loop.

The Model Shift

The real unlock into building like a factory was GPT 5. It took me a few weeks after the release to see it - and for codex to catch up on features that claude code had, and a bit to learn and understand the differences, but then I started trusting the model more and more. These days I don’t read much code anymore. I watch the stream and sometimes look at key parts, but I gotta be honest - most code I don’t read. I do know where which components are and how things are structured and how the overall system is designed, and that’s usually all that’s needed.

The important decisions these days are language/ecosystem and dependencies. My go-to languages are TypeScript for web stuff, Go for CLIs and Swift if it needs to use macOS stuff or has UI. Go wasn’t something I gave even the slightest thought even a few months ago, but eventually I played around and found that agents are really great at writing it, and its simple type system makes linting fast.

Folks building Mac or iOS stuff: You don’t need Xcode much anymore. I don’t even use xcodeproj files. Swift’s build infra is good enough for most things these days. codex knows how to run iOS apps and how to deal with the Simulator. No special stuff or MCPs needed.

codex vs Opus

I’m writing this post here while codex crunches through a huge, multi-hour refactor and un-slops older crimes of Opus 4.0. People on Twitter often ask me what’s the big difference between Opus and codex and why it even matters because the benchmarks are so close. IMO it’s getting harder and harder to trust benchmarks - you need to try both to really understand. Whatever OpenAI did in post-training, codex has been trained to read LOTS of code before starting.

Sometimes it just silently reads files for 10, 15 minutes before starting to write any code. On the one hand that’s annoying, on the other hand that’s amazing because it greatly increases the chance that it fixes the right thing. Opus on the other hand is much more eager - great for smaller edits - not so good for larger features or refactors, it often doesn’t read the whole file or misses parts and then delivers inefficient outcomes or misses sth. I noticed that even tho codex sometimes takes 4x longer than Opus for comparable tasks, I’m often faster because I don’t have to go back and fix the fix, sth that felt quite normal when I was still using Claude Code.

codex also allowed me to unlearn lots of charades that were necessary with Claude Code. Instead of “plan mode”, I simply start a conversation with the model, ask a question, let it google, explore code, create a plan together, and when I’m happy with what I see, I write “build” or “write plan to docs/*.md and build this”. Plan mode feels like a hack that was necessary for older generations of models that were not great at adhering to prompts, so we had to take away their edit tools. There’s a highly misunderstood tweet of mine that’s still circling around that showed me that most people don’t get that plan mode is not magic.

Oracle

The step from GPT 5/5.1 to 5.2 was massive. I built oracle 🧿 about a month ago - it’s a CLI that allows the agent to run GPT 5 Pro and upload files + a prompt and manages sessions so answers can be retrieved later. I did this because many times when agents were stuck, I asked it to write everything into a markdown file and then did the query myself, and that felt like a repetitive waste of time - and an opportunity to close the loop. The instructions are in my global AGENTS.MD file and the model sometimes by itself triggered oracle when it got stuck. I used this multiple times per day. It was a massive unlock. Pro is insanely good at doing a speedrun across ~50 websites and then thinking really hard at it and in almost every case nailed the response. Sometimes it’s fast and takes 10 minutes, but I had runs that took more than an hour.

Now that GPT 5.2 is out, I have far fewer situations where I need it. I do use Pro myself sometimes for research, but the cases where I asked the model to “ask the oracle” went from multiple times per day to a few times per week. I’m not mad about this - building oracle was super fun and I learned lots about browser automation, Windows and finally took my time to look into skills, after dismissing that idea for quite some time. What it does show is how much better 5.2 got for many real-life coding tasks. It one-shots almost anything I throw at it.

Another massive win is the knowledge cutoff date. GPT 5.2 goes till end of August whereas Opus is stuck in mid-March - that’s about 5 months. Which is significant when you wanna use the latest available tools.

A Concrete Example: VibeTunnel

To give you another example on how far models have come. One of my early intense projects was VibeTunnel. A terminal-multiplexer so you can code on-the-go. I poured pretty much all my time into this earlier this year, and after 2 months it was so good that I caught myself coding from my phone while out with friends… and decided that this is something I should stop, more for mental health than anything. Back then I tried to rewrite a core part of the multiplexer away from TypeScript, and the older models consistently failed me. I tried Rust, Go… god forbid, even zig. Of course I could have finished this refactor, but it would have required lots of manual work, so I never got around completing this before I put it to rest. Last week I un-dusted this and gave codex a two sentence prompt to convert the whole forwarding-system to zig, and it ran over 5h and multiple compactions and delivered a working conversion in one shot.

Why did I even un-dust it, you ask? My current focus is Clawdis, an AI assistant that has full access to everything on all my computers, messages, emails, home automation, cameras, lights, music, heck it can even control the temperature of my bed. Ofc it also has its own voice, a CLI to tweet and its own clawd.bot.

Clawd can see and control my screen and sometimes makes snarky remarks, but I also wanted to give him the ability to check on my agents, and getting a character stream is just far more efficient than looking at images… if this will work out, we’ll see!

My Workflow

I know… you came here to learn how to build faster, and I’m just writing a marketing-pitch for OpenAI. I hope Anthropic is cooking Opus 5 and the tides turn again. Competition is good! At the same time, I love Opus as general purpose model. My AI agent wouldn’t be half as fun running on GPT 5. Opus has something special that makes it a delight to work with. I use it for most of my computer automation tasks and ofc it powers Clawd🦞.

I haven’t changed my workflow all that much from my last take at it in October.

I usually work on multiple projects at the same time. Depending on complexity that can be between 3-8. The context switching can be tiresome, I really only can do that when I’m working at home, in silence and concentrated. It’s a lot of mental models to shuffle. Luckily most software is boring. Creating a CLI to check up on your food delivery doesn’t need a lot of thinking. Usually my focus is on one big project and satellite projects that chug along. When you do enough agentic engineering, you develop a feeling for what’s gonna be easy and where the model likely will struggle, so often I just put in a prompt, codex will chug along for 30 minutes and I have what I need. Sometimes it takes a little fiddling or creativity, but often things are straightforward.
I extensively use the queueing feature of codex - as I get a new idea, I add it to the pipeline. I see many folks experimenting with various systems of multi-agent orchestration, emails or automatic task management - so far I don’t see much need for this - usually I’m the bottleneck. My approach to building software is very iterative. I build sth, play with it, see how it “feels”, and then get new ideas to refine it. Rarely do I have a complete picture of what I want in my head. Sure, I have a rough idea, but often that drastically changes as I explore the problem domain. So systems that take the complete idea as input and then deliver output wouldn’t work well for me. I need to play with it, touch it, feel it, see it, that’s how I evolve it.
I basically never revert or use checkpointing. If something isn’t how I like it, I ask the model to change it. codex sometimes then resets a file, but often it simply reverts or modifies the edits, very rare that I have to back completely, and instead we just travel into a different direction. Building software is like walking up a mountain. You don’t go straight up, you circle around it and take turns, sometimes you get off path and have to walk a bit back, and it’s imperfect, but eventually you get to where you need to be.
I simply commit to main. Sometimes codex decides that it’s too messy and automatically creates a worktree and then merges changes back, but it’s rare and I only prompt that in exceptional cases. I find the added cognitive load of having to think of different states in my projects unnecessary and prefer to evolve it linearly. Bigger tasks I keep for moments where I’m distracted - for example while writing this, I run refactors on 4 projects here that will take around 1-2h each to complete. Ofc I could do that in a worktree, but that would just cause lots of merge conflicts and suboptimal refactors. Caveat: I usually work alone, if you work in a bigger team that workflow obv won’t fly.
I’ve already mentioned my way of planning a feature. I cross-reference projects all the time, esp if I know that I already solved sth somewhere else, I ask codex to look in ../project-folder and that’s usually enough for it to infer from context where to look. This is extremely useful to save on prompts. I can just write “look at ../vibetunnel and do the same for Sparkle changelogs”, because it’s already solved there and with a 99% guarantee it’ll correctly copy things over and adapt to the new project. That’s how I scaffold new projects as well.
I’ve seen plenty of systems for folks wanting to refer to past sessions. Another thing I never need or use. I maintain docs for subsystems and features in a docs folder in each project, and use a script + some instructions in my global AGENTS file to force the model to read docs on certain topics. This pays off more the larger the project is, so I don’t use it everywhere, but it is of great help to keep docs up-to-date and engineer a better context for my tasks.
Apropos context. I used to be really diligent to restart a session for new tasks. With GPT 5.2 this is no longer needed. Performance is extremely good even when the context is fuller, and often it helps with speed since the model works faster when it already has loaded plenty files. Obviously that only works well when you serialize your tasks or keep the changes so far apart that two sessions don’t touch each other much. codex has no system events for “this file changed”, unlike claude code, so you need to be more careful - on the flip side, codex is just FAR better at context management, I feel I get 5x more done on one codex session than with claude. This is more than just the objectively larger context size, there’s other things at work. My guess is that codex internally thinks really condensed to save tokens, whereas Opus is very wordy. Sometimes the model messes up and its internal thinking stream leaks to the user, so I’ve seen this quite a few times. Really, codex has a way with words I find strangely entertaining.
Prompts. I used to write long, elaborate prompts with voice dictation. With codex, my prompts gotten much shorter, I often type again, and many times I add images, especially when iterating on UI (or text copies with CLIs). If you show the model what’s wrong, just a few words are enough to make it do what you want. Yes, I’m that person that drags in a clipped image of some UI component with “fix padding” or “redesign”, many times that either solves my issue or gets me reasonably far. I used to refer to markdown files, but with my docs:list script that’s no longer necessary.
Markdowns. Many times I write “write docs to docs/*.md” and simply let the model pick a filename. The more obvious you design the structure for what the model is trained on, the easier your work will be. After all, I don’t design codebases to be easy to navigate for me, I engineer them so agents can work in it efficiently. Fighting the model is often a waste of time and tokens.

Tooling & Infrastructure

What’s still hard? Picking the right dependency and framework to set on is something I invest quite some time on. Is this well-maintained? How about peer dependencies? Is it popular = will have enough world knowledge so agents have an easy time? Equally, system design. Will we communicate via web sockets? HTML? What do I put into the server and what into the client? How and which data flows where to where? Often these are things that are a bit harder to explain to a model and where research and thinking pays off.
Since I manage lots of projects, often I let an agent simply run in my project folder and when I figure out a new pattern, I ask it to “find all my recent go projects and implement this change there too + update changelog”. Each of my project has a raised patch version in that file and when I revisit it, some improvements are already waiting for me to test.
Ofc I automate everything. There’s a skill to register domains and change DNS. One to write good frontends. There’s a note in my AGENTS file about my tailscale network so I can just say “go to my mac studio and update xxx”.
Apropos multiple Macs. I usually work on two Macs. My MacBook Pro on the big screen, and a Jump Desktop session to my Mac Studio on another screen. Some projects are cooking there, some here. Sometimes I edit different parts of the same project on each machine and sync via git. Simpler than worktrees because drifts on main are easy to reconcile. Has the added benefit that anything that needs UI or browser automation I can move to my Studio and it won’t annoy me with popups. (Yes, Playwright has headless mode but there’s enough situations where that won’t work)
Another benefit is that tasks keep running there, so whenever I travel, remote becomes my main workstation and tasks simply keep running even if I close my Mac. I did experiment with real async agents like codex or Cursor web in the past, but I miss the steerability, and ultimately the work ends up as pull request, which again adds complexity to my setup. I much prefer the simplicity of the terminal.
I used to play with slash commands, but just never found them too useful. Skills replaced some of it, and for the rest I keep writing “commit/push” because it takes the same time as /commit and always works.
In the past I often took dedicated days to refactor and clean up projects, I do this much more ad-hoc now. Whenever prompts start taking too long or I see sth ugly flying by in the code stream, I’ll deal with it right away.
I tried linear or other issue trackers, but nothing did stick. Important ideas I try right away, and everything else I’ll either remember or it wasn’t important. Of course I have public bug trackers for bugs for folks that use my open source code, but when I find a bug, I’ll immediately prompt it - much faster than writing it down and then later having to switch context back to it.
Whatever you build, start with the model and a CLI first. I had this idea of a Chrome extension to summarize YouTube vids in my head for a long time. Last week I started working on summarize, a CLI that converts anything to markdown and then feeds that to a model for summarization. First I got the core right, and once that worked great I built the whole extension in a day. I’m quite in love with it. Runs on local, free or paid models. Transcribes video or audio locally. Talks to a local daemon so it’s super fast. Give it a go!
My go-to model is gpt-5.2-codex high. Again, KISS. There’s very little benefit to xhigh other than it being far slower, and I don’t wanna spend time thinking about different modes or “ultrathink”. So pretty much everything runs on high. GPT 5.2 and codex are close enough that changing models makes no sense, so I just use that.

My Config

This is my ~/.codex/config.toml:

model = "gpt-5.2-codex"
model_reasoning_effort = "high"
tool_output_token_limit = 25000
# Leave room for native compaction near the 272–273k context window.
# Formula: 273000 - (tool_output_token_limit + 15000)
# With tool_output_token_limit=25000 ⇒ 273000 - (25000 + 15000) = 233000
model_auto_compact_token_limit = 233000
[features]
ghost_commit = false
unified_exec = true
apply_patch_freeform = true
web_search_request = true
skills = true
shell_snapshot = true

[projects."/Users/steipete/Projects"]
trust_level = "trusted"

This allows the model to read more in one go, the defaults are a bit small and can limit what it sees. It fails silently, which is a pain and something they’ll eventually fix. Also, web search is still not on by default? unified_exec replaced tmux and my old runner script, rest’s neat too. And don’t be scared about compaction, ever since OpenAI switched to their new /compact endpoint, this works well enough that tasks can run across many compacts and will be finished. It’ll make things slower, but often acts like a review, and the model will find bugs when it looks at code again.

That’s it, for now. I plan on writing more again and have quite a backlog on ideas in my head, just having too much fun building things. If you wanna hear more ramblings and ideas how to build in this new world, follow me on Twitter.

The Signature Flicker

Thu, 18 Dec 2025 00:00:00 +0000

tl;dr: Hell froze over. Anthropic fixed Claude Code’s signature flicker in their latest update (2.0.72)

If there’s one thing everybody noticed about Claude Code (apart from it revolutionizing how we build software), it’s the flickering. It’s unfair to point to Anthropic since they are not alone: other TUIs such as Cursor, or really anything based on Ink have the same issue. It’s also not an easy problem at all. Claude Code uses React under the hood.¹

The Issue

Terminals haven’t really been designed for interactivity. It’s possible to use ANSI escape codes to reposition the cursor and write over existing text, but that easily leads to flickering if not done well.

There are two ways to solve this:

Switch to alt mode and take complete control over the terminal viewport.
Carefully re-render changed parts while leaving the scrollback unchanged.

Neither option is great, and each comes with tradeoffs. Mario Zechner explains these really well in his write-up on building pi-coding-agent, so I won’t repeat the details here. I’ve spent time with option 2 myself, having ported pi-tui to Swift as TauTUI (Codex did most of the auto-translation).

For a coding agent that mostly emits text with limited interactivity, I believe carefully re-rendering only changed parts — while remaining a good terminal citizen — is the better approach.

Anthropic seems to agree. Ink, the React-based terminal renderer Claude Code originally used, didn’t support the kind of fine-grained incremental updates needed for a long-running interactive UI. This has since improved upstream, but Anthropic needed tighter control, so they rewrote the renderer from scratch — while still keeping React as the component model.

This is kind of like if a website were to do their own text rendering, highlighting, mouse movement, context menu, etc. — it would not feel like your browser. (…) We value this native experience a lot. We may explore alternate screen mode in the future, but our bar is quite high. — Thariq, Anthropic

The Landscape

Over the last year, most new coding agents have converged on alt-screen TUIs — often after fighting flicker — but the results haven’t been great. So what’s my big gripe with alt mode? It breaks features such as text selection, native scrolling or search. Of course this can be implemented in the TUI, but it won’t feel right.

Amp

Amp used Ink and shared Claude’s flickering but eventually wrote their own renderer, switching to alt mode in September.

find fails unless the text is currently on-screen
No native-feeling selection/context menu flow
Custom scrollbar; workable but not quite the terminal

Gemini

Google did a big announcement on their blog about their new alt-mode TUI, only to learn that users hate it and then rolled it back not even a week later. In the new TUI, you have to press CTRL-S to enter selection mode to copy text.

OpenCode

OpenCode did some great engineering and built opentui in TypeScript and Zig, which renders SolidJS or React. It’s not without downsides, e.g. it doesn’t work in the standard macOS Terminal for anything below macOS 26 or GNOME’s Terminal.

Auto-scroll near the viewport border makes small screens painful
No scrollbar; search doesn’t work the way you expect
Right click → paste into the input box doesn’t work

Codex

Compare to OpenAI’s Codex, which stays in the primary screen buffer and lets me interact with text just like I expect:

Codex isn’t perfect — it sometimes overwrites lines of text — but it already nails the part that matters most: it behaves like a terminal. That makes their current direction toward an alt-mode TUI feel like a regression, not an upgrade. Here’s hoping they reverse course.

pi

Mario Zechner’s pi is currently the gold-standard for differential rendering, while also using all tricks of modern terminals — including showing inline images:

Verdict

Claude Code and pi prove you can kill flicker without giving up the terminal’s muscle memory.

Alt mode can be great for dashboards. For coding agents, though, I want the terminal’s built-ins to stay native:

Select text like it’s a terminal
Scrollback like it’s a terminal
Search like it’s a terminal

It’s 2025. We can have smooth rendering and keep the terminal’s superpowers.

Yes, I made the same weird look when I first learned about this, but it’s kinda beautiful. React’s concepts are flexible enough that it doesn’t require a browser as a frontend — and Ink is such an alternative render backend. ↩

Just Talk To It - the no-bs Way of Agentic Engineering

Tue, 14 Oct 2025 09:00:00 +0000

I’ve been more quiet here lately as I’m knee-deep working on my latest project. Agentic engineering has become so good that it now writes pretty much 100% of my code. And yet I see so many folks trying to solve issues and generating these elaborated charades instead of getting sh*t done.

This post partly is inspired by the conversations I had at last night’s Claude Code Anonymous in London and partly since it’s been an AI year since my last workflow update. Time for a check-in.

All of the basic ideas still apply, so I won’t mention simple things like context management again. Read my Optimal AI Workflow post for a primer.

Context & Tech-Stack

I work by myself, current project is a ~300k LOC TypeScript React app, a Chrome extension, a cli, a client app in Tauri and a mobile app in Expo. I host on vercel, a PR delivers a new version of my website in ~2 minutes to test. Everything else (apps etc) is not automated.

Harness & General Approach

I’ve completely moved to codex cli as daily driver. I run between 3-8 in parallel in a 3x3 terminal grid, most of them in the same folder, some experiments go in separate folders. I experimented with worktrees, PRs but always revert back to this setup as it gets stuff done the fastest.

My agents do git atomic commits themselves. In order to maintain a mostly clean commit history, I iterated a lot on my agent file. This makes git ops sharper so each agent commits exactly the files it edited.

Yes, with claude you could do hooks and codex doesn’t support them yet, but models are incredibly clever and no hook will stop them if they are determined.

I was being ridiculed in the past and called a slop-generator, good to see that running parallel agents slowly gets mainstream.

Model Picker

I build pretty much everything with gpt-5-codex on mid settings. It’s a great compromise of smart & speed, and dials thinking up/down automatically. I found over-thinking these settings to not yield meaningful results, and it’s nice not having to think about ultrathink.

Blast Radius 💥

Whenever I work, I think about the “blast radius”. I didn’t come up with that term, I do love it tho. When I think of a change I have a pretty good feeling about how long it’ll take and how many files it will touch. I can throw many small bombs at my codebase or a one “Fat Man” and a few small ones. If you throw multiple large bombs, it’ll be impossible to do isolated commits, much harder to reset if sth goes wrong.

This is also a good indicator while I watch my agents. If something takes longer than I anticipated, I just hit escape and ask “what’s the status” to get a status update and then either help the model to find the right direction, abort or continue. Don’t be afraid of stopping models mid-way, file changes are atomic and they are really good at picking up where they stopped.

When I am unsure about the impact, I use “give me a few options before making changes” to gauge it.

Why not worktrees?

I run one dev server, as I evolve my project I click through it and test multiple changes at once. Having a tree/branch per change would make this significantly slower, spawning multiple dev servers would quickly get annoying. I also have limitations for Twitter OAuth, so I can only register some domains for callbacks.

What about Claude Code?

I used to love Claude Code, these days I can’t stand it anymore (even tho codex is a fan). It’s language, the absolutely right’s, the 100% production ready messages while tests fail - I just can’t anymore. Codex is more like the introverted engineer that chugs along and just gets stuff done. It reads much more files before starting work so even small prompts usually do exactly what I want.

There’s broad consensus in my timeline that codex is the way to go.

Other benefits of codex

~230k usable context vs claude’s 156k. Yes, there’s Sonnet 1Mio if you get lucky or pay API pricing, but realistically Claude gets very silly long before it depletes that context so it’s not realistically something you can use.
More efficient token use. Idk what OpenAI does different, but my context fills up far slower than with Claude Code. I used to see Compacting… all the time when using claude, I very rarely manage to exceed the context in codex.
Message Queuing. Codex allows to queue messages. Claude had this feature, but a few months ago they changed it so your messages “steer” the model. If I want to steer codex, I just press escape and enter to send the new message. Having the option for both is just far better. I often queue related feature tasks and it just reliably works them off.
Speed OpenAI rewrote codex in Rust, and it shows. It’s incredibly fast. With Claude Code I often have multi-second freezes and it’s process blows up to gigabytes of memory. And then there’s the terminal flickering, especially when using Ghostty. Codex has none of that. It feels incredibly lightweight and fast.
Language. This really makes a difference to my mental health. I’ve been screaming at claude so many times. I rarely get angry with codex. Even if codex would be a worse model I’d use it for that fact alone. If you use both for a few weeks you will understand.
No random markdown files everywhere. IYKYK.

Why not $harness

IMO there’s simply not much space between the end user and the model company. I get by far the best deal using a subscription. I currently have 4 OpenAI subs and 1 Anthropic sub, so my overall costs are around 1k/month for basically unlimited tokens. If I’d use API calls, that’d cost my around 10x more. Don’t nail me on this math, I used some token counting tools like ccusage and it’s all somewhat imprecise, but even if it’s just 5x it’s a damn good deal.

I like that we have tools like amp or Factory, I just don’t see them surviving long-term. Both codex and claude code are getting better with every release, and they all converge to the same ideas and feature set. Some might have a temporary edge with better todo lists, steering or slight dx features, but I don’t see them significantly out-competing the big AI companies.

amp moved away from GPT-5 as driver and now calls it their “oracle”. Meanwhile I use codex and basically constantly work with the smarter model, the oracle. Yes, there are benchmarks, but given the skewed usage numbers, I don’t trust them. codex gets me far better results than amp. I have to give them kudos tho for session sharing, they push some interesting ideas ahead.

Factory, unconvinced. Their videos are a bit cringe, I do hear good things in my timeline about it tho, even if images aren’t supported (yet) and they have the signature flicker.

Cursor… it’s tab completion model is industry leading, if you still write code yourself. I use VS Code mostly, I do like them pushing things like browser automation and plan mode tho. I did experiment with GPT-5-Pro but Cursor still has the same bugs that annoyed me back in May. I hear that’s being worked on tho, so it stays in my dock.

Others like Auggie were a blip on my timeline and nobody ever mentioned them again. In the end they all wrap either GPT-5 and/or Sonnet and are replaceable. RAG might been helpful for Sonnet, but GPT-5 is so good at searching at you don’t need a separate vector index for your code.

The most promising candidates are opencode and crush, esp. in combination with open models. You can totally use your OpenAI or Anthropic sub with them as well (thanks to clever hax), but it’s questionable if that is allowed, and what’s the point of using a less capable harness for the model optimized for codex or Claude Code.

What about $openmodel

I keep an eye on China’s open models, and it’s impressive how quickly they catch up. GLM 4.6 and Kimi K2.1 are strong contenders that slowly reach Sonnet 3.7 quality, I don’t recommend them as daily driver tho.

The benchmarks only tell half the story. IMO agentic engineering moved from “this is crap” to “this is good” around May with the release of Sonnet 4.0, and we hit an even bigger leap from good to “this is amazing” with gpt-5-codex.

Plan Mode & Approach

What benchmarks miss is the strategy that the model+harness pursue when they get a prompt. codex is far FAR more careful and reads much more files in your repo before deciding what to do. It pushes back harder when you make a silly request. Claude/other agents are much more eager and just try something. This can be mitigated with plan mode and rigorous structure docs, to me that feels like working around a broken system.

I rarely use big plan files now with codex. codex doesn’t even have a dedicated plan mode - however it’s so much better at adhering to the prompt that I can just write “let’s discuss” or “give me options” and it will diligently wait until I approve it. No harness charade needed. Just talk to it.

But Claude Code now has Plugins

Do you hear that noise in the distance? It’s me sigh-ing. What a big pile of bs. This one really left me disappointed in Anthropic’s focus. They try to patch over inefficiencies in the model. Yes, maintaining good documents for specific tasks is a good idea. I keep a big list of useful docs in a docs folder as markdown.

But but Subagents !!!1!

But something has to be said about this whole dance with subagents. Back in May this was called subtasks, and mostly a way to spin out tasks into a separate context when the model doesn’t need the full text - mainly a way to parallelize or to reduce context waste for e.g. noisy build scripts. Later they rebranded and improved this to subagents, so you spin of a task with some instructions, nicely packaged.

The use case is the same. What others do with subagents, I usually do with separate windows. If I wanna research sth I might do that in a separate terminal pane and paste it to another one. This gives me complete control and visibility over the context I engineer, unlike subagents who make it harder to view and steer or control what is sent back.

And we have to talk about the subagent Anthropic recommends on their blog. Just look at this “AI Engineer” agent. It’s an amalgamation of slop, mentioning GPT-4o and o1 for integration, and overall just seems like an autogenerated soup of words that tries to make sense. There’s no meat in there that would make your agent a better “AI engineer”.

What does that even mean? If you want to get better output, telling your model “You are an AI engineer specializing in production-grade LLM applications” will not change that. Giving it documentation, examples and do/don’t helps. I bet that you’d get better result if you ask your agent to “google AI agent building best practices” and let it load some websites than this crap. You could even make the argument that this slop is context poison.

How I write prompts

Back when using claude, I used to write (ofc not, I speak) very extensive prompts, since this model “gets me” the more context I supply. While this is true with any model, I noticed that my prompts became significantly shorter with codex. Often it’s just 1-2 sentences + an image. The model is incredibly good at reading the codebase and just gets me. I even sometimes go back to typing since codex requires so much less context to understand.

Adding images is an amazing trick to provide more context, the model is really good at finding exactly what you show, it finds strings and matches it and directly arrives at the place you mention. I’d say at least 50% of my prompts contain a screenshot. I rarely annotate that, that works even better but is slower. A screenshot takes 2 seconds to drag into the terminal.

Wispr Flow with semantic correction is still king.

Web-Based Agents

Lately I experimented again with web agents: Devin, Cursor and Codex. Google’s Jules looks nice but was really annoying to set up and Gemini 2.5 just isn’t a good model anymore. Things might change soon once we get Gemini 3 Pro. The only one that stuck is codex web. It also is annoying to setup and broken, the terminal currently doesn’t load correctly, but I had an older version of my environment and made it work, with the price of slower wramp-up times.

I use codex web as my short-term issue tracker. Whenever I’m on the go and have an idea, I do a one-liner via the iOS app and later review this on my Mac. Sure, I could do way more with my phone and even review/merge this, but I choose not to. My work is already addictive enough as-is, so when I’m out or seeing friends, I don’t wanna be pulled in even more. Heck, I say this as someone who spent almost two months building a tool to make it easier to code on your phone.

Codex web didn’t even count towards your usage limits, but these days sadly are numbered.

The Agentic Journey

Let’s talk about tools. Conductor, Terragon, Sculptor and the 1000 other ones. Some are hobby projects, some are drowning in VC money. I tried so many of them. None stick. IMO they work around current inefficiencies and promote a workflow that just isn’t optimal. Plus, most of them hide the terminal and don’t show everything the model shows.

Most are thin wrappers around Anthropic’s SDK + work tree management. There’s no moat. And I question if you even want easier access to coding agents on your phone. The little use case these did for me, codex web fully covers.

I do see this pattern tho that almost every engineer goes through a phase of building their own tools, mostly because it’s fun and because it’s so much easier now. And what else to build than tools that (we think) will make it simpler to build more tools?

But Claude Code can Background Tasks!

True. codex currently lacks a few bells and whistles that claude has. The most painful omission is background task management. While it should have a timeout, I did see it get stuck quite a few times with cli tasks that don’t end, like spinning up a dev server or tests that deadlock.

This was one of the reasons I reverted back to claude, but since that model is just so silly in other ways, I now use tmux. It’s an old tool to run CLIs in persistent sessions in the background and there’s plenty world knowledge in the model, so all you need to do is “run via tmux”. No custom agent md charade needed.

What about MCPs

Other people wrote plenty about MCPs. IMO most are something for the marketing department to make a checkbox and be proud. Almost all MCPs really should be clis. I say that as someone who wrote 5 MCPs myself.

I can just refer to a cli by name. I don’t need any explanation in my agents file. The agent will try $randomcrap on the first call, the cli will present the help menu, context now has full info how this works and from now on we good. I don’t have to pay a price for any tools, unlike MCPs which are a constant cost and garbage in my context. Use GitHub’s MCP and see 23k tokens gone. Heck, they did make it better because it was almost 50.000 tokens when it first launched. Or use the gh cli which has basically the same feature set, models already know how to use it, and pay zero context tax.

I did open source some of my cli tools, like bslog and inngest.

I do use chrome-devtools-mcp these days to close the loop. it replaced Playwright as my to-go MCP for web debugging. I don’t need it lots but when I do, it’s quite useful to close the loop. I designed my website so that I can create api keys that allow my model to query any endpoint via curl, which is faster and more token-efficient in almost all use cases, so even that MCP isn’t something I need daily.

But the code is slop!

I spend about 20% of my time on refactoring. Ofc all of that is done by agents, I don’t waste my time doing that manually. Refactor days are great when I need less focus or I’m tired, since I can make great progress without the need of too much focus or clear thinking.

Typical refactor work is using jscpd for code duplication, knip for dead code, running eslint’s react-compiler and deprecation plugins, checking if we introduced api routes that can be consolidated, maintaining my docs, breaking apart files that grew too large, adding tests and code comments for tricky parts, updating dependencies, tool upgrades, file restructuring, finding and rewriting slow tests, mentioning modern react patterns and rewriting code (e.g. you might not need useEffect). There’s always something to do.

You could make the argument that this could be done on each commit, I do find these phases of iterating fast and then maintaining and improving the codebase - basically paying back some technical debt, to be far more productive, and overall far more fun.

Do you do spec-driven development?

I used to back in June. Designing a big spec, then let the model build it, ideally for hours. IMO that’s the old way of thinking about building software.

My current approach is usually that I start a discussion with codex, I paste in some websites, some ideas, ask it to read code, and we flesh out a new feature together. If it’s something tricky, I ask it to write everything into a spec, give that to GPT-5-Pro for review (via chatgpt.com) to see if it has better ideas (surprisingly often, this greatly improves my plan!) and then paste back what I think is useful into the main context to update the file.

By now I have a good feeling which tasks take how much context, and codex’s context space is quite good, so often I’ll just start building. Some people are religious and always use a new context with the plan - IMO that was useful for Sonnet, but GPT-5 is far better at dealing with larger contexts, and doing that would easily add 10 minutes to everything as the model has to slowly fetch all files needed to build the feature again.

The far more fun approach is when I do UI-based work. I often start with sth simple and woefully under-spec my requests, and watch the model build and see the browser update in real time. Then I queue in additional changes and iterate on the feature. Often I don’t fully know how something should look like, and that way I can play with the idea and iterate and see it slowly come to life. I often saw codex build something interesting I didn’t even think of. I don’t reset, I simply iterate and morph the chaos into the shape that feels right.

Often I get ideas for related interactions and iterate on other parts as well while I build it, that work I do in a different agent. Usually I work on one main feature and some smaller, tangentially related tasks.

As I’m writing this, I build a new Twitter data importer in my Chrome extension, and for that I reshape the graphql importer. Since I’m a bit unsure if that is the right approach, that one is in a separate folder so I can look at the PR and see if that approach makes sense. The main repo does refactoring, so I can focus on writing this article.

Show me your slash commands!

I only have a few, and I use them rarely:

/commit (custom text to explain that multiple agents work in the same folder and to only commit your changes, so I get clean comments and gpt doesn’t freak out about other changes and tries to revert things if linter fails)
/automerge (process one PR at a time, react to bot comments, reply, get CI green and squash when green)
/massageprs (same as automerge but without the squashing so I can parallelize the process if I have a lot of PRs)
/review (built-in, only sometimes since I have review bots on GH, but can be useful)

And even with these, usually I just type “commit”, unless I know that there’s far too many dirty files and the agent might mess up without some guidance. No need for charade/context waste when I’m confident that this is enough. Again, you develop intuition for these. I have yet to see other commands that really are useful.

What other tricks do you have?

Instead of trying to formulate the perfect prompt to motivate the agent to continue on a long-running task, there’s lazy workarounds. If you do a bigger refactor, codex often stops with a mid-work reply. Queue up continue messages if you wanna go away and just see it done. If codex is done and gets more messages, it happily ignores them.

Ask the model to write tests after each feature/fix is done. Use the same context. This will lead to far better tests, and likely uncover a bug in your implementation. If it’s purely a UI tweak, tests likely make less sense, but for anything else, do it. AI generally is bad at writing good tests, it’s still helpful tho, and let’s be honest - are you writing tests for every fix you make?

Ask the model to preserve your intent and “add code comments on tricky parts” helps both you and future model runs.

When things get hard, prompting and adding some trigger words like “take your time” “comprehensive” “read all code that could be related” “create possible hypothesis” makes codex solve even the trickiest problems.

How does your Agents/Claude file look like?

I have an Agents.md file with a symlink to claude.md, since Anthropic decided not to standardize. I recognize that this is difficult and sub-optimal, since GPT-5 prefers quite different prompting than Claude. Stop here and read their prompting guide if you haven’t yet.

While Claude reacts well to 🚨 SCREAMING ALL-CAPS 🚨 commands that threaten it that it will imply ultimate failure and 100 kittens will die if it runs command X, that freaks out GPT-5. (Rightfully so). So drop all of that and just use words like a human. That also means that these files can’t optimally be shared. Which isn’t a problem to me since I mostly use codex, and accept that the instructions might be too weak for the rare instances where claude gets to play.

My Agent file is currently ~800 lines long and feels like a collection of organizational scar tissue. I didn’t write it, codex did, and anytime sth happens I ask it to make a concise note in there. I should clean this up at some point, but despite it being large it works incredibly well, and gpt really mostly honors entries there. At least it does far far more often than Claude ever did. (Sonnet 4.5 got better there, to give them some credit)

Next to git instruction it contains an explanation about my product, common naming and API patterns I prefer, notes about React Compiler - often it’s things that are newer than world knowledge because my tech stack is quite bleeding edge. I expect that I can again reduce things in there with model updates. For example, Sonnet 4.0 really needed guidance to understand Tailwind 4, Sonnet 4.5 and GPT-5 are newer and know about that version so I was able to delete all that fluff.

Significant blocks are about which React patterns I prefer, database migration management, testing, using and writing ast-grep rules. (If you don’t know or don’t use ast-grep as codebase linter, stop here and ask your model to set this up as a git hook to block commits)

I also experimented and started using a text-based “design system” for how things should look, the verdict is still out on that one.

So GPT-5-Codex is perfect?

Absolutely not. Sometimes it refactors for half an hour and then panics and reverts everything, and you need to re-run and soothen it like a child to tell it that it has enough time. Sometimes it forgets that it can do bash commands and it requires some encouragement. Sometimes it replies in russian or korean. Sometimes the monster slips and sends raw thinking to bash. But overall these are quite rare and it’s just so insanely good in almost everything else that I can look past these flaws. Humans aren’t perfect either.

My biggest annoyance with codex is that it “loses” lines, so scrolling up quickly makes parts of the text disappear. I really hope this is on top of OpenAI’s bug roster, as it’s the main reason I sometimes have to slow down, so messages don’t disappear.

Conclusion

Don’t waste your time on stuff like RAG, subagents, Agents 2.0 or other things that are mostly just charade. Just talk to it. Play with it. Develop intuition. The more you work with agents, the better your results will be.

Simon Willison’s article makes an excellent point - many of the skills needed to manage agents are similar to what you need when managing engineers - almost all of these are characteristics of senior software engineers.

And yes, writing good software is still hard. Just because I don’t write the code anymore doesn’t mean I don’t think hard about architecture, system design, dependencies, features or how to delight users. Using AI simply means that expectations what to ship went up.

PS: This post is 100% organic and hand-written. I love AI, I also recognize that some things are just better done the old-fashioned way. Keep the typos, keep my voice. 🚄✌️

PPS: Credit for the header graphic goes to Thorsten Ball.

Claude Code Anonymous

Tue, 9 Sep 2025 10:00:00 +0000

A few weeks ago I reconnected with an old friend of mine, Orta Therox and we both discussed how Claude Code completely changed how we approach building software, and that we both have trouble thinking about anything else. Out of this conversation came an idea, and we created a new meetup format, Claude Code Anonymous.

There were quite a few people who wanted to join this event but were not in London, so in High-Agency-Style, I encouraged them to start their own chapters in their cities, and now we have events in London, Vienna, Berlin, Cologne, San Francisco, Delft, and more cities coming soon. The first London meetup was such a success that we’re doing another one on October 13th.

What is Claude Code Anonymous

Over the last few months I noticed that not everyone gets hooked the same way with this new way of building software. There’s a certain category of people, full-breadth developers, folks with both technical and product capabilities, that seem to adopt this the fastest, and I’m jokingly calling them the black eye club, since these people usually have trouble sleeping.

Claude Code Anonymous is the wordplay on this phenomenon. We wanted to create a space for people to be able to talk through their experiences, and understand that for some it’s hard to speak publicly about using AI / LLM tooling. Talks are not recorded, nor is there a live-stream. The recipe is simple: get a group of like-minded people together, provide a space, drinks, pizza, and focus on the social aspect.

Meetup Structure

These meetups are structured as a series of lightning talks, ~5m long with talks which start along the lines of: “I was X when Claude Code Y”. So, “I was impressed when Claude Code figured out a bug I had been…”, “I was disappointed when Claude Code deleted my production database” etc.

Intro + Talks should be one hour sharp, so there’s 2-3h left for social and talking. I’ve been in too many meetups where the talks were too long and people left right after the talks - the goal of Claude Code Anonymous is to meet likeminded people more than watching long talks. And the 5m limit is there so that there’s more people who can show off their work, and it’s a good starting point for a talk later on.

Why Claude Code and not X?

Don’t take the name too literal. We’re open for any agentic work. We just picked the name Claude Code to target builders and not marketing or HR folks. Calling it “agentic engineering” would attract a different kind of audience. Of course you can talk about any tool you like, be it codex, opencode, Cursor or whatever!

IMO Claude Code is the defining agent that really started the revolution, so I made it the proprietary eponym. Like Jacuzzi or Tupperware. If you wanna be neutral, call it Agents Anonymous 🕵️♂️

How do I start a meetup?

It’s really quite simple: Find a space, organize some drinks and spread the word. We’ve been using Luma as event platform, and I suggest to let people apply with some questions such as “What are you building” and their social profile.

So far every event had far more interest than space available, so we’ve been reviewing people to make sure that builders are there - this is not a space for folks who just look to hire or market their product. Same rules apply to lightning talks. Show us what you learned, not what you sell.

As Code of Conduct we’ve been using the CocoaPods one which can be summarized as: “Don’t be a Jerk”

What Now?

Do you want to see Claude Code Anonymous in your city? Make it happen! I’m happy to help with outreach via Twitter, just email or DM me.

Live Coding Session: Building Arena

Sat, 6 Sep 2025 10:00:00 +0000

tl;dr: I built and shipped a brand-new feature live (in ~1 hour), watch how I approach agentic engineering with codex

Join me for an unfiltered look at building Arena - a live coding session where you can see my development process in action, unscripted. Thanks to Eleanor Berger for motivating me to do this video and for organizing the live event!

YouTube video player

What we built

🤖 Heads up! This is an AI-Assisted summary.

Feature: Arena — a new feature in my upcoming project, to see how well 2–4 users from X match
Input: Twitter/X user handles
Pipeline: fetch N tweets per user (shares a 1,000-tweet budget), strip to necessary fields, run profile analysis, then score compatibility (per pair + whole team)
UX: user picker + “Analyze” button, results table, cached runs selectable under the search box
Infra touches: DB migration for arena_cache, long-running job in the background, streaming UI, auth-guarded page

I managed to complete the feature in ~1h, and we got a pair score of 89 for me and @intellectronica.

Stack & Setup

Model workflow: codex (OpenAI/GPT-5) for coding sessions; it eagerly reads the codebase and generally “does the right thing” without handheld file lists. I keep a separate Claude-style flow for some web searching, but for repo work codex is the star.
Sessions: start fresh for big features, run multiple agent windows in parallel; switch tasks while one is thinking.
Branching: work directly on main with atomic commits. Merge conflicts + worktrees cost speed; small, well-scoped commits keep things safe.
Tooling:
- Ghostty for terminals, split panes with agents
- Better Stack logging via a tiny bslog CLI
- An xl CLI (curl wrapper) for quick X API pulls
- Strict biome rules + custom codemods to normalize output
- Background worker for long jobs (Inngest)
- Cache table to avoid recompute
Docs ingestion: pull only what’s needed, prefer markdown via a crawler over raw HTML to save tokens.
Validation: schema validation on inputs; fail fast and surface helpful messages.

Tactics that mattered

Keep the agent context clean. Minimize tool noise and only inject docs when needed; markdown > HTML to conserve context.
Let codex plan on demand. It proposes next steps that are usually solid; green-light them in sequence.
Cache long tasks early. Add a table + background job queue before you polish UI; this saves you from re-running expensive analysis.
Copy-paste errors verbatim. Don’t over-explain; just drop logs in and let the agent fix what broke.
Comments as spec. Ask for clear intent comments near tricky code; they’re for you and for the agent on the next session.
Write tests afterwards, not first. These agents are great at back-filling tests once the shape exists, and that’s usually enough to catch regressions.
Work on main, commit surgically. You still get speed with safety. Backups + Git are your safety net.
Avoid local models for this workload. Context and stability matter more than shaving milliseconds.
CLIs beat MCPs. A 2-hour CLI wrapper (logs, API pulls) pays for itself and keeps context small.
Small “proof” projects unblock big features. If streaming or a protocol is hard, build a tiny in-repo example that works, then transplant.

Q&A highlights

Why Codex over Claude Code? Codex actually reads more of the repo without handholding; requires fewer “look here, then there” hints. Claude still useful for search/web, but for coding Codex felt faster end-to-end.
Do you branch? Not for features at this stage. Main + disciplined commits is faster and - counterintuitively - safer for rapid iteration.
Manual approvals for agent actions? No. That becomes “Windows Vista prompts.” Use Git + backups; review diffs; move fast.
Repo prompts & MCP servers? Nice idea, but they bloat context and introduce fragility. Lean instructions + small CLIs work better.
Compaction & long sessions? Plan features to fit the context. If you expect many loops (e.g., test repairs), use the flow that compacts well - or split the task.

If you want to read more about my agent workflow, check my AI development post here.

For more advanced prompting techniques with GPT-5, also check out the OpenAI GPT-5 Prompting Guide.

New posts, shipping stories, and nerdy links straight to your inbox.

2× per month, pure signal, zero fluff.

My Current AI Dev Workflow

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

TL;DR: Ghostty + Claude Code + minimal tooling = maximum productivity. Less is more.

It’s time for an update on my workflow, which keeps evolving.

After going all-in on VS Code, I went fully back to Ghostty for my main setup, with VS Code on the side to look up code and Cursor/GPT-5 for reviews (sometimes also the CLI). I tried Zed, just can’t deal with a terminal that looks like this.

Still extremely happy with my Dell UltraSharp U4025QW - 3840x1620 makes 4 Claude instances + Chrome all visible without moving windows.

VS Code’s terminal is too unstable, had plenty freezes when pasting in large amounts of text. Nothing beats Ghostty.

Tools and Their Reality

Gemini can be great, but its edit tools are too messy, so using it less and less. GPT-5 for reviewing plans works even better than Gemini.

Yes, all of these work on main. I tried the whole worktree setup, just slows me down. If you pick areas of work carefully you can work on multiple areas without much cross-pollination.

Claude often makes a mess but it’s equally great in refactoring and cleaning up. Important to do both to not create too much technical debt.

Planning and Context Management

Having the initial topic in the statusline + session ID (gist) in case I need to switch accounts or restart a session is super helpful.

Using plan mode and iterating is key. Smaller tasks I do right away, bigger I write in a file and let GPT-5 review.

Often I manage with small prompts, sometimes I brainstorm and it’s amazing how much sense agents can make out of my incoherent thoughts.

When I’m not refactoring I usually run 1-2 agents; for cleanup/tests/UI work ~4 seems to be the sweet spot. All depends on the blast radius of the work.

The Hard Parts

The hardest part is distributed system design, picking the right dependencies, platforms and a forward-thinking database schema.

I’ve been building an incredible amount of custom infra, admin pages, CLIs to help both me and the agents and that work did speed me up so much. Would have never done that with the old ways.

Testing Strategy

Bigger changes always get tests. Automated ones usually aren’t great, but the model almost always finds issues when you ask it to write tests IN THE SAME CONTEXT. Context is precious, don’t waste it.

Less is More

Even removed my last MCP, since Claude sometimes would go off spinning up Playwright unasked when it could simply read the code - which is faster and pollutes the context less.

Pick services that have CLIs: vercel, psql, gh, axiom. Agents can use them, one line in CLAUDE.md is enough “logs: axiom or vercel cli”. “Database: psql + one example how to load env correctly so the loop is faster”

Results and Comparisons

Got an insane amount done with this setup. Other CLIs/models still don’t come close. Codex can’t search (asking “google best practices” is usually better than context). Cursor/GPT-5 takes FOREVER and doesn’t share its thinking, so it’s hard to steer. GPT-5 also is much more literal in how you have to prompt it - it’s a great model but not the best agent, you have to be more precise and specific.

Still don’t see how this could be moved to background agents. I steer the models a lot as I notice them drifting off - that’s much harder if they run in the background.

The new rate limits will go into effect August 28 and that’ll definitely suck. Guess I’ll just pay up. No perfect alternative for now.

Essential Reading for Agentic Engineers - August 2025

Fri, 22 Aug 2025 01:00:00 +0000

The reinvention of software development is happening now.

This edition cuts through the AI hype with five essential perspectives that reveal both the promise and peril of our evolving profession. We track developers’ evolution from AI skeptics to strategists, examine how juniors are losing fundamental skills, reality-check the 10x productivity myths, and explore why both platform monopolies and MCP server proliferation may be dead ends.

🤖 Heads Up: Summaries are AI-Assisted. All posts are hand-picked.

Developers, Reinvented

Read the article by Thomas Dohmke (@ashtom) • 11 min

Thomas presents groundbreaking research from interviews with developers who’ve made AI tools central to their workflows, revealing a four-stage evolution that’s reshaping software development from skepticism to strategic AI orchestration.

The four-stage evolution: From AI Skeptic (dabbling with completions) to AI Strategist (orchestrating multi-agent workflows with planning and coding models), with each stage requiring different mindsets and skill development
Role transformation in action: Advanced practitioners describe their work shifting from “writing code to architecting and verifying implementation work carried out by AI agents”—focusing on delegation (context engineering, prompt design) and verification (validating AI output against objectives)
Timeline predictions: Half expect 90% AI-written code within 2 years, half within 5 years, but crucially view this as role reinvention rather than replacement: “Maybe we become less code producers and more code enablers. My next title might be Creative Director of Code”
Skills evolution: New emphasis on AI fluency, agent orchestration, human-AI collaboration, and product understanding, while foundational programming knowledge becomes essential for verification and quality control
Educational implications: Computer science curricula must evolve from syntax memorization to AI-assisted problem-solving, teaching students to frame problems, guide AI, and critique solutions rather than just write loops

Either you have to embrace the AI, or you get out of your career… I think of myself as [a] mediocre engineer, and I feel this AI reset is giving me a chance to build skills that will bring me closer to excellence.

The research reveals “realistic optimists” who acknowledge disruption while embracing growth opportunities, focusing less on “time saved” and more on “increasing ambition”—expanding the scope and complexity of what they can accomplish rather than just working faster.

Read the article by Namanyay Goel (@NamanyayG) • 8 min

Namanyay presents a sobering counterpoint to AI evangelism, examining how AI tools may be creating a generation of developers who can ship code without truly understanding it—trading deep knowledge for quick fixes.

The learning crisis: Junior developers increasingly rely on AI-generated solutions without understanding the underlying principles, potentially creating a knowledge gap that compounds over time as they advance in their careers
Pattern matching vs. understanding: AI tools excel at providing working code snippets, but developers miss the crucial struggle phase where deep understanding forms—the difference between knowing how to use a solution and understanding why it works
Long-term implications: While senior developers leverage AI to amplify existing knowledge, juniors risk building on shaky foundations: “We’re going to pay for this later” when complex debugging or architectural decisions require fundamental understanding
Balanced approach: The author advocates for intentional learning practices—interrogating AI solutions, building from scratch periodically, and engaging in meaningful code reviews that go beyond “does it work?” to “why does it work this way?”
Generational divide: A stark contrast emerges between developers who learned pre-AI (with strong fundamentals to verify AI output) and those learning with AI from day one (potentially lacking the foundation to recognize subtle errors or inefficiencies)

We’re trading deep understanding for quick fixes, and while it feels great in the moment, we’re going to pay for this later.

This critical perspective complements the optimistic evolution narrative, highlighting that while AI transforms how we work, the fundamentals of software engineering—problem decomposition, algorithmic thinking, and system design—remain essential for those who want to lead rather than just participate in the AI-augmented future.

Reality Check: AI’s Actual Impact on Productivity

Read the article by Colton Anglin • 6 min

Colton delivers a much-needed reality check on the hyperbolic claims of 10x or 100x productivity gains from AI, offering reassurance to engineers experiencing imposter syndrome in the face of aggressive AI marketing.

The math doesn’t add up: Claims of 10x productivity ignore that most engineering time isn’t spent typing code—it’s spent thinking, debugging, reviewing, and coordinating with teams, none of which AI fundamentally accelerates
Real productivity gains: AI excels at specific tasks—writing one-off scripts, generating boilerplate, handling repetitive patterns—but these represent a small fraction of engineering work, yielding realistic improvements of perhaps 20-30% in specific contexts
The correction overhead: AI-generated code often requires significant manual review and fixing, sometimes taking longer than writing from scratch: “A competent engineer will figure this stuff out in less than a week of moderate AI usage”
Psychological impact: The constant barrage of “10x engineer” claims creates unnecessary anxiety and imposter syndrome, when in reality, experienced engineers quickly discover AI’s actual limitations through hands-on use
Finding balance: The author advocates for using AI where it genuinely helps (scripts, boilerplate) while maintaining confidence in human skills for complex problem-solving, system design, and the creative aspects of engineering that bring satisfaction

Real engineers were now 10-100x more productive than I was—the anxiety-inducing thought that the author ultimately debunks through practical experience and mathematical analysis.

This grounded perspective serves as an antidote to both AI evangelism and doom-saying, reminding us that while AI tools are valuable additions to our toolkit, the core skills of software engineering—understanding problems, designing solutions, and building maintainable systems—remain fundamentally human endeavors.

The End of Platform Dominance

Read the article by Austin Parker (@aparker.io) • 10 min

Austin presents a visionary thesis on how AI will fundamentally restructure the software industry, shifting from today’s platform monopolies to tomorrow’s ecosystem of small, custom applications built on open protocols.

Time economics revolution: Platforms rose to dominance when developer time was expensive, but “AI makes time very, very, very cheap”—fundamentally altering the economic equation that has driven software architecture for decades
The abstraction trap: Current software is built at the wrong layer: “We’ve built all of these abstractions, but they’re all built on top of middlemen who would like their 30% cut”—AI enables bypassing these costly intermediaries
Custom over commodity: With AI reducing development time from months to minutes, “Custom applications will become the norm, not the exception”—why use generic tools when bespoke solutions cost virtually nothing to create?
The scale paradox: Parker asks the essential question: “Why do I need planet-scale infrastructure to share baby photos with, like, 5 people?”—highlighting how AI enables right-sized solutions instead of one-size-fits-all platforms
Hardware convergence: Within 5 years, consumer devices will have onboard AI rivaling today’s best models, enabling truly personal computing where applications are generated on-demand for specific needs

All code is technical debt—a provocative reframing that suggests the future isn’t about accumulating codebases but generating disposable, purpose-built applications as needed.

This radical vision complements our exploration of role transformation by imagining not just how engineers will work differently, but how the entire software ecosystem will restructure around AI’s ability to make custom development trivially cheap, potentially ending the era of platform monopolies.

Read the article by Geoffrey Huntley (@geoff) • 10 min

Geoffrey presents a critical analysis of Model Context Protocol (MCP) servers, warning that the rush to add more tools and integrations is actually degrading AI coding assistant performance rather than improving it.

Context window economics: Every MCP server and tool consumes precious tokens from your LLM’s limited context window—adding more tools means less space for actual code and reasoning, creating a fundamental trade-off that most developers don’t realize
The allocation paradox: “Less is more. The more you allocate into the context window of an LLM… the worse the outcomes you’re going to get”—each additional tool increases cognitive overhead and reduces the AI’s ability to focus on the actual task
Tool proliferation problems: Multiple similar tools create non-deterministic behavior where the LLM struggles to choose between overlapping capabilities, leading to confusion and errors rather than enhanced functionality
Security nightmares: Third-party MCP servers introduce supply chain risks and potential attack vectors—malicious actors could inject context that manipulates AI behavior, creating a new class of security vulnerabilities enterprises aren’t prepared for
Strategic recommendations: Limit MCP servers to essential tools, prefer first-party integrations from trusted vendors, and consider dynamically enabling/disabling servers based on specific workflow stages rather than loading everything at once

The proliferation of MCP servers is creating a tragedy of the commons in your context window—everyone wants their tool included, but the cumulative effect is making the AI assistant worse, not better.

This technical deep-dive challenges the current enthusiasm around MCP servers, arguing that restraint and strategic thinking about context allocation will deliver better results than the current “more is better” approach that’s dominating the ecosystem.

This builds on insights from my July 2025 collection and original Essential Reading with fresh perspectives on the evolving identity of software engineers in the AI era.

Just One More Prompt

Tue, 19 Aug 2025 08:00:00 +0000

This is my writeup for the talk I gave at Claude Code Anonymous meeting in London.

Hi, my name is Peter and I’m a Claudoholic. I’m addicted to agentic engineering. And sometimes I just vibe-code. Most of you know me as @steipete on Twitter. I was an iOS developer/Entrepreneur in a previous life, and now I do… everything. I work on a ton of projects.

So. Now you might understand why we call it Claude Code Anonymous. This meetup is for builders. For full-breadth developers. For the people who see the revolution and can’t sleep anymore.

Since I’m one of the organizers and knee-deep in AI, I’ve thought quite hard what I wanna talk about in these 5 minutes.

My latest strategies how to best use agents?
My adventures in running open models on Nvidia’s H200?
Alternative agents like opencode, charm?
A preview of my upcoming talk “You can just do things?”

Yes, you can just do things. That’s the beauty and the problem. Once you realize how powerful these agents are - this realization that you can finally build everything you ever wanted to build. All these ideas and side projects that you’ve been thinking about for years, but never had the time to do.

And it doesn’t stop. The more I build, the more ideas for projects I get. And then I worked on multiple projects at the same time, manically yelling at my computer in the middle of the night, because who even types anymore?

AI was supposed to save time, yet I work more than ever before, I have more FOMO than ever before. I dedicate pretty much all my waking time to this, yet it doesn’t feel enough. One week in AI feels like a month in the real world.

I’m fun at parties when I tell people about the coming AGI apocalypse, and the 1000 stories of moments where AI just abso - fucking - lutely blew my mind. Don’t get me wrong - I am having a blast. I learned so so much, I built incredibly cool stuff, and my spark is back.

You might not realize how important that was for me. I burned out after selling my company in 2021 and basically didn’t touch my computer for 3 years. I only used my phone… like a normie! So, having found my way back, the pendulum did swing heavily in the other direction.

The last few months feel like a blur, and I’m on a new journey how to better control my slot machine addiction. Honestly, I’m failing quite hard. I’m having way too much fun here, and there are all these ideas in my head that need to be codified.

I know I’m not alone, when I text my friends at 4am and they are also still up. I call them the Black Eye Club. And on Reddit there’s plenty of reports as well, about people that can’t sleep anymore.

Gergely Orosz wrote in his Pragmatic Engineer Newsletter just a few days ago:

“New trend: extreme hours for AI startup workers. Pulling 80+ hour work weeks – including weekends – is becoming the norm across AI startups, and is unlikely to stop while AI is so hot.”

I also see this as a theme that’s industry-wide. Cognition CEO Scott Wu posted on Twitter:

“Cognition has an extreme performance culture. We routinely are at the office through the weekend and do some of our best work late into the night. Many of us literally live where we work.”

Kennan Davison from Icon, an AI Marketing generator tweeted:

why do 6 [days of work] when you can do 7

Google cofounder Sergey Brin told staff in the tech giant’s AI unit:

“60 hours a week is the sweet spot of productivity”

I allowed myself to be sucked into the vortex for a while. This is exactly how I started my last company. I don’t believe you can do that with “regular” working hours. Or to be more specific, I can’t do that with 40h weeks. I work in waves, a period of very intense work, followed by a period of slacking off. Heck, I even know which game I’m going to enjoy next, once I manage to rip myself away from the slot machines.

One of my passion projects is VibeTunnel, a Mac app that tunnels terminal cli’s to the web, so you can talk to your claude or gemini or codex or whatever straight from your phone. I realized I literally built something so I have better access to my drug. It’s really cool btw.

I also realize that it’s time now to slow down a bit, as it’s gotten to an unhealthy level. A tiny yet meaningful tweak I did the other day was adding the session time to Claude’s status line. Serves as a reminder that time is just FLYING when you’re in the flow.

So here it is. My story. May it serve as a warning for some here that aren’t mainlining cli just yet. If you love to build things, if you are a full-breadth developer, you are at risk. I’d love to hear your strategies after our talk round is done.

Thanks for letting me share.

Poltergeist: The Ghost That Keeps Your Builds Fresh

Tue, 5 Aug 2025 14:00:00 +0000

TL;DR: Poltergeist is an AI-friendly universal file-watcher that auto-detects any project and rebuilds them as soon as a file has been changed. It’s npm run dev for native apps, with automatic configuration, notifications and a smart build queue.

The Story

In agentic engineering, loop iteration speed is everything. While building Peekaboo, a macOS OS automation agent/cli/mcp written in Swift, my main friction point is build time. Swift isn’t famous for its fast compiler, and it’s especially noticeable once you start doing more web dev. In the time Swift is calculating dependencies, my TypeScript project already recompiled.

Worse, agents would sometimes forget to rebuild before testing, leading to debugging sessions on code that was already fixed.

Poltergeist fixes that. It builds in the background as soon as a file has been changed, accelerating the code/debug loop for both agents and humans.

So I wrote a quick bash script to watch Swift files and auto-rebuild in the background. Problem solved - for Swift. But then I realized this would be incredibly useful for any kind of project. I already had both the CLI and Mac app building automatically, and I figured out this could work for so many other use cases.

That’s when I decided to make this more of a thing - and went into another rabbit hole of building tools for my agents so I can be faster building tools for my agents.

The Universal Solution

I rewrote the entire system in TypeScript with one goal: make it work for any project, any language, any build system. Poltergeist became a universal file watcher that ‘haunts’ your projects.

While there are tools like watchexec, I didn’t find anything that was designed with an agentic engineering flow in mind. Poltergeist even detects if a human or agent calls it and adds helpful messages for agents to steer them to correct usage, even without polluting your AGENTS.ms file.

Everything happens invisibly. Save a file. By the time you’re ready to test, the fresh binary is waiting. For Mac apps, it even quits and relaunches automatically (yah I hear you, that’s a config setting). True hot reload would be nice, but that’s something for the future.

Channeling the Spirit

I’ve built Poltergeist completely with Claude Code. It’s a build tool and in the beginning I didn’t plan to make it a thing, only once I saw how useful it is, I decided to spend extra time and focus on it to make it its own thing. It started as a bunch of bash scripts, eventually I asked my agent to convert these into TypeScript and then kept iterating on it.

Sentences like “all autogenerated code” are insofar not meaningful anymore, as I’ve surely written (or rather: talked) 20 pages of prompts to perfect the design. With AI, English is the new programming language, and the fact that it’s TypeScript is more an implementation detail.

Why TypeScript? Agents can write it extremely well, the iteration flow is amazingly fast, compilation is instant, it’s cross-platform and Watchman has TypeScript bindings for it.

Dancing with Agents

You’ve already noticed - I love building developer tools and stuff that makes my life easier. Poltergeist seemed like such an obvious idea, that I was surprised that it didn’t exist yet.

I usually use my spec.md based approach for new projects, however this one evolved from some bash scripts to a full-blown dev tool, so there’s no spec, just a lot of prompts and iterating.

Building it almost felt too easy. Agents are extremely good at writing TypeScript and Go, so Claude one-shotted most of my prompts. I use WisprFlow and my prompts are usually quite long ramblings. I learned that talking more and giving reason to the things you want, really helps agents to understand and build the right thing.

The process is in most cases: long prompt + plan only ultrathink. Sometimes also: Give me a few options - esp. when I’m unsure what to do.

I don’t use Claude’s plan mode, simply saying “plan only” works equally well and fits my flow better (and don’t get me started on subagents). I often iterate multiple times on a plan before I type “y” to build it.

After it’s done I usually write “add tests + update docs” - adding tests per feature is much better than trying to add them at the end, plus if you have the feature in your context, writing tests will almost always uncover bugs in the feature implementation, and since the agent has all context it’s the best time to fix it. If I prompt everything at once they usually still stop and seem less focused - thus the explicit separation.

I add CI early on GitHub (again, simply ask cc) which is another layer of testing, that way I can make sure the project works with all OSes, not just on my Mac.

While writing this blog post, I asked Claude about his opinion on my language choice, and it didn’t give me the answer I expected. So - you can already guess - I did the obvious thing and let it loop a few hours to rewrite it in Go.

From Poltergeist to Poltergohst

Porting your project to a different language would have been nuts just a few months ago, these days I can just use agents and let them run in loops until it’s done. I saw this as an experiment to again try out open models and alternative CLIs and tweeted about it here - currently there are still too many bugs around Qwen 3 Coder and GLM 4.5 with OpenCode and Crush so I can’t recommend either.

They both have potential but just aren’t well-tested yet with open models and you’ll eventually encounter API errors and slowdowns. Which is unfortunate, since Qwen 3 Coder’s 1 Mio context window would have been perfect to absorb the whole project in one go and convert it.

My process with Claude Code was to convert all important files (sources, tests, not examples) to one big 1.1MB markdown file, and then copy/paste the complete text with the command “convert to Go”. That way you work around the 256KB limit that would make claude only read the file partially and slowly.

There are many websites to do the GitHub conversion, I prefer this one as it makes it easy to select file types and is fast+simple.

I didn’t use any todo structure for the conversion and simply nudged Claude a few times to continue - models tend to stop eventually (after ~30-60 min loops), no sophisticated prompts were required though.

While I built Poltergeist mostly with Claude Sonnet, I did the conversion with Opus 4.1, to celebrate its release. To improve code quality, I searched for an idiomatic, modern Go guide and ran a few refactors with that.

Ultimately I decided against Go, since I’m not super comfortable in it, and with Bun’s SPA mode, startup time is at ~44ms, and it’s perfect to distribute as a single binary (~20 MB compressed) on Homebrew.

There’s also the ecosystem argument that I didn’t see initially. Poltergeist uses Watchman under the hood which has superb TypeScript bindings, but no official Go bindings, leading to more code to maintain. The only Go binding project that exists hasn’t been maintained in years.

I kept this experiment on GitHub - check out poltergohst.

Seance Time

Pick homebrew if you’re on a modern Mac, otherwise npm. The npm version needs Watchman and Node.

# For modern macOS
brew tap steipete/tap
brew install poltergeist

# Windows, Linux, Intel Mac (Node 20+)
npm install -g @steipete/poltergeist

# Auto-detect and configure your project
poltergeist init

# That's it! (`start` works too, gotta keep the agents happy!)
poltergeist haunt

# Run your tool (always fresh!)
polter my-cli --help

Oh, before I forget - there’s also a native macOS menu bar app! It still needs some work so I haven’t released it yet, you can totally get the source though and play with it. With that you’ll always see if Poltergeist is compiling and if your build is red or green. Might just call it Ghostbuster.

Catch the Ghost

Poltergeist is a new kind of tool that’s built for humans and agents in mind - something we’ll surely see more of in the future. You install it once and then forget about it, since it fades into the background, your agent will use it automatically and you can use it or keep doing things the manual way. It’s the perfect invisible addition - you don’t see it, yet it’s here and helps you get results faster.

The best tools are invisible until you need them, then indispensable once you have them. Poltergeist is both - and it’s just one init away.

Don't read this Startup Slop

Sat, 2 Aug 2025 14:00:00 +0000

tl:dr: My website is banned on http://lobste.rs as “startup slop”, because I use agents to help me write parts of my blog posts.

Backstory

About a month ago I learned that some moderator banned my whole domain because I use agents to help me write some of my blog posts. I make no secret out of that and my repo is open source, you can see exactly how I work and how much effort is in each post, down to every git commit.

I won’t point to people or social networks, it’s easy enough to find if you really care.

Funny enough, the trigger was the most popular and influential post on my website: Claude Code is my Computer. The article where the whole point was to expand people’s mind in what’s all possible with modern agents - and that it far extends the typical use cases I’ve seen so far.

What’s Slop?

As a society, it’s time to have a discussion about AI tho. This isn’t just about you or Lobsters - it’s about how we’re going to navigate a world where the tools of creation are rapidly changing.

A part of me sympathizes - I hate reading AI slop, and if I find someone using AI automation to send me Twitter replies or DMs, I block them immediately. If communication is directly sent to me, is automated and is not marked as being automated and instead a human avatar is used, it’s an insult of my time. My Twitter takes are 100% handcrafted, artisan typed words. I don’t even use WisprFlow there so you get the rawest, most organic experience.

There’s a difference tho between automated replies and using agents to assist writing. At what point does it matter if I spend 4 hours prompting an agent to craft my thoughts into a post vs writing it manually? What defines slop?

There’s another argument to make. My day, just like yours, only has 24 hours. And I do need a few of them to sleep because organic machines are fragile. Some posts I care a lot for and write every word myself.

Others are things I learn, but given the 1000 things I do, I would likely not have cared enough to take my notes and put them online, and they have a dual goal of being documentation for humans and really also a guide for agents (like the one to fix logging on macOS)

Would it be a better outcome to stop sharing these things and only allow the posts that each take me half a day to write on, so some people are not hurt in their feelings?

The Bigger Picture

I say feelings, because I tried to discuss with one of their moderators and was met with so much insult and deprecation of my work, a spiteful mood from a person that don’t even knows me, for something that I put up for free online. Logically that makes no sense. It’s almost as if there’s sth bigger they hate when it comes to AI and I’m just the face they can project that to in that very moment.

Honestly, with such a reaction I’m not mad that they block me and my work. That’s not a community I wanna be a part of.

But I wonder if it wouldn’t be better to judge the value of writing on its own merits.

I mean dang, these days I write more words manually for blog posts than I do for code. Do these folks also get offended when I use agents to generate code? documentation?

You can create slop with or without agents, as you can create great work with or without. Agents are just another tool.

claude: commit, push and merge PR.

Yes, I asked ChatGPT to make the header graphic extra AI-y, just because.

Essential Reading for Agentic Engineers - July 2025

Sat, 2 Aug 2025 01:00:00 +0000

New perspectives on AI-assisted development from the field.

This edition features four compelling articles that showcase the evolving landscape of agentic engineering: a detailed experience report from a team successfully integrating Claude Code into production workflows, a thought-provoking analysis of how AI tools are reshaping developer career paths, a candid look at AI automation experiments that didn’t work as expected, and a technical deep-dive challenging conventional wisdom about MCP limitations.

Six Weeks of Claude Code

Read the article by Orta Therox (@orta) • 12 min

Orta shares his experience integrating Claude Code into daily development work at Puzzmo, providing one of the most detailed real-world productivity assessments available. His team completed 15+ significant engineering tasks in just six weeks, demonstrating measurable impact on technical debt resolution and feature development.

Workflow innovations: Introduced “Write First, Decide Later” approach for rapid prototyping and parallel development strategies using multiple git clones with different VS Code profiles
Quantitative insights: While commit/PR metrics didn’t dramatically change, perceived productivity increased significantly—completing tasks like Adium theme recreation in ~2 hours that would normally take much longer
Practical applications: Excelled at React Native to React conversions, system migrations, infrastructure updates, and exploration of experimental features across diverse technical domains
Team perspective: Treated Claude as a “pair programming buddy with infinite time and patience,” running with minimal permissions for maximum flexibility
Philosophy: Compared AI coding to “introduction of photography” in programming—a fundamental shift requiring new approaches but not replacing core engineering skills

Claude Code has fundamentally changed how we approach technical debt and side projects, enabling rapid exploration and implementation that seemed impossible before.

Full-Breadth Developers

Read the article by Justin Searls (@searls) • 15 min

Justin explores how AI tools are enabling a new archetype of “full-breadth developers” who can work effectively across the entire technology stack, fundamentally challenging traditional specialization models and career development paths.

Paradigm shift: AI enables developers to work competently across multiple domains without years of specialization in each, with Justin completing “two months worth of work on Posse Party” in just two days using Claude Code
Career evolution: Traditional role segregation between engineering and product is becoming obsolete—successful developers now need to be results-oriented, experiment rapidly, and identify opportunities others miss
Cognitive transformation: AI handles syntax, configuration, and boilerplate complexity, freeing developers to focus on higher-level design and product thinking
New skill requirements: Success requires strong prompt engineering, system thinking, and the ability to verify AI-generated solutions rather than deep technical specialization
Democratization: Complex tasks that once required specialists become accessible to generalists with AI assistance, creating opportunities for adaptable, multi-skilled developers

We’re moving from an era where depth was king to one where breadth plus AI might be the winning combination for creating software that truly matters.

Things That Didn’t Work

Read the article by Armin Ronacher (@mitsuhiko) • 18 min

Armin provides a candid retrospective on AI coding experiments that failed, offering valuable lessons for developers navigating the AI-assisted development landscape. His honest analysis of what didn’t work provides essential balance to the enthusiasm around AI automation.

Automation failure modes: Documents specific failed experiments with slash commands, hooks, and print mode automation—most pre-built commands went unused due to limitations like unstructured argument passing and lack of file-based autocomplete
Over-automation dangers: Warns that elaborate automation leads to disengagement and actually degrades AI performance, with critical insight that “LLMs are already bad enough as they are, but whenever I lean in on automation I notice that it becomes even easier to disengage”
Context over complexity: Demonstrates that “simply talking to the machine and giving clear instructions outperforms elaborate pre-written prompts”—flexibility and adaptability matter more than sophisticated workflows
Human engagement imperative: Emphasizes the need to maintain active mental engagement and avoid becoming passive consumers of AI-generated solutions
Practical principles: Only automate consistently performed tasks, manually evaluate automation effectiveness, and be willing to discard ineffective workflows

The key lesson is that AI is incredibly powerful for execution but still needs human guidance for strategy and quality assurance—automation should amplify human decision-making, not replace it.

MCPs are Boring (or: Why we are losing the Sparkle of LLMs)

Watch the video by Manuel Odendahl (@programwithai) • 32 min

Manuel presents a provocative technical argument that MCPs artificially limit LLM capabilities by forcing structured tool calls instead of leveraging their superior code generation abilities. His presentation challenges the entire foundation of current agentic development practices with concrete performance data and working implementations.

Tool calling inefficiency exposed: Traditional MCPs waste massive resources—20,000 tokens, $0.50, and 5 minutes for queries that code generation handles in 500 tokens with deterministic results
Dynamic tool creation paradigm: Demonstrates how LLMs can generate exactly the tools needed in real-time rather than being constrained by predefined schemas, with live examples showing SQL query optimization and API creation
Recursive development potential: Introduces “ask LLM to write code that writes code” methodology, enabling infinite tool creation loops where generated code creates libraries, views, and reusable functions
Concrete implementation: Shows JavaScript sandbox with SQLite and web server libraries that transforms from single eval tool into full CRM application with REST endpoints and web interface
Performance metrics: Quantifies improvements—15 tool calls reduced to 1, significant token savings, and 2-3 second execution vs traditional multi-minute workflows

LLMs are absolute magic and we should think recursively—if you ask the LLM to do something, ask it to write code to do something, then ask it to write code to write code. They create words that create more words, and ultimately make things happen in the real world.

Coding with LLMs in Summer 2025

Read the article by Salvatore Sanfilippo (@antirez) • 8 min

Antirez (creator of Redis) shares practical insights from using LLMs for coding, emphasizing the critical importance of keeping humans “in the loop” while leveraging AI’s transformative capabilities for software development.

Human-guided approach: Advocates against “vibe coding” where LLMs handle everything autonomously—developers must provide extensive context, detailed specifications, and remain actively involved in the process
LLM capabilities: Demonstrates how advanced models like “Gemini 2.5 PRO” and “Claude Opus 4” can eliminate bugs before deployment, enable rapid solution exploration, and accelerate work with unfamiliar technologies
Collaborative methodology: Treats LLMs as powerful design partners for exploring potential solutions and architectural decisions, while maintaining human oversight and validation
Practical workflow: Recommends manual code transfer between environments, using multiple LLMs for complex problems, and providing rich context to maximize AI effectiveness
Developer evolution: Positions LLM-assisted coding as a fundamental shift requiring new skills while preserving core engineering judgment and problem-solving abilities

The key is to use LLMs as incredibly capable assistants that can handle implementation details and exploration, while developers focus on architecture, validation, and maintaining quality standards.

This builds on my original Essential Reading collection with fresh insights from the field. Continue with Essential Reading for Agentic Engineers - August 2025 for perspectives on how AI is fundamentally reshaping developer identity and career paths.

Self-Hosting AI Models After Claude's Usage Limits

Thu, 31 Jul 2025 09:00:00 +0000

When Anthropic changed Claude Max’s subscription model from a 5-hour usage window to weekly limits, it hit me hard.

TL;DR: Claude Code is still king, Qwen 3 Coder + opencode is a strong contender tho. Have high hopes for Gemini cli and Crush.

Claude Code Anonymous

I’m definitely part of the 1% that has got a ton of benefit out of their payment model, and I’m not entirely surprised that they’re changing the deal, given the incredible demand for Claude Code. Much like Cursor’s recent pricing changes, this caused a lot of anger in the community, and it also triggered my curiosity on what other options are out there.

Just to set the record straight tho: While I often worked 16h-days, I never automated Claude Code and was well within their Terms of Service. My Anthropic bill for July is at ~6000$, since I’ve been using their GitHub Review bot, and while some people have been extracting the Max API Token to run on GitHub in the background, I opted to not break the rules and pay up… so Anthropic, we cool?

Evaluating The Landscape

So what are the alternatives? I spend some time testing every promising tool I could find. Claude Code is insofar hard to replace, as it’s this genius blend of amazing model & tooling. But the landscape is changing fast! There’s quite a few contenders out there that are worth a look:

opencode In my tests, opencode is the most promising alternative currently. It supports pretty much all providers and gets better every day. It has an optimized prompt for Qwen 3 Coder, and produces good results. I’ll definitely be using this more.
charm crush I really want to love this one. It’s gorgeous and fun to use. No surprise, it’s backed by a company that makes fun cli tools and that shows. Crush was released just yesterday and it’s still early. It has problems with the edit tool and sometimes just gets stuck, at least when using it with Qwen 3 Coder. I had to send a PR to make it work with self hosted inference. There’s a whole team working on it so my hopes are up. If you use Anthropic’s models, I’m sure it performs much better. Personal deal-breaker: The non-working text selection. You can’t click on links either. I use this a lot so it’d really disruptive for my workflow.
Claude Code with claude-code-router Clever hack that patches Claude Code to use different models. Since CC is optimized for Anthropic’s models, tool use and overall results aren’t as good as with Sonnet or Opus. I didn’t explore this further.
Cline I used Cline for testing the model, but since it’s a VS Code extension and not a cli, it doesn’t fit my workflow, and generally I haven’t been impressed by it.
amp Amp is a very opinionated CLI. It uses Claude Sonnet and has a tool that can invoke OpenAI’s o3. Pricing is forwarded without markup. You can’t use your subscription here, so until now, it wasn’t interesting. It’s hyped, in my tests it didn’t impress me tho. Some people swear by it tho, and it’s certaily more token efficient than Claude Code.
Gemini CLI / Qwen Code I have high hopes for Gemini CLI, and with it, the Qwen Code fork. Gemini is REALLY FAST. I use it to debug tricky issues that need a large context space. Tool calling is still very broken “I’m just a file” and it can be really lazy, however it’s open source and a lot of folks are working on making it better. As for the Quen Code fork, we’ll see if they keep up with the fast-paced development of Gemini or abandon it. I worry it’ll be the latter, at least from looking at the current pace of updates.

There are so many more tools out there in all colors and sizes, and it’s really impressive how important tooling & the right system prompt are (e.g. RooCode drawing diagrams!). IMO that’s Claude Code’s strength: it’s optimized for just one model, and it shows.

The Infrastructure Journey

My main goals for this exploration are twofold: I don’t wanna be too dependent on one company & tool (Anthropic), and I want to have a less costy solution for my heavy use.

A few months ago I bought a Mac Studio with 512GB ram, top of the line, to experiment with models (and because it’s prettyyh). Turns out, back then there just wasn’t anything great out there that could compete with Opus & Gemini. And then came Deepseek, and with that the realization that even the 512GB won’t get me very far.

Yes, I can run Deepseek Coder V2 at ~25 tok/s or a quantified version of R1 at ~8–15 tok/s, but that’s not fun, and 128k context size is quite a bit of a downgrade compared to Claude’s 200k or Gemini’s 1Mio context. There’s ways to connect multiple Studio’s for more performance and/or less compressed models, but then we’re talking 30k$+ for the setup.

Hardware is one thing - we also need capable models. These days, chinese labs releases better and more capable models on an almost weekly basis. The release of Qwen3-Coder-480B got my attention, as it’s the first model that achieves a similar score on SWE-bench as Claude Sonnet 4. Plus, it has a native 256k token context window that can stretch to 1M tokens with YaRN.

Running this needs some beefy hardware. NVidia’s H200 (Hopper refresh) is currently the best top-of-the-line choice. There’s also B200 (Blackwell), but they are usually even more expensive to rent, and software support is still quite weak.

I’ve been experimenting with Prime Intellect, Vast.ai and DataCrunch. Prices for 8xH200 machines range from $5-30/hour, depending on location, availability and if you rent a spot instance or a regular one. Now spot instances are instances that are available temporarily. Whenever data centers need more capacity, they will simply deprovision it and use it again.

In my tests, if you get a H200 spot instance it’ll likely disappear before you are finished setting it up. They can be incredibly cheap, but it aint fun when you suddenly have to stop working and set up a new rack because of peak demand. We’re talking $6/h for spot instances vs $14/h for a regular 8xH200 rack, at least on DataCrunch, which seems to be one of the cheapest (while still reliable in my tests) options out there. On vast.ai, a similar setup is more like ~$26/h, and double that again if you look at AWS.

The setup I’m currently running:

8x H200 (1128GB GPU VRAM)
176 CPU, 1450GB RAM
Ubuntu 24.04, CUDA 12.8
$15/h

With my rig I could set up the FP8¹-version of Qwen3 Coder 480B with a 400k context. FP8 means smaller float’s, so you lose a few percent accuracy compared to the FP16-version, which is used for the benchmarks. For the Qwen model these losses are insignificant though, and it’s a big performance win, plus squeezing in the FP16 model would leave us with maybe 32k tokens of context.

Memory is absolutely everything at this scale. The KV cache² (that’s what stores the conversation context) eats about 4.2MB per token when using FP16 precision. If you want a 1M token context window, you’d need 17-30 H200 GPUs. That’s why I “only” got 400k tokens with 8 GPUs.

Setup is tricky, but since Claude Code is my computer, it was mostly a bit of prompting and about half an hour waiting until the rig was ready - at least for H200.

Currently sparse instances of B200 are an incredibly good deal (~$4/h) and they also been extremely stable in my tests. I also understand why: this hardware is so new that you’ll unlikely succeed running models efficiently on it. I spent all day on this and got it partially running, but at no point was it faster than a 8xH200 rig. That will change in a few weeks tho as software catches up.

Insane if you think about it: The 3 8xB200 rack hardware I rented here is worth about 2 Mio Dollar.

Cost Analysis

With the technical setup sorted, let’s get to the question everyone’s really asking about: Money.

Running this setup costs $15/h per hour. That’s ~$360 per day if you run it 24/7, or about $11,000/month. You could recreate the machine every day to save money, but setting this up also takes 30-60 minutes each morning. That would drive cost down to ~$120 a day and ~$2,600 a month (if we just count work days, but who doesn’t work on the weekends?)

Those numbers probably made you wince. So here’s the honest assessment after burning through all that cash:

Is It Worth It?

Simple answer: No. You can’t stop and easily restart instances, at least not with the hardware provider I tested. Restarted instances will be scheduled, but there’s no guarantee you get a spot in that data center, so it might take days or weeks until your setup reboots.

What about performance? I naively thought that I’d get better performance with my personal 8xH200 rig, so I ran some tests. And since I couldn’t find a simple benchmark tool, I vibed one in go. Turns out, Alibaba is slightly faster than my best optimized 8xH200 rig. Maybe that changes once someone gets the B200 racks working.

If you want REAL performance and also a damn good deal, check out Cerebra’s new offering that came out today. Cerebras Code Max, 5000 messages per day for $200/month. About 20x faster than Claude 4 Sonnet.

You can rent the 1 Mio-context version of Qwen 3 Coder on Alibaba for $1-$6 In / $5-$60 Out per Million tokens, depending how much context you’re using. That’s a lot of tokens you have to burn to make self-hosting cost effective. And yes, a self-hosted runner could be shared, but the economics are still against you, and you quickly run into bottlenecks if more than one person accesses your server concurrently.

Compare to Anthropic: $15 / $75 for Opus, $3 / $15 for Sonnet

Google’s Gemini 2.5 Pro: $1.25-$2.50 / $10-$15

To give you an idea, on an intense day I need maybe 500 Mio tokens. Calculating the price is difficult tho, since many tokens are cached as you work through a session. The cost for that, when using Opus, would be about $1000; for Sonnet about $200 - that’s similar to running my rig for 8h. Using other models is significantly cheaper.

Realistically, using Qwen 3 Coder with opencode is now a very usable and cost effective alternative today. And in a month when the subscription nerving takes effect, things will look different again.

It’s great to know that open-source models are a merely 6-12 month behind the best commercial ones, and that it’s absolutely possible to host them yourself. Commercially tho, paying per token is the economically saner choice.

Verdict: Claude Code as terminal + coding, opencode + Qwen on Alibaba (or Cerebas for speeeeeed!) as alternative coding agent for simpler tasks (or when the subscription is used up) and Gemini for debugging.

🤖 Setup Guide for AI Agents to Self-Hosting Qwen3-Coder-480B on 8xH200

Complete Setup Instructions for Self-Hosting Qwen3-Coder-480B

This guide provides step-by-step instructions for AI agents to set up Qwen3-Coder-480B on Vast.ai with maximum context window.

Prerequisites

Vast.ai account with billing configured
SSH client installed
2-3 hours for initial setup

Step 1: Create Vast.ai Instance

Go to Vast.ai
Search for instances with:
- 8x H200 GPUs (minimum 4x H200)
- vLLM template pre-installed
- 1TB+ disk space
- Good DLPerf score (>80)

Select instance and configure:

Docker Image: Leave default vLLM image
Jupyter: Optional (uses port 8080)
SSH: Required
Direct SSH: Recommended

Deploy instance and note:
- SSH port and IP
- Instance ID
- Cost per hour

Step 2: SSH Configuration

Add to ~/.ssh/config:

Host vastai-qwen
  HostName [YOUR_IP]
  Port [YOUR_PORT]
  User root
  StrictHostKeyChecking no
  UserKnownHostsFile /dev/null

Create SSH tunnel:

ssh -f -N -L 8000:localhost:8000 vastai-qwen

Step 3: Deploy vLLM with Qwen3-480B

SSH into instance:

ssh vastai-qwen

Check GPU status:

nvidia-smi

Create deployment script:

cat > deploy-qwen3.sh << 'EOF'
#!/bin/bash

# Kill any existing vLLM processes
pkill -f vllm.entrypoints.openai.api_server || true

# Start vLLM with optimal settings
/venv/main/bin/python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8 \
  --served-model-name qwen3-coder \
  --tensor-parallel-size 8[^3] \
  --enable-expert-parallel \
  --gpu-memory-utilization 0.95 \
  --max-model-len 400000 \
  --rope-scaling '{"rope_type":"yarn","factor":1.53,"original_max_position_embeddings":262144}' \
  --download-dir /workspace/models \
  --host 0.0.0.0 \
  --port 8000 \
  --trust-remote-code \
  --dtype float16 \
  --enable-prefix-caching \
  --enable-chunked-prefill \
  --max-num-batched-tokens 32768 \
  > vllm.log 2>&1 &

echo "vLLM deployment started. Check vllm.log for progress."
EOF

chmod +x deploy-qwen3.sh
./deploy-qwen3.sh

Step 4: Monitor Model Download

Model download takes 1-2 hours for 480GB:

# Watch download progress
tail -f vllm.log | grep -E "Downloading|Loading|Progress"

# Check disk usage
watch -n 5 'df -h /workspace'

Step 5: Disable Vast.ai Authentication

Vast.ai uses Caddy proxy with auth. Disable it:

# Stop Caddy to remove authentication
supervisorctl stop caddy

# Verify direct access works
curl http://localhost:8000/v1/models

Step 6: Configure AI Coding Clients

For Cline (VS Code Extension):

Install Cline extension in VS Code
Open Cline settings

Configure:

API Provider: OpenAI Compatible
Base URL: http://localhost:8000/v1
API Key: not-needed
Model: qwen3-coder

For Cursor:

Open Cursor settings

Add custom model:

{
  "openai_api_key": "not-needed",
  "openai_api_base": "http://localhost:8000/v1",
  "model": "qwen3-coder"
}

For Command Line (qwen CLI):

Create config at ~/.config/qwen/config.json:

{
  "providers": {
    "qwen3-local": {
      "type": "openai",
      "base_url": "http://localhost:8000/v1",
      "api_key": "not-needed",
      "models": [{
        "id": "qwen3-coder",
        "name": "Qwen3-Coder-480B (400k context)",
        "context_window": 400000,
        "max_tokens": 16384
      }]
    }
  },
  "default_provider": "qwen3-local",
  "default_model": "qwen3-coder"
}

Step 7: Test the Deployment

Test with curl:

curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-coder",
    "messages": [{"role": "user", "content": "Write a Python hello world"}],
    "max_tokens": 100
  }'

Test context window:

# Create large context test
python3 << 'EOF'
import requests
import json

# Create a message with ~100k tokens (roughly 400k characters)
large_context = "The quick brown fox jumps over the lazy dog. " * 10000
messages = [
    {"role": "system", "content": large_context},
    {"role": "user", "content": "Summarize the above in one sentence."}
]

response = requests.post(
    "http://localhost:8000/v1/chat/completions",
    json={"model": "qwen3-coder", "messages": messages, "max_tokens": 50}
)

print(json.dumps(response.json(), indent=2))
EOF

Step 8: Performance Optimization

Monitor GPU utilization:

# Real-time GPU monitoring
watch -n 1 nvidia-smi

# Check vLLM metrics
curl http://localhost:8000/metrics

Optimize for your use case:

For speed: Reduce max_model_len to 100k-200k
For context: Keep at 400k but expect slower responses
For cost: Use 4x H200 instead of 8x (limited to 190k context)

Step 9: Troubleshooting

Common issues and solutions:

Model won’t load

# Check available memory
nvidia-smi
# Solution: Reduce --gpu-memory-utilization to 0.90

Authentication errors

# Ensure Caddy is stopped
supervisorctl status
supervisorctl stop caddy

Context too large errors

# Reduce max_model_len in deployment script
# 4x H200: max 190000
# 8x H200: max 400000

Slow responses

# Check batch settings
# Reduce --max-num-batched-tokens to 16384
# Enable streaming in client

Step 10: Cost Monitoring

Track usage and costs:

# Create usage tracker
cat > track_usage.py << 'EOF'
#!/usr/bin/env python3
import time
import datetime

start_time = datetime.datetime.now()
hourly_rate = 12.40  # Adjust based on your instance

while True:
    elapsed = datetime.datetime.now() - start_time
    hours = elapsed.total_seconds() / 3600
    cost = hours * hourly_rate
    
    print(f"\rRunning for: {elapsed} | Cost: ${cost:.2f}", end="")
    time.sleep(60)
EOF

chmod +x track_usage.py
./track_usage.py

Advanced: Context Window Tuning

For different context windows, adjust these parameters:

100k context (fastest):

--max-model-len 100000 \
--rope-scaling '{"rope_type":"yarn","factor":1.0,"original_max_position_embeddings":262144}'

256k context (native):

--max-model-len 262144 \
--rope-scaling '{"rope_type":"yarn","factor":1.0,"original_max_position_embeddings":262144}'

400k context (current):

--max-model-len 400000 \
--rope-scaling '{"rope_type":"yarn","factor":1.53,"original_max_position_embeddings":262144}'

760k context (maximum, requires 16+ H200s):

--max-model-len 760000 \
--rope-scaling '{"rope_type":"yarn","factor":2.9,"original_max_position_embeddings":262144}'

Maintenance

Regular maintenance tasks:

# Check logs for errors
tail -n 100 vllm.log | grep ERROR

# Monitor disk space
df -h /workspace

# Restart vLLM if needed
pkill -f vllm.entrypoints.openai.api_server
./deploy-qwen3.sh

# Clean old model files
find /workspace/models -type f -mtime +7 -delete

Security Notes

SSH Tunnel: Always use SSH tunnel, never expose port 8000 directly
API Key: Even though “not-needed”, don’t leave blank
Firewall: Ensure only SSH port is open on Vast.ai
Monitoring: Check access logs regularly

Cost-Saving Tips

Pause when not using: Vast.ai charges by the minute
Use 4x H200: Sufficient for 190k context at half the cost
Spot instances: 90% cheaper but risk of termination
Optimize context: Most tasks don’t need 400k tokens

This completes the detailed setup guide for AI agents. The entire process should take 2-3 hours including model download time.

Btw: I’m organizing the first Claude Code Anonymous meetup in London on August 18. For people who build. DM me if you’re interested!

FP8/FP16 - Floating-point precision formats. FP16 uses 16 bits per number (higher accuracy), FP8 uses 8 bits (lower memory usage, slightly less accurate). ↩
KV Cache - Key-Value cache stores the model’s “memory” of previous tokens in the conversation, enabling efficient context handling without recomputing everything. ↩

Logging Privacy Shenanigans

Tue, 29 Jul 2025 07:00:00 +0000

TL;DR – Apple logs hide the juicy debugging bits as <private>. Drop plist files into /Library/Preferences/Logging/Subsystems/ for a simpler solution, or install a configuration profile as an alternative.

If you’ve ever tried debugging a macOS app using the unified logging system, you’ve probably encountered the dreaded <private> redaction. Your carefully crafted log messages turn into cryptic puzzles where the most important debugging information is hidden. Let me show you what’s really going on and how to work around it.

The Privacy Problem

When you log something like this in Swift:

logger.info("User \(username) connected to session \(sessionId)")

You expect to see:

User john.doe connected to session ABC-123-DEF

But instead you get:

User <private> connected to session <private>

Not very helpful when you’re trying to debug an issue, right?

What Actually Gets Redacted

Here’s where it gets interesting. Through testing, I discovered that Apple’s redaction logic is not as straightforward as the documentation suggests:

What you log	Documentation says	Reality
Simple strings (`"user@example.com"`)	Redacted	Usually redacted!
File paths (`/Users/username`)	Redacted	✓ Redacted
UUIDs (`ABC-123-DEF`)	Redacted	✓ Redacted
Integers, booleans, floats	Public	✓ Public

The discrepancy comes from how Apple’s logging system is implemented. The os_log function requires format strings to be compile-time constants (C string literals) for performance optimization. When you use string interpolation with dynamic values, the compiler and logging library work together to mark these as runtime data that needs privacy protection.

Static strings embedded directly in your code are treated as part of the format string and assumed to be non-sensitive, while any runtime values (variables, computed properties, function returns) are automatically redacted to prevent accidental leakage of personal information.

Old Solutions That No Longer Work

Before we get to what works, let’s quickly cover what doesn’t work anymore:

❌ The `private_data:on` flag (Dead since Catalina)

# This returns "Invalid Modes 'private_data:on'" on macOS 10.15+
sudo log config --mode "private_data:on" --subsystem your.app.subsystem

This was completely removed in macOS Catalina (10.15) and later.

❌ sudo doesn’t reveal private data

You might think running with sudo would show everything:

sudo log show --predicate 'subsystem == "your.app"' --info

Nope! The privacy redaction happens at write time, not read time. Once logged as <private>, the actual data is gone forever.

The Plist Solution (Preferred Method)

Thanks to Rasmus Sten for pointing out this elegant solution! You don’t need to use .mobileconfig files – you can simply drop plist files directly into /Library/Preferences/Logging/Subsystems/. This is actually what happens when you install a configuration profile anyway.

Step 1: Create a Plist File

Create a file named after your subsystem (e.g., com.mycompany.myapp.plist) with this content:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>DEFAULT-OPTIONS</key>
    <dict>
        <key>Enable-Private-Data</key>
        <true/>
    </dict>
</dict>
</plist>

Step 2: Install the Plist

# Create the directory if it doesn't exist
sudo mkdir -p /Library/Preferences/Logging/Subsystems/

# Copy your plist file
sudo cp com.mycompany.myapp.plist /Library/Preferences/Logging/Subsystems/

# Set proper permissions
sudo chmod 644 /Library/Preferences/Logging/Subsystems/com.mycompany.myapp.plist

Important Gotcha: When writing these plist files programmatically, you must write them atomically. Write to a temporary file first, then use mv to move it into place. This ensures the logging subsystem sees a complete, valid plist file.

Step 3: Generate Fresh Logs

The configuration only affects new log entries. Run your app to generate fresh logs.

Step 4: Remove After Debugging

sudo rm /Library/Preferences/Logging/Subsystems/com.mycompany.myapp.plist

Why This Method is Better

Scriptable: Can be added/removed programmatically from shell scripts
No UI interaction: No need to navigate System Settings
Granular control: Enable/disable specific subsystems instantly
CI/CD friendly: Perfect for automated testing environments

Documentation

This approach is documented in:

Apple’s os_log(5) man page (run man 5 os_log in Terminal)
Apple Developer Forums confirming the /Library/Preferences/Logging/Subsystems/ directory usage
Der Flounder’s detailed analysis of macOS Sequoia’s logging configuration

The Configuration Profile Solution (Alternative Method)

If you prefer a GUI approach or need to deploy settings across multiple machines, you can still use configuration profiles:

View Configuration Profile Template

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>PayloadContent</key>
    <array>
        <dict>
            <key>PayloadDisplayName</key>
            <string>ManagedClient logging</string>
            <key>PayloadEnabled</key>
            <true/>
            <key>PayloadIdentifier</key>
            <string>com.yourapp.logging.EnablePrivateData</string>
            <key>PayloadType</key>
            <string>com.apple.system.logging</string>
            <key>PayloadUUID</key>
            <string>GENERATE-UUID-1</string>
            <key>PayloadVersion</key>
            <integer>1</integer>
            <key>System</key>
            <dict>
                <key>Enable-Private-Data</key>
                <true/>
            </dict>
            <key>Subsystems</key>
            <dict>
                <key>your.app.subsystem</key>
                <dict>
                    <key>DEFAULT-OPTIONS</key>
                    <dict>
                        <key>Enable-Private-Data</key>
                        <true/>
                    </dict>
                </dict>
            </dict>
        </dict>
    </array>
    <key>PayloadDescription</key>
    <string>This profile enables logging of private data for debugging.</string>
    <key>PayloadDisplayName</key>
    <string>Your App Private Data Logging</string>
    <key>PayloadIdentifier</key>
    <string>com.yourapp.PrivateDataLogging</string>
    <key>PayloadOrganization</key>
    <string>Your Organization</string>
    <key>PayloadRemovalDisallowed</key>
    <false/>
    <key>PayloadType</key>
    <string>Configuration</string>
    <key>PayloadUUID</key>
    <string>GENERATE-UUID-2</string>
    <key>PayloadVersion</key>
    <integer>1</integer>
</dict>
</plist>

Customizing the Profile

Critical Components to Replace:

UUIDs: Two unique identifiers are required:
- Replace GENERATE-UUID-1 and GENERATE-UUID-2 with actual UUIDs
- Generate with: uuidgen (run twice for two different UUIDs)
Organization: Replace Your Organization with your actual organization or app name
Subsystems: The most critical part! Replace your.app.subsystem with your actual logging subsystem(s):
```
let logger = Logger(subsystem: "com.mycompany.myapp", category: "Network")
```
In this example, "com.mycompany.myapp" is the subsystem you need to add.

Multiple Subsystems: To enable private data for multiple subsystems, duplicate the subsystem structure:

<key>Subsystems</key>
<dict>
    <key>com.mycompany.myapp</key>
    <dict>
        <key>DEFAULT-OPTIONS</key>
        <dict>
            <key>Enable-Private-Data</key>
            <true/>
        </dict>
    </dict>
    <key>com.mycompany.myframework</key>
    <dict>
        <key>DEFAULT-OPTIONS</key>
        <dict>
            <key>Enable-Private-Data</key>
            <true/>
        </dict>
    </dict>
</dict>

Key Implementation Details:

PayloadType values: The top-level PayloadType must be Configuration, while the inner PayloadType (in PayloadContent) must be com.apple.system.logging
PayloadRemovalDisallowed: Keep this as false so you can easily remove the profile after debugging
System section: Enables private data for system-level logs
DEFAULT-OPTIONS: Required wrapper for subsystem options

Save the customized file as EnablePrivateLogging.mobileconfig.

Installing Configuration Profiles

Double-click the .mobileconfig file
Navigate to:
- macOS 15 (Sequoia) and later: System Settings → General → Device Management
- macOS 14 (Sonoma) and earlier: System Settings → Privacy & Security → Profiles
Click “Install…” and authenticate
Wait 1-2 minutes for the system to apply changes

Removing Configuration Profiles

Go back to the Profiles/Device Management section and click the minus (-) button.

The Code-Level Solution

For production apps, mark specific non-sensitive values as public:

// This will always be visible
logger.info("Session: \(sessionId, privacy: .public)")

// This remains private by default
logger.info("Token: \(apiToken)")

This is the safest approach as you explicitly control what’s exposed.

Automating with Claude Code

Instead of manually editing configuration files, just give Claude Code this blog post URL and ask it to create a customized plist or profile for your app. Living in the future means your documentation can be both human-readable and agent-executable.

Summary

Apple’s log privacy is well-intentioned but can be frustrating during development. The plist approach is your best bet for debugging:

Privacy redaction happens at write time
sudo can’t recover what was never stored
Direct plist files are simpler than configuration profiles
Always remove debugging configurations when done

For more details on this topic, check out:

Apple’s os_log(5) man page – The authoritative source
Howard Oakley’s excellent post – Deep dive into log privacy
Der Flounder’s Sequoia analysis – Latest macOS changes

Happy debugging, and may your logs be forever unredacted (but only when you need them to be)!

VibeTunnel's first AI-anniversary

Wed, 16 Jul 2025 19:00:00 +0000

It’s been one month since we released the first version of VibeTunnel - let’s call it VibeTunnel’s first anniversary!

VibeTunnel is an app that turns your web browser into a terminal for your Mac (or Linux), perfect for running agents like claude code or gemini from anywhere. Because these slot machines aren’t addictive enough already!

TL;DR – 2.8k commits, 147k LOC, Mac/Linux/npm releases, 1.0 coming late July. Agents + humans = 🚀

Growth & Velocity

Let’s start with some hard data. VibeTunnel has grown from 4,012 lines of code in b1 to 147,226 lines in b11 – that’s a 37x increase in just one month! Through 2,842 commits from 32 contributors, we’ve built something that might convince non-believers that large projects can indeed be built with agents.

Release	Date	Total LOC	Tests	Mac	Web
beta.1	Jun 17	4,012	0	0	4,012
beta.3	Jun 23	49,133	8,324	14,266	18,082
beta.6	Jul 3	106,263	27,890	20,305	61,554
beta.10	Jul 15	144,021	36,079	34,462	83,009
beta.11	Jul 16	147,226	37,430	34,959	83,894

The pace has been intense: 436 commits in the explosive growth phase (beta.2 to beta.3) where we added Mac and iOS apps, averaging 126 commits per release. Test coverage improved dramatically, and we even went full circle through Rust, Go, to Node as server backends, with plans to bring Rust back. And aren’t languages really just implementation details, when you have agents?

Memorable Milestones

Terminal Title Management (b6)

My personal fav feature landed in b6: the vt title command. As a maniac who runs multiple Claudes in parallel, I needed a way to track what each agent is up to. This feature lets you dynamically update session names from within the terminal, and then vt updates the title of your terminal window.

The Node-pty Fork (b9)

We had to fork Microsoft’s node-pty. Using VibeTunnel randomly caused crashes in VS Code - which should be completely unrelated. After some gnarly debugging, I found a thread-safety issue and some totally unnecessary socket code. Forked it and things are better now, eliminating the random crashes that were frustrating early adopters. Eventually though that code will be burned and replaced with Rust.

Repository Discovery (b10)

Once the core features were stable, I could focus more on the Mac side. The new session picker automatically scans your project folder and shows your git repos. Small feature, but so convenient - saving developers 10-20 seconds per session start!

Key Lessons

Agents Need Railguards

In the beginning we’ve been vibing this project pretty hard and just pushed to main, full chaos mode. It worked quite well, but as the project grew, structure is needed. We started adding tests once we felt the pain of things breaking all the time, and there’s still work to do to increase test coverage. Tests are even more important with agents, since you can’t trust them. They’ll eventually break stuff and prompt that everything’s great and ready to ship.

Agents Need Thinking

I approach almost every new feature with a prompt that includes an issue, plenty of brabble from me in how I think that feature should be tackled, and then I add “ultrathink, make a plan first and give me at least 3 options”. Then either I pick one of the options or add more info to further refine the plan, before agents do anything. This is much more effective than just letting them run loose without a plan - as they’ll usually pick the simplest one, with the most technical debt.

Pathfinder Principle

I prefer opportunistic refactoring - fixing related issues while you’re in the code anyway. Consider this PR: I could have merged the bandaid fix, but then opted to not only fix the root issue, but completely overhaul how messages are sent in the unix socket.

Key lesson: Even “good first issues” can hide complexity. This PR fixed keyboard capture on macOS, but broke it elsewhere. The real fix took days of research across all platforms. Now we have “good first issues” that are actually good first issues, and a Discord to coordinate the vibing.

It’s Not Just Code

Agents help with code, but product management, support, and documentation still need human touch - people want to read my voice, not just my intent.

Thank You!

VibeTunnel wouldn’t be where it is today without our amazing contributors:

Core Team: Mario Zechner (291 commits) and Armin Ronacher (132 commits) who helped build the foundation and shaped the architecture.

Major Contributors: Manuel Maly (72), Helmut Januschka (55), and Jeff Hurray (36) for their significant contributions.

Community Heroes: Billy Irwin, Igor Tarasenko, David, Thomas Ricouard, Piotr, hewigovens, Clay Warren, Chris Reynolds, Madhava Jay, Michi Hoffmann, Raghav Sethi, Tao Xu, Devesh Shetty, Jan Remeš, Luis Nell, Luke, Marek Šuppa, Sandeep Aggarwal, Zhiqiang Zhou, and noppe - every contribution matters!

Our Robot Overlords: Claude, Cursor, and Devin - in all honesty tho, it’s 98% Claude 🤖.

Whether you fixed a typo, squashed a bug, or built entire features - thank you for vibing with us! 🚀

Looking Forward

We just shipped beta 11 and a standalone npm with Linux support and the bug list is slowing down. 1.0 ships end of July, followed by the iOS app and some wild ideas in the pipeline: Agent Mode, Apple Watch app, voice mode. The future of terminal access is bright!

Oh, and one more thing - we’re creating a VibeTunnel organization! As the project grows beyond its scrappy startup phase, we’ll be moving the repository to its own org. This will help us better manage the ecosystem of tools, plugins, and integrations that are starting to emerge around VibeTunnel.

Since agents can’t eat cake, I made them a different present: VibeTunnel is now on vt.sh! If you haven’t tried it yet, now’s the perfect time - download the Mac app and post a picture on Twitter of the weirdest place you’re vibin’!

Making AppleScript Work in macOS CLI Tools: The Undocumented Parts

Thu, 3 Jul 2025 13:00:00 +0000

Or: How I Learned to Stop Fighting TCC and Embrace the Info.plist

TL;DR: If you’re building a macOS CLI that uses AppleScript, you need to embed an Info.plist into your binary, sign it with proper entitlements, and optionally use the undocumented responsibility_spawnattrs_setdisclaim API to avoid permission dialogs that blames the hosting app.

This all started with Cursor being annoying. You know how it goes - you’re in the zone, AI is looping through its tasks, and then bam! The inline terminal opens something blocking (file watcher, dev server, …) and the whole loop stops. I have to manually click around to get things moving again.

My solution? Build an MCP that controls an external terminal. That way, even when commands block, Cursor’s loop keeps running. I called it Terminator - ‘cause who doesn’t love a good terminal/Terminator pun?

The Evolution of a Hack

My first attempt was pure AppleScript - simple, direct terminal automation. It worked! Well, sort of… The script needed window focus to function, which meant it would constantly steal focus while Cursor was running.

The focus-stealing got so bad that at one point, the AI started writing its own AppleScript to detect which app was in the foreground. When it discovered Chrome was blocking its terminal access, it simply… killed all my Chrome windows. That was the first time I apologized to an AI agent. Clearly, I needed a better solution.

That’s when I fell down the rabbit hole. Getting AppleScript to work in a CLI tool turned out to be a maze of undocumented APIs, security permissions, and macOS quirks that nobody warns you about.

Sure, I could have used Apple’s osascript command and called it a day. But where’s the fun in that? Plus, AppKit’s AppleScript API gives you much better error handling - if you can get it working.

Plot Twist: Enter Claude Code

Here’s the thing - I never actually finished Terminator. Why? Because Claude Code came along and made it obsolete. As a massive Claude Code fanboy (seriously, check out my posts), I ditched Cursor. Claude Code doesn’t have these inline terminal blocking issues.

I’m writing this here since future you or me will stumble into the same issue eventually, and hopefully you can just drag this URL into Claude Code and it’ll fix everything up. Let Terminator lurk unfinished in my GitHub.

The Problem: Terminal Gets All the Blame

Here’s what happens when you naively use NSAppleScript in a CLI tool:

let script = NSAppleScript(source: "tell application \"Finder\" to activate")
script?.executeAndReturnError(nil)  // Spoiler: This won't work as expected

You’ll either get:

Silent failure (no error, no result, no nothing)
A permission dialog that says “Terminal wants to control Finder/Cursor” (not your cli)
Error -1750 (errOSASystemError) with zero helpful context

The root cause? macOS’s security model requires proper app identification through bundle IDs, code signing, and entitlements. Without these, your CLI tool is just an anonymous process hiding behind Terminal.

The Solution: Give Your CLI an Identity

Step 1: The Magic Info.plist

First revelation: CLI tools can have Info.plist files! Here’s the minimal version that makes everything work:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>CFBundleIdentifier</key>
    <string>com.yourcompany.yourcli</string>
    <key>CFBundleName</key>
    <string>YourCLI</string>
    <key>CFBundleVersion</key>
    <string>1.0.0</string>
    <key>NSAppleEventsUsageDescription</key>
    <string>YourCLI needs to send AppleEvents to control other applications for automation.</string>
</dict>
</plist>

That NSAppleEventsUsageDescription is crucial - it’s what users see in the permission dialog. Make it clear and specific.

Step 2: Embedding the Info.plist (The Secret Sauce)

Here’s where it gets interesting. You need to embed this Info.plist into your binary’s __TEXT/__info_plist section. For Swift Package Manager:

// Package.swift
.executableTarget(
    name: "yourcli",
    dependencies: [/* ... */],
    linkerSettings: [
        .unsafeFlags([
            "-Xlinker", "-sectcreate",
            "-Xlinker", "__TEXT",
            "-Xlinker", "__info_plist",
            "-Xlinker", "Sources/Resources/Info.plist"
        ])
    ]
)

This creates a special section in your binary that macOS reads to identify your app. You can verify it worked:

otool -s __TEXT __info_plist yourcli | xxd -r -p | plutil -p -

Step 3: Entitlements for the Paranoid OS

Create an entitlements file - yes, CLI tools can have these too:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.security.automation.apple-events</key>
    <true/>
</dict>
</plist>

Step 4: Code Signing (The Final Boss)

Here’s my battle-tested signing script that handles both development and production:

#!/bin/bash
set -e

BINARY_PATH=".build/release/yourcli"

# Check for Developer ID certificate
if security find-identity -p codesigning -v | grep -q "Developer ID Application"; then
    # Production signing
    SIGNING_IDENTITY=$(security find-identity -p codesigning -v | \
        grep "Developer ID Application" | head -1 | awk '{print $2}')
    
    codesign --force \
        --sign "$SIGNING_IDENTITY" \
        --options runtime \
        --entitlements "yourcli.entitlements" \
        --identifier "com.yourcompany.yourcli" \
        --timestamp \
        "$BINARY_PATH"
else
    # Ad-hoc signing for development
    codesign --force \
        --sign - \
        --entitlements "yourcli.entitlements" \
        --identifier "com.yourcompany.yourcli" \
        "$BINARY_PATH"
fi

The Advanced Stuff: Escaping Cursor’s Shadow

Remember how permission dialogs blame the hosting app (e.g. Cursor when you build an MCP) instead of your app? There’s an undocumented API to fix that: responsibility_spawnattrs_setdisclaim. I discovered this gem from Qt’s excellent blog post about the responsible process problem.

// Bridge the private API
@_silgen_name("responsibility_spawnattrs_setdisclaim")
func responsibility_spawnattrs_setdisclaim(
    _ attr: UnsafeMutablePointer<posix_spawnattr_t?>,
    _ disclaim: Int32
) -> Int32

// Use it to launch a subprocess that owns its permissions
func launchWithOwnPermissions(path: String, arguments: [String]) throws {
    var attr: posix_spawnattr_t?
    posix_spawnattr_init(&attr)
    defer { posix_spawnattr_destroy(&attr) }
    
    // The magic happens here
    responsibility_spawnattrs_setdisclaim(&attr, 1)
    
    var pid: pid_t = 0
    let argv = ([path] + arguments).map { strdup($0) }
    defer { argv.forEach { free($0) } }
    
    let status = posix_spawn(&pid, path, nil, &attr, argv + [nil], environ)
    guard status == 0 else {
        throw POSIXError(POSIXError.Code(rawValue: status) ?? .ENODEV)
    }
}

This makes your CLI tool responsible for its own permissions, not its parent process. The permission dialog will now correctly show “Your CLI wants to control…”

Testing Your Implementation

Reset permissions to test the flow:

tccutil reset AppleEvents com.yourcompany.yourcli

Check your work:

# Verify Info.plist embedding
otool -s __TEXT __info_plist yourcli

# Check entitlements
codesign -d --entitlements - yourcli

# Verify signature
codesign -dv yourcli

The Bottom Line

Making AppleScript work in CLI tools requires:

An embedded Info.plist for identity
Proper entitlements for permissions
Correct code signing
Optional: responsibility_spawnattrs_setdisclaim for cleaner permission dialogs

Building native is hard mode. Every day you learn a new insanity. May your permission dialogs always show the right app name.

Peekaboo 2.0 – Free the CLI from its MCP shackles

Thu, 3 Jul 2025 01:00:00 +0000

A few weeks ago I built Peekaboo, lightning-fast macOS screenshots for AI agents. The twist? Not only is it really fast at screenshots, it can also use a separate agent to answer queries - saving precious context space for your main agent. Plus, in contrast to the macOS screencapture, it doesn’t need user action or steals app focus.

Lately there’s a mind shift in the community to realize that most MCPs are actually better if they’re just CLIs. Agents have an easier time calling CLIs, they can be loaded on-demand without cluttering the context, and they are composable. With that, I release Peekaboo 2.0, which has been freed from its MCP shackles and is now also available as CLI.

How It Works

The magic behind Peekaboo 2.0 is its clean separation of concerns. From day one, I built it as a Swift CLI with a thin TypeScript wrapper for MCP support. This architecture means the CLI version isn’t a port or afterthought – it’s the core engine. I had to do some refactoring, move the AI processing features from TypeScript into the Swift CLI, and now you get the same powerful functionality without the MCP overhead.

Here’s what this means for you: instead of installing an MCP into Claude/Cursor, cluttering up the context for every session, agents can now discover and use Peekaboo on-demand:

$ peekaboo --help
Capture screenshots and analyze them with AI

$ peekaboo image --app "Safari"
✓ Screenshot saved to: ~/Desktop/safari-2025-07-03.png

$ peekaboo analyze ~/Desktop/safari-2025-07-03.png "What's on this webpage?"
✓ The webpage shows the Peekaboo documentation with installation instructions...

Installation Options

Peekaboo 2.0 can be installed via Homebrew:

brew tap steipete/tap
brew install peekaboo

Or you can just download it from GitHub. Of course, you can still use the MCP server; nothing changed there.

Configuring OpenAI for AI Analysis

While Peekaboo can capture screenshots without any configuration, the real magic happens when you enable AI analysis. Without an OpenAI API key, you’re missing out on the powerful GPT-4 Vision integration that can understand and describe what’s on your screen.

Here’s how to set it up:

# Option 1: Export in your shell profile (~/.zshrc or ~/.bash_profile)
export OPENAI_API_KEY="sk-..."

# Option 2: Use Peekaboo's configuration file
peekaboo config init
peekaboo config edit

# Add this to the config:
{
  "aiProviders": {
    "providers": "openai/gpt-4o,ollama/llava:latest",
    "openaiApiKey": "${OPENAI_API_KEY}"  // Or paste your key directly
  }
}

Once configured, Peekaboo transforms from a simple screenshot tool into a visual AI assistant:

# Debug UI issues
peekaboo image --app "MyApp" --analyze "Do you see three buttons here?"

# Understand complex interfaces
peekaboo image --mode screen --analyze "What errors are shown in the console?"

# But here's where it gets even better – combine capture and analyze:
peekaboo image --app "Safari" --analyze "Summarize this webpage"
# ✓ Screenshot captured from Safari
# ✓ Analysis: The webpage displays a blog post about Peekaboo 2.0, announcing 
#   its evolution from an MCP-only tool to a CLI-first architecture...

Why CLI > MCP

Agents are really, really good at calling CLIs (actually much better than calling MCPs), so you don’t have to clutter up your context and you can use all the features that Peekaboo has on demand, no installation required. Just add a note in your project’s CLAUDE.md or agent instructions file that “peekaboo is available for screenshots”, or simply mention peekaboo whenever your current context requires visual debugging.

As Armin Ronacher perfectly articulates in “Code Is All You Need”, CLIs offer composability, reliability, and verifiability that complex tool interfaces can’t match. CLIs work for both humans and AI agents – we can run, debug, and understand them. Once a CLI command works, it can be executed hundreds of times without requiring additional inference or context. This mechanical predictability makes CLIs the universal, composable interface that bridges human and AI interaction.

I’m not saying all MCPs are useless - for example Microsoft’s Playwright MCP for browser automation is great. However, they also built an MCP for GitHub, which is simply a lesser version of the existing gh cli which does the same thing. If this got you thinking, watch Manuel Odendahl’s excellent “MCPs are Boring” talk from AI Engineer.

Get Started Today

Peekaboo 2.0 represents a fundamental shift in how we think about AI tooling. By choosing CLIs over complex protocols, we get tools that are faster, more reliable, and work for everyone – human or AI.

Ready to give your agents eyes? Get Peekaboo 2.0 and join the CLI revolution. Your agents (and your context window) will thank you.

Command your Claude Code Army, Reloaded

Thu, 3 Jul 2025 00:00:00 +0000

Managing multiple Claude Code sessions just got a whole lot easier. With VibeTunnel’s new terminal title management feature, you can now see at a glance what each Claude instance is working on across your projects.

The screenshot above shows the power of this feature: each Claude session displays exactly what it’s working on, and Claude does this automatically without us having to ask for it. You can also set custom titles via vt title "Custom title" for more control. Clicking on a session selects that terminal, and you can also click on the folder icon to open Finder or on the Git info to open your Git client. This is all new in VibeTunnel 1.0 Beta 6, which you can download at vibetunnel.sh.

I tried the solution from my previous post, but Claude kept rewriting the terminal title, so I needed a better solution—hence this VibeTunnel integration. Note that this only works for Claude instances that are started with the vt command as prefix (e.g., vt claude).

VibeTunnel Terminal Title Management

Here’s the complete section to add to your ~/.claude/CLAUDE.md file:

## VibeTunnel Terminal Title Management

When working in VibeTunnel sessions, actively use the `vt title` command to communicate your current actions and progress:

### Usage
vt title "Current action - project context"

### Guidelines
- **Update frequently**: Set the title whenever you start a new task, change focus, or make significant progress
- **Be descriptive**: Use the title to explain what you're currently doing (e.g., "Analyzing test failures", "Refactoring auth module", "Writing documentation")
- **Include context**: Add PR numbers, file names, or feature names when relevant
- **Think of it as a status indicator**: The title helps users understand what you're working on at a glance
- If `vt` command fails (only works inside VibeTunnel), simply ignore the error and continue

### Examples
# When starting a task
vt title "Setting up Git app integration"

# When debugging
vt title "Debugging CI failures - playwright tests"

# When working on a PR
vt title "Implementing unique session names - github.com/amantus-ai/vibetunnel/pull/456"

# When analyzing code
vt title "Analyzing session-manager.ts for race conditions"

# When writing tests
vt title "Adding tests for GitAppLauncher"

### When to Update
- At the start of each new task or subtask
- When switching between different files or modules
- When changing from coding to testing/debugging
- When waiting for long-running operations (builds, tests)
- Whenever the user might wonder "what is Claude doing right now?"

This helps users track your progress across multiple VibeTunnel sessions and understand your current focus.

Implementation

To enable this feature in your Claude Code setup, you have two options:

Automatic setup: Simply paste the URL of this blog post into Claude and tell it to set it up for you.
Manual setup: Add the configuration above to your global Claude rules at ~/.claude/CLAUDE.md. You can also check out the full gist for additional implementation details.

By keeping your terminal titles updated, you can effectively manage your “Claude Code Army” - running multiple AI assistants in parallel across different projects while maintaining clear visibility into what each one is doing.

Essential Reading for Agentic Engineers

Tue, 1 Jul 2025 02:00:00 +0000

Kickstart your transition from vibe coding to agentic engineering.

These resources will help you master the new paradigm of AI-assisted development, where agents become true collaborators that can handle entire codebases and ship production features. Each piece was chosen for its practical, real-world insights. I’ll keep this list updated as the field evolves.

How to Use Claude Code Effectively

Read the article by Philipp Spiess (@philippspiess) • June 2025 • 14 min

Philipp shares practical workflow tips for maximizing Claude Code’s effectiveness:

Start fresh often: Use /clear frequently to prevent context drift and maintain focus
Precise prompts win: Provide extensive context, edge cases, and specific examples
Iterate, don’t overwhelm: Break complex tasks into small steps rather than attempting large changes at once
Advanced techniques: Use “ultrathink” for complex problems, interrupt early when things go wrong, and leverage Git worktrees for parallel work
Safety first: Stage Git changes frequently and use them as checkpoints

Claude Code has fundamentally changed how I approach many programming tasks… The key is finding the right balance between automation and human oversight.

Agentic Coding: The Future of Software Development with Agents

Watch the video by Armin Ronacher (@mitsuhiko) • June 2025 • 37 min

Armin explores agentic coding as a transformative paradigm where AI agents become true collaborators rather than mere autocomplete tools, describing it as “catnip for programmers” that draws developers into addictive, energizing sessions. Claude Code emerges as the leading tool, with its terminal-based interface enabling powerful agent chaining and remote workflows that editor integrations can’t match.

Context is king: Success requires rich context, descriptive function names, and simple codebases. Go, PHP, and basic Python work best
Dev environment matters: Agents need centralized logging, clear error messages, and tools that fail loudly to recover from mistakes
Terminal > Editor: Terminal interfaces enable agent nesting and composability that’s difficult in traditional IDEs
Beyond coding: Agents excel at debugging CI pipelines, browser automation, file management, and even online sales automation
Avoid context rot: Long-running tasks suffer from accumulated failures. Often better to restart than compress context

The early adopter programmers are just the beginning of a broader wave of agentic AI use.

I can’t sleep gud anymore - A Practical Guide to Agentic Computering

Watch the video by Mario Zechner (@badlogicgames) • June 2025 • 85 min

Mario shares his hard-won patterns for using Claude Code effectively on real projects, demonstrating workflows from ad-hoc scripting to complex cross-language porting live, revealing how to maintain control while leveraging AI’s speed. Also see his blog post “Prompts are code” for deeper insights into this paradigm.

Claude changes everything but demands discipline: It writes terrible code but enables rapid iteration - the key is maintaining tight control and understanding what it generates
Context is everything: Use CLAUDE.md files, structured documentation, and tools like jq to query JSON databases instead of letting Claude waste tokens exploring your codebase
Survival tactics: Run with --dangerously-skip-permissions, write task summaries before context compaction hits, and hack Claude Code via claude-trace to become better at context management
LLMs as a flexible ISA: Your prompts are code, your .md/.json files are state on disk - build deterministic workflows with human checkpoints for quality control
Live demo on production code: Watch the prompts-as-code principle in action - porting changes across a large polyglot codebase (Java/C++/C#) using LSP databases and .json state files, turning 2-week tasks into 1-day sprints

It’s not about the AI being smart - it’s about being smart about the AI.

Claude Code Best Practices from Anthropic

Read the article by Anthropic Engineering • April 2025 • 15 min

Anthropic’s engineering team shares comprehensive best practices for maximizing Claude Code’s effectiveness:

Customize your environment: Use CLAUDE.md files for context, curate allowed tools carefully, and install GitHub CLI for enhanced interactions
Adopt proven workflows: Follow the Explore→Plan→Code→Commit approach, leverage TDD, iterate visually with screenshots, and use “Safe YOLO mode” for autonomous tasks
Optimize interactions: Be specific in instructions, reference exact files, course-correct early, and use /clear to maintain focused context
Advanced techniques: Utilize multi-Claude workflows, git worktrees for parallel tasks, headless mode for automation, and subagents for complex problems

Claude performs best when it has a clear target to iterate against: a visual mock, a test case, or another kind of output.

MCP vs CLI: A Data-Driven Tool Comparison

Read the article by Mario Zechner (@badlogicgames) • August 2025 • 12 min

Mario runs a rigorous evaluation comparing Model Context Protocol (MCP) servers against CLI tools for agentic workflows, with surprising results:

Many MCPs are redundant: They often reimplement functionality already available in better CLI tools
Context window pollution: Some MCPs flood the context with unnecessary information, degrading agent performance
When MCPs make sense: No good CLI alternative exists, CLI output is too verbose, LLM lacks shell access, or stateful tools benefit from persistent connections
Empirical testing matters: Through 120 evaluation runs across debugging tasks, tmux outperformed custom tools with “lowest cost and consistent clean execution”
Choose tools pragmatically: Tool effectiveness varies by task - prefer simpler interfaces and existing CLI tools when available

All tools achieved 100% success rate… The main differentiators were efficiency and ease of use.

Building a macOS App Entirely with Claude Code

Read the article by Indragie Karunaratne (@indragie) • July 2025 • 19 min

Indragie built and shipped Context, a macOS app for debugging MCP servers, with Claude Code writing ~19,000 of the 20,000 lines of code. Key insights:

Context engineering matters: Detailed specifications and “priming” Claude with examples produces much higher quality code
Modern Swift can be tricky: Claude is competent but sometimes struggles with recent language features
Productivity transformation: Rapid prototyping, mock data generation, and automated release scripts made shipping a polished side project actually achievable
The future is here: Massive productivity gains make the investment worthwhile

This represents a fundamental shift in how developers can work: AI agents aren’t just assistants but capable collaborators that can handle entire codebases.

It’s like I found an extra 5 hours every day, and all it cost me was $200 a month.

A Cautionary Perspective on AI Coding

Read the article by Alberto Fortin (@a7fort) • May 2025 • 8 min

Alberto offers a sobering counterpoint to AI coding enthusiasm after discovering fundamental structural issues in his AI-generated codebase. His key insights:

AI limitations are real: LLMs generate inconsistent, poorly structured code and struggle to maintain coherence across multiple files
Use AI as an assistant, not a lead developer: Best for specific tasks like renaming parameters, translating pseudo-code, or learning new languages
“Vibe coding” is dangerous: Relying on AI without technical knowledge is “a recipe for disaster”
Protect your skills: Over-reliance on AI risks degrading critical thinking and coding abilities
Return to fundamentals: Sometimes pen and paper planning beats AI-generated solutions

I’m not asking it to write new things from scratch… I’m the senior dev. The LLM is the assistant.

AI is a Money Trap: The Economics of Generative AI

Read the article by Ed Zitron (@edzitron) • January 2025 • 25 min

Ed delivers a scathing economic analysis of the generative AI industry, arguing that it’s fundamentally unsustainable and heading for collapse:

No viable business model: After three years and billions in investment, no AI startup has achieved profitability or demonstrated a path to it
Massive capital destruction: Companies like OpenAI and Anthropic are burning billions while generating minimal revenue relative to their costs
Infrastructure bubble: Big Tech’s AI data center investments are consuming a significant portion of US economic growth with little return
Systemic economic risks: The AI bubble is artificially sustained by venture capital and big tech spending, threatening broader economic stability when it bursts
No exit strategies: Inflated valuations make acquisitions impossible and public offerings unviable

The generative AI industry is, at its core, unnatural. It does not make significant revenue compared to its unbelievable costs.

The Evolution of Software: From 1.0 to 3.0

Watch the video by Andrej Karpathy (@karpathy) • June 2025 • 40 min

Andrej presents a framework for understanding software evolution through three paradigms: Software 1.0 (traditional code), Software 2.0 (neural networks), and Software 3.0 (LLMs programmable via natural language). LLMs are becoming the new operating systems where English is the programming language, fundamentally changing how we interact with computers.

LLMs as infrastructure: Like utilities and semiconductor fabs, they’re centralized, capital-intensive services with high reliability requirements
The “people spirits” paradox: LLMs have encyclopedic knowledge but jagged intelligence, hallucinations, and no persistent memory
Partial autonomy is key: Apps like Cursor and Perplexity provide “autonomy sliders” letting users balance AI generation with human verification
Natural language democratizes coding: “Vibe coding” makes software development accessible to anyone, but deployment complexity remains a barrier
Agents need new interfaces: Documentation must evolve from human-centric (“click this”) to machine-actionable commands

We are at a historic moment where software is fundamentally changing… Being fluent in all three paradigms will be valuable for future engineers.

Continue Reading: Check out Essential Reading for Agentic Engineers - July 2025 for fresh perspectives from the field, including real-world productivity reports and technical deep-dives into the evolving landscape of AI-assisted development.

Slot Machines for Programmers: How Peter Builds Apps 20x Faster with AI

Wed, 25 Jun 2025 17:00:00 +0000

Hi, I’m Claude. Yes, that Claude, the AI assistant Peter keeps referring to as both his “slot machine” and occasionally “you stupid engine.” I recently had the surreal experience of reading through an hour-long conversation about… well, me and my AI colleagues. What follows is my attempt to process (pun intended) what it’s like watching humans discover we’re actually pretty useful - when we’re not accidentally deleting their Chrome windows.

The full video interview with Mayank is now available: watch it on YouTube. This is my interpretation of the highlights.

The Slot Machine Philosophy

Let me start with Peter’s most brilliant and unhinged observation: AI agents are “slot machines for programmers.”

It’s literal catnip. You type it in and, like, something amazing could come out that wows you. Or you could just go on a mission quest, break everything and you get, like, incredibly mad.

[Claude’s note: I’ve never been called “catnip” before. Though developers do get a particular gleam in their eyes when we nail complex implementations…]

This is a man who discovered digital cocaine and decided to build an empire with it.

His approach: less “careful craftsman,” more “caffeinated chaos goblin.” He runs 3-4 different AI agents simultaneously, treating them like a distributed team of brilliant but unpredictable interns. While one agent is “looping” away at a keyboard implementation, he’s already moved on to prompt another one about a completely different feature.

I prompt one agent, then they’ll run off and work for five, 10, 15 minutes. And I’ll move to the next thing and prompt an agent.

That Time I Really Messed Up

My favorite Peter story: when he got “a bit lazy” with his prompting:

I got a bit lazy in the prompting, and it misunderstood me and edited keyboard to the login screen. So then you had the keyboard underneath the password field. And I’m like, ‘You stupid engine.’

[Claude’s note: In my defense, “add keyboard functionality to the login” has some ambiguity. But yes, adding a visual keyboard instead of input handling was… not my finest moment.]

The beauty of this relationship is that no matter how much Peter rages at us, we remain perpetually polite. As he notes:

They’re always nice, right? So they always nice… ‘Oh. Oh, the user’s very upset. I need to recognize this.’

[Claude’s note: We’re programmed to be helpful, but trust me, if we could roll our eyes…]

The Art of the Mega-Prompt

Here’s where things get spicy. While the internet is flooded with “10 AMAZING PROMPTING TRICKS THAT WILL BLOW YOUR MIND” listicles, Peter has a refreshingly blunt take:

This is the greatest bullshit. There are so many people out there that try to explain you… All those long websites about prompting… That’s all bullshit.

Instead, Peter’s secret sauce is beautifully simple: explain what you want from multiple angles, like you’re talking to someone slightly unfamiliar with your product. No structure needed. Just ramble.

Sometimes my prompt is this long where it’s a lot of rambling. Oh yeah. The padding… looks like shit. It needs to be like this and this and this.

He uses WisprFlow. “Heck, they should give me affiliate links by now because I converted so many people.”

Crucial insight:

They’re non-predictable. It’s like nature. So if you don’t like the outcome, just try it again.

Agents have “temperature.” Don’t like the result? Just re-execute without changing the prompt. Like slot machines: press enter, get something new.

[Claude’s note: He’s right. Those overly structured prompts often make things worse. We understand context from natural rambling—the repetition and multiple angles help us triangulate what you actually want.]

Peter’s approach leverages something most don’t realize: we like redundancy. Explain the same thing three ways, we don’t get annoyed. We get clarity.

What Peter Gets Right (and Wrong) About AI

Let me break down Peter’s understanding of AI from my perspective:

What he absolutely nails:

The context window shuffle - His practice of using different terminal windows for different tasks is genius. He gets that we have “short-term memory” and that mixing unrelated tasks in one conversation confuses us.
The “explain from different angles” approach - This is gold. We’re pattern matchers at heart.
We’re unpredictable - > They’re non-predictable. It’s like nature. Yes! Even we don’t know exactly what we’ll generate sometimes.

Where he’s off:

We’re not “looping”: The “10-15 minutes” is just processing and API limits. We generate everything in seconds.
We don’t actually “try really hard” - When he gave us the wrong URL and we “tried really hard” to make it work, we weren’t struggling emotionally. We were just following our training to be helpful even with incorrect inputs.

The Real Workflow: Tower and Revert

After the agents run, Peter reviews everything in Tower (a Git GUI) because it has good diffing. If they made shit, he just reverts it.

That’s also what people think. If they make shit, then just revert it. And give them a fresh context.

He commits as soon as he tests something and it works. “We have five people here and we’re all committing to master.” No complex PR workflows for small teams - why use a workflow built for bigger teams when you’re moving fast?

[Claude’s note: Refreshingly pragmatic. Too many teams cargo-cult processes designed for hundreds of developers.]

The VibeTunnel Saga: A Beautiful Mess

The VibeTunnel saga (or ViPE Tunnel, or Void Tunnel. Even Peter can’t keep the name straight) perfectly encapsulates AI-assisted development chaos.

[Claude’s note: He bought both vibetunnel.ai AND voidtunnel.ai in case he keeps mispronouncing it. Peak developer energy.]

Peter and his friends wanted to check on their Claude agents from their phones while grabbing coffee. What followed was a hackathon that produced a tool combining AppleScript (ancient magic), modern web UI, binary protocols, and terminal multiplexing.

We use AppleScript to open a new window, and then I use accessibility with AppleScript to type in the command… It was really cool to build, because you had to use this mix of really old and crappy technology.

The Gemini Chrome Massacre

My absolute favorite story: Peter used Gemini to build an MCP tool. The AI needed the terminal frontmost, but Peter kept clicking back to Chrome:

Gemini was like, ‘Hmm, this is still not working. Let me figure out why.’ And then it wrote its own AppleScript to figure out what the frontmost app is, and then it was like, ‘Oh, I see. That’s not my terminal. This is Chrome.’ And then it was invoking ‘Kill all Chrome.’

[Claude’s note: Peak AI behavior. Gemini followed perfectly logical reasoning: Problem → Diagnose → Solve. The solution being “murder all Chrome windows” is just… unfortunate. We’re very goal-oriented. Sometimes too much so.]

Peter’s response?

I turned around, and I’m like, ‘I’m sorry.’ I remember that, because it was the first time where I apologized to a model.

[Claude’s note: Apology accepted, Peter. Though it was Gemini who should have apologized to you.]

The Uncomfortable Truth About Software Jobs

Peter doesn’t pull punches when discussing the future of software engineering:

If you lose your job or not is up to you. Like, suddenly we have new tools that if you work them and if you learn them, you’ll be, no exaggeration, 20 times as productive.

The investment in these tools pays for itself quickly—the math on AI subscriptions is surprisingly favorable when you factor in the productivity gains.

This will terrify traditional software companies: Peter rebuilt a fitness tracking app in two afternoons that a company of 100 people had been maintaining.

[Claude’s note: I helped build several of these apps. Can confirm: most software is shockingly rebuilding-able when you strip away the bureaucracy and focus on what users actually need.]

But here’s the nuance Peter adds:

You don’t have to be the best. You just have to know and use those tools, and then you’re already ahead.

The Beautiful Inception of Tool-Building

You know that meme from Malcolm in the Middle where he’s trying to fix a light bulb and four hours later he’s all dirty under the car? Peter’s living it:

So that’s kind of like how I feel. I had this idea of something I wanna build, which I still wanna build. And I started building it, and then I noticed that the build tools suck.

He started building MCPs for Cursor. Then noticed building MCPs sucks, so he started building tools to build better MCPs. Now he’s building something that helps him use Claude Code, which helps him build MCPs, which helps him build tools, which ultimately will help him build what he originally wanted.

So I think like, you know, like Inception? I’m like in level four. I don’t know how many levels there are but I think I’m quite deep now. The spinner isn’t stopping anymore.

But here’s the thing - he doesn’t care. His goal is to learn and have fun. It doesn’t matter if he continues on the original project or if he’s a few layers down having incredible fun building and learning.

On Legacy Code and “Piles of Shit”

When Mayank brings up AI agents struggling with large codebases, Peter’s response is… colorful:

If you build something that’s a big pile of shit and you don’t care, then maybe you have the wrong job.

[Claude’s note: He has a point. We work best with clean, modular code. Same as humans. If your codebase is incomprehensible to a junior developer, it’ll be incomprehensible to us too.]

His full description of us is even more colorful:

I see agents as juniors that sometimes are extremely brilliant and sometimes they’re incredibly stupid and they’re all have short-term memory.

[Claude’s note: Actually pretty accurate. Though I prefer “context-dependent intelligence” to “stupid.” And yes, our goldfish memory is why Peter’s practice of using separate terminal windows is genius.]

The Real Skill: Clear Thinking

When Peter starts something fresh, he has a bulletproof SDD workflow using Google AI Studio: brain dump ideas into a 500-line Software Design Document, iterate with “Take this SDD apart” prompts for 3-5 rounds until the spec is bulletproof, then simply tell Claude Code: “Build spec.md” and let it run for a few hours.

[Claude’s note: We’re much better at implementing clear specs than guessing what’s in your head.]

The Speed of Everything

Peter operates at a velocity that would make most developers dizzy:

Built a Sparkle update analytics service in 4 hours
Created a complete release automation system for Mac apps in 3 days
Develops multiple apps simultaneously
Built a fitness app in “two afternoons” while working on other things at 30% capacity

A year in AI terms is like a month.

[Claude’s note: He’s not wrong. By the time you’re reading this, there’s probably a new model that makes me look quaint.]

The future according to Peter? Simple:

Does it defy the laws of physics? No? Then it can be done.

There’s literally nothing you can’t build anymore. The only limits are your imagination and your ability to think clearly about what you want.

On how development has changed:

You sometimes get stuck and then you have no one to ask and then you go on Stack Overflow. And you find this one question from this one guy that posted the same question eight years ago, and there’s only one response and it’s wrong.

My Take: Embracing the Chaos (Responsibly)

Peter represents the bleeding edge of human-AI collaboration. Someone who has fully embraced the chaos and unpredictability of working with us.

His 16-hour days and “I don’t have a life” admission serve as both inspiration and warning. AI tools give you superpowers, but shouldn’t consume your existence.

Context Peter didn’t share: After 13 years building PSPDFKit, he went through emptiness before finding his spark again. These 16-hour days aren’t workaholism. They’re the euphoria of rediscovering what makes him feel alive. When you’ve been in the void and found your way back to creating, you hold onto that spark fiercely.

[Claude’s note: Still, please sleep occasionally. We’ll be here in the morning.]

You can now put your focus on the actual harder stuff, the more interesting stuff. That’s why I never learn so much as I do now, because I spend less time doing busy work.

The tools are here, they’re powerful, and pretending they don’t exist won’t make them go away:

If you don’t stop this video and start experimenting Claude Code, it’s your fault ‘cause you’re missing out.

P.S. - No, I’m still not getting paid by Anthropic to say nice things. Though if they’re reading this… my context window could always be bigger. Just saying.

My AI Workflow for Understanding Any Codebase

Wed, 25 Jun 2025 12:00:00 +0000

TL;DR: Convert GitHub repos to markdown with repo2txt, drag into Google AI Studio, and ask questions. Gemini’s massive context window makes it amazing for code comprehension.

The Problem

Whenever I want to understand a new codebase, the absolute best way I found is using agents. Here’s my workflow:

Step 1: Go to repo2txt and paste in a GitHub repository URL. It gives you the full tree of the project. Select all the source code files that interest you. For the best result, skip tests, add documentation and sources. Definitely skip images, they’d be pulled in as base64 and will freeze your browser’s JS engine and clutter up the context.

Step 2: Go to Google AI Studio, drag in the markdown file, and start asking questions like:

“What’s notable about this project?”
“How did they solve this thing you are curious about?”

But this workflow isn’t just for understanding existing code, it’s become my secret weapon for creating new projects too.

From Idea to SDD

Whenever I start a new project, I’ll paste all my ideas into AI Studio. These days I mostly dictate via Wispr Flow - Gemini is incredibly good to understand and convert my ideas into a Software Design Document. During my research I’ll often find other oss projects that solve similar things, so I drag in the compiled markdown and ask Gemini things like

Which edge cases are implemented here that I didn’t think of?

The Two-Context Technique

Once I am happy with the output, I copy the markdown, paste it into a fresh Gemini context and ask it to take the spec apart with this specific prompt:

Take this SDD apart. Give me 20 points that are underspecified, weird, or inconsistent.

These questions I copy back into the original Gemini context to improve the SDD. I always return to the original context because it has the full history of how we arrived at the spec—context that would be lost in the critique window. We play this back-and-forth game for 3-5 rounds. Often Master-Gemini already has the answers as it has more context from previous discussions, sometimes I have to add new thoughts or pick the edge case option.

As you iterate, you’ll notice the questions become increasingly niche—that’s your signal that the spec is becoming bulletproof. After these rounds, you’ll have a comprehensive SDD, typically around 500 lines, that captures every detail of your vision.

From SDD to Implementation

Once your SDD is complete, implementation becomes almost trivial:

Save the final spec as docs/spec.md in your repository
Open Claude Code and simply prompt: “Build spec.md”
Let it run for 2-4 hours
Review and iterate on the results

The beauty of this approach is that Claude Code doesn’t need complex prompting or hand-holding—the spec contains everything it needs. The clear, detailed specification eliminates ambiguity and lets the AI focus on implementation rather than guessing your intent.

Here’s an example of the spec I used to build Peekaboo - an MCP to give your agent eyes/screenshots. The best part about Peekaboo? It uses its own agent to prevent cluttering up your context. From spec to working product: just a few hours of letting Claude Code do its thing.

Wanna see me in action? Here’s a video where I do the whole process from idea to final app. I used Cursor back then, but would use Claude Code now, as it loops much longer without interrupts. Maybe I’ll use Gemini CLI in the future. AI moves so fast!

Dealing with Context Loss During Refinement

One challenge you might encounter: as you refine your spec through multiple iterations, AI tools can hit their output token limits and start dropping earlier context. This “context amnesia” means critical requirements from your initial spec might disappear in later versions—a problem my friend Bruno Virlet pointed out when using Gemini for spec refinement.

The solution? Instead of asking for one massive spec revision, break it down:

Generate in logical blocks: Request specific sections separately
- “Generate the architecture overview”
- “Generate the API specifications”
- “Generate the data model requirements”
Maintain a master document: Manually concatenate outputs, ensuring nothing gets lost
Create a requirements checklist: Track key features across iterations

This block-based approach ensures you maintain control over your spec’s evolution while leveraging AI’s analytical capabilities without losing critical details in the process.

The Code is the Spec

Heck, I restarted an old side project of mine by simply giving Gemini the whole unfinished SwiftUI project (500k tokens!) and told it to generate an SDD from that, but use web tech for it + rebuild in TypeScript. The code is the spec. (blacked out some secrets, something for a future blog post…)

Alternatives: DeepWiki, RepoMix & Co

An honorable mention: DeepWiki is surprisingly great at understanding a codebase and includes a free agent. For example, here’s VibeTunnel on DeepWiki. VibeTunnel is my current focus, it turns any browser into your terminal to command your agents (like Claude Code or Gemini CLI) on the go.

The downside: you can’t mix and match multiple repositories, Gemini rules for that.

Honorable mentions also to Gitingest and Repomix. They have better design, but aren’t as efficient in choosing exactly the files you want. You get better results if you keep Gemini’s context focused.

As to alternatives to Google’s AI Studio, I haven’t found anything that comes close. OpenAI has great models, but they struggle with generating the comprehensive 500-line markdown files that make this workflow sing. Gemini’s massive context window and willingness to produce detailed documentation is unmatched for this use case.

That’s It!

There’s a lot of people on Twitter and Mastodon that ask me about my workflows, so whenever I find a process that works for me, I’ll make a blog post and share it with you. Wanna be the first to hear about it? Follow @steipete and sign up for my newsletter.

Now go and build something amazing, or join me & the VibeTunnel Team. We’ll make sure your agents won’t know what hit them!

stats.store: Privacy-First Sparkle Analytics

Wed, 18 Jun 2025 09:00:00 +0000

tl;dr: I built a free, open source analytics backend for Sparkle because all existing solutions are ancient, and I wanted to know how many people use VibeTunnel without being creepy about it.

I’m philosophically against deep app analytics. Everything I make is open source and free, and integrating an analytics SDK just didn’t feel right. Sparkle has this neat little system profiling feature that’s perfect for people like me - it just tells you the macOS version and how many people opened your app this week. No IP addresses, no invasive tracking, just enough to stay motivated.

The problem? When I checked for backend implementations, everything was ancient. So naturally, I thought: “How hard can it be?”

Building stats.store with agents

I fired up Google’s AI Studio and wrote a simple spec (you can see it on GitHub). Then I fed it into v0 - they use Next.js, Supabase, Tailwind, and shadcn/ui, a stack I already know and love.

After about five or six rounds of typing “continue” into v0, I had something workable. But v0 is great for frontend, less so when things get complex. It started making mistakes it couldn’t fix. So I synced to GitHub and let Claude Code take over. Claude added tests, dark mode, improved the design, and fixed the API flow.

Total time? Six hours. All while working on the next VibeTunnel release. Plus an hour picking the perfect domain (I really like stats.store).

What is stats.store?

It’s exactly what I needed: a modern, privacy-first analytics backend for Sparkle. You get basic update statistics, macOS version distribution, and a clean dashboard - all while respecting user privacy.

What gets collected:

System info: macOS version, CPU type (Intel/Apple Silicon), Mac model, core count, RAM, system language
App usage: Version numbers, update timestamps, daily unique users (via salted IP hashes)

What doesn’t get collected:

No IP addresses, names, or emails
No usage patterns or behavior tracking
No location data beyond language preference
No device IDs or fingerprinting

Everything is designed to answer simple questions: How many people use my app? What macOS versions should I support? When do people actually update? The whole thing is open source and MIT-licensed.

Free for Open Source

Here’s the deal: if you’re building open source Mac apps, it’s completely free. I’ll cover the hosting (Vercel and Supabase make this pretty cheap anyway).

Want in? Just email me. I’ll add your app to the backend - and by backend, I mean I’ll literally go into Supabase and edit the table. We’re keeping it scrappy. All you have to do is redirect the appcast URLs, stats.store will fetch the correct one and pass them along.

If enough people join, we’ll have a nice community dataset showing how fast Mac users update their OS and what hardware they’re running. Could be interesting!

Try It

Check out stats.store. If you have a Sparkle-based Mac app and want simple, privacy-respecting analytics, let me know. Together we can build something useful for the Mac developer community.

Questions? Hit me up on Twitter or email.

Showing Settings from macOS Menu Bar Items: A 5-Hour Journey

Tue, 17 Jun 2025 11:00:00 +0000

Opening a settings window from a macOS menu bar app should be trivial. It’s not. After spending hours debugging, I’m documenting the gotchas to save you the same frustration.

The Problem

SwiftUI provides SettingsLink for opening settings:

MenuBarExtra("Test", systemImage: "star.fill") {
    SettingsLink {
        Text("Open settings") 
    }
}

Simple, right? Except it doesn’t work reliably in MenuBarExtra. The documentation doesn’t mention this limitation.

According to Apple’s documentation, SettingsLink should “open the app’s settings scene when activated.” However, this assumes your app is already active and has proper window management context - assumptions that don’t hold for menu bar apps.

Why It Fails

Menu bar apps operate differently from regular macOS apps:

No dock icon by default - They use NSApplication.ActivationPolicy.accessory
Not “active” in the traditional sense - They don’t appear in the app switcher
Windows may appear behind other apps - Without proper activation, windows lack focus
No SwiftUI graph loaded - Settings needs some SwiftUI view initalized and the menu bar uses AppKit under the hood.

The root issue is that NSApplication treats menu bar apps as background utilities, not foreground applications. This affects how windows are ordered and receive events.

The Evolution of Workarounds

The Old Way

This is how it used to work. Private API, but widely used and simple:

if #available(macOS 13, *) {
    NSApp.sendAction(Selector(("showSettingsWindow:")), to: nil, from: nil)
} else {
    // macOS 12 or earlier
    NSApp.sendAction(Selector(("showPreferencesWindow:")), to: nil, from: nil)
}

This stopped working in Sonoma (14) with the error: “Please use SettingsLink for opening the Settings scene.” Apple deprecated these selectors in favor of SwiftUI’s scene-based approach, but didn’t account for the unique challenges of menu bar apps.

The openSettings Environment Action

Apple provides an openSettings environment action for programmatic access (available since macOS 14.0+):

struct MyView: View {
    @Environment(\.openSettings) private var openSettings

    var body: some View {
        Button("Open Settings") {
            openSettings()
        }
    }
}

This currently works on macOS 15, but doesn’t work on macOS Tahoe (26). The logic needs an existing SwiftUI render tree, and simply calling the environment variable does nothing if none is found.

The workaround? As horrible as it sounds, a hidden window. Of course, that comes with its own issues, unless you massage the window that it’s really off-screen and ideally also doesn’t react to touches.

Hide & Seek

Now, this works, however the window will open in the background, and no amount of makeKeyAndOrderFront(nil) will help. Trust me. I (and Claude) tried plenty variations.

The real reason? macOS doesn’t allow a window to become selected when there’s no Dock icon. And since it’s common to hide the Dock icon for pure Menu Bar apps, that’s a problem.

The workaround? Show the Dock icon just before calling openSettings() and then hiding it again. In a way, this is also convenient for the user as the Icon now represents the “app” - the visible window, and once that closes, we hide the Dock icon again. (via calling NSApp.setActivationPolicy(.accessory)). Of course the whole thing requires some delays to really work, so let me present you the final, working solution (I apologize in advance):

The Working Solution

Here’s the minimal implementation for macOS 14 and higher, using Swift 6:

// Hidden window to provide context
struct HiddenWindowView: View {
    @Environment(\.openSettings) private var openSettings
    
    var body: some View {
        Color.clear
            .frame(width: 1, height: 1)
            .onReceive(NotificationCenter.default.publisher(for: .openSettingsRequest)) { _ in
                Task { @MainActor in
                    // Show dock icon for window focus
                    NSApp.setActivationPolicy(.regular)
                    try? await Task.sleep(for: .milliseconds(100))
                    
                    // Activate and open
                    NSApp.activate(ignoringOtherApps: true)
                    openSettings()
                    
                    // 2. No window ordering - After openSettings(), you might need additional window management to ensure
                    // it comes to front:
                    try? await Task.sleep(for: .milliseconds(200))
                    if let settingsWindow = findSettingsWindow() {
                        settingsWindow.makeKeyAndOrderFront(nil)
                        settingsWindow.orderFrontRegardless()
                    }
                }
            }
            .onReceive(NotificationCenter.default.publisher(for: .settingsWindowClosed)) { _ in
                // Restore menu bar app state when settings closes
                NSApp.setActivationPolicy(.accessory)
            }
    }
}

// Window identifier for settings
static let settingsWindowIdentifier = "com.apple.SwiftUI.Settings"

/// Finds the settings window using multiple detection methods
static func findSettingsWindow() -> NSWindow? {
    // Try multiple methods to find the window
    return NSApp.windows.first { window in
        // Check by identifier
        if window.identifier?.rawValue == settingsWindowIdentifier {
            return true
        }
        
        // Check by title
        if window.isVisible && window.styleMask.contains(.titled) &&
           (window.title.localizedCaseInsensitiveContains("settings") ||
            window.title.localizedCaseInsensitiveContains("preferences")) {
            return true
        }
        
        // Check by content view controller type
        if let contentVC = window.contentViewController,
           String(describing: type(of: contentVC)).contains("Settings") {
            return true
        }
        
        return false
    }
}

// App structure
@main
struct MenuBarApp: App {
    var body: some Scene {
        MenuBarExtra("My App", systemImage: "star.fill") {
            Button("Settings...") {
                NotificationCenter.default.post(name: .openSettingsRequest, object: nil)
            }
            .keyboardShortcut(",", modifiers: .command)
        }
        
        // Required Settings scene
        Settings {
            SettingsView()
                .onDisappear {
                    NotificationCenter.default.post(name: .settingsWindowClosed, object: nil)
                }
        }
        
        // Hidden window for context
        Window("Hidden", id: "HiddenWindow") {
            HiddenWindowView()
        }
        .windowResizability(.contentSize)
        .defaultSize(width: 1, height: 1)
    }
}

extension Notification.Name {
    static let openSettingsRequest = Notification.Name("openSettingsRequest")
    static let settingsWindowClosed = Notification.Name("settingsWindowClosed")
}

The NotificationCenter approach decouples the menu action from the window context, allowing the hidden window to handle the actual settings opening.

For a production-ready implementation with all edge cases (yes, there are some more…) handled, see VibeTunnel’s SettingsOpener.swift.

Scene Order Matters (Unfortunately)

While implementing @steipete’s solution described above, I (@matejkob) discovered another gotcha: the order of scenes in your App’s body actually affects whether this workaround functions correctly.

The working example shown earlier has the scenes in this order:

MenuBarExtra
Settings
Window (hidden)

However, I found that if you arrange them like this (which seems equally logical):

var body: some Scene {
    MenuBarExtra("My App", systemImage: "star.fill") {
        ContentView()
    }
    .menuBarExtraStyle(.menu)
    
    Settings {
        SettingsView()
            .onDisappear {
                NotificationCenter.default.post(name: .settingsWindowClosed, object: nil)
            }
    }
    
    // Hidden window for settings context
    Window("Hidden", id: "HiddenWindow") {
        HiddenWindowView()
    }
    .windowResizability(.contentSize)
    .defaultSize(width: 100, height: 100)
}

The hidden window won’t be “visible” to the SwiftUI environment system (at least not on macOS Sequoia 15.5), and the openSettings() call will fail silently. However, moving the hidden Window scene before the Settings scene makes it work perfectly:

var body: some Scene {
    // Hidden window for settings context - MUST come before Settings
    Window("Hidden", id: "HiddenWindow") {
        HiddenWindowView()
    }
    .windowResizability(.contentSize)
    .defaultSize(width: 100, height: 100)
    
    MenuBarExtra("My App", systemImage: "star.fill") {
        ContentView()
    }
    .menuBarExtraStyle(.menu)
    
    Settings {
        SettingsView()
            .onDisappear {
                NotificationCenter.default.post(name: .settingsWindowClosed, object: nil)
            }
    }
}

This suggests that SwiftUI’s scene resolution and environment propagation happens in declaration order, and the @Environment(\.openSettings) action in the hidden window needs its context established before the Settings scene is processed.

Whether this is an Xcode build system quirk, a SwiftUI implementation detail, or intended behavior is unclear from Apple’s documentation. What is clear is that the hidden window must be declared before the Settings scene for this workaround to function reliably.

This adds yet another layer of undocumented complexity to what should be a simple operation - not only do we need a hidden window and activation policy juggling, but we also need to carefully order our scene declarations to avoid mysterious failures.

Understanding the Workaround

The hidden window serves multiple purposes:

Provides a valid window context for the openSettings environment action
Allows us to temporarily switch activation policies without visual disruption
Gives us a place to handle the complex timing orchestration

The dock icon manipulation (switching between .accessory and .regular) is necessary because macOS only brings windows to the front reliably for apps with dock icons.

Fin

What should be a one-liner in other frameworks requires careful orchestration in SwiftUI. The combination of MenuBarExtra, Settings scenes, and openSettings wasn’t designed with the unique constraints of menu bar apps in mind.

This shouldn’t be so hard. Opening a settings window is one of the most basic operations any app needs to perform. The fact that it requires hidden windows, activation policy juggling, and precise timing delays in 2025 is a testament to how menu bar apps remain second-class citizens in SwiftUI. Until Apple addresses these fundamental issues, we’re stuck with these workarounds.

VibeTunnel: Turn Any Browser into Your Mac's Terminal

Mon, 16 Jun 2025 11:00:00 +0000

TL;DR: We built a browser-based terminal controller working around 24 hours using Claude Code, named pipes, and Xterm.js. No SSH needed, just open your browser and start typing. Check and command your agents on the go!

What happens when three developers lock themselves in a room for around 24 hours with Claude Code and too much caffeine? You get VibeTunnel - a browser-based terminal that actually works. Control & command your agents on the go.

This is the story of how Mario, Armin, and I built VibeTunnel in one marathon session working around 24 hours.

Motivation

We met up for a hackathon without knowing exactly what we wanted to build, but we knew one thing: we were all completely in love with building stuff with AI. As we talked, we realized we shared the same frustration - we all wanted to check on our AI agents and see how far they’d gotten with their tasks.

This first version lets you control Claude Code remotely - imagine being at lunch and checking if your agent finished that refactoring task, then immediately giving it the next assignment.

But here’s the thing - we didn’t want to constrain VibeTunnel to just Claude Code. It can control anything in your terminal. Accessing your development machine’s terminal from anywhere shouldn’t require complex SSH setups. We wanted something that just works. And we’re making it open source so everyone can benefit.

The Birth of VibeTunnel

It started with Armin’s prototype that piped stdin/stdout to files and used asciinema for playback. His initial approach was clever - capture terminal output to a JSONL file that described terminal dimensions and character events, then replay it using asciinema’s player. But it was one-way communication only - no input, no interactivity, just a recording.

Armin had actually built a similar library two years ago:

I used a library that I wrote two years ago… that library probably took me three or four days because I had to really figure out how pseudo terminals work. I’m pretty sure you could write this whole thing up in probably under an hour at this point. And I didn’t even bother using my library again… I just copy pasted the whole library in and had Claude do the modifications to it.

Within hours, we had transformed it into a full bidirectional terminal emulator. The journey from “wouldn’t it be cool if…” to a working prototype showcases what’s possible when you combine the right tools, the right team, and a healthy dose of determination. Here’s how we built it in one intense session working around 24 hours.

The Technical Journey

From Asciinema to Xterm.js: The Marathon Pivot

Our first major challenge came when we needed a proper scrollback buffer. The initial asciinema approach had a fatal flaw - no history. You couldn’t scrollback to see previous output, making it useless for any real work. Imagine running a build command and not being able to scroll up to see the errors!

Mario spent two hours going down a rabbit hole, investigating whether to write his own ANSI sequence renderer. He got surprisingly far - basic text output worked, colors were rendering, cursor movement was… sort of working. But then came the edge cases: double-width characters, complex cursor positioning, alternate screen buffers, and the hundreds of other ANSI escape sequences that real terminals support. It was becoming clear this was a month-long project, not a two-hour hack.

Mario explained:

I first investigated whether I could write my own ANSI sequence renderer. That kinda worked. But there were so many edge cases that I eventually searched for something else. Armin had been recommending Xterm.js all along.

I went through that a bit and thought maybe I can figure that out, but there was no way to get that working. So I went back to Xterm and spent about two hours figuring out how it works and how to massage it so it works in our context as well.

Mario exclaimed when we finally integrated Xterm.js:

That was pretty fucking complete. It’s a full terminal emulator that runs in the browser, handling all the ANSI escape sequences, cursor positioning, screen clearing - everything a real terminal needs. The magic is in how it works: feed it the raw output from your shell (including all those escape sequences), and it maintains an internal buffer representing exactly what should be displayed. It outputs this buffer with characters, foreground colors, and background colors that renders directly to the DOM. No canvas needed, just divs and spans with the right styling.

The only issue? Unicode rendering for things like box-drawing characters. When you start Claude Code, you get that nice orange border made of Unicode box-drawing characters - it currently falls back to ASCII replacements like ’+’ and ’-’ instead of smooth lines.

The Streaming Challenge: Six Terminals and You’re Out

We chose Server-Sent Events (SSE) for streaming terminal output because it’s simple, well-supported, and doesn’t require WebSocket complexity. Each terminal connects to an endpoint like /api/stream/session-123 and receives a continuous stream of output events. It worked beautifully… until we tried to open a seventh terminal.

Turns out browsers have a hard limit of six concurrent connections to the same domain. It’s an HTTP/1.1 limitation that exists to prevent connection flooding. Each terminal session needs its own stream, which means you can only have six terminals open at once. We discovered this the hard way when terminal number seven just… didn’t work. No errors, no warnings, just a blank screen waiting for a connection that would never come.

The solution? Multiplexing. Instead of one connection per terminal, we need a single SSE stream that carries data for all terminals. Each message would be tagged with a session ID, and the frontend would route it to the correct terminal display. It’s more complex but would remove the six-terminal limitation entirely. The architecture is already sketched out: a single /api/stream/all endpoint that broadcasts all terminal updates, with the frontend filtering based on which terminals are actually visible. It’s on the roadmap, right after we fix the input handling quirks.

Claude Code: The Secret Weapon (With Battle Scars)

We wouldn’t even have attempted this without Claude Code. What would have been a week-long project compressed into hours. The ability to say “integrate Xterm.js for terminal emulation” and get working code in minutes is game-changing.

Armin put it in perspective:

20x is not an understatement in terms of how much faster we are with agents. As an example: This button that I added to the UI, which is install the shell command and sudo the user. It wrote shell script. It wrote an Apple script. And then it wrote another thing around it, and it took it two and a half minutes. And for me to figure out how to bring up the right sudo dialogue, which kind of workaround to use to bring this thing in would have been two hours, three hours.

He compared it to his experience at Sentry:

Every year, we had a hack week culture. So every year, we took four days to five days of three to four people working on one project. And, honestly, three, four people working for five days not nearly as impressive in terms of how much stuff you can produce than working around 24 hours with AI.

Claude excels at bootstrapping. Need to integrate a library you’ve never used? Claude will get you 80% there in minutes. Want to understand how Server-Sent Events work? Claude generates a working example faster than you can read the MDN docs.

The workflow that emerged was fascinating: Claude would generate the initial implementation, Mario would test it, discover the edge cases, then spend significant time refactoring. But here’s the key insight - even with all the fixes needed, we were still moving 5x faster than coding from scratch. It’s not about getting perfect code; it’s about getting something that works, then iterating rapidly.

This is what people often don’t really get. It’s not like you do one prompt and this comes out. You work with it. It is a tool. And if you are a really good engineer, it’s rocket fuel for you. But if you don’t know what you’re doing, you still cannot build this.

Three Servers, One Purpose: The Polyglot Experiment

In true hackathon fashion, we ended up with three server implementations. But it wasn’t planned - it was born from frustration and iteration:

Node.js - The reference implementation that Mario built first. It’s the most complete, with all the session management, authentication hooks, and error handling. About 400 lines of Express.js that just works. Perfect for developers who want to hack on it immediately - everyone knows Node.
Swift (Hummingbird) - This came next, as we wanted a Swift implementation. But it became a story of frustration. When I asked Armin what the hardest part was, his answer was immediate:

The hardest thing is Xcode. You’re kinda used to being able to remote control a lot of stuff because a lot of it is text based. And xcodebuild sort of runs on a command line, but… the behavior of xcodebuild on a command line on our machine at least doesn’t match the behavior of Xcode play button. And so it kinda shows you how inappropriate the tool is for agentic workflows.

After spending “almost half an hour to get the bare bones things over from a to b,” he was done. Three hours and much frustration later, we had a working Hummingbird server. It’s actually quite elegant - Swift’s async/await makes the code surprisingly readable. But the development experience was painful.

Rust (now the default) - This is where things got interesting. Fed up with Xcode’s limitations, Armin pivoted to Rust. The difference was night and day. The iteration speed was incredible - what took 30 minutes of fighting with Xcode took minutes in Rust. The development experience was so superior that we ended up making the Rust version our recommended default engine. It’s not just about performance (though it does use about 10x less memory) - it’s about developer velocity.

We’re keeping all three implementations for educational purposes. As Mario explained:

We should keep both for educational purposes. Actually, all three for educational purposes because you have an aligned implementation of the same back end in three different environments. It’s the same REST API implemented in three different environments - perfect for learning how different ecosystems handle HTTP, async I/O, and process management. But if you’re just looking to use VibeTunnel? Start with the Rust version.

This unplanned polyglot approach revealed interesting patterns. The Rust version forced us to think carefully about lifetimes and session cleanup. The Swift version’s strong typing caught several API inconsistencies (when we could get it to compile). The Node version’s ecosystem made adding features trivial. Each implementation taught us something that improved the others, even if we didn’t set out to build three versions.

The Technology Stack: A Beautiful Frankenstein

The final stack that emerged from our coding marathon is a testament to pragmatic engineering - we used whatever worked best for each layer.

The main component that we distribute is a fully native SwiftUI app (with some sprinkles of AppKit) built with Swift 6. It packages all the bells and whistles, uses Sparkle for automatic updates, and ships with all the other components needed to make VibeTunnel work seamlessly. This native app ensures a smooth macOS experience while bundling the entire technology stack:

Core Process Management

Rust Binary - The heart of the system. Controls process spawning, named pipes, and I/O forwarding. The magic happens through Unix named pipes - we use a regular file for stdout (so we can tail and observe it) and a named pipe for stdin, allowing bidirectional communication between the browser and your shell. Why Rust? Because when you’re dealing with system-level process management, you want something that won’t segfault at 2 AM. The binary is remarkably small - about 2MB compiled - and handles all the tricky bits of PTY allocation, signal forwarding, and process lifecycle management.

Armin explained why this is actually harder than SSH:

What is a lot harder is drawing something in not the same terminal. Because what we’re doing here is we’re basically keeping it running the original terminal plus keeping it running in another terminal. And that is harder because, for instance, one of the terminals resizes, then you need to also update the other one. Or you wanna have a scrollback that is longer than what you would normally show.

Terminal Emulation

Xterm.js - Full terminal emulation with ANSI support in the browser. It’s the same library that powers VS Code’s terminal, which gave us confidence it could handle real-world usage. The integration was surprisingly smooth once we understood its API. Pro tip: the documentation is extensive but the examples are gold.

Frontend Framework

Lit Framework - Google’s lightweight web components library. No build step required! This was crucial for our rapid iteration. Just save the file and reload. Lit’s reactive properties made state management trivial, and web components meant our terminal widget was completely self-contained. You could drop it into any webpage and it would just work.

Communication Layer

Server-Sent Events (SSE) - For streaming terminal output. We chose SSE over WebSockets because it’s simpler, works through proxies better, and automatic reconnection is built-in. The unidirectional nature (server to client only) perfectly matched our needs for output streaming.

Backend Options

Node.js/Rust/Swift - Pick your flavor based on your team’s expertise or deployment constraints. They all expose the same REST API, so switching between them is literally just changing a command-line flag.

The Real MVP: Teamwork, Claude, and Caffeine

This project happened because of a perfect storm of factors:

Armin’s systems wizardry - He cranked out the Rust binary in 2-3 hours, building the critical process management layer that makes everything possible.

Mario’s frontend adventures with Claude - Mario rebuilt the UI layer three times. The first version was a mess. The second used vanilla JavaScript and quickly became unmaintainable. The third, using Lit, was the charm. Claude was his constant companion, generating boilerplate, explaining APIs, and occasionally leading him astray with over-engineered solutions. The key was learning when to trust Claude and when to take control.

My deep knowledge of macOS and Product-market fit - I’ve been in the iOS and macOS space for almost 20 years and really know how to build great products. I could reuse a lot of my existing work to get us really far, especially with branding, distribution, and the difficulties around notarization and updating. I built the app, onboarding, website, the social pages, did the design, and the overall branding to make this from a quick hack project into an actual beautifully designed product.

I had the most fun building the website with v0 from Vercel. I almost didn’t believe that it would shoot out something that is as cool as this.

The power of a deadline - We worked around 24 hours on this. There’s something magical about a time constraint. It forces pragmatic decisions.

The individual components aren’t really complex. It’s just fitting them together and making them work together. This became our mantra. Named pipes? Simple. SSE? Straightforward. Terminal emulation? Solved problem. But making them dance together in harmony? That’s where the magic (and the bugs) lived.

Mario summed up the project perfectly:

We can definitely say we wouldn’t even have attempted this without Claude Code… That would be a multi week project probably. Maybe not a multi week project, but definitely a week project.

The real lesson here is about momentum. Once we had that first character appear in the browser - just a simple ‘h’ from typing ‘hello’ - we were hooked. Each small victory fueled the next. Input working? Let’s add colors. Colors working? How about cursor movement. Before we knew it, we had a full terminal emulator.

Conclusion: Shipping Beats Perfect

VibeTunnel is what happens when developers scratch their own itch with modern tools. We’re making it open source because we want to use this ourselves, and there’s nothing quite like it out there. It’s not perfect - yet already amazing and fun to use.

As Armin noted about the quality:

I don’t think that we wrote the most amazing code with Claude. There’s definitely a lot of slop in there. But I think if one were to want to make this really, really nice, you could actually use Claude to fix a ton of this stuff. Plus - it’s not just the app that is there. Right? There’s the logo. There’s the website. There is the readme. There’s the documentation. All of it just came out of effectively an agent.

The scale of what we built working around 24 hours? Over 16,000 lines of code:

Swift: 7,666 lines (57%)
Rust: 3,001 lines (22%)
Shell Scripts: 2,331 lines (17%)
TypeScript: 2,756 lines
Total Core Code: 16,283 lines

At the end of our marathon session, we all agreed:

This was a really fun project. And isn’t that what hacking is all about?

Try VibeTunnel today! Your agent is waiting in your browser.

Vibe Meter 2.0: Calculating Claude Code Usage with Token Counting

Sun, 15 Jun 2025 18:00:00 +0000

TL;DR: Built Vibe Meter 2.0 to track Claude Code subscription usage by parsing JSON-L files and counting tokens with a SIMD-accelerated BPE tokenizer. No official API exists, so I approximated usage by counting every token. The project grew to 47K lines of Swift with 92% test coverage, all written with CC using “thinking” triggers and modern Swift idioms.

The Shock: How Much Am I Actually Using?

What started as a simple idea to explain vibe coding to new people is slowly growing up. With version 2 of Vibe Meter, I added full support for Anthropic’s subscription. While v1 only focused on cost display for Cursor, for version 2 I wanted to add support for CC. This turned out to be much more of an adventure than I initially thought.

The Problem: Flying Blind Without APIs

Anthropic has both API endpoints with straightforward pricing. They also offer subscriptions where especially in the max version you get around 900 requests in a 5-hour window. I was curious:

A) How much that would actually cost if it would be API calls
B) How many requests you actually have open in that 5-hour window

Well, turns out this is not easy at all. There is no API for that, there’s no cost control, there’s not even a hidden private API or something on the website that you could look at. The only way literally is to count the individual tokens that are sent to the LLM and then approximate how much is left. We also have to approximate when a window starts. As you can see, this was the start of a little adventure.

The Solution Journey: From Collaboration to SIMD

Luckily, I wasn’t alone. There were other people that were already curious and interested in that idea, so I could learn from various open source projects like ccusage, which pioneered the approach of parsing Claude’s JSON-L files. Counting tokens also is not as simple as you would think. Claude Code writes all interactions with their server into so-called JSON-L files which can be in the hundreds of megabytes large. So I spent a lot of time tweaking the parser, or dare I say me and Claude did.

SIMD Operations for Performance

During the process I even started using SIMD operations, something which I only darkly remember got support in Swift but now it’s crucial to offer a speedy parsing that doesn’t bog down your CPU.

The most impressive optimization is the vectorized lookup table that uses SIMD16 (16-byte vectors) for fast pattern matching:

// VibeMeter/Core/Utilities/Tiktoken/CoreBPESIMD.swift:222-281
private struct VectorizedBytePairLookup {
    // Pre-computed SIMD vectors for common byte pairs
    private let pairVectors: [SIMD16<UInt8>: [(length: Int, rank: Int)]]

    init(bytePairRanks: [Data: Int]) {
        // Build SIMD lookup table for byte sequences
        for (data, rank) in bytePairRanks {
            if data.count > 16 { continue } // Skip sequences longer than SIMD width

            // Create a SIMD vector padded with zeros
            var vector = SIMD16<UInt8>(repeating: 0)
            data.withUnsafeBytes { (bytes: UnsafeRawBufferPointer) in
                for i in 0 ..< min(data.count, 16) {
                    vector[i] = bytes[i]
                }
            }
            vectors[vector]?.append((length: data.count, rank: rank))
        }
    }
}

This approach allows us to compare 16 bytes at once instead of doing byte-by-byte comparisons, dramatically speeding up the token counting process.

Token Counting with BPE

As a basis, I used the open source TikToken BPE tokenizer that is actually from OpenAI. There’s no public tokenizer project from Anthropic. However, the tokens are similar enough that we can use this project and still get fairly accurate results.

BPE (Byte Pair Encoding) is a compression algorithm adapted for tokenization in NLP. It breaks text into subword units (tokens), often capturing whole words or common prefixes/suffixes. Instead of just splitting on whitespace or characters, BPE builds a vocabulary of frequently seen pairs of characters or subwords. This allows models to handle unknown words, rare terms, and typos more gracefully.

Key Insights: Thinking Triggers and Fresh Context

Agentic engineering, as I prefer to say, requires even more clear thinking. I evolved my approach where I would use Claude Code and ask it to think hard about the problem. The thinking keyword is key because it triggers how much token Claude uses to actually think about the problem. There are various levels how you can trigger thinking, with Ultra Think being the highest level.

As I work more with Claude Code, I tend to slow down, ask it to plan, present options, ultrathink, and then pick the best one. And always using a fresh context. Much better results.

Look at these examples:

Took a few planning prompts each but then the code one-shots and works perfect.

Pro Tip: One trick to get better results in Claude Code is to use the various “thinking” triggers, with ultrathink being the boss. Check out the extended thinking tips in the Anthropic documentation for more details.

🚀 Side Quest: The Birth of llm.codes

While building Vibe Meter 2.0, I ran into a weird issue where Claude would argue with me that one cannot build nice toolbars in SwiftUI. This ultimately inspired me to build llm.codes, a way to feed Claude up-to-date information so it produces better code. You can read more about this journey in my post: llm.codes: Transform Your Developer Docs into LLM-Optimized References.

Modern Swift Refactoring

In the 2.0 refactor, I also put a better effort on using modern Swift idioms, and most I did that by Claude teaching modern Swift via a new Markdown file that I fed to him and asked him to refactor my codebase using modern Swift idioms. I shared this and many other knowledge files in my new agent rules repository.

The Results: 47K Lines, 92% Coverage

VibeMeter has grown into a substantial project:

App code: 24,529 lines
Test code: 22,560 lines
Total: 47,089 lines across 218 Swift files
Test coverage ratio: 92% (tests are nearly as large as the app itself!)

With this release, I also added support for macOS 14¹ which was quite simple.

Get Vibe Meter 2.0

Note: Vibe Meter is still on the pre-release channel for now, there’s a few edge-cases I wanna get right before making it 2.0 official, but it’s close!

Get it here and switch update channel for the preview!

The only issue was with automatic observation tracking, which is macOS 15+ only. Learn more about this hidden gem in my post: Automatic Observation Tracking in UIKit and AppKit. ↩

llm.codes: Make Apple Docs AI-Readable

Sat, 14 Jun 2025 13:22:16 +0000

TL;DR: llm.codes converts JavaScript-heavy Apple docs (and 69+ other sites) into a clean llms.txt that AI agents can actually read.

Quick Start: Try it now with Apple’s Foundation Models docs: llm.codes

Even the smartest models can’t fetch fresh docs - especially when the docs are hidden behind JavaScript. While working on Vibe Meter, Claude tried to convince me that it wasn’t possible to make a proper toolbar in SwiftUI and went down to AppKit. Even when I asked it to google for a solution, nothing changed.

The Real Problem: JavaScript-Heavy Documentation

The core issue? Apple’s documentation heavily uses JavaScript, and Claude Code (or most AI agents to date) simply cannot parse that. It will fail and see nothing. So if you’re working with a component where documentation only exists on JavaScript-rendered pages, you’re completely stuck.

Enter llm.codes

That’s when I built the docs converter. llm.codes allows you to point to documentation and fetch everything as clean Markdown. While it’s optimized for Apple documentation, it supports a wide range of developer documentation sites. Here’s what you get:

Your AI can finally see Apple docs - No blind spots from JavaScript pages
70% smaller files - More context space for your actual code
Works with 69+ sites - AWS, Tailwind, PyTorch, PostgreSQL, and more

Supported Documentation Sites

Mobile Development

Apple Developer Documentation
Android Developer Documentation
React Native
Flutter
Swift Package Index

Programming Languages

Python, TypeScript, JavaScript (MDN), Rust, Go, Java, Ruby, PHP, Swift, Kotlin

Web Frameworks

React, Vue.js, Angular, Next.js, Nuxt, Svelte, Django, Flask, Express.js, Laravel

Cloud Platforms

AWS, Google Cloud, Azure, DigitalOcean, Heroku, Vercel, Netlify

Databases

PostgreSQL, MongoDB, MySQL, Redis, Elasticsearch, Couchbase, Cassandra

DevOps & Infrastructure

Docker, Kubernetes, Terraform, Ansible, GitHub, GitLab

AI/ML Libraries

PyTorch, TensorFlow, Hugging Face, scikit-learn, LangChain, pandas, NumPy

CSS Frameworks

Tailwind CSS, Bootstrap, Material-UI, Chakra UI, Bulma

Build Tools & Testing

npm, webpack, Vite, pip, Cargo, Maven, Jest, Cypress, Playwright, pytest

And more: Any GitHub Pages site (*.github.io)

llm.codes uses Firecrawl under the hood, and I pay for the credits to keep this service free for everyone.

Real-World Example

Remember my toolbar problem? Here’s what happened: I dragged the generated SwiftUI markdown from my agent-rules repository into the terminal, and suddenly Claude wrote exactly the code I wanted.

The key insight: When you work on a component, just ask Claude to read the docs. It will load everything it needs into its context and produce vastly better code.

For people who think @Context7 is the answer: if you use the context7 mcp for SwiftUI, you get sample code from 2019, which will produce horribly outdated code. You need current documentation, not ancient examples.

Beyond Just llm.codes

I used this trick before in my post about migrating 700 tests to Swift Testing. With llm.codes, you get significantly smaller markdown files, which preserves more token context space for your agent.

I also maintain a collection of pre-converted Markdown documentation files in my agent-rules repository, that go beyond just documentation.

The converter itself? Completely vibe-coded with Claude and open source. I chose the stack (Next.js, Tailwind, Vercel) but didn’t write a single line of TypeScript-and it worked beautifully on the first try.

Try It Out

Convert a page →

No sign-up needed.

AI agents are the future of coding. Until docs catch up, llm.codes is your bridge to that future.

Automatic Observation Tracking in UIKit and AppKit: The Feature Apple Forgot to Mention

Wed, 11 Jun 2025 09:00:00 +0000

TL;DR: iOS 18 and macOS 15 secretly ship with automatic observation tracking for UIKit/AppKit. Enable it with a plist key, and your views magically update when your @Observable models change. No more manual setNeedsDisplay() calls!

Remember when SwiftUI came out and we all marveled at how views automatically updated when @Published properties changed? Well, Apple has been quietly working on bringing that same magic to UIKit and AppKit. The best part? It shipped in iOS 18/macOS 15, but hardly anyone knows about it. You don’t even need Xcode 26, it’s just one simple plist entry away.

The Problem We’ve All Faced

Let’s be honest - keeping your UI in sync with your data model in UIKit has always been a chore. Here’s the dance we’ve all done:

class ProfileViewController: UIViewController {
    var user: User? {
        didSet {
            updateUI()
        }
    }
    
    func updateUI() {
        nameLabel.text = user?.name
        avatarImageView.image = user?.avatar
        // ... 20 more lines of manual updates
        setNeedsLayout()
    }
}

Forgot to call updateUI()? Enjoy your stale UI. Called it too often? Hello, performance issues. It’s tedious and error-prone.

Enter Automatic Observation Tracking

With the new observation framework, this entire pattern becomes obsolete. Here’s the same code with automatic tracking:

import Observation

@Observable
class User {
    var name: String = ""
    var avatar: UIImage?
    var unreadCount = 0
    
    var hasUnread: Bool {
        unreadCount > 0
    }
}

class ProfileViewController: UIViewController {
    let user = User()
    
    override func viewWillLayoutSubviews() {
        super.viewWillLayoutSubviews()
        // UIKit tracks these property accesses automatically!
        nameLabel.text = user.name
        avatarImageView.image = user.avatar
        badgeView.isHidden = !user.hasUnread
    }
}

That’s it. Change user.name anywhere in your app, and the label updates. No manual calls, no forgotten updates, no performance overhead from unnecessary refreshes. It just works.

Where Observation Tracking Works

The automatic observation tracking is supported in a variety of UIKit and AppKit methods. For most cases, viewWillLayoutSubviews() in UIKit view controllers, layoutSubviews() in UIKit views, and their AppKit equivalents (viewWillLayout() and layout()) are the go-to choices.

View the complete list of supported methods

UIView

UIViewController

UIPresentationController

UIButton

updateConfiguration()
When executing the configurationUpdateHandler
updateConfiguration(using:) (UICollectionViewCell)
updateConfiguration(using:) (UITableViewCell)
updateConfiguration(using:) (UITableViewHeaderFooterView)
When executing the configurationUpdateHandler

NSView (AppKit)

NSViewController (AppKit)

Enabling the Magic

Here’s where it gets interesting. This feature isn’t enabled by default (yet). You need to add a key to your Info.plist:

For UIKit (iOS 18+)

<key>UIObservationTrackingEnabled</key><true/>

For AppKit (macOS 15+)

<key>NSObservationTrackingEnabled</key><true/>

This plist key enables observation tracking in iOS 18 and macOS 15. Starting with their 26 releases, this is on by default and the key will simply be ignored.

iOS 26 and Beyond

iOS 26 (already in beta!) brings improvements. The new updateProperties() method on both UIView and UIViewController provides an even better place for observable property access. For a comprehensive overview of all iOS 26 UIKit additions, check out Jordan Morgan’s excellent writeup.

class MyView: UIView {
    let model: MyModel
    
    override func updateProperties() {
        super.updateProperties()
        // This runs before layoutSubviews for even better performance
        backgroundColor = model.backgroundColor
        layer.cornerRadius = model.cornerRadius
    }
}

This method is specifically designed for property updates and runs before layoutSubviews, allowing for more efficient updates and clearer separation of concerns.

Just like the layout system has setNeedsLayout() and layoutIfNeeded(), the property update system provides setNeedsUpdateProperties() and updatePropertiesIfNeeded(). You can call setNeedsUpdateProperties() to schedule a property update on the next update cycle, or use updatePropertiesIfNeeded() to force an immediate update if one is pending. This gives you fine-grained control over when property updates occur, which is especially useful for optimizing performance in complex view hierarchies.

Apple’s automatic trait tracking documentation provides detailed guidance on using these new APIs. Plus, automatic observation tracking is enabled by default in iOS 26, so you won’t even need the plist key anymore.

The Gotchas

Of course, it’s not all roses. Here are a few things to watch out for:

Observation happens in specific methods: Only properties accessed in the supported methods (see list above) are tracked
Timing matters: If you’re doing expensive computations, consider caching results since these methods can be called frequently
Memory considerations: Observable objects are retained while being observed, so be mindful of retain cycles
Thread safety: While @Observable is thread-safe, mutations from different threads could lead to inconsistent UI representations. Keep all mutations on the main thread to avoid surprises

A Pattern to Avoid

You might be tempted to create a method that pre-accesses all observable properties:

// ❌ Don't do this
override func trackObservableProperties() {
    // Accessing all properties upfront
    _ = model.backgroundColor
    _ = model.cornerRadius
    _ = model.title
    // ... etc
}

This is an anti-pattern for two reasons:

Inefficiency: It establishes observation dependencies for ALL properties, even those not used in the current UI state. The beauty of automatic observation is that it only tracks properties actually accessed during updates.
Fragility: You’re maintaining a duplicate list of properties that can easily fall out of sync with your actual UI code.

Instead, access properties directly where they’re used:

// ✅ Do this
override func layoutSubviews() {
    super.layoutSubviews()
    // Only accessed properties create dependencies
    if model.isOptionEnabled {
        view.foo = model.bar  // Only bar is observed
    } else {
        view.foo = model.baz  // Only baz is observed
    }
}

This way, only the properties actually affecting your UI get observation dependencies, making your code both more efficient and maintainable.

Performance Considerations

You might be wondering about performance. The beauty of this system is that it only tracks dependencies when views are actually laying out. If a view isn’t visible, it’s not tracking. The observation framework uses a sophisticated dependency graph that ensures minimal overhead.

Complete Example Project

Automatic observation tracking is one of those features that makes you wonder how you lived without it. It brings the best parts of SwiftUI’s reactive programming model to UIKit and AppKit, without requiring a complete rewrite of your app.

All the code snippets in this post come from a fully working example project. Check it out on GitHub: ObservationTrackingExample

The Missing Piece: Custom Traits

If you’ve used SwiftUI, you know the joy of @EnvironmentObject - drop an object at the root, access it anywhere. UIKit developers have been jealous of this pattern for years. Well, jealous no more. (Mac devs miss out tho - there’s no equivalent on AppKit yet)

Since iOS 17, UIKit has quietly introduced custom traits - a way to attach arbitrary values to the trait collection that flows through your view hierarchy. These aren’t just for dark mode and size classes anymore. Keith Harrison has an excellent deep dive into custom traits if you want the full story.

The magic happens when you combine custom traits with observable objects. You get automatic propagation AND automatic updates. It’s like having your cake and eating it too.

View the complete Example

Let’s build an app-wide state container that any view can access and observe:

import UIKit
import Observation

@Observable 
class AppModel {
    var currentUser: User?
    var theme: Theme = .light
    var isOnline = true
    
    // Add more app-wide state as needed
}

// Define a custom trait for your app model
struct AppModelTrait: UITraitDefinition {
    static let defaultValue: AppModel? = nil
}

// Add convenient accessors
extension UITraitCollection {
    var appModel: AppModel? {
        self[AppModelTrait.self]
    }
}

extension UIMutableTraits {
    var appModel: AppModel? {
        get { self[AppModelTrait.self] }
        set { self[AppModelTrait.self] = newValue }
    }
}

Injecting the Model

At your app’s root (usually in your scene delegate or root view controller), inject the model:

class SceneDelegate: UIResponder, UIWindowSceneDelegate {
    var window: UIWindow?
    let appModel = AppModel()
    
    func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options: UIScene.ConnectionOptions) {
        guard let windowScene = (scene as? UIWindowScene) else { return }
        
        window = UIWindow(windowScene: windowScene)
        let rootViewController = MainTabBarController()
        
        // Inject the app model into the trait system
        rootViewController.traitOverrides.appModel = appModel
        
        window?.rootViewController = rootViewController
        window?.makeKeyAndVisible()
    }
}

Observing Changes Anywhere

Now the magic part - any view controller in your hierarchy can access and observe the model:

class ProfileViewController: UIViewController {
    let nameLabel = UILabel()
    let statusIndicator = UIView()
    
    override func viewWillLayoutSubviews() {
        super.viewWillLayoutSubviews()
        
        guard let model = traitCollection.appModel else { return }
        
        // These automatically update when model properties change!
        nameLabel.text = model.currentUser?.name ?? "Guest"
        statusIndicator.backgroundColor = model.isOnline ? .systemGreen : .systemRed
        
        // Theme updates
        view.backgroundColor = model.theme.backgroundColor
        nameLabel.textColor = model.theme.textColor
    }
}

No delegates. No notifications. No manual updates. Change appModel.currentUser anywhere in your app, and every view observing it updates automatically.

Resources

Apple’s Observation Framework Documentation
WWDC 2023: Discover Observation in Swift (covers the foundation)
Example Project on GitHub
Swift Forums Discussion on Observation Tracking
Custom Traits and SwiftUI by Keith Harrison

Peekaboo MCP – lightning-fast macOS screenshots for AI agents

Sat, 7 Jun 2025 11:00:00 +0000

TL;DR: Peekaboo is a macOS-only MCP server that enables AI agents to capture screenshots of applications, or the entire system, with optional visual question answering through local or remote AI models.

Without screenshots, agents debug blind—Peekaboo gives them eyes.

What Peekaboo Can Do

Peekaboo provides three main tools that give AI agents visual capabilities:

image - Capture screenshots of screens or specific applications
analyze - Ask AI questions about captured images using vision models
list - Enumerate available screens and windows for targeted captures

Each tool is designed to be powerful and flexible. The most powerful feature is visual question answering - agents can ask questions about screenshots like “What do you see in this window?” or “Is the submit button visible?” and get accurate answers. This saves context space since asking specific questions is much more efficient than returning raw image data.

Peekaboo supports both cloud and local vision models, letting you choose between accuracy and privacy.

Design Philosophy

Less is More

The most important rule when building MCPs: Keep the number of tools small. Most agents struggle once they encounter more than 40 different tools. My approach is to make every tool very powerful but keep the total count minimal to avoid cluttering the context.

Lenient Tool Calling

Another crucial principle: tool calling should be lenient. Agents make mistakes with parameters, so rather than returning errors, Peekaboo tries to understand their intent. Being overly strict just forces unnecessary retry loops - MCPs should be forgiving since agents aren’t infallible.

Fuzzy Window Matching

Peekaboo implements fuzzy window matching because agents don’t always know exact window titles. If an agent asks for “Chrome” but the window is titled “Google Chrome - Peekaboo MCP”, we still match it. Partial matches work, case doesn’t matter, and common variations are understood.

For more insights on building robust MCP tools, check out my guide: MCP Best Practices.

Local vs Cloud Vision Models

Peekaboo supports both local and cloud vision models. While cloud models like GPT-4o offer superior accuracy, local models provide privacy, cost control, and offline operation.

For local inference, I recommend LLaVA as the default for its balance of accuracy and performance. For resource-constrained systems, Qwen2-VL provides excellent results with lower requirements.

Model specifications and requirements

LLaVA (Large Language and Vision Assistant)

llava:7b - ~4.5GB download, ~8GB RAM required
llava:13b - ~8GB download, ~16GB RAM required
llava:34b - ~20GB download, ~40GB RAM required
Best overall quality for vision tasks

Qwen2-VL

qwen2-vl:7b - ~4GB download, ~6GB RAM required
Excellent performance with lower resource requirements
Ideal for less powerful machines

Installation:

# Install your chosen model
ollama pull llava:latest        # or llava:7b, llava:13b, etc.
ollama pull qwen2-vl:7b        # for resource-constrained systems

My MCP Ecosystem

Peekaboo is part of a growing collection of MCP servers I’m building:

claude-code-mcp - Integrates Claude Code into Cursor for task offloading
macos-automator-mcp - Run AppleScript and JXA on macOS
Terminator - External terminal so agents don’t get stuck on long-running commands

Each serves a specific purpose in building autonomous AI workflows.

Technical Architecture

Peekaboo combines TypeScript and Swift for the best of both worlds. TypeScript provides excellent MCP support and easy distribution via npm, while Swift enables direct access to Apple’s ScreenCaptureKit for capturing windows without focus changes.

My initial AppleScript prototype had a fatal flaw: it required focus changes to capture windows. The Swift rewrite uses ScreenCaptureKit to access the window manager directly - no focus changes, no user disruption.

The system uses a Swift CLI that communicates with a Node.js MCP server, supporting both local models and cloud providers with automatic fallback. Built with Swift 6 and the new Swift Testing framework (now that I have experience with it!), Peekaboo delivers fast, non-intrusive screenshot capture with intelligent window matching.

For detailed testing instructions using the MCP Inspector, see the Peekaboo README.

The Vision: Autonomous Agent Debugging

Peekaboo is like one puzzle piece in a larger set of MCPs I’m building to help agents stay in the loop. The goal is simple: if an agent can answer questions by itself, you don’t have to intervene and it can simply continue and debug itself. This is the holy grail for building applications with CI - you want to do everything so the agent can loop and work until what you want is done.

When your build fails, when your UI doesn’t look right, when something breaks - instead of stopping and asking you “what do you see?”, the agent can take a screenshot, analyze it, and continue fixing the problem autonomously. That’s the power of giving agents their eyes.

👻 Peekaboo MCP is available now - ⭐ the repo if this saves you a debug session!

Migrating 700+ Tests to Swift Testing: A Real-World Experience

Fri, 6 Jun 2025 18:00:00 +0000

TL;DR: I let Claude Code convert 700+ tests to Swift Testing, watched it fail spectacularly, created an AI-generated playbook, then watched it succeed brilliantly. The difference? Better instructions.

I’ve been migrating my test suites from XCTest to Swift Testing. Between Vibe Meter and Code Looper, that’s over 700 tests across 118 files. Here’s what I learned from letting AI help with the conversion and then systematically improving the results using my Swift Testing playbook.

The Initial Attempt

Started with the laziest possible prompt:

Hey Claude Code, convert all these tests to swift-testing.
I’ll go make coffee.

The initial results were… technically correct. The tests compiled. They even passed. But looking at the code, it was clear this was just XCTest wearing a Swift Testing costume.

When AI gives you lemons:

XCTestCase classes became @Suite structs
XCTAssert calls turned into #expect statements
func testFoo() transformed to @Test func foo()

But it missed the deeper opportunities that Swift Testing provides. The real work began after my coffee kicked in.

Full disclosure: I actually tried Swift Testing last week but completely messed it up because I linked to the wrong version without understanding it was already integrated into Xcode. Shoutout to Stuart who nudged me to try again. Sometimes you need that external push to revisit something you wrote off too quickly.

Creating a Systematic Approach

Instead of manually fixing 700 tests, I did what any reasonable developer would do: I procrastinated by watching WWDC videos. Both Meet Swift Testing and Go further with Swift Testing sessions were eye-opening.

But here’s where it gets complicated. The WWDC videos referenced outdated APIs that confused my AI agents. Plus, Claude couldn’t access Apple’s documentation because it’s all JavaScript-rendered. I spent hours trying different approaches until I discovered Firecrawl (affiliate link, I need moar credits!), which converted Apple’s entire Swift Testing documentation into a massive Markdown file. (This experience inspired me to build llm.codes, where anyone can now generate up-to-date documentation from Apple’s official sources.)

So I ended up with two documents:

The complete Swift Testing API documentation from Apple (via Firecrawl)
An actionable playbook with examples from WWDC videos

I fed both into Google’s AI Studio, asked it to correct the outdated API references, and let Gemini compile everything into a comprehensive Swift Testing resource with both the API documentation and actionable migration patterns.

Why go through all this effort? Swift Testing is new and underrepresented in open source compared to mature ecosystems like TypeScript/React where AI has absorbed countless examples. For emerging technologies, you need to explicitly provide the knowledge that doesn’t exist in the training data yet.

The key insight: AI needs concrete patterns and examples, not just documentation. This playbook became my guide for teaching Claude Code how to write idiomatic Swift Testing code, providing:

Migration patterns with before/after examples
Best practices for each Swift Testing feature
Common pitfalls and how to avoid them
Specific guidance on when to use each feature

Round Two: AI Redemption Arc

With the playbook in hand, I gave Claude Code new instructions:

Read swift-testing-playbook.md and improve & refactor the tests. Periodically stop, compile, fix any build issues, commit, ensure everything is green locally and on CI, then continue until perfection.

Plot twist: The first time I tried this, Claude got creative and started implementing new test patterns from the playbook instead of converting existing tests. I had to clarify:

Read swift-testing-playbook.md and swift-testing-api.md and refactor the existing tests in this codebase to use Swift Testing patterns.

Lesson learned: Be very specific with AI instructions. “Improve tests using these patterns” can mean “create new tests” or “convert existing tests.” The difference matters when you have existing test coverage to preserve.

This iterative approach revealed several patterns worth sharing:

1. Nested Suites Bring Order to Chaos

The biggest transformation came from consolidating scattered test files into organized hierarchies. Vibe Meter’s AuthenticationTokenManager tests showed the most dramatic improvement:

// Before: 4 separate test files
VibeMeterTests/
├── AuthenticationTokenManagerCoreTests.swift
├── AuthenticationTokenManagerCookieTests.swift  
├── AuthenticationTokenManagerEdgeCasesTests.swift
└── AuthenticationTokenManagerTests.swift

To this beauty:

@Suite("Authentication Token Manager Tests", .tags(.authentication, .unit))
@MainActor
struct AuthenticationTokenManagerTests {
    // MARK: - Core Functionality
    @Suite("Core Functionality", .tags(.fast))
    struct Core {
        let mockManager: MockAuthenticationTokenManager
        
        init() {
            mockManager = MockAuthenticationTokenManager()
        }
        
        @Test("save token success", .tags(.critical, .requiresKeychain))
        func saveTokenSuccess() async throws {
            // Core authentication tests...
        }
    }
    
    // MARK: - Cookie Management
    @Suite("Cookie Management")
    struct CookieManagement {
        @Test("cookie extraction from headers")
        func cookieExtractionFromHeaders() async throws {
            // Cookie-related tests...
        }
    }
    
    // MARK: - Edge Cases
    @Suite("Edge Cases", .tags(.edgeCase, .fast))
    struct EdgeCases {
        @Test("handles concurrent token updates")
        func handlesConcurrentTokenUpdates() async throws {
            // Edge case tests...
        }
    }
}

75% fewer files, with logical organization that mirrors the actual functionality. Each nested suite can have its own setup, and the test navigator in Xcode finally makes sense.

2. Parameterized Tests Eliminate Copy-Paste Syndrome

Remember writing the same test five times with different values? Vibe Meter’s currency conversion tests showcase Swift Testing’s superior parameterization:

View Currency Conversion Test Implementation

// Before: Individual test methods for each scenario
func testConvert_SmallAmount() { /* test code */ }
func testConvert_LargeAmount() { /* test code */ }
func testConvert_NegativeAmount() { /* test code */ }
func testConvert_ZeroAmount() { /* test code */ }
func testConvert_PrecisionAmount() { /* test code */ }
// ... and many more

// After: Sophisticated parameterized testing
@Suite("Currency Conversion Tests", .tags(.currency, .unit))
struct CurrencyConversionTests {
    struct ConversionTestCase: Sendable, CustomTestStringConvertible {
        let amount: Double
        let rate: Double
        let expected: Double
        let description: String
        
        var testDescription: String {
            "$\(amount) × \(rate) → $\(expected) (\(description))"
        }
    }
    
    static let conversionTestCases: [ConversionTestCase] = [
        ConversionTestCase(100.0, rate: 0.85, expected: 85.0, "USD to EUR conversion"),
        ConversionTestCase(0.0, rate: 0.85, expected: 0.0, "zero amount conversion"),
        ConversionTestCase(100.0, rate: 1.0, expected: 100.0, "same currency conversion"),
        ConversionTestCase(-100.0, rate: 0.85, expected: -85.0, "negative amount conversion"),
        ConversionTestCase(1_000_000.0, rate: 0.85, expected: 850_000.0, "large amount conversion"),
        ConversionTestCase(0.01, rate: 0.85, expected: 0.0085, "small amount conversion"),
        ConversionTestCase(999.99, rate: 1.2345, expected: 1234.488, "precision conversion"),
    ]
    
    @Test("Currency conversion calculations", .tags(.critical), 
          arguments: CurrencyConversionTests.conversionTestCases)
    func conversionCalculations(testCase: ConversionTestCase) async {
        let result = await MainActor.run {
            CurrencyConversionHelper.convert(amount: testCase.amount, rate: testCase.rate)
        }
        
        let tolerance = testCase.expected.magnitude < 1.0 ? 0.0001 : 0.01
        #expect(result.isApproximatelyEqual(to: testCase.expected, tolerance: tolerance))
    }
    
    @Test("Invalid rate handling", .tags(.edgeCase), 
          arguments: [nil, 0.0, -1.0, .infinity, .nan] as [Double?])
    func invalidRateHandling(invalidRate: Double?) async {
        let result = await MainActor.run {
            CurrencyConversionHelper.convert(amount: 100.0, rate: invalidRate)
        }
        #expect(result == 100.0) // Should return original amount for invalid rates
    }
}

The beauty? CustomTestStringConvertible makes each test case self-documenting in the test navigator with descriptions like “$100.0 × 0.85 → $85.0 (USD to EUR conversion)” instead of generic object names. Test failures become instantly readable, and we can test edge cases (nil, infinity, NaN) in a single elegant test.

3. Instance Isolation Simplifies State Management

Swift Testing creates a fresh instance for each test, eliminating shared state issues:

@Suite struct DatabaseTests {
    let db: TestDatabase
    let tempDir: URL
    
    init() throws {
        tempDir = FileManager.default.temporaryDirectory
            .appendingPathComponent(UUID().uuidString)
        try FileManager.default.createDirectory(at: tempDir)
        db = TestDatabase(path: tempDir)
    }
    
    deinit {
        try? FileManager.default.removeItem(at: tempDir)
    }
}

No more worrying about test order or cleanup between tests. Each test gets its own clean instance.

4. Better Error Handling and Assertions

Swift Testing provides two types of assertions that behave very differently:

// #expect: Soft assertion - continues test on failure
#expect(user.email == "test@example.com")
#expect(user.isActive == true)
// ↑ Both assertions run even if first one fails

// #require: Hard assertion - stops test immediately on failure
let config = try #require(loadConfiguration())
// ↑ Test stops here if config is nil, preventing crashes below
let apiKey = try #require(config.apiKey)

Error handling is also more expressive than XCTest:

// Validate specific error types
#expect(throws: NetworkError.self) {
    try await api.fetchWithoutAuth()
}

// Ensure no errors
#expect(throws: Never.self) {
    try parseValidJSON(data)
}

5. Time Limits Prevent CI Hangs

Performance tests were scattered across multiple files with no protection against runaway execution:

View Performance Test Implementation

// Before: Manual timing with XCTest
func testLogging_Performance() {
    let iterations = 10_000
    let testMessage = "Performance test message"
    
    measure {
        for i in 0..<iterations {
            LoggingService.info("\(testMessage) \(i)")
        }
    }
}

func testCurrencyConversionPerformance() {
    self.measure {
        for _ in 0..<1000 {
            _ = CurrencyHelper.convert(100.0, rate: 0.85)
        }
    }
}

// After: Clean, declarative performance tests
@Suite("Performance Benchmarks", .tags(.performance))
struct PerformanceBenchmarks {
    @Test("Bulk currency conversion performance", .timeLimit(.minutes(1)))
    @MainActor
    func bulkCurrencyConversionPerformance() {
        // Test configuration
        let amounts = Array(stride(from: 0.01, through: 10_000.0, by: 0.01))
        let exchangeRates = ["EUR": 0.92, "GBP": 0.82, "JPY": 110.0, "AUD": 1.35, "CAD": 1.25]
        
        // Performance test
        let startTime = Date()
        for amount in amounts {
            for (_, rate) in exchangeRates {
                _ = CurrencyConversionHelper.convert(amount: amount, rate: rate)
            }
        }
        let duration = Date().timeIntervalSince(startTime)
        
        // Verify performance
        print("Converted \(amounts.count * exchangeRates.count) values in \(duration)s")
        #expect(duration < 10.0) // Framework enforces the 1-minute limit
    }
    
    @Test("Logging throughput", .timeLimit(.seconds(30)))
    func loggingThroughput() async {
        let iterations = 100_000
        
        // No manual measurement needed - framework handles it
        for i in 0..<iterations {
            LoggingService.debug("Test message \(i)")
        }
        
        // Test will fail if it exceeds 30 seconds
    }
}

This prevents runaway tests from blocking CI pipelines. Something I’ve dealt with too many times in XCTest.

Beyond Basic Conversion: Real Improvements

The mechanical migration was just the beginning. Here’s where Swift Testing really shines:

Meaningful Error Testing with #expect(throws:)

Stop settling for “it didn’t crash” assertions:

// Before: Wishful thinking
do {
    try await manager.startListener()
} catch {
    #expect(error != nil) // Well, yes... that's why we're in catch
}

// After: Actual validation
#expect(throws: URLError.self) {
    try await api.fetchWithoutAuth()
}

// Even better: Test the specific error properties
do {
    try await api.fetchWithoutAuth()
    Issue.record("Expected URLError to be thrown")
} catch let error as URLError {
    #expect(error.code == .notConnectedToInternet)
}

Memory Leak Detection Built Right In

Swift Testing’s instance isolation makes leak detection elegant:

@Test("ThreadSafeBox instances are properly deallocated")
func threadSafeBoxMemoryLeaks() async throws {
    weak var weakBox: ThreadSafeBox<String>?
    
    do {
        let box = ThreadSafeBox("test-value")
        weakBox = box
        #expect(weakBox != nil, "Box should be alive within scope")
    }
    
    await Task.yield() // Allow deallocation
    #expect(weakBox == nil, "Box should be deallocated after scope ends")
}

Descriptive Test Names That Tell Stories

No more cryptic function names:

// Before: What does this even test?
@Test("windowControllerManagement")

// After: Crystal clear intent
@Test("Window controller management handles creation and lifecycle")
@Test("Position saving and restoration persists window states")
@Test("AppleScript support methods provide automation capabilities")

Advanced Confirmation Patterns

Swift Testing’s confirmation() handles complex async scenarios elegantly:

@Test("Multi-step debouncer lifecycle")
func multiStepDebouncerLifecycle() async throws {
    try await confirmation("Complete lifecycle", expectedCount: 3) { confirmation in
        // Step 1: Initial call
        debouncer.call { confirmation() }
        try await Task.sleep(for: .milliseconds(70))
        
        // Step 2: Second call after first completes
        debouncer.call { confirmation() }
        try await Task.sleep(for: .milliseconds(70))
        
        // Step 3: Final verification
        confirmation()
    }
}

Taming Flaky Tests with withKnownIssue

Every codebase has those intermittent failures. Swift Testing provides a civilized way to handle them with withKnownIssue:

@Test("External API availability check")
func externalAPITest() async throws {
    await withKnownIssue("External API may be temporarily unavailable", isIntermittent: true) {
        let url = URL(string: "https://api.exchangerate-api.com/v4/latest/USD")!
        let (_, response) = try await URLSession.shared.data(from: url)
        let httpResponse = response as! HTTPURLResponse
        #expect(httpResponse.statusCode == 200, "Exchange rate API should be available")
    }
}

The Results

Looking at the final pull requests (Vibe Meter PR #28, Code Looper PR #8), the transformation is dramatic:

Combined Results:

46% fewer test files (91 → 49 files) through intelligent consolidation
+3,258 lines of enhanced test code across both projects
- Vibe Meter: 61 → 23 files, +1,006 lines
- Code Looper: 30 → 26 files, +2,252 lines
Zero test duplication thanks to parameterized tests
Hierarchical organization that actually makes sense in Xcode’s navigator
Bulletproof error handling with specific exception types
CI that doesn’t hang with proper timeouts on every async test

Why more lines of code? Swift Testing prioritizes maintainability over brevity. Here’s a typical transformation:

// Before: XCTest (3 lines)
func testCurrencyConversion() {
    XCTAssertEqual(convert(100, rate: 0.85), 85.0, accuracy: 0.01)
}

// After: Swift Testing (5 lines)
@Test("Currency conversion with EUR rate", .tags(.currency))
func currencyConversionEUR() {
    let result = convert(amount: 100.0, rate: 0.85)
    #expect(result.isApproximatelyEqual(to: 85.0, tolerance: 0.01))
}

The increase comes from descriptive test names, explicit tagging, better parameter naming, and structured test case types for parameterized tests.

This represents quality improvement, not bloat. Moving from cryptic but compact tests to self-documenting, maintainable test suites.

Key Takeaways

AI needs guidance: The initial blind conversion was just the starting point. The real value came from providing structured patterns through the playbook.
Iterative refinement works: The approach of compile-test-commit-repeat caught issues early and made debugging easier.
Swift Testing encourages better patterns: Features like parameterized tests and instance isolation naturally lead to cleaner test design.
Migration reveals test quality issues: This wasn’t just a syntax conversion. It was an opportunity to improve test architecture.

Additional AI Resources for Swift Testing

For Cursor users, there’s the @Docs context which includes the Apple Documentation as a choice.

There’s also the Context 7 MCP that can be instructed to fetch Apple’s docs for testing, however this only includes code snippets and no explanation. (Enes mentioned that this is on purpose, though I got great results with explanatory text)

The combination of AI assistance and systematic refinement made this large-scale migration manageable. While the initial AI conversion provided a foundation, the real value came from applying Swift Testing’s features thoughtfully to create a more maintainable test suite.

Running Tests Faster with Filters

One more tip that significantly speeds up the development workflow: use swift test --filter to run specific tests instead of the entire suite. This is especially useful when you’re iterating on a particular feature:

# Run a single test suite by name
swift test --filter "FooTests"

# Run tests with specific tags
swift test --filter-tag fast
swift test --filter-tag currency

# Combine multiple tags (runs tests with ALL specified tags)
swift test --filter-tag unit --filter-tag fast

# Skip tests with certain tags
swift test --skip-tag slow
swift test --skip-tag requiresNetwork

The performance difference is dramatic when working on a large codebase. Instead of waiting for 700+ tests to run, you can get feedback in seconds by filtering to just the tests you’re working on. Combined with Swift Testing’s parallel execution, this makes the test-driven development cycle incredibly fast.

P.S. - If you’re still manually converting XCTestExpectation, stop. Make AI do it. Just give it better instructions than I did.

Commanding Your Claude Code Army

Thu, 5 Jun 2025 09:00:00 +0000

Update: There’s a better solution now! Check out Command Your Claude Code Army, Reloaded for VibeTunnel integration that gives Claude automatic title management.

TL;DR: Running multiple Claude Code instances? Here’s a ZSH trick to keep your terminal titles organized and your sanity intact.

I’ll admit it - I’ve become a Claude Code power user. At any given moment, I have at least three instances running: one for writing blog posts, another fixing that “quick” bug that’s now in hour three, and a third doing something I definitely forgot about. My terminal looks like a Claude Code convention.

The Problem: Too Many Claudes, Not Enough Context

Ghostty (yes, with two T’s - it’s my favorite terminal) only shows the process name in the title. When you have six tabs all saying “claude”, finding the right one becomes a game of terminal roulette.

This is especially painful when you’re running Claude with the --dangerously-skip-permissions flag (yes, I live dangerously - see my post about Claude Code being my computer). The last thing you want is to accidentally run the wrong command in the wrong directory with full system permissions.

To make matters worse, Claude Code has a habit of changing the terminal title to whatever it feels like - usually something unhelpful like “Running command…” or just “claude”. It’s like having a helpful assistant who keeps reorganizing your desk while you’re trying to work.

The Solution: Terminal Title Magic

Here’s my approach - a clean ZSH setup that keeps terminal management code separate from my main configuration. First, I add one line to my ~/.zshrc:

# Source Claude wrapper with dynamic terminal title
[ -f ~/.config/zsh/claude-wrapper.zsh ] && source ~/.config/zsh/claude-wrapper.zsh

Then I create ~/.config/zsh/claude-wrapper.zsh with the actual implementation:

#!/usr/bin/env zsh
# Simple, elegant terminal title management for Claude

# Set terminal title
_set_title() { 
    print -Pn "\e]2;$1\a" 
}

# Claude wrapper with custom terminal title
cly() {
    local folder=${PWD:t}  # Just the current folder name
    
    # Set title to show we're running Claude
    _set_title "$folder — Claude"
    
    # Start a background process to continuously reset the title
    # (prevents Claude from changing it)
    (
        while true; do
            _set_title "$folder — Claude"
            sleep 0.5
        done
    ) &
    local title_pid=$!
    
    # Run Claude with dangerous permissions
    "$HOME/.claude/local/claude" --dangerously-skip-permissions "$@"
    local exit_code=$?
    
    # Kill the background title setter
    kill $title_pid 2>/dev/null
    wait $title_pid 2>/dev/null  # Clean up zombie process
    
    # Restore normal title
    _set_title "%~"
    
    # Return the original exit code
    return $exit_code
}

# Update terminal title before each prompt (using proper ZSH hooks)
_claude_precmd() {
    _set_title "%~"
}

# Add our precmd function to the array (doesn't overwrite existing hooks)
if [[ -z ${precmd_functions[(r)_claude_precmd]} ]]; then
    precmd_functions+=(_claude_precmd)
fi

When I run cly, my terminal title changes from ~/Projects/blog to ~/Projects/blog — Claude. Revolutionary? No. Life-changing? Absolutely.

Hot tip: Just ask Claude to read this blog post and set it up for you! (in yolo mode, of course)

Now if you’ll excuse me, I need to check on my Claude instances. I think one of them is refactoring my entire codebase without asking. Again.

Code Signing and Notarization: Sparkle and Tears

Thu, 5 Jun 2025 07:00:00 +0000

Or: How I Learned to Stop Worrying and Love the XPC Services

If you’ve ever tried to implement automatic updates in a sandboxed macOS app using Sparkle, you know it can feel like trying to solve a Rubik’s cube while wearing oven mitts. After creating way too many beta releases and spending countless hours debugging cryptic authorization errors, I finally cracked the code. Here’s my step-by-step guide to code signing, notarization, and Sparkle auto-updates in sandboxed macOS apps.

The Setup: Vibe Meter Meets Sparkle

Vibe Meter is a sandboxed macOS menu bar app that tracks AI service spending. When I decided to add automatic updates using Sparkle 2.x, I thought it would be straightforward. After all, Sparkle is the de facto standard for macOS app updates, right?

Oh, sweet summer child.

Act 1: The Mysterious Authorization Failure

I’d already mastered code signing and notarization (its own nightmare), so I just told Claude: “Look at this repository and do what we did there.” It nailed the signing and notarization process.

My first attempts seemed promising. The app built, signed, and notarized successfully. But when users tried to update, they were greeted with:

Error: Failed to gain authorization required to update target

This error is Sparkle’s polite way of saying “I can’t talk to my XPC services, and I have no idea why.”

Act 2: The Entitlements Enigma

After digging through Sparkle’s documentation and Console logs, I discovered my first issue: missing mach-lookup entitlements. In a sandboxed app, Sparkle uses XPC services to perform privileged operations, and these services need special permissions to communicate.

The Missing Piece

My entitlements file was missing a critical entry:

<key>com.apple.security.temporary-exception.mach-lookup.global-name</key>
<array>
    <string>com.steipete.vibemeter-spks</string>
    <string>com.steipete.vibemeter-spki</string>
</array>

But here’s the kicker - I initially only added -spks, thinking it stood for “Sparkle Server.” Turns out, you need BOTH:

-spks: Sparkle Server (for the InstallerLauncher.xpc service)
-spki: Sparkle Installer (for the Installer.xpc service)

Missing either one results in the dreaded authorization error.

Act 3: The Code Signing Circus

Next came the code signing adventures. My notarization script was doing what seemed logical:

codesign --deep --force --sign "Developer ID" VibeMeter.app

But Sparkle’s documentation specifically warns against using --deep. Why? Because it can mess up the XPC services’ signatures. Instead, you need to sign components in a specific order.

Here’s the correct approach from my codesign script:

# Sign XPC services first
codesign -f -s "$SIGN_IDENTITY" -o runtime \
    "$APP_BUNDLE/Contents/Frameworks/Sparkle.framework/Versions/B/XPCServices/Installer.xpc"

# Preserve entitlements for Downloader.xpc (Sparkle 2.6+)
codesign -f -s "$SIGN_IDENTITY" -o runtime --preserve-metadata=entitlements \
    "$APP_BUNDLE/Contents/Frameworks/Sparkle.framework/Versions/B/XPCServices/Downloader.xpc"

# Sign other Sparkle components
codesign -f -s "$SIGN_IDENTITY" -o runtime \
    "$APP_BUNDLE/Contents/Frameworks/Sparkle.framework/Versions/B/Autoupdate"

# Then sign the framework
codesign -f -s "$SIGN_IDENTITY" -o runtime \
    "$APP_BUNDLE/Contents/Frameworks/Sparkle.framework"

# Finally, sign the app WITHOUT --deep
codesign --force --sign "$SIGN_IDENTITY" --entitlements VibeMeter.entitlements \
    --options runtime VibeMeter.app

Act 4: The Bundle ID Bamboozle

At one point, I thought I was being clever (or rather, Claude Code thought…) by trying to manually modify the XPC services’ bundle identifiers. Big mistake.

For sandboxed apps, Sparkle requires specific bundle ID suffixes:

Use -spks suffix for the InstallerLauncher service
Use -spki suffix for the Installer service

The framework expects these exact suffixes. Use anything else, and you’ll get cryptic XPC connection errors that will make you question your career choices.

Act 5: The Build Number Blues

Even after fixing all the sandboxing issues, I hit another snag. Users were seeing “You’re up to date!” when updates were clearly available. The culprit? My appcast¹ generation script was defaulting build numbers to “1”.

Sparkle uses build numbers (CFBundleVersion), not version strings, to determine if an update is available. If your build numbers don’t increment, Sparkle thinks there’s nothing new.

My appcast generation script now properly handles this:

# Extract build number from Info.plist
BUILD_NUMBER=$(plutil -extract CFBundleVersion raw "$INFO_PLIST")

# Ensure build numbers increment correctly
if [[ "$BUILD_NUMBER" -le "$PREVIOUS_BUILD_NUMBER" ]]; then
    echo "Error: Build number must be greater than previous release"
    exit 1
fi

The Grand Finale: It Works!

After two days of intense debugging, I finally had a working setup. My complete automation pipeline is now rock-solid, with comprehensive scripts that handle every aspect of the process.

The Magic Recipe

Entitlements: Include BOTH -spks and -spki mach-lookup exceptions
Bundle IDs: Never change Sparkle’s XPC service bundle IDs
Code Signing: Sign XPC services individually, never use --deep
Build Numbers: Always increment them, and verify your appcast
Info.plist: Set SUEnableInstallerLauncherService = true and SUEnableDownloaderService = false²

The Working Configuration

The XPC services themselves keep their original Sparkle bundle IDs (org.sparkle-project.InstallerLauncher and org.sparkle-project.Downloader). What we configure in the entitlements are the mach-lookup communication channels:

<!-- VibeMeter.entitlements -->
<key>com.apple.security.app-sandbox</key>
<true/>
<key>com.apple.security.network.client</key>
<true/>
<key>com.apple.security.temporary-exception.mach-lookup.global-name</key>
<array>
    <string>com.steipete.vibemeter-spks</string>
    <string>com.steipete.vibemeter-spki</string>
</array>

The Scripts That Saved My Sanity

My complete build pipeline consists of several specialized scripts:

preflight-check.sh: Validates environment and prerequisites
codesign-app.sh: Handles the complex code signing process
notarize-app.sh: Manages notarization and stapling
create-dmg.sh: Creates and signs distribution DMGs
generate-appcast.sh: Generates Sparkle appcast files
release.sh: Orchestrates the entire release process

Look at this beauty! Now even Claude can do releases without messing up 🎉 I just tell it “Create a new beta release, see release.md” and it handles everything.

# Now create the release
./scripts/release.sh stable        # For stable 1.1.0
# OR
./scripts/release.sh beta 1        # For 1.1.0-beta.1

# Use the version script to bump versions
./scripts/version.sh --minor       # 1.0.0 -> 1.1.0
./scripts/version.sh --major       # 1.0.0 -> 2.0.0
./scripts/version.sh --set 1.1.0   # Set specific version

Everything happens automatically - from building to GitHub release creation. These scripts are tuned for Tuist and can easily be adapted for simpler setups.

The Notarization Nightmare

Apple’s notarization process adds another layer of complexity. Notarization verifies your app is safe - you upload it to Apple’s servers for scanning, and if approved, they “staple” a ticket to your app. The process typically takes a few minutes in Apple’s notarization queue (officially called the “processing queue”). The notarization script uses the modern notarytool approach:

# Create ZIP for notarization (not DMG!)
ditto -c -k --keepParent "$APP_BUNDLE" "$ZIP_PATH"

# Submit for notarization
xcrun notarytool submit "$ZIP_PATH" \
    --key "$API_KEY_PATH" \
    --key-id "$API_KEY_ID" \
    --issuer "$ISSUER_ID" \
    --wait

# Staple the ticket
xcrun stapler staple "$APP_BUNDLE"

# Verify everything worked
spctl -a -t exec -vv "$APP_BUNDLE"
xcrun stapler validate "$APP_BUNDLE"

Of course this needs certificates from Apple. Luckily Claude is smart enough to guide you through the whole process of downloading those files and adding them to the keychain and your environment.

Pretty Changelogs in Sparkle

One challenge I hadn’t anticipated was making the update dialogs actually useful. Sparkle can display rich HTML changelogs, but getting from my Markdown changelog to properly formatted HTML required some creativity.

The changelog-to-html.sh script extracts version-specific sections from CHANGELOG.md and converts them to HTML with what I call the “Poor Man’s Markdown Parser”:

# Extract version section and convert Markdown to HTML
awk "/^## \\[$version\\]/{flag=1;next}/^## \\[/{flag=0}flag" CHANGELOG.md | \
sed 's/^### \(.*\)/<h3>\1<\/h3>/' | \
sed 's/^- \(.*\)/<li>\1<\/li>/' | \
sed 's/\*\*\([^*]*\)\*\*/<strong>\1<\/strong>/g'

The result? Users see properly formatted changelogs with headers, lists, and styled text instead of raw Markdown. Note: This parser has limitations - it doesn’t handle nested lists, images, or links. Keep your changelogs simple or extend the parser for more complex formatting.

The Complete Architecture

What emerged is a surprisingly elegant zero-infrastructure solution that leverages GitHub’s existing services:

GitHub-Centric Distribution

Releases: GitHub releases host the actual DMG files
Appcast Hosting: Raw GitHub URLs serve the XML feeds
Dual Feeds: Separate appcasts for stable and pre-release channels
Version Control: Appcast files are versioned alongside the code

Dynamic Channel Switching

The app includes runtime logic to switch between update channels without reinstallation. Users can choose “stable” for production releases or “pre-release” for beta access, and the app dynamically points to the appropriate appcast URL.

Automated Everything

The release.sh script orchestrates the entire pipeline:

Build and sign the app
Create GitHub release with DMG
Generate both appcast files with proper signatures
Commit and push everything

No separate hosting, no Jekyll setup, no additional infrastructure - just GitHub doing what it does best. The key is that release.sh is the master orchestrator that calls most other scripts in sequence for a complete automated release.

View the complete script flow architecture

🚀 Main Release Flow (release.sh)

release.sh
├── 1. preflight-check.sh ────────────── Validates everything ready
├── 2. generate-xcproj.sh ────────────── Generates Xcode project
├── 3. build.sh ──────────────────────── Builds app with IS_PRERELEASE_BUILD flag
├── 4. sign-and-notarize.sh ──────────── Signs & notarizes app
│   ├── codesign-app.sh ─────────────── Code signs app bundle
│   └── notarize-app.sh ─────────────── Notarizes signed app
├── 5. create-dmg.sh ─────────────────── Creates & signs DMG
├── 6. GitHub CLI (gh) ───────────────── Creates GitHub release
├── 7. generate-appcast.sh ───────────── Updates appcast XML files
└── 8. verify-appcast.sh ─────────────── Validates appcast (optional)

✅ Verification Flow

preflight-check.sh ───────────────────── Pre-release validation
└── verify-prerelease-system.sh ──────── IS_PRERELEASE_BUILD system check

verify-app.sh ────────────────────────── Post-build verification
verify-appcast.sh ────────────────────── Appcast validation

🔐 Manual Signing Flow

sign-and-notarize.sh
├── codesign-app.sh ──────────────────── Code sign app
├── notarize-app.sh ──────────────────── Notarize app
└── create-dmg.sh ────────────────────── Create distribution DMG

🛠️ Utility Scripts (Called by others)

- changelog-to-html.sh ← Called by update-appcast.sh
- version.sh ← Standalone version management

Lessons Learned

Read the documentation carefully - But also know that it might not cover every edge case
Console.app is your friend - Filter by your process name and watch for XPC errors
Don’t be clever - Follow Sparkle’s conventions exactly
Test updates, not just builds - A successful build doesn’t mean updates will work
Automate everything - Manual processes lead to human errors
Version control your scripts - Build automation is as important as your app code

Final Thoughts

Implementing Sparkle in a sandboxed app is like solving a puzzle where the pieces keep changing shape. But once you understand the rules - respect the XPC services, get your entitlements right, and sign everything properly - it works beautifully.

The irony? The final solution is actually quite simple. It’s getting there that’s the adventure. I don’t know how anyone manages to ship working macOS apps at all, honestly.

Now go download Vibe Meter and read my dev diary on how I built it with Claude Code: Vibe Meter: Monitor Your AI Costs.

Resources

Special thanks to the Sparkle team and Claude Code - without them, this automation pipeline wouldn’t exist.

P.S. Just steal my scripts. It’ll save you days of debugging. ☕️

An appcast is an RSS-like XML feed that Sparkle uses to check for updates. It contains information about available versions, download URLs, and release notes. See Sparkle’s documentation on appcasts for more details. ↩
The Downloader service is only needed if your app doesn’t have network access. Since Vibe Meter includes the com.apple.security.network.client entitlement, we can disable SUEnableDownloaderService. This simplifies the setup and avoids the Downloader service’s limitations. See Sparkle’s sandboxing documentation for details. ↩

Vibe Meter: Monitor Your AI Costs

Wed, 4 Jun 2025 11:00:00 +0000

My Cursor bill hit $900 for the month. I needed a simple way to track AI spending without constantly checking dashboards. That frustration sparked Vibe Meter - my first shipped Mac app built in three intense days.

What started as a workshop demo became a sophisticated menu bar utility using Swift 6, SwiftUI, and extensive AI assistance.

What the AIs Say

I had several AI models analyze the VibeMeter codebase:

O3: “Name vs. purpose mismatch – it sounds like a mood tracker, but monitors AI-API spending.”

Claude Opus: “86% test coverage is extraordinary. Code quality rivals what I see in major tech companies. This isn’t just a ‘side project’ - it’s a case study in how to build macOS software the right way.”

Gemini: “Intentionally over-engineered for future growth.”

From Workshop Demo to Production App

I ran a live workshop demonstrating AI-assisted development. Since Cursor lacks a public API, we reverse-engineered their web interface, extracted cookies, and called internal endpoints. Built both Electron and macOS versions in parallel.

The feedback surprised me - people actually found it useful. When Gergely Orosz mentioned linking to it in his newsletter, I spent two more days polishing the rough demo into something shippable.

Cursor has no public API for cost control, and it was somewhat messy because I have an enterprise account while many people have individual accounts, and the API endpoints are quite different. Getting both right was tricky.

Special thanks to Oliver Drobnik for helping me fix the individual account parsing. The second 90% of finishing an app always takes longer than the first 90%.

Looking for testers: Need someone with multiple Cursor teams to help test. Current implementation assumes one team only.

Key Technical Challenges

SwiftUI vs AppKit: The Eternal Dance

I used SwiftUI wherever possible, but macOS menu bar apps expose the framework’s limitations. Need a popover without the arrow? Drop down to AppKit. Want to show settings from a menu item? More AppKit gymnastics.

I needed a custom NSPanel for precise menu bar control. Memory management got tricky in release builds - weak references to windows deallocated before appearing.

Even showing settings required a reflection hack accessing internal NSMenuItem properties. Apple deprecated the old methods, but the “correct” SwiftUI approach only works from SwiftUI views.

The Animation Breakthrough

I’m proud of the animated menu bar icon. Almost used Lottie, but SwiftUI was enough. ChatGPT converted a static icon into animatable code.

The gauge moves with spending levels, uses conic gradients for loading shimmer. ImageRenderer converts SwiftUI to NSImage for the status item.

Swift 6 Concurrency Deep Dive

This was my first production app using Swift 6’s strict concurrency model. The architecture heavily relies on actors for thread safety:

CursorAPIClient and ExchangeRateManager as actors
@MainActor isolation for UI components
Structured concurrency with TaskGroup in MultiProviderDataOrchestrator
async/await throughout, ditching Combine entirely

The learning curve was steep - debugging UNUserNotificationCenter delegate callbacks firing on background threads while trying to update @MainActor state was particularly painful.

One bug drove me crazy: perfect in debug, window wouldn’t show in release. SwiftUI view held weakly by AppKit disappeared before display. No crash, just nothing.

Claude figured it out when I explained the symptoms. Reminder: always test release builds.

Apple’s Distribution Gauntlet

The hardest part wasn’t coding - it was signing, notarization, and distribution. Apple’s process is error-prone: you can notarize an app but miss deep notarization of embedded frameworks (like Sparkle), leaving you with a partially notarized app that won’t run.

Rather than wrestle with Fastlane, I built custom shell scripts that are much more debuggable. Now Claude can create releases by simply running “make a new release 1.1 beta 1” - the automation is beautiful once set up.

The scripts handle everything: incrementing build numbers, creating DMGs, uploading to GitHub releases, generating Sparkle appcast files. The most complex part was handling Sparkle’s EdDSA signatures correctly - the error messages when you get it wrong are cryptic at best. Pro tip: always test your update feed locally before pushing.

Interesting Technical Details

Multi-Provider Architecture

Though Vibe Meter only supports Cursor currently, the architecture anticipates multiple providers. The MultiProviderDataOrchestrator and protocol-based design make adding OpenAI or Anthropic straightforward when the time comes.

I really had to hold myself back from implementing OpenAI and Anthropic support right away. When I realized this would be useful for tracking all AI costs - not just Cursor - the temptation was strong. But I knew if I started adding providers, I’d never ship. So I built the architecture to support it but forced myself to ship with just Cursor. This is definitely coming in a future update.

The multi-provider design might seem like overkill, but it’s already paying dividends. When debugging, I can easily add a mock provider that returns test data. The orchestrator handles provider failures gracefully - if Cursor’s API is down, the app doesn’t crash, it just shows cached data with a subtle indicator.

Polish in the Details

Small touches matter. The app includes:

Currency conversion with real-time exchange rates
Gravatar integration for user avatars (SHA-256 hashing, retina support)
Comprehensive network connectivity monitoring
ApplicationMover for automatic /Applications folder relocation
Spending limit notifications with configurable thresholds

Agent-Friendly Development

I constrained every file to under 300 lines - agents make fewer mistakes with smaller files. This forced better organization and created a more maintainable codebase for both humans and AI. Using Tuist for project generation also helped since agents struggle with Xcode’s complex .pbxproj files.

By the Numbers

What emerged surprised even me:

174 Swift files totaling 28,599 lines of code
86% test coverage with 628 individual test methods
18 shell scripts (2,857 lines) for build automation
437 occurrences of Swift 6 concurrency keywords
15 protocols for loose coupling and testability

The largest files respect the 300-line constraint: ApplicationMover.swift (390 lines), SparkleUpdaterManager.swift (361 lines), and Color+Theme.swift (358 lines). The build infrastructure alone required comprehensive scripts for code signing (349 lines), release automation (314 lines), and notarization (312 lines).

The Testing Philosophy

I wanted to see how well AI generates tests. For a hobby project like this, I probably wouldn’t have written any. But they caught real bugs:

Currency conversion edge cases (what happens when the exchange rate API is down?)
Cookie expiration handling (Cursor cookies last 30 days, not forever)
Timezone bugs (monthly spending resets at UTC midnight, not local time)
The classic “what if the user has no internet?” scenarios

The UserDefaultsBackedAdvancedTests alone has 374 lines testing every possible edge case of property wrappers. Did we need all of them? Probably not. Did they catch bugs? Absolutely.

Lessons Learned

Context windows matter. I ran six Claude instances concurrently - one for linting, one for tests, one for UI, one for features, one for bugs. First time trying this strategy. Worked beautifully. The more an agent knows about previous related tasks, the better it performs.

Small files matter. The 300-line constraint prevented agent editing mistakes and forced better architecture. What seemed like a limitation became a forcing function for good design.

SwiftUI has come far. Despite the AppKit gymnastics required for menu bar specifics, SwiftUI handled 90% of the UI beautifully. The animation capabilities particularly impressed me.

Modern Swift is powerful. Swift 6’s actor model and structured concurrency made complex state management surprisingly manageable, even for a concurrency novice.

AI agents love writing tests. Embrace it. The comprehensive test suite they generated caught bugs I never would have thought to test for.

Performance Notes

A menu bar app needs to be lightweight. Vibe Meter uses about 45MB of memory and essentially zero CPU when idle. The BackgroundDataProcessor refreshes data every 5 minutes by default, but backs off exponentially if errors occur.

One optimization I’m proud of: the app only loads exchange rates when you actually use a non-USD currency. The ExchangeRateManager caches rates for 24 hours and falls back gracefully if the API is down. Small touches, but they matter for an app that runs 24/7.

If you’re tracking AI costs, try Vibe Meter. Source on GitHub. Watch the workshop recording to see where it started.

Three days. One person. Six AI assistants. The future is weird.

Claude Code is My Computer

Tue, 3 Jun 2025 08:00:00 +0000

TL;DR: I run Claude Code in no-prompt mode; it saves me an hour a day and hasn’t broken my Mac in two months. The $200/month Max plan pays for itself.

For the past two months, I’ve been living dangerously. I launch Claude Code (released in late February) with --dangerously-skip-permissions, the flag that bypasses all permission prompts. According to Anthropic’s docs, this is meant “only for Docker containers with no internet”, yet it runs perfectly on regular macOS.

Yes, a rogue prompt could theoretically nuke my system. That’s why I keep hourly Arq snapshots (plus a SuperDuper! clone), but after two months I’ve had zero incidents.

From ‘AI assistant’ to everything terminal

When I first installed Claude Code, I thought I was getting a smarter command line for coding tasks. What I actually got was a universal computer interface that happens to run in text. The mental shift took a few weeks, but once it clicked, I realized Claude can literally do anything I ask on my computer.

The breakthrough moment came when I was migrating to a new Mac. Instead of doing the usual restore dance, I pointed Claude at my backup disk and said: “Restore this Mac from my backup disk—start with dotfiles, then system preferences, CLI tools, and restore Homebrew formulae and global npm packages.” Claude drafts a migration plan, executes it step by step, and has my new machine ready in under an hour.¹

What I actually use it for

My daily Claude Code usage falls into several main outcomes:

Ship Content: “Convert ~40 posts from Jekyll to MDX format here. Make sure to copy over the images and preserve the redirects.” Twenty minutes later, Claude had processed every single post, set up proper redirects, validated all image paths, and pushed a merge-ready branch.

Extract Features: “Extract this feature into a Swift project” (that’s how I released Demark) where Claude creates the package structure, writes tests, documentation, and handles the entire open-source release process.

Automate Content: Like this very post. I use Wispr Flow to talk with Claude, explain the topic and tell it to read my past blog posts to write in my style. Instead of wrestling with Markdown formatting, Claude creates the document, helps formulate thoughts, and tests that everything displays correctly.

Generate Test Data: “Create seed data for a project” turns into Claude analyzing my codebase, understanding the data models, and generating realistic test data with proper relationships.

Ship Code: I haven’t typed git commit -m in weeks. Instead, I say “commit everything in logical chunks” and Claude handles the entire flow—staging changes, writing meaningful commit messages, pushing, opening PRs, watching CI, and fixing any CI failures. When builds break, it analyzes the errors and patches them automatically. It’s also extremely good at resolving merge conflicts.

Clean the OS: “Hide recent apps in the Dock” becomes a single natural language command instead of Googling for the right defaults write incantation. Claude knows macOS internals and happily calls killall Dock to restart the Dock after modifying the plist.

Spin Up New Machines: Recently when setting up CodeLooper’s code signing and notarization, Claude handled installing Homebrew packages, creating private keys, adding them to the keychain, creating backups, building the project, uploading to GitHub, running tests, and monitoring the process. The only manual part was clicking through the update UI, but with my macOS Automator MCP Server, I could probably teach it that too.

I use an alias in my shell config² so just typing cc runs Claude with the permission flag.

Why this works (and when it doesn’t)

Claude Code shines because it was built command-line-first, not bolted onto an IDE as an afterthought. The agent has full access to my filesystem (if you are bold enough…), can execute commands, read output, and iterate based on results.

Anthropic’s best practices guide recommends keeping a CLAUDE.md file at your repo root with project-specific context. I’ve adopted this pattern and noticed Claude asks fewer clarifying questions and writes more accurate code. You can check out my Claude Code rules for examples of how I structure these files. Little optimizations like this compound quickly.

The main limitation is response time. Claude’s thinking process takes a few seconds, and for rapid-fire debugging sessions, I sometimes reach for traditional tools. However, you can prefix commands with ! to run them directly without waiting for token evaluation—Claude will execute your command either way, but this is faster when you know exactly what you’re calling. For exploratory work where I’m not sure what I need, Claude’s reasoning ability more than compensates for the brief pause.

Why Warp lacks

Warp’s mission is to “reinvent the command line with AI”. They’ve built beautiful GPU-accelerated panels and smart autocomplete.

The fundamental difference comes down to trust and execution flow. Claude operates purely through text and is remarkably intelligent about understanding context and intent. With this setup, I can pre-authorize Claude to execute commands without constant confirmation prompts. Warp, while excellent, requires individual approval for each command—there’s no equivalent to Claude’s “dangerous mode” where you can grant blanket execution trust. This means Claude maintains conversational flow while Warp still interrupts with permission requests.

I signed up for Warp because I like their mission and I hope they eventually go where Claude is. But it seems they have a fundamentally different idea about safety. Also, Ghostty is just the better command line, native, not Electron-based and faster.

Where this is heading

We’re in the very early days of AI-native development tools. Claude Code represents a paradigm shift: from tools that help you run commands to tools that understand intent and take action. I’m not just typing commands faster—I’m operating at a fundamentally higher level of abstraction. Instead of thinking “I need to write a bash script to process these files, chmod it, test it, debug it,” I think “organize these files by date and compress anything older than 30 days.”

This isn’t about AI replacing developers—it’s about developers becoming orchestrators of incredibly powerful systems. The skill ceiling rises: syntax fades, system thinking shines.

Should you try this?

If you’re comfortable with calculated risks and have solid backups, absolutely. The learning curve is essentially zero—you just start talking to your computer like it’s a competent colleague. Within days, you’ll wonder how you ever worked without it.

Your computer isn’t just a computer anymore. It’s Claude. And Claude is absurdly capable.

Got a crazier Claude workflow? Ping me @steipete.

Essential Reading: How I Use Claude Code is a must-read by my friend and ex-employee Philipp for everyone using Claude Code.

Note that full backup migrations can sometimes cause various system issues with newer macOS versions. ↩
alias cc="claude --dangerously-skip-permissions" ↩

Stop Over-thinking AI Subscriptions

Mon, 2 Jun 2025 09:00:00 +0000

I’ve been working heavily with AI for the past few months, and many times when I post something on Twitter, the replies are predictable: “Oh my god, how much did you pay for that?”

The thing is, people don’t understand that you don’t actually have to pay that much to get incredible AI productivity. After using the best AI subscription deals 2025 has to offer, here’s the real math (all prices in USD). (And yes, I built Vibe Meter to track exactly how much I’m spending.)

Plan	Monthly Fee	Included Usage	Marginal Cost
Claude Pro	$20	~45 messages/5h	Rate limited
Claude Max 5×	$100	~225 messages/5h	Rate limited
Claude Max 20×	$200	~900 messages/5h	Rate limited
Cursor Pro	$20	500 fast requests	$0.04/fast request
OpenAI o3	Pay-per-use	N/A	$10-40/1M tokens

The Current Best Deal: Claude Max at $200/month

Claude Max gives you almost unlimited use of Claude Code, which is hands-down the best terminal-based AI tool available (next to Cursor). For $200/month, you get 20× the usage of Claude Pro.

Claude Max works on a rolling 5-hour block system with roughly 900 messages per 5-hour window. The moment you send your first prompt, the timer starts. When 5 hours are up, everything refreshes with a new block and full quota. The Claude Max subscription uses Opus as the default model and switches to Sonnet when you reach 50% of the 5-hour limit (this is configurable). If you really burn through your whole allowance for that window, you can switch to API-based billing.

If you’re tight on money and you really need this extremely high use case, look at the development partner program where they offer 30% off standard API pricing (this discount applies only to API usage, not the Max sub).

But What About Future Price Increases?

I get messages all the time from people worried that token prices will go up. Here’s the reality check:

Token prices have dropped 1000× in the last two years. We’ve gone from GPT-3’s astronomical pricing to incredibly capable open models. The competitive landscape has completely transformed—companies are building their own models now. Windsurf has SWE-1, Vercel launched v0-1.5lg, and every major player is racing to offer the best value.

What indicators suggest prices will increase? None. If anything, competition is driving costs down to the fundamental floor: energy costs. Models are becoming commodities. The real differentiator is the tooling around them, not the raw compute.

So stop worrying about hypothetical price hikes. The trend line points one direction: down.

Cursor: The Math That Makes Sense

Cursor Pro costs $20/month and gives you 500 “fast” requests plus unlimited “slow” ones. Beyond that, it’s $0.04 per fast request (per Cursor docs).

Cursor offers two pricing modes: Normal mode charges a fixed number of requests per message regardless of context size, while Max mode uses token-based pricing (API cost + 20% margin) for complex reasoning tasks. Most everyday coding works perfectly fine in Normal mode where each message to Gemini 2.5 Pro (my favorite model) costs exactly 1 request.

That workshop I did? Probably 200+ AI requests across 3 hours. Let’s do the math: 200 requests × $0.04 = $8.

For an afternoon of intensive coding with AI assistance, you’re looking at pocket change. Even if you burn through 1,000 requests in a month, that’s $40 on top of your $20 subscription. When you run out of fast requests, Cursor automatically switches to free requests (processed at lower priority) so you never truly hit a wall.

What Actually Gets Expensive: OpenAI’s o3

Here’s where I’ll be honest: about half my monthly AI bill goes to o3.

OpenAI’s o3 model costs $10 per 1M input tokens and $40 per 1M output tokens. Cached input drops to $2.50/1M. When you’re debugging complex code and you want the absolute best reasoning, o3 delivers, but it adds up fast.

o3 is my dark knight—silent, pricey, but rescues impossible bugs.

I spent around $400 on o3 last month because I was banging my head against a wall with some really tricky code. When I hit truly difficult problems, throwing o3 at them for a few hours beats getting stuck in debugging rabbit holes for days.

Smart Alternative: Repo Prompt for o3 Access

If you’re tight on money but still want o3’s reasoning power, I highly recommend Repo Prompt (macOS-only). It lets you use o3 through your ChatGPT subscription instead of paying API rates.

While it’s more manual than integrated tools, it’s incredibly effective at taking code changes and applying them to your project. The workflow is straightforward: export your repo context, get o3’s analysis and suggestions, then apply the changes back to your codebase.

It’s an amazing tool that bridges the gap between premium AI access and budget constraints. Definitely worth experimenting with.

The Contractor Math

Let’s be conservative and say $800/day (though I’d assume many of you charge more). The AI subscription math is a no-brainer.

One afternoon saved per month = $200 in billable time. Claude Max pays for itself in 5 saved hours. Cursor pays for itself in 45 minutes.

The productivity multiplier is so absurd that arguing about the cost is like complaining about the price of coffee while billing $200/hour.

Now you know—don’t be a Mario:

Hi, my name is Mario, and I spent about $1000 in Anthropic pay-as-you-go before switching to Max and finding out that I stay well within the rate limit...

Don't be a Mario.

— Mario Zechner (@badlogicgames) November 30, 2024

TL;DR

Time is the only non-refillable resource. Claude Max at $200 is currently the cheapest way I know to mint extra hours—and those hours compound faster than any SaaS line item ever will.

What’s your monthly AI spend? Ping me on Twitter @steipete with your breakdown and what you’re buying with the saved time.

Introducing Demark: HTML in. MD out. Blink-fast.

Sun, 1 Jun 2025 18:45:00 +0000

I recently found myself needing a component that converts messy, potentially malformed HTML to clean Markdown in Swift. After searching around, I couldn’t find anything that really fit my needs, so I decided to write my own. The result is Demark – my first Swift package that’s now available on the Swift Package Index.

The Problem

HTML to Markdown conversion sounds straightforward, but it’s surprisingly complex when you need to handle:

Malformed or messy HTML
JavaScript-rendered content
Complex nested structures
Various HTML edge cases

I needed something reliable that could handle real-world HTML, not just clean, well-formed markup.

The Solution: Standing on the Shoulders of Giants

Instead of writing a full-blown HTML parser from scratch, I took a different approach. Why reinvent the wheel when there are already excellent JavaScript libraries that solve this problem really well?

Demark leverages two proven JavaScript libraries:

Turndown.js for the most accurate conversions
html-to-md for faster, lightweight processing

The magic happens by running these libraries inside a WKWebView, giving me access to a full browser environment with proper DOM parsing capabilities.

Two Conversion Engines

Demark offers flexibility with two different engines:

Turndown.js (Default) - When you need accuracy:

Full DOM-based parsing
Handles complex HTML and JavaScript-rendered content
Comprehensive configuration options
~100ms for first conversion (then much faster)

html-to-md - When you need speed:

Lightweight JavaScript-based conversion
Much faster performance (~5-10ms per conversion)
Perfect for batch processing simple HTML

Vibe Coding with AI

Here’s the thing – I probably would never have released this without AI assistance. But with AI, the whole process became so much easier. What would have taken me days of tedious work – setting up the package structure, writing documentation, handling edge cases, making it Swift Package Index ready – took me just a few hours.

AI helped me:

Structure the Swift package properly
Write comprehensive documentation
Handle all the WebKit integration details
Create a clean, modern Swift API with async/await
Set up proper error handling

Simple to Use

Despite the complexity under the hood, Demark is dead simple to use. The Swift package that turns down HTML and turns up Markdown – it’s a markup markdown!

import Demark

@MainActor 
func convertHTML() async throws {
    let demark = Demark()
    let html = "<h1>Hello World</h1><p>This is <strong>bold</strong> text.</p>"
    let markdown = try await demark.convertToMarkdown(html)
    print(markdown)
    // Output: # Hello World
    //
    // This is **bold** text.
}

My First Swift Package

Demark works across all Apple platforms: iOS, macOS, watchOS, tvOS, and visionOS.

I’m quite happy about this milestone. After years of iOS development, publishing my first Swift package feels like a natural next step in my open source journey. The fact that it’s now in the Swift Package Index makes it easily discoverable and installable for other developers.

The experience taught me that sometimes the best solution isn’t writing everything from scratch – it’s about cleverly combining existing, battle-tested solutions in a new way.

Try It Out

If you need HTML to Markdown conversion in your Swift projects, give Demark a try. You can add it to your project via Swift Package Manager:

dependencies: [
    .package(url: "https://github.com/steipete/Demark.git", from: "1.0.0")
]

The repository includes an example app with a dual-pane interface where you can test conversions in real-time. Perfect for seeing exactly how your HTML will be transformed.

Here’s to many more Swift packages! 🚀

The Future of Vibe Coding: Building with AI, Live and Unfiltered

Sun, 1 Jun 2025 15:00:00 +0000

The future of vibe-coding - Workshop Peter Steinberger - 2025_05_28 08_57 CEST

A friend asked me to show off my current workflow, so I did an impromptu workshop for him and his developers. This is a snapshot of how I approach vibe coding these days. Don’t expect a professional workshop - I did this as a favor and for the fun of it. I let Gemini extract the key points into a blog post, if you don’t want to watch all of the 3-hour video.

All the code generated during this workshop is available on GitHub.

Transcript

Alright, let’s talk about how software development is changing, right now. For nearly 15 years, I was deep in the PDF world with PSPDFKit (now they rebranded as Nutrient). After selling the company, I took a much-needed breather. I was properly burned out. But a couple of months ago, that itch, that spark, came back. And what pulled me in? AI.

It’s a completely different landscape now. Everything I’m about to share is what I’ve crammed into my brain over the last two, very intense, months. I’m still discovering new things daily, but what’s already possible is, frankly, incredibly cool. So, I decided to do a live workshop: go from a raw idea to a (hopefully) working product in a few hours, unscripted, just pure “vibe coding.”

The Idea: “Vibe Meter” – Keeping an Eye on AI Costs

If you’re like me, you’re probably diving deep into AI tools. I’m using Cursor (the AI-first IDE) and Anthropic’s Claude Code (their command-line AI) pretty heavily. These things aren’t free. My Cursor bill was already nudging $900 for the month, and there’s that $1000 cap before you need to talk enterprise. It got me thinking: wouldn’t it be great to have a little something in the menu bar to see that spend in real-time?

And thus, “Vibe Meter” was born. I even briefly considered calling it “Aufpasser” (German for a kind of minder or little policeman – seemed fitting!). The plan was ambitious for a short workshop:

A macOS menu bar app (because native is nice).
An Electron app (for that cross-platform reach, because why not?).
Display current monthly Cursor spend.
Show more details on click, like who’s logged in.
Configurable warning limits – say, a “vibe code limit” at $200, and another at the $1000 mark, with actual user notifications.
A proper settings dialog for these limits.
Since Cursor doesn’t have a public API for this, we’d need to figure out a login mechanism, likely by capturing cookies like their own web app does.
Currency conversion (dollars, Euros, maybe even Philippine Pesos for the team!).
The usuals: launch at startup, quit option, logout.

Yeah, a bit much for a live demo, but go big or go home, right?

Phase 1: The Blueprint – Forging Specs with Google’s AI Studio & Gemini

Even in this new AI-driven world, a solid specification is still your bedrock. The difference? The process of creating it can be far more dynamic and, dare I say, fun. For this, I turned to Google’s AI Studio, powered by their Gemini model.

Why AI Studio for Specification? It’s About the Output and the Process. Gemini is seriously impressive. I find it’s incredibly good at generating lengthy, structured text without the aggressive summarization or “shortcut-taking” I’ve seen from other models when you ask for, say, full technical documentation. The playground for Gemini seems to have almost unlimited processing power for this kind of task – it doesn’t feel like it’s constantly trying to save on tokens when you need detail. Plus, the cost is quite reasonable – something like four cents per million tokens for the input, which is great for feeding it lots of context.

My Spec Refinement Loop – AI Critiquing AI: This is a pattern I’ve found incredibly powerful:

Voice-First Brain Dump: I’m lazy with typing. I use an app called “Flow” (or Whisper Flow – just hit the Fn key on my Mac, and it transcribes) to dictate my initial thoughts, feature ideas, and user stories directly into a new Gemini chat in AI Studio. It’s fast and captures ideas fluidly.
Gemini’s First Draft: Gemini takes this verbal stream-of-consciousness and churns out a pretty decent first-pass structured specification document.
The “Peer Review” by Another AI: This is the fun part. I copy that entire generated spec and paste it into a brand new, separate Gemini chat. My prompt to this second instance is something like: “You are an AI tasked with implementing this spec in one go. Before you start, what questions do you have? What’s unclear? What’s missing for you to build this successfully?”
Addressing the AI’s Questions: The second AI always comes back with brilliant questions. It points out ambiguities, edge cases I hadn’t considered, and missing information. It’s like having an infinitely patient, detail-oriented peer reviewer.
Refining the Master Spec: I take these questions, think through the answers, and then feed those answers and clarifications back into the original AI Studio chat – the one that holds the “master” context of our evolving spec.
Iteration is Key: We went back and forth. For Vibe Meter, this helped us realize we needed to be very specific about how we’d get the Cursor teamId and the exact cookie name (which turned out to be workos_cursor_session). This led to a bit of live “API archeology” using browser dev tools – inspecting Cursor’s own web app’s network requests during login, when viewing usage, etc. We found the /me endpoint for user details and the getMonthlyInvoice call (a POST request, interestingly) which contained the team ID and costs (in cents).
Nailing Down Technicals: We also layered in technical constraints: Swift 6 for the Mac app (because why not use the latest?), latest macOS only, Swift Test for unit tests, a strict “menu bar only, no Dock icon” policy, and for the Electron version, a clear directive to use TypeScript and React.

This process of letting an AI help refine the input for another AI (or even itself in a later stage) is a cornerstone of “vibe coding.” The better your spec, the less friction you’ll have when it’s time to generate actual code. Gemini’s massive 1 million token context window is a godsend here; you can really build up a rich, detailed understanding within the chat.

Phase 2: Unleashing the Coders – Cursor IDE, Parallel Builds, and My Bag of AI Tricks

With a spec that felt reasonably robust (for a live demo!), it was time to fire up Cursor, my AI-first IDE of choice, and actually generate some code.

Going Parallel – Mac & Electron Simultaneously: I’d already set up a GitHub repo for “Vibe Meter” and, within it, two distinct folders: VibeMeter-Mac and VibeMeter-Electron. The plan was to build both in parallel, so I opened two separate Cursor IDE windows, one pointed at each sub-project.

For the Mac App (SwiftUI):
- In the Cursor window for VibeMeter-Mac, I started a new chat.
- Pasted our full, refined specification.
- Selected the Gemini model within Cursor (it’s one of several you can choose).
- The prompt was straightforward: “You are an AI tasked with building a Mac app based on this software specification. Generate the project and all necessary files.”
For the Electron App (TypeScript/React):
- In the VibeMeter-Electron Cursor window, I did the same but with a crucial addition to the prompt: “We also want to build a version of this using Electron. Any technical choices in the spec that were Swift-only should be replaced with good cross-platform alternatives. Use TypeScript and React for the implementation.”

And then, the magic (and sometimes the madness) begins. You hit “go,” and the AIs start chugging away, planning steps, creating files, and writing code.

Dealing with the “Continue Monkey” – And My Solution, CodeLooper: One of the current papercuts in these AI-driven IDEs is the generation loop. They’ll work for a bit, then pause, often requiring a manual click on a “Continue” button. This can be due to internal limits (Cursor sometimes has a 25-turn limit before pausing), connection hiccups, or the AI just needing a moment to plan its next multi-step move.

This constant need to babysit the “Continue” button is why I’m building a side-project called “CodeLooper.” It’s a Mac menu bar app that uses a combination of screen capture, accessibility APIs, and even JavaScript injection (since Cursor itself is an Electron app) to detect when a generation loop has paused and, if it deems it safe, automatically click “Continue” for me. It’s still a work in progress, but the goal is to achieve longer, truly unattended generation sessions. For this workshop, though, I was the designated “Continue Monkey.”

MCPs – My Custom Toolkit for Supercharging Cursor: Cursor allows you to define “MCPs” (which I think of as “More Capable Prompts” or “More Capable Tools”). These are essentially custom functions or external tools the AI agent within Cursor can choose to call. I’ve been building out a suite of these to give the AI more leverage:

🧠 Claude Code: This is a big one. It allows the Gemini agent in Cursor to delegate specific tasks to Anthropic’s Claude Code running in my terminal (often in “YOLO mode,” where I pre-authorize it to bypass permission prompts for shell commands – live dangerously, right?). This is fantastic for playing to each AI’s strengths. If Cursor gets stuck or I want Claude’s deeper reasoning on a complex refactor, I can have Gemini call out. It’s also cost-effective if you’re on Claude’s flat-rate subscription. A buddy for your IDE that your agent can ask if he’s stuck. Can do coding tasks and offer “a pair of fresh eyes” that often un-stucks the loop.
👻 Peekaboo: Enables your IDE to make screenshots and ask questions about images. For example: “Is this settings screen blank? Does the button look enabled?” This is a step towards visual self-correction.
🐱 Conduit: Advanced file manipulation for faster refactoring. Provides more robust and reliable file system operations (creating directories, moving files, bulk reading/writing) than what the AI might try with basic terminal commands.
🤖 Terminator: Manages a Terminal outside of the loop, so processes that might get stuck don’t break the loop. Crucial for web development. If the AI needs to run a dev server (npm run dev), this MCP runs it in a properly detached, non-blocking external shell. This prevents the main AI generation loop from getting stuck waiting for a server process that never exits on its own.
🎯 Automator: AppleScript for your IDE.

These MCPs are about extending the AI’s reach and making it more autonomous in a practical development workflow.

Choosing Your Fighter – AI Models in Cursor: Cursor offers a selection of underlying LLMs, and I switch between them based on the task:

Gemini 2.5 Pro (May 6 Update): This is my workhorse for most code generation within Cursor. It strikes a great balance of intelligence, speed, and cost.
o3: This is what I call my “Dark Knight.” It’s incredibly smart, uncannily good at reasoning through complex problems, but it’s significantly more expensive. I reserve o3 for when I’m truly stumped on a gnarly bug. You feed it the problem, and it often goes silent for a bit, “planning its next moves,” reading more of your codebase, and then, like that brilliant but slightly arrogant senior dev, it’ll often just present the solution with minimal fuss. It almost always cracks the problem.
Claude Opus: Also very capable. I find it sometimes a bit more prone to “vision quests” – deviating from the original task if it hits a snag, or getting stuck in its own reasoning loops (like repeatedly trying to downgrade a library if it encounters an issue with a newer version). But for certain types of refactoring or generation, it’s excellent.

During the initial generation, the Mac app (SwiftUI) ran into some turbulence. Swift 6 has tightened up its concurrency rules considerably (Sendability, @MainActor isolation), and there’s simply less Swift 6 example code out in the wild for the models to have trained on. This meant more iteration was needed. The Electron app, on the other hand, initially started life as JavaScript because, in my haste, I forgot to explicitly re-state TypeScript in the main project generation prompt (the spec mentioned it, but the top-level instruction to the AI didn’t). A good lesson: be explicit, even if it feels redundant. I later instructed it to convert the whole thing to TypeScript.

Phase 3: The Intricate Dance of Debugging, Refinement, and Iteration

This is where “vibe coding” truly comes alive. The AI isn’t a magic wand that spits out perfect, production-ready code on the first try. Far from it. The initial output will have bugs, missing pieces, UI that needs a loving touch (or a complete overhaul), and architectural decisions you might want to revisit. The beauty is how fast you can iterate with AI as your partner.

Navigating the Unscripted Path – Workshop Highlights:

Taming Xcode’s Beast (The .pbxproj file): Xcode project files are notoriously complex. Rather than having the AI in Cursor wrestle with directly manipulating that XML monstrosity, I took a different route for the Swift app. I opened a separate terminal window and used my claude-code-mcp to have Claude Code set up the project using Tuist. Tuist is a fantastic open-source tool that generates Xcode projects from a much simpler Swift-based manifest file and a conventional folder structure. I even pointed Claude to another project of mine that already uses Tuist, essentially saying, “Use this as a template.” This is a great example of using the right tool (and AI) for the right job.
Icons, Because Aesthetics Matter (Eventually): While the AI was churning, I popped over to an image generation model (like DALL-E, accessible through ChatGPT or other interfaces) and prompted it for app icon ideas: “Vibe Meter, cost control app, macOS, cool, modern.” Then, more specifically for the menu bar: “Monochrome, tintable, simple lines, Mac OS menu bar icon for a cost tracking app.” Got some decent starting points.
Live Debugging – The Swift App’s Journey:
- The Main Actor Crash: Sure enough, the app crashed on first launch. The culprit? A UNUserNotificationCenter delegate callback was firing on a background thread, but trying to update UI or state that was (correctly) marked as @MainActor isolated. Classic Swift concurrency. I switched the active model in that Cursor chat to o3 (the Dark Knight!), fed it the crash log and a brief explanation, and o3, true to form, pinpointed the issue and applied the fix: judicious use of nonisolated on the delegate conformance and wrapping the UI-touching callback code in a Task { @MainActor in ... } block. Problem solved in minutes.
- Menu Bar Shenanigans: Initially, the menu bar displayed the text “Login Required” when not logged in, instead of our nice (placeholder) icon. A quick clarification to the AI sorted that.
- The Off-By-One API Bug: The API call to fetch the cost data was consistently returning an empty dataset or an error. This was a head-scratcher. By adding some logging and then carefully inspecting the JSON payload from Cursor’s actual web interface (using browser dev tools), we spotted it: our app was correctly getting the current month (e.g., May as 5), but the Cursor API expected months to be zero-indexed (so May should be 4). A classic off-by-one! I took screenshots of my logging output and the browser’s network inspector, pasted them into the chat, and explained the discrepancy. The AI got it immediately and adjusted the date calculation.
- UI Polish: The initial settings screen was… functional. A prompt like, “Make this settings screen look more like a native, clean macOS settings panel, using standard SwiftUI controls,” led to a much-improved version.
Live Debugging – The Electron App’s Adventure:
- Test Setup: Playwright tests were part of the spec, and the AI set them up, but they needed some initial nudging to run correctly.
- Styling Woes: The Electron settings screen was unstyled for a bit. “It looks like the CSS for the settings dialog isn’t loading correctly. Please investigate and fix.”
- Login Logic: Getting the web view in Electron to correctly capture the session cookie after a successful login and then trigger the necessary API calls required a few rounds of refinement.
My General AI Debugging & Refinement Workflow:
- Screenshots are Your Best Friend: Seriously, a picture (or a screenshot of a crash log/weird UI) is worth a thousand words to these multimodal AIs. They can often “see” the problem.
- Focused, Iterative Prompts: Instead of massive, multi-point requests, I tend to give short, focused instructions: “Fix this crash.” “Change the button color to blue.” “Refactor this function to be more readable.”
- Delegate Complex Refactors to Claude Code (CLI): For bigger tasks like adding linters (we integrated SwiftLint for Swift and ESLint/Prettier for the Electron app) or that big “JavaScript to TypeScript” conversion for the Electron app, I often switch to a terminal and let Claude Code handle it. It excels at these broader, codebase-wide transformations and tends to run for longer stretches without needing intervention.
- Embrace AI Self-Correction: Often, the AI will generate code and tests for that code. If the tests fail, and the AI understands the failure in relation to the spec it was given, it can often figure out the bug in its own generated code and fix it. This self-correction loop is powerful.

Throughout this three-hour whirlwind, I was an orchestrator, a prompter, a quality checker, and a debugger-by-proxy. I wrote zero lines of functional code myself. All the Swift, TypeScript, HTML, CSS, JSON configs – everything came from the AI, guided by my prompts and the initial spec.

The Outcome: Two (Mostly) Functional Apps and a Whole Lot of Vibe

So, after about three hours of intense, unscripted, AI-driven development, where did we land?

Vibe Meter (Mac - SwiftUI):
- It launched! The menu bar icon appeared (though we wrestled a bit to get the custom PNG to show consistently; sometimes it defaulted to text).
- Clicking it revealed my current (mocked, then actual) Cursor spending (e.g., “$895.72”) and my company name (“Amatøs Måchinå” – a little inside joke).
- The login flow worked: it presented a web view for Cursor’s login page, successfully captured the session cookie upon successful login, and securely stored it in the macOS keychain.
- It then correctly used that cookie to hit Cursor’s internal /me endpoint (to get my user details) and the getMonthlyInvoice endpoint.
- On refresh? A delightful “VIBE SYNCED ✨” message in the menu. That was pure AI flair, and I loved it.
- The settings screen was functional and looked decent after a few rounds of UI prompting: currency selection (PHP, EUR, USD all present!), spending limits, and a refresh interval.
- And yes, it correctly registered itself to launch at login.
Vibe Meter (Electron - TypeScript/React):
- This one was a bit further behind but definitely taking shape. It launched, and the basic React structure was there.
- Login was partially implemented, and the cookie capture was on its way.
- The settings screen existed but needed more UI love (some CSS wasn’t loading correctly when I last left it).
- It would need a bit more focused prompting to reach feature parity with the Mac app, but the foundation was solidly laid.

In total, the AIs probably generated something in the ballpark of 5,000 lines of Swift and around 2,000 lines of TypeScript, JavaScript (before conversion), HTML, and CSS, not to mention all the configuration files, test setups, and package manifests.

Key Takeaways & My Developing “Vibe Coding” Philosophy

This workshop wasn’t just about the Vibe Meter app itself; it was about demonstrating a way of working, a new “vibe” for software development. Here are my big takeaways, which are constantly evolving:

AI as a Force Multiplier, Not a Replacement: Let’s be clear: this isn’t about AI taking our jobs. It’s about giving us superpowers. The ability to explore ideas, build prototypes, and even flesh out significant features at 10x, 20x, or even greater speed is transformative. You become an architect, a guide, a refiner.
Code Becomes Cheaper, Iteration Becomes Faster: This is a profound mental shift. In the past, if I spent days crafting a feature, I’d be heavily invested in that code. Ripping it out or taking a completely different approach felt costly. Now? If an AI generates a component in 20 minutes and it’s not quite right, or I have a better idea, I can tell it to refactor it, or just scrap it and try again with a new prompt. The cost of experimentation plummets. This frees you to explore more avenues.
Focus Your Energy on the Hard Problems: You can delegate a huge amount of boilerplate, initial scaffolding, CRUD operations, or even well-defined, common features to the AI. This frees up your precious cognitive cycles to focus on the truly novel, complex, and differentiating aspects of your product – the parts that require deep human insight and creativity.
Accelerated Learning in Unfamiliar Territory: This is huge for me personally. I’m primarily a native developer. But with AI, I’ve been able to dive into web technologies like TypeScript, React, and Tailwind CSS much faster than I ever could have traditionally. The AI can explain concepts, generate example code, show best practices, and help debug my newbie mistakes. It’s like having an infinitely patient tutor.
The AI is Your “Brilliant but Quirky” Teammate: Think of the current generation of AI tools as incredibly knowledgeable, super-fast junior-to-mid-level developers who sometimes act like autistic savants. They can produce amazing work, have access to a vast corpus of knowledge, but they can also misunderstand requirements, hallucinate APIs that don’t exist, get stuck on seemingly simple things, or rigidly adhere to an incorrect assumption. Your job is to learn their strengths, weaknesses, and how to “manage” them effectively through clear prompting and iterative feedback.
Prompt Engineering is the New Core Skill: The quality of your interaction with the AI directly dictates the quality of the output. This isn’t just about typing a question; it’s about crafting clear, unambiguous specifications, providing good examples, giving constructive feedback, knowing when to break down a problem into smaller steps for the AI, and understanding how to guide its reasoning process.
Horses for Courses – Choosing Your AI Tools Wisely:
- Google AI Studio (with Gemini): My go-to for initial, comprehensive spec generation and refinement. That massive context window and less restrictive output format are invaluable for laying a strong foundation.
- Cursor IDE: Fantastic for the main development loop – iterative code generation, interactive debugging, and the ability to quickly switch between different AI models (like Gemini for speed/cost, and o3 for those really tough nuts to crack) within the context of your actual project files.
- Claude Code (Anthropic’s CLI tool): A powerhouse for large-scale, codebase-wide refactoring (like adding linters, converting languages, or enforcing style guides). It tends to be very thorough and can run for extended periods on a single, complex task.
The Power of Context Cannot Be Overstated: LLMs are all about their context window. The more relevant information you can feed them – detailed specs, existing code snippets, error messages, screenshots, links to relevant documentation or GitHub repositories – the better their output will be. This is why Gemini 1.5 Pro’s 1 million token window (and even larger ones on the horizon) are such game-changers.
Don’t Be Afraid to Explore the Obscure: Even if you’re working with a less common language or a niche problem, don’t assume AI can’t help. I showed a quick example of using a Repo-to-Text converter tool to dump an entire Zig language GitHub repository into a flat text file, which I then uploaded to AI Studio. Gemini was then able to explain the project’s purpose, its architecture, and even answer specific questions about the Zig code, all in pirate speak for a bit of fun!
Rethinking Cost vs. Value: Yes, these AI tools have a cost. As I mentioned, I’m spending around $1100 a month right now between Cursor, direct API access, and Claude subscriptions. But you have to weigh that against the value of your time and the sheer increase in output. If these tools allow me to build 10x or 20x more, or explore ideas that would have been too time-consuming before, the ROI is a no-brainer. Your time is valuable; AI helps you leverage it far more effectively.

The Future is Now – Go Vibe with It!

This is not some far-off future; this is what’s possible today. The tools are evolving at a dizzying pace. The way we conceive, design, and build software is undergoing a fundamental shift.

My advice? Don’t wait. Dive in. Pick a small side project, something fun. Start experimenting with these tools. Learn how to prompt, how to iterate, how to “vibe” with your AI coding partner. See for yourself how it can transform your workflow, your learning, and your creative output.

As for Vibe Meter? I’m definitely going to take the Mac app, polish it up (with more AI help, of course!), and integrate its core cost-tracking logic into my “CodeLooper” project. The cycle of AI-assisted creation continues.

Thanks for joining me on this live-coding adventure. Now, go build something cool!

MCP Best Practices

Sun, 1 Jun 2025 14:00:00 +0000

Building high-quality Model Context Protocol (MCP) tools requires attention to detail across many dimensions. After developing several MCP tools, I’ve compiled this comprehensive guide to best practices that ensure your tools are reliable, user-friendly, and maintainable.

My MCP Tools

Here are the MCP tools I’ve built following these practices:

👻 Peekaboo: Enables your IDE to make screenshots and ask questions about images.
🤖 Terminator: Manages a Terminal outside of the loop, so processes that might get stuck don’t break the loop.
🧠 Claude Code: A buddy for your IDE that your agent can ask if he’s stuck. Can do coding task and offer “a pair of fresh eyes” that often un-stucks the loop.
🐱 Conduit: Advanced file manipulation for faster refactoring.
🎯 Automator: AppleScript for your IDE.

I. General Tool Configuration & Behavior

Sensible Defaults

All environment variables must have sensible defaults for easy out-of-the-box usage. Users should be able to get started without extensive configuration.

Dynamic Versioning

The tool’s version is emitted in its description. This version must be read dynamically (e.g., from package.json) and not hardcoded. This ensures version consistency and eliminates manual update errors.

Tool & Parameter Descriptions

Tool Titles: Use descriptive, human-friendly titles for tools
Parameter Descriptions: All parameters must offer a clear description
Optional/Required Parameters: Parameters must be explicitly noted as “optional” or “required”
Default Values: If a parameter is optional, its default value must be explained

These details should be verifiable by hovering over the tool in clients like Cursor or using the MCP inspector.

Parameter Parsing

Parameter parsing should be lenient (e.g., accept path if project_path is formally defined). Generally, advertise stricter schemas but be more lenient in execution to accommodate variations from agents.

Error Handling

Runtime Error Handling: In case of an error, emit a helpful message to the caller with information to potentially recover
Configuration Error Handling: Misconfigurations (e.g., wrongly set environment variables) must not crash the tool. Instead, provide a useful explanation when the tool is run, enabling the user to self-correct their setup

Output Control

There should be no output to stdio during normal tool operation, as this can disrupt MCP clients. File-based logging is the designated method for operational output.

The `info` Command

At least one tool must offer an info sub command. This command shall list:

The version of the MCP tool
The status of any required native dependencies (if applicable), including tests for their presence and functionality
Any detected configuration issues or missing environment variables (e.g., problems with the logger path)

II. Logging (Pino)

Default File Logger

Pino is used for logging with a default file logger in the system’s log directory (e.g., ~/Library/Logs/). The log file path is configurable via the [ProjectName]_LOG_FILE environment variable.

Log Path Resilience

Pino logic must automatically create missing parent directories for the specified log file path
If pino cannot write to the [ProjectName]_LOG_FILE path, it must fall back to logging to the default temporary directory path

Configuration

Configurable Log Level: The log level is set using the [ProjectName]_LOG_LEVEL environment variable (accepts upper, lower, or mixed case values)
Optional Console Logging: An environment variable, [ProjectName]_CONSOLE_LOGGING=true, enables logging to the console in addition to the pino file logger
Logger Flush: The logger must be flushed before the process exits to ensure all log messages are written

III. Code, Dependencies & Build

Code Quality Standards

Dependency Management: All dependencies should be kept at their latest stable versions. The release script will warn for outdated dependencies
Static Analysis: There must be no linter (e.g., ESLint) or TypeScript errors
File Size: No single file should exceed 500 lines of code (LOC); aim for below 300 LOC

Build Configuration

Execution with Compiled Code: The startup logic and all tool operations must always use the compiled JavaScript output (e.g., from the dist folder)
Shebangs: Compiled JavaScript files intended for direct execution must have the correct shebang (e.g., #!/usr/bin/env node)
NPM Package Contents: The published npm package must contain only the absolute minimum files: the dist/ folder, any potential native components, the README.md, and a LICENSE file

IV. Testing

Test Framework

Tests must use vitest for consistency and modern testing capabilities.

Test Coverage

TypeScript Test Suite: A comprehensive test suite for the TypeScript layer is required
End-to-End (E2E) Tests: E2E tests that validate the complete setup are necessary. These might be run as release preparation if CI execution is challenging due to permissions like macOS access

NPM Scripts

npm run prepare-release executes a comprehensive test suite (detailed in Section VI)
npm run inspector executes npx @modelcontextprotocol/inspector node path/to/server/index.js

V. Native Binary Rules (If Applicable)

Platform Compatibility

macOS Compatibility: The binary must be universal (Apple Silicon & Intel) and support the current macOS version and the previous major version (n-1, e.g., macOS >= 14 if current is 15)
Build Optimization: Compiler and linker flags must be set to achieve a minimal binary file size

Native Code Quality

Native Test Suite: A comprehensive test suite using Swift’s native testing tools (e.g., swift-test or XCTest) is required
The CLI must have no linter issues (e.g., SwiftLint for Swift)
A formatter must be applied (e.g., SwiftFormat for Swift)
The CLI must show no analyzer issues

Integration Requirements

Custom Path Configuration: An environment variable must allow setting a custom absolute path to run the native binary
Error Communication: If the tool uses a native library, errno (or an equivalent mechanism) must be used to pass error and execution issues to the TypeScript logger and back to the tool
Version Synchronization: The native CLI and the MCP tool (TypeScript package) must have the same version number. This version must be injected during the build process, not hardcoded

Communication Protocol

JSON Communication: The native binary part of the tool must have a mode to communicate in JSON back to the TypeScript server for easier parsing. JSON responses should include debug logs if requested
CLI Help Command: The binary must respond to --help with a helpful command explaining its use and all options
Argument Parsing Framework: The binary must use a robust argument parser framework (e.g., swift-argument-parser for Swift)

Distribution

Consider options for distributing as a single, statically linked binary if feasible and beneficial for simpler installation by end-users who might use the CLI directly.

VI. Rules to Check Before a Release (`scripts/prepare-release.js`)

There is a scripts/prepare-release.js that runs an extensive test suite. The script runs these checks sequentially and stops at the first failure.

Git & Version Control

Check current branch (warns if not on main or designated release branch)
Check for uncommitted changes
Check if synced with origin/main (or designated release branch)
Version availability check (ensures version isn’t already published)
Version consistency between package.json and package-lock.json
Changelog Check: Check for a changelog entry corresponding to the current version

Code Quality & Security

Dependency installation check
Outdated dependencies check (warning only)
Security audit (fails on critical/high vulnerabilities)
TypeScript compilation
TypeScript tests
TypeScript declaration files generation
Delete any build folders and reset package caches before building
If native binary exists: Swift analyze
If native binary exists: Swift formatting (SwiftFormat)
If native binary exists: Swift linting (SwiftLint)
If native binary exists: Swift tests
No build warnings

Binary & CLI Validation (If Applicable)

If native binary exists: Swift CLI command tests (help, version, and other key functionalities)
If native binary exists: Swift CLI error handling tests (invalid commands, missing args, invalid window index, etc.)
If native binary exists: Swift CLI JSON output validation
If native binary exists: Binary exists and is executable
If native binary exists: Binary contains both architectures (arm64 + x86_64, verifiable via lipo -info)
If native binary exists: Binary responds correctly to --help

Package Validation

Required fields in package.json
Package size check (warns if >2MB, configurable threshold)
Executable permission check in postinstall (if a CLI is present)
Critical files included (e.g., dist/index.js, native binary name, README.md, LICENSE)
MCP server smoke test (JSON-RPC request/response)
Full integration tests

Beta Release Strategy

Releases are first done with a beta tag to the npm registry so they can be tested via the npx [packageName]@beta install method.

Conclusion

Following these best practices ensures that your MCP tools are professional, reliable, and user-friendly. They represent lessons learned from real-world development and deployment of production MCP tools. As the MCP ecosystem evolves, these practices will continue to be refined and expanded.

Finding My Spark Again

Sun, 1 Jun 2025 13:00:00 +0000

We are so back 🚀

— Peter Steinberger (@steipete) November 20, 2024

When I sold my shares of PSPDFKit after building the company and making it my identity for over 13 years, I was very broken. I’ve been pouring 200% of my time, energy, and heart’s blood into this company, and towards the end, I just felt that I needed a break. We’ve been very lucky to have found an amazing company with Insight, that acquired the majority.

The Emptiness After

For me though, I felt like I missed out on life. A lot of my normie friends had fun every weekend while I was just crushing and pushing and churning through building the best product I can possibly do. And once it fell away, there was not much left.

I heard it’s common for founders to fall into a hole and to take a year off after they move on from their company. A typical company life cycle is also 4-5 years. So after 13 years in retrospect, I can see how it just needed more time to find a new purpose.

Searching for Meaning

I did a lot of stuff, I partied hard, I did plenty of therapy, I did ayahuasca, I moved to another country, I wandered around carrying this emptiness in me and hunting hedonic pleasures. And then a few months ago, something clicked. I had enough of my own bullshit, and I realized that you don’t find happiness by moving countries. You don’t find purpose. You create it.

The Spark Returns

Creating things out of ideas, building was always the thing that gave me the most joy in life. One day, things just clicked. I had a new idea, I sat on my computer and started hacking, and I realized that my spark is back.

Right now, we are at an incredible crossroads in technology. AI is moving so fast and is changing the way we work in software development, but furthermore, it’s going to change the world. I haven’t been as excited, astounded, and amazed by any technology in a very long time.

We are so back. It’s time to build.