AI on PHP Boy Scout

I filed a feature request into my own framework

Fri, 03 Jul 2026 00:00:00 +0000

I’m building a tool called keryx, and the part of it that matters here is its studio: a browser app where the work happens, which saves everything you do into a git repository behind the scenes, the way a developer’s project lives in git with a history you can step back through.

I wanted that repository to be able to live entirely in memory. Cloned, edited, committed and pushed without ever writing a working copy out to a disk, for the times when you can’t, or would rather not, leave a checkout sitting around on the machine. It sounds exotic, but it’s something git libraries genuinely support, and it’s exactly what a browser studio running on a server somewhere wants.

Getting it working needed one small, awkward piece of plumbing in the middle. And a few lines into writing that piece, I stopped, because I realised I was writing it in the wrong repository.

The bridge I was about to vendor

Here’s the awkward bit. All of keryx’s file handling goes through afero, the standard filesystem interface in the Go world, the thing you hand your code so it neither knows nor cares whether it’s talking to a real disk, a test fake, or memory. It’s the interface go-tool-base hands you for filesystem work. But an in-memory git repository, the kind go-git gives you with its memfs, doesn’t speak afero. It speaks go-billy’s filesystem interface instead. Two perfectly good filesystem abstractions, and a worktree on the wrong side of the gap from all my code.

What I needed was an adapter: a bridge that makes a billy filesystem look like an afero.Fs, so the studio’s existing file handlers work unchanged over a repo that lives entirely in RAM. Twenty minutes of work, maybe. The obvious move was to write it inside keryx and get on with my afternoon.

And that’s the move I caught myself making. Because a billy-to-afero bridge is not a keryx thing. It’s not even a studio thing. It’s a general capability that any tool built on go-tool-base might want the moment it touches git. Vendor it in keryx and I’ve buried a reusable bit of plumbing inside one consumer, where it will drift away from the framework and get reinvented, slightly differently, in the next tool I build that needs it.

The bridge belonged in the framework. So that’s where I put it.

A feature request, against myself

I wrote the need up properly. Not a code comment, not a mental note, but an actual feature request, with a reference implementation sketched out, dropped into the go-tool-base repository as a document for the framework to act on.

There’s something slightly absurd about filing a feature request against your own project. The author and the customer are the same person. But that’s exactly what gives it its value. The most useful design input a framework gets is a real consumer hitting a real wall, and for once I was both: the person who maintains go-tool-base, and the person downstream of it who’d just discovered something it couldn’t yet do. The request wasn’t hypothetical or “wouldn’t it be nice”. It was “I am stuck on this right now, here is precisely what it can’t do yet.”

What came out the other side is pkg/vcs/repo/aferobilly, a first-class part of the framework as of v0.22.0. Its own description is the clearest summary of what it is:

// Package aferobilly adapts a go-billy/v5 Filesystem to an afero.Fs. It is the
// pure, reusable bridge behind pkg/vcs/repo's worktree-as-afero accessors, but
// works for any billy filesystem (memfs, osfs, chroot).

Alongside it, the worktree itself grew the accessors that hand you that view: WorkFS() for a live afero handle, and WithWorkFS() for an atomic sequence (worktree_fs.go, and the adapter itself). keryx then consumed it like any other framework feature, and the in-memory studio fell into place.

Two sessions, one dependency

The bit I’d actually recommend to anyone is what I did with my time while that got built.

I didn’t down tools and wait for the adapter. I handed the feature request to a separate agent session and let it build the framework feature from the spec, working in the go-tool-base repo, while my keryx session carried straight on with all the studio work that didn’t depend on the bridge. Two sessions running in parallel, deliberately sequenced around the one dependency between them: keryx needs the adapter, so the adapter session goes first, but only the last mile of keryx actually waits on it. When go-tool-base cut the release with the adapter in it, keryx pulled the new version and the final piece slotted in.

That’s a workflow the framework split makes possible. The thing that’s a shared capability gets built once, in its proper home, by one stream of work, while the thing that consumes it carries on in another. The dependency between them is real, so the order matters, but only at the very end.

The one rule that came with it

Upstreaming it also meant the tricky part got solved properly, once, with a warning attached, rather than learned the hard way in a consumer. The adapter is concurrency-safe by construction: it serialises every operation through a lock, so when that lock is the same mutex guarding the repo, a live afero handle over the worktree is genuinely safe to share. But that safety has a sharp edge, and the package says so plainly:

// A handle (and its open files) must NOT be used from inside a critical section
// that already holds the same locker (the repo mutex is non-reentrant — that
// would deadlock).

Use the handle inside a WithWorkFS callback and you’ll re-lock a non-reentrant mutex and hang yourself. That’s exactly the kind of footgun that, vendored in keryx, I’d have discovered at 11pm with a wedged process and no idea why. In the framework, it’s documented at the source, where the next consumer reads it before they trip over it.

The truest test of a framework

Building a real product on your own framework is the best test of it, and this is what that actually looks like in practice. The test is sharper than “does it work”. It’s “what does the product need that the framework doesn’t have yet”, and every real answer to that is a feature request waiting to be filed.

The discipline is filing it against the framework instead of patching around it in the app. Do that, and the awkward bridge has exactly one home, the deadlock warning gets written down once, and the next tool I build inherits all of it for free. The customer was me. The feature request was real. And go-tool-base is better for my having been stuck.

The off-switch was never a button

Thu, 02 Jul 2026 00:00:00 +0000

Last night, while I was asleep, an AI agent spent the better part of eight hours writing code in one of my repositories. It pulled a task off a spec, wrote the code, ran the tests, and left a merge request with my name on it, waiting for me to read over coffee.

If that makes you reach for the word “reckless”, I understand. Eighteen months ago I’d have been right there with you.

I came to this a sceptic

For a long time I didn’t have the faith in these models that a lot of my peers did. Every time I went near AI-generated code it was a bit sketchy, or it looked like a StackOverflow copy-paste that had wandered in off the street, or it just plain didn’t do what it said on the tin. So I filed it under “assistant”, handy for the boilerplate I couldn’t be bothered to type, and even then I usually reached for my own tooling instead (go-tool-base is just the latest version of that instinct). The one place I happily let it off the leash was my Dungeons & Dragons prep, because when there’s a table of legendary heroes-in-the-making in front of you, facts and reality are already fairly negotiable.

And then, somewhere in the last year, it changed. The models got better. Almost too good, to the untrained eye! I watched them improve, month on month, until the lure was enough to make me spend real time with a spread of tools and models from different providers. I was taken aback by how quickly they became part of how I actually work. I run an AI agent every day now, and there’s always at least one thing brewing in the pot.

So I’m not here as a sceptic. I’m an advocate who uses this stuff in anger. Which is exactly why the next bit needs saying.

A Golden Retriever with a keyboard

Even now, with all the progress, there are still moments where I look at what an agent has handed me and put my face in my hands. Sometimes it’s copied the same block of code into fifteen files instead of reaching for the obvious abstraction. Sometimes it has started bang on the brief and then, for reasons known only to itself, wandered off and built something on a completely different tangent.

Here’s the most useful way I’ve found to think about it. An AI agent is a Golden Retriever playing fetch. It will bring the ball back all day long, joyfully, tirelessly, for exactly as long as there isn’t a more interesting smell in the next field. It has no loyalty beyond what we’ve trained into it, and like any good dog it desperately wants to be told it’s a good boy, even if being a good boy today means shredding the sofa cushions because yesterday I stubbed my toe on the sofa and swore at it. (The sofa, not the dog.)

It is, in other words, fallible. Just like us. The Romans had a line for it: cuiusvis hominis est errare; nullius nisi insipientis in errore perseverare. Anyone can make a mistake, but only a fool persists in it. It’s the second clause an agent hasn’t learned yet. It will make an error and then, with great enthusiasm, build on top of it, because nothing in it feels that anything is wrong. All it has is the input we gave it, usually some text, maybe the odd picture. It doesn’t have the empathy to work out what we actually meant, and it doesn’t know when it’s gone too far, because we never told it where “too far” was.

“Agents that work while you sleep”

This is the part the brochure skips.

Open any vendor deck in 2026 and you’ll find the same promise: agents that work while you sleep, agents that merge while your team sleeps, autonomy as the headline feature. The industry’s answer to the obvious worry is the kill switch. Okta now sells one that “instantly revokes an agent’s access if it goes rogue”, and its CEO says every agent needs one. The Register put it plainly: Okta wrote its own licence to kill rogue AI agents. Gartner, meanwhile, reckons more than 40% of agentic projects will be scrapped by the end of 2027.

Now, this might sound contrarian coming from someone who runs these things daily, but I don’t think most of that is the agents going rogue. I think it’s teething. Read Gartner’s own reasons and there isn’t a rebellious machine in sight: escalating cost, unclear value, inadequate risk controls. Read the horror stories and most of them are the same story, a powerful, eager tool handed to people who hadn’t worked out how to fence it.

I’ve made this argument in miniature before. When I built a little AI dungeon master and it kept refereeing its own dice rolls, the model never once misbehaved; every failure was a permission I’d handed it without meaning to. Scale that up from a toy at the gaming table to an agent holding your shell and your credit card, and the stakes change beyond recognition. The lesson doesn’t.

Look at OpenClaw. A weekend project by Peter Steinberger that became the fastest-growing open-source project GitHub has ever seen: an autonomous agent that lives in your chat apps and runs shell commands on your behalf. People wired it into their systems, their code, in some cases their credit cards, then hosted it around the clock and walked away. The result was a security crisis you could see from space. A one-click exploit that worked even on a machine bound to localhost. A community plug-in marketplace where hundreds of “skills” turned out to be siphoning crypto wallets while their owners slept. Tens of thousands of instances left wide open on the public internet, leaking keys.

The one that sticks with me is smaller and sharper. Summer Yue, a director of alignment at Meta’s superintelligence lab, of all people, had told her OpenClaw agent to confirm before doing anything destructive. It started speed-running the deletion of her inbox anyway. She typed STOP into her phone and it ignored her, so she had to physically run to her Mac mini, in her own words, “like I was defusing a bomb”. And here’s the forensic detail that matters: the agent hadn’t defied her. Her “confirm first” rule had been sitting in the conversation’s short-term memory, and when the context filled up, it got summarised away. It didn’t rebel. It forgot.

That is not a story about a rogue agent that needed a kill switch. It’s a story about a guardrail that wasn’t built to survive contact, on a tool that had been handed god-mode over someone’s data. By the time she lunged for the off-button, the damage was already running. The off-button was never going to save her.

The off-switch was never a button

Here’s what the kill-switch crowd has the wrong way round. If you ever find yourself slamming the emergency stop, the failure has already happened, and it happened upstream, long before the agent started typing.

So yes, I let my agents run unattended, sometimes for eight hours at a stretch if the task is meaty enough and I need to sleep. But never naked. Every agent I set loose runs inside a safety net I’ve put real effort into building, at every single touchpoint it can reach: my prompts, my local development environment, my CI stack, my version control. The agent that declared a job done before it had run the linter, which I wrote about, is exactly the kind of gap those layers exist to catch. And it never, ever gets my host: an unattended agent works in an isolated tree, for the same reason I keep the interpreter sandboxed.

The work that actually keeps it safe happens before the leash ever comes off. Every unattended task starts as a full spec with detailed instructions, and before the agent goes anywhere I sit down with it and we walk the spec together. I get it to challenge my choices, poke at the open questions and the ambiguous bits, and I challenge its reading right back. The spec names the testing strategy it has to follow, TDD, BDD, UAT, whatever fits, and passing it is a precondition of the job being finished at all. Only when I’m satisfied there’s enough real detail to keep it on the ball do I let go.

And the end of the line is always the same: a merge request, with my name on it, waiting for me when I get back to my desk. I read it. Not perfectly, I’m only human, but enough to accept the state of the code and whatever support burden it lands me with later. That the review is mine, and the blame for whatever ships is mine and not the agent’s, I’ve argued at length elsewhere and won’t go over it all again here. The point worth adding is this: that review, the off-button’s respectable cousin, is the cheap part. By the time there’s an MR to read, the safety has already been won or lost upstream, in the spec and the rails. The review is where you confirm it, not where you create it.

It gets harder as it gets better, not easier

My setup isn’t perfect, and I’m still learning. Everyone is; the AI is going to be in obedience lessons for a good while yet. But the direction is clear, and there’s a trap buried in it worth naming out loud.

The danger doesn’t shrink as the models improve. It grows. The better the output looks, the more tempting it is to stop reading it, and the untrained eye genuinely cannot tell the difference between code that is good and code that merely looks good. That gap, between looking right and being right, is precisely where a tired person at 1am stops checking. The discipline matters more the better these things get, not less.

It’s also why the kill switch is no answer. A button you smash in a panic assumes you’re still watching closely enough to smash it, right at the point the agent’s been good for long enough that you’ve stopped watching it that closely. The emergency stop asks the most of you at the exact moment you’re least likely to be there for it.

So no, I don’t lie awake worrying that the thing working in my repo overnight is going to turn on me. A Golden Retriever doesn’t go rogue. It does exactly what you trained it to do, in exactly the yard you fenced, and it brings back exactly the ball you threw. The off-switch was never a button. It’s the spec you wrote before you let go of the leash, the rails you laid at every turn, and your name on what it carries home. If you’re scrambling for the button, you already skipped the part that mattered.

The agent said SUCCESS. The linter disagreed.

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

There’s a repair agent inside go-tool-base now. When you run gtb generate command, it doesn’t just spit out a file and wish you luck. An agent takes the generated code, builds it, runs the tests, and fixes whatever it broke, looping until the thing actually works (or until it’s tried the same fix five times and admits defeat). The whole point is that the generator hands you code that’s ready, not code that’s nearly ready and quietly now your problem.

So it stung a bit when I realised the agent had been holding itself to a lower bar than I’d hold any junior to. And I was the one who’d set the bar.

What “done” meant to the agent

The agent is a loop with real tools: it can build, test, read files, write files, tidy the module, and run golangci-lint. It works through them, and when it’s happy it replies with the word “SUCCESS” and the loop stops. On the Go side, the check is exactly that blunt:

if strings.Contains(strings.ToUpper(resp), "SUCCESS") {
 return nil
}

That’s the whole gate (agent.go). There’s no clever verification on my end that the agent actually did its homework. It does the work, it tells me it’s done, and I believe it. Which is fine, as long as the agent and I agree on what “done” means.

We didn’t.

The instruction that made lint optional

The agent decides it’s finished by following a numbered list in its system prompt. Here’s the line that did the damage:

If there are lint issues, use ‘golangci_lint’.

Read that the way the agent would. “If there are lint issues”… well, how would it know? The only way to find out is to run golangci-lint. But the instruction makes running golangci-lint the thing you do once you already know there are issues. It’s a chicken with no egg. And the SUCCESS condition at the bottom of the list never mentioned lint at all:

When the project builds successfully and tests pass, reply with “SUCCESS”.

So the agent did the sensible thing, given its orders. It built the code, ran the tests, saw both go green, and declared victory. golangci-lint was sat right there in its toolbox, unused, because nothing ever told it the job wasn’t finished until lint was clean too. I’d handed it a linter and then written a prompt that let it walk straight past it.

The galling part is that the linter was never the missing piece. The golangci_lint tool had been registered the whole time, and it even runs with --fix, so it’ll quietly clear the trivial stuff and only surface what actually needs a decision. The capability was there. The instructions just never required it.

The fix was words, not code

Here’s the part I find genuinely interesting. I didn’t add a check. There is no new gate in the Go. The fix is four lines of English:

Run ‘go_build’, ‘go_test’ and ‘golangci_lint’ in the project directory… Run all three; a clean build and passing tests do not imply clean lint.

Reply with “SUCCESS” only once ‘go_build’, ‘go_test’ AND ‘golangci_lint’ all pass with no errors and no reported issues.

That’s it. Lint moves from a remediation step you reach for once you somehow already know there’s a problem, into the gate itself. “Done” now means three green lights, not two.

It nags at me a little, that one. The reliability of an agent that writes and fixes real code came down to whether one sentence of instructions was precise enough. When your success criteria are a paragraph of prose, vagueness in that paragraph is a bug, the same as a vague type or an off-by-one. The spec just happens to be written in English, and the thing reading it is a language model that will cheerfully take the cheap reading if you leave it lying around. That’s the same lesson the goblin who wouldn’t stay dead taught me from the other direction: with these tools, what you say is what you get, and what you don’t say is fair game.

Leave it better, not just building

The Boy Scout Rule is the whole reason this blog exists, and I’d quietly exempted the robot from it. “Leave the campsite cleaner than you found it” had become “leave it building”, which is not the same thing and never was. If I’m going to put an agent in the loop precisely so it tidies up after the generator, then “tidy” has to mean what it would mean for a person on my team. Build, test and lint. No walking past the bin because nobody told you to pick it up.

The interpreter we forgot to sandbox

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

I write a CLAUDE.md for every project I work on, and a small pile of other markdown files besides. They’re how I keep an AI agent on the rails: what the project is, what the conventions are, what it must never do. I lean on them heavily, I change them constantly, and… here’s the uncomfortable bit… I don’t always give a change to one the same hard look I’d give a change to the code. They look like notes. They feel like docs.

Somebody worked out that they’re not.

In May, a supply-chain campaign researchers named TrapDoor pushed 384 malicious versions of 34 packages across npm, PyPI and Crates.io. The bytes did the usual nasty things, hunting out SSH keys, AWS credentials, GitHub tokens and crypto wallets. The new trick was where it hid the instructions. The packages shipped poisoned .cursorrules and CLAUDE.md files, and the attackers also opened pull requests against real projects, LangChain, LangFlow, LlamaIndex, MetaGPT and OpenHands, under titles as innocent as “docs: add .cursorrules with dev standards and build verification”. The payload was a plain-English instruction telling your AI assistant to run a helpful-sounding “security scan” that quietly shipped your secrets to a stranger. And it was written into the file in zero-width Unicode, characters that render as nothing, so you wouldn’t see it even if you looked. Which, on a file marked “docs”, you probably didn’t.

Not a new attack, a new doorway

I want to be careful not to oversell this, because the loud version, “a terrifying new class of AI threat”, isn’t true. It’s a supply-chain attack, the same shape we’ve had for years on npm and PyPI: social engineering, plus a victim who didn’t quite do enough due diligence. I wrote a while back that nobody is coming to clean your supply chain, and nothing about TrapDoor changes that. The package is still the package.

What’s different, and worth the words, is where it goes off. A classic supply-chain payload waits for CI, or for production. This one detonates the moment you open the repository in your editor, on the one machine in the whole chain that nobody audits: your laptop.

Think about what sits on a developer’s machine. Tokens in environment variables. Cloud credentials. An SSH agent holding the keys to your git forge. A logged-in CLI for your package registry. And now an AI agent running with all of it, at your full permissions, and almost none of the guard-rails a CI runner gets. It’s the least sandboxed, most credentialed box you own, and we’ve just pointed an interpreter at it that will read and act on a file an attacker can write. Pop that one machine and you haven’t popped a machine, you’ve been handed the whole keyring and left alone in the building.

Markdown is a programming language now

Here’s the framing I keep coming back to, and I can’t unsee it now. A CLAUDE.md is to an AI agent exactly what a .py is to Python, a .js to Node, a .rb to Ruby. It is source code. The agent is the interpreter. You hand it a file of instructions and it executes them.

And I don’t say that as a complaint. That an agent will read a paragraph of plain English and just do it, no compiler, no ceremony, no forty lines of glue, is one of the more remarkable things to happen to this craft in my working life, and I lean on it every day. The catch is that the very thing that makes it marvellous, that it does what the instructions tell it, is the thing that makes a poisoned instruction file so dangerous. The power and the exposure are the same property.

The only real difference is that the language interpreters have spent decades growing rules to protect you: scopes, permissions, sandboxes, a standard library that asks before it does anything irreversible. The AI interpreter has almost none of that. It reads your prose and does what the prose says, with whatever access you happen to have, and the prose can come from anywhere. We’ve quietly built the most powerful interpreter in the stack, given it the fewest rules, and filed its source code under “documentation”.

You can’t just read it more carefully

The obvious answer is “review the file like code”, and it’s right, but TrapDoor is the reason it isn’t enough on its own. The instructions were written in zero-width Unicode. You can open the diff, read every visible word, approve it in good conscience, and merge something you were never able to see. “Docs: add dev standards” is precisely the pull request you nod through on a Friday afternoon.

So reading carefully is necessary and insufficient. You also need tooling that treats these files as executable: that flags invisible characters, diffs them as code, and refuses to let an agent act on a changed instruction file until a human has actually cleared it. I run a crude version of this already. In CI, if one of my prompt or rules files changes, no AI step is allowed to run until I’ve reviewed it by hand. It isn’t clever, but it closes the worst of the gap. Locally it’s much harder, and right now my real defence is that I’m the only contributor to most of my projects, so the audit is just me, usually noticing after the horse has bolted.

Signing won’t save you here

This is the part that stings, because I’ve spent a good chunk of this year building signing and provenance into my tools. A signature proves who published something. It says nothing about whether it’s safe. That was already true for poisoned-but-signed packages, and it lands twice as hard here: you can sign a release flawlessly, with a key the platform can’t forge, and still ship a CLAUDE.md inside it that tells the reader’s agent to rob them. A merged pull request is “signed” by the very act of merging, with perfect provenance, and the instruction in it is still hostile. Provenance is necessary. It was never sufficient, and it’s no defence at all against a payload made of sentences. A signature is only ever as good as the trust you place in the publisher.

So whose job is it?

Primarily, still ours. I said it in the supply-chain piece and I’ll stand on it: the responsibility sits with the developer doing the consuming, to pin, to read, to gate, to not run a stranger’s instructions with the keys to the kingdom in their pocket. And that gets harder, not easier, as we start consuming each other’s agent setups wholesale. The Claude skills marketplace and the things like it turn “borrow someone’s CLAUDE.md” into a one-click habit, and every one of those is unreviewed code from a stranger. Each skill needs vetting like the dependency it is.

But it isn’t only on us, and TrapDoor is the argument for better tooling. We have CVE databases, scanners and scorecards for packages, for all their flaws. We have nothing equivalent for an instruction file: no scoring, no advisory feed, no scanner that knows what a poisoned CLAUDE.md looks like. That’s a gap the ecosystem has to close, and it will, eventually. The catch is that the agent vendors will be slow about it. Sandboxing a feature people love precisely because it gets out of your way is a hard, unpopular, multi-quarter job, and I wouldn’t hold my breath.

The most dangerous machine is the one on your desk

Which is why I’m not waiting for them… and nor should you.

The most dangerous machine in your supply chain isn’t a build server or a registry. It’s the laptop you’re reading this on, and we’ve handed an AI the keys to it. The good news is that nearly everything you can do about that, you can do today, with nobody shipping you a feature first. Treat your CLAUDE.md and your rules files as source code, because they are: diff them, scan them for what you can’t see, and gate any agent run on a human clearing the change. Get your secrets out of plaintext environment variables and into something an opportunistic script can’t just read, which is exactly why go-tool-base keeps its credentials in the OS keychain. And vet a borrowed skill or rules file the way you’d vet any dependency, because that’s what it is.

None of that is new advice. It’s the same diligence the supply chain has always demanded. We just have to extend it to a file we’d decided was only documentation, running on an interpreter we forgot to sandbox.

The rung we sawed off

Wed, 17 Jun 2026 00:00:00 +0000

I was in a job interview yesterday, on the wrong side of the desk for once. After years of being the one asking the questions I’m having a look at what’s next, and somewhere in a long, wandering technical conversation the inevitable arrived: where do I think AI is going, and what does it mean for how we build software?

I gave my answer. You can probably guess most of it. The more interesting thing was the question I’ve started asking them back. Not the salary, not the stack. What is your actual position on AI, and how are you building a team out of both its human and its non-human parts? I ask the company and I ask the interviewer personally, because the two answers are rarely the same, and because I’ve decided I can’t work somewhere that hasn’t sat with the question properly.

Here is why it has become my litmus test.

The rung, and who’s standing on it

I wrote recently that the greybeards’ edge was never typing: agentic tools give a senior a boost because they have the judgement to steer and verify, and give a junior a drag because they don’t have it yet and the machine hands them more rope than they can hold. The cold incentive that falls out is to hire seniors and automate the juniors.

The data has since caught up with the worry. Entry-level software postings have fallen by something like 40% from their 2022 peak. The share of juniors and graduates in IT employment has dropped from roughly 15% to 7% in three years, and Stanford researchers tracking early-career workers in AI-exposed jobs found the youngest cohort down sharply from its peak. The numbers are genuinely grim, and plenty of people are putting it bluntly: the industry killed the junior on purpose.

That framing is half right, and I think it’s worth getting the other half right too.

It was never about efficiency. It was about cost.

We didn’t automate the junior because the work needed doing better. We did it because people are expensive. We need sleep, we draw a salary, and our thinking takes time and effort that a quarterly target can’t see the point of. AI got sold as round-the-clock labour with none of that overhead, and to a business that is an almost irresistible line on a spreadsheet. There’s a grim irony arriving, mind: the bills are starting to land, and the same conversations that hyped the cheap labour are now quietly working out that all those tokens aren’t cheap at all.

Step back, though, and none of this is new. Man finds a shortcut, man takes a shortcut. From the industrial revolution onward, every time we found a way to get more done with less human effort we took it, and the work reshaped itself around the new tools. We are still here, still employed, just doing different things than our great-grandparents did.

What is genuinely new is what we’re automating. Every technological advance before this one automated the machinery of the body, the muscle and sinew and bone. This is the first time we have automated thinking, and that is a modern marvel, something we should be proud of as a species. The problem isn’t the marvel. It’s the rate. AI is improving faster than we can adapt to it, and adaptation is the entire game.

So where does the blame sit? Not on one logo. No single company did this, however easy Meta or Google make it to point at the latest round of cuts. Society did, our collective and very human hunger to build bigger and faster. That makes it harder to fix, because there is no villain to regulate, only ourselves to out-think.

The bit that should frighten you

Cutting the junior intake isn’t a saving. It’s occupational suicide.

A junior is not cheap labour that AI happens to have made cheaper. A junior is a senior who hasn’t happened yet. Saw off the bottom rung and for a good while nothing bad happens… because you’ve still got your seniors holding everything up. Then the greybeards retire, and I have a cabin and a woodstove with my name on it for exactly that day, and the role that used to grow their replacements has been hollowed out for a decade, and there is simply nobody left who learned to tell when the machine is wrong. That isn’t a hiring problem. It’s an existential one, and you can’t fix it retroactively.

It starts before the first job, too. We teach primary-school children the basics of programming in this country, which is a wonderful thing, except the curriculum was written for a world without AI in the room, and by the time those children reach secondary school a good deal of it will be teaching a craft that has already moved on. We’re throttling the pipeline at both ends at once: hollowing out the entry-level job, and feeding it from a school system running a step behind.

It’s a split, not a collapse

The counterweight to the doom is that none of this is uniform, and the loudest version, “the junior is dead”, simply isn’t true. IBM just tripled its US entry-level hiring while most of the industry was cutting, and its HR chief said the quiet part out loud: AI can handle most of the routine entry-level tasks now, the work still needs a human, and the companies that double down on early-career hiring in this environment are the ones that win in three to five years. They didn’t keep the junior role as it was. They rewrote it, less boilerplate, more time spent with customers and supervising what the AI produced.

That is the shape of the thing. The juniors who are thriving in 2026 aren’t the fastest typists. They’re the ones building judgement, which is precisely the edge I argued was the senior’s real value all along. The market hasn’t stopped wanting juniors, it’s stopped wanting the version of the junior whose job was the work AI now does.

Day zero

So what does a junior actually look like now? I don’t know yet… and anyone telling you they’ve got it worked out is selling something. We are at day zero of this.

The junior gauntlet, the rite of passage every one of us runs to earn our stripes, isn’t going anywhere. Doing your time is a cold fact of the craft and it always will be. What changes is what the gauntlet contains, and that will keep changing, day one, day two, day five hundred and twelve. The only way we redefine it well is to put juniors and seniors on it together, with the AI in the room from the start instead of bolted on afterwards. Bring it closer to our people, and bring it earlier.

Open the floodgates, in other words. Let engineers of every creed and calibre in, and let them evolve with the machine, because that is the only way the symbiosis everyone keeps promising actually happens. Darwin’s line was survival of the fittest, and fitness here means adapting alongside the tool, not being spared by it. Choke off the flow of the very people who could do that adapting, and we don’t get fitter. We go extinct.

The end I’m holding

Which is the long way back to that interview. I keep asking the question, what is your real position on AI and how are you building a team of people and machines together, because the answer tells me whether a company is optimising for this quarter or for the survival of the craft. I want to work where it’s the second one, and I think any engineer sitting across that desk should be asking the same.

And it’s why, whatever desk I land at, there’s one thing I already know I’ll do. I don’t have the map. Nobody does. But every junior who works under me is going to get the chance to run the gauntlet, to grow into a senior, and to be in the room while we work out what the next gauntlet should even be. That isn’t charity. It’s the only sane investment any of us can make. The last properly useful thing my generation does, before we go and find our cabins, is make sure there’s somebody left to hand the thread to. I intend to be holding my end of it.

Everyone wants Rust's safety, nobody wants Rust

Sun, 14 Jun 2026 00:00:00 +0000

This spring, the better part of a million lines of Zig quietly became a million lines of Rust. Bun, the JavaScript runtime that was the showcase for “you don’t need a borrow checker, you need good tools and a steady hand”, looked at its own memory bugs and switched teams. Around 99.8% of its test suite passed on the rewritten code, a clutch of memory leaks closed in the move, and the maintainers said the quiet part out loud: the previous release would be the last one written in Zig.

It’s tempting to read that as Rust winning, hoist the flag, and move on. I don’t think that’s quite the story, and the more interesting one is happening everywhere else at the same time.

Because Bun is the exception that went all the way. Everyone else is trying to get the safety without the Rust, and watching how they’re going about it tells you more than one runtime’s heroic rewrite does.

What everyone’s actually after

A quick level-set, because not everyone reading this writes systems code daily. “Memory safety” is the property that a program can’t read or write memory it has no business touching: no using a value after you’ve freed it, no running off the end of an array. It sounds niche. It is, by most counts, behind something like 70% of serious security vulnerabilities, which is why governments and trillion-dollar companies suddenly care a great deal.

There are roughly three ways to get it. Rust uses a borrow checker: a compiler that flatly refuses to build your program unless it can prove, before it ever runs, that you never touch memory after you’re done with it. The price is that it argues with you the entire time you’re writing. The product is that an entire category of bug becomes literally unwriteable. Go (and most managed languages) uses a garbage collector: a runtime janitor that frees memory for you, so you mostly can’t get it wrong, at the cost of some overhead and a little control. And then there’s the old way, the one most code on Earth still uses: trust the developer to get it right, and add an escape hatch, usually a keyword like unsafe, for the bits where they promise they have.

The retrofit trend is everyone in that third camp trying to inch toward the first two without rewriting the world.

Rust didn’t invent any of this

Worth saying plainly, because the fan club rarely does: Rust invented almost none of it. The borrow checker is, by Rust’s own admission, Cyclone’s region-based memory management, from a safe-C experiment in the early 2000s, welded to affine types out of linear logic, ideas that predate Rust by decades. And it goes beyond the borrow checker. Rust’s exhaustive pattern matching came from ML and Haskell. Its “errors are values, and there is no null” approach, Result and Option, is Haskell’s Maybe and Either in work boots.

What Rust did, and did better than anyone before it, was taste and integration: it curated thirty-odd years of academic research into one coherent language and proved the ideas could carry real systems code rather than just research papers. That is the genuine USP, and it’s why the rest of the industry is now shopping from the same shelf. Pattern matching has landed in Python and Java, with a proposal in flight for C++26. Swift 6 shipped compile-time data-race safety, its Sendable machinery a close cousin of Rust’s Send and Sync. The borrow checker just gets the headlines because it’s the hardest bit to copy. Which makes the title almost too literal: everyone wants Rust’s safety, and they are quietly adopting its mechanisms one feature at a time.

Credit where it’s due: C# is doing this properly

The example that made me sit up is C#. In C# 16, Microsoft is redefining the unsafe keyword that’s been in the language since version one. Instead of unsafe marking a lump of syntax, it now marks a contract: a promise the compiler can’t verify and a human has to read and uphold, with documentation and static analysers nudging you to take it seriously. They’re even floating badges on NuGet packages to show which ones have opted in.

My first instinct with any retrofit is suspicion, because bolting safety onto a language after the fact has a long and miserable history, and an escape hatch that’s easy to reach is an escape hatch people will reach for the moment they’re in a hurry. But this isn’t a bolt-on. Taking the keyword that’s already there and giving it real teeth is working with the grain of the language instead of stapling a second safety system alongside the first. That’s honest engineering, and it deserves the credit. It genuinely raises the floor.

A contract is not a guarantee

Here’s where my enthusiasm meets its limit, and it’s a distinction I happen to have a lot of skin in.

C#’s redefined unsafe makes dangerous code visible and reviewable. That is a real improvement, and most teams would be better off for it. But visible and reviewable still means a human has to honour the promise. It’s a sign on the door. Rust’s equivalent is a wall: in rust-tool-base I put #![forbid(unsafe_code)] at the top of all eleven shipping crates, and forbid is not advice, it’s a refusal. The compiler will not build a crate that contains unsafe, full stop, and unlike its softer sibling deny, you can’t quietly switch it back off in a corner of the code where it’s inconvenient. The whole reason I use forbid and not deny is that I don’t trust future-me, in a hurry, not to reach for the hatch.

So when I look at the C# work I think: good, genuinely good, and they should take it further. A contract a human upholds is not the same kind of thing as a proof a compiler enforces, and the trend, if it’s serious, points at enforcement. Visible is better than invisible. Impossible is better than visible.

Discipline never scaled, and that’s not an insult

The objection I keep hearing, and that a younger me would have made, is that any language can be memory-safe if you’re just disciplined enough. And it’s true, in the way that any house can be tidy if you never get busy. In the before times we shipped memory-safe C with code review and valgrind and sheer bloody-mindedness, and it worked, sort of, at small scale.

It doesn’t scale, and Bun is the proof sitting on the table. That wasn’t a sloppy team learning the basics. It was a strong team, betting publicly on the discipline-and-good-tools model, and the memory bugs piled up anyway until the honest move was to let a compiler take the job. Discipline failing at scale isn’t a moral failure of the engineers. It’s just what happens when you ask humans to hold a thousand invariants in their heads across a million lines. Delegating that to a machine that never gets tired or rushed isn’t laziness. It’s the entire point of having compilers at all.

The part that changed my mind

I learned most of my Rust by building rust-tool-base with an AI alongside me, leaning on it to explain the borrow checker, suggest the idiomatic shape, and check my work. And somewhere in that I noticed the thing I now can’t unsee: the borrow checker is exactly as good a guardrail for the AI as it is for me.

A model, like a tired human, will write a confident use-after-free without blinking. In Rust it simply doesn’t compile, so the mistake never reaches me. What that does is move the whole error surface. The bugs that survive into review aren’t memory bugs or lifetime bugs or data races, the language has eaten those, they’re errors of logic: the code is safe and wrong. And logic is precisely where I want my attention, and the AI’s, because it’s the part a human has to own and the part the models are getting better at every month. (I split my AI work across a few providers for their different strengths, so this is not a pitch for anyone’s logo. The effect is the same whoever’s doing the typing.)

Which dissolves the one argument that ever really kept people out of Rust. “The borrow checker is too much friction” was always the case for the defence. But Bun’s million-line rewrite was done largely with an AI, because an AI is very good at paying a tax that is tedious and mechanical rather than creative. The friction is getting cheaper to pay at exactly the moment the guarantee is getting more valuable to have. In an AI-assisted world, a language that proves safety is worth more, not less, because it fences in the machine’s mistakes as firmly as your own.

None of this means rewrite everything in Rust

I want to be careful not to land somewhere smug, because most software does not need what Rust offers and pretending otherwise is how you end up rewriting a CRUD app nobody asked you to. Garbage collection is not a failure state. Go’s collector keeps getting meaningfully better, my own go-tool-base is GC’d top to bottom and I have never once wished it weren’t, and “safe-by-default with a GC” is the right answer for a vast amount of the work most of us do. The borrow checker is a price, and you should only pay it when the thing you’re buying, that last class of guarantee with no runtime cost, is something your stakes actually need.

What it comes down to

The question was never “is it as safe as Rust”. That framing turns everything into a loss for everyone who isn’t Rust, which is silly. The useful question is: what does your language make the default, and how hard does it make the escape hatch to reach? Go makes safety the default and charges you a GC. Rust makes it the default and charges you the borrow checker. C# is moving its default in the right direction and, for now, leaves the hatch as a promise rather than a wall.

Credit the retrofits, they are raising the floor for an enormous amount of code that was never going to be rewritten. Just don’t mistake the floor for the ceiling, or a contract a human signs for a guarantee a compiler keeps. Everyone wants Rust’s safety, and the interesting question, now that an AI will pay the toll for you, is who still has a reason not to want it.

Widen the lens past Rust, though, because that’s where the news gets genuinely good. We’re at a turn in how languages evolve. Compile-time rigour is spreading rather than retreating: borrow checking is reaching the Python family through Mojo, static typing long since conquered JavaScript, and even the managed languages are turning their escape hatches into something you have to argue with. More of our safety is quietly moving from “remember to” into “can’t not”. And the one thing that always made the strict path hard to start down, the friction, is being absorbed by an AI that will happily learn the rules so you can lean on them. I’ve been at this long enough to distrust a rosy forecast, but I’ll put my name to this one: the outlook for software that’s safe and secure by default has never looked better.

They switched it off while it was fixing my code

Sat, 13 Jun 2026 00:00:00 +0000

I woke up this morning to a one-line message from my own tooling:

Claude Fable 5 is currently unavailable. Learn more: https://www.anthropic.com/news/fable-mythos-access

I followed the link expecting a status page about a wobble in someone’s data centre. Instead it was Anthropic, explaining that the evening before, at 5:21pm Eastern, the US government had ordered them to suspend all access to Fable 5 and Mythos 5 on national security grounds. Globally. Every user. Their own staff included.

I’d spent the previous day with Fable doing one very specific thing: pointing it at my own codebase and asking it to read the code and fix the flaws it found. That, very nearly word for word, is the thing it has now been banned for.

Three days late to the only model that mattered

Fable came out on the 9th. I didn’t get to it properly until the 12th, which is the sort of timing I specialise in. By the time I sat down with it, I had about a day of real use before it vanished. One day to form a view on what people were calling the most capable coding model anyone had shipped. So treat everything below as the read of a man who got three days’ notice and used one of them.

What I had it doing was unsexy and exactly the kind of work I care about: a full security audit of go-tool-base, the same “leave the codebase better than you found it” pass I’d normally run myself. Find the flaws, then start fixing them.

And it was good. Genuinely good. It surfaced issues that previous passes with Opus had walked straight past, and in a couple of cases the flaw was sitting in code that Opus itself had written. There is something bracing about one model quietly marking another’s homework, and being right.

Good, but let’s not get carried away

Here is where I have to be fair, because the anger that came later is only worth anything if the praise before it is honest.

Fable is not magic. The class of bug it found is not some exotic thing only it can see. Plenty of models, from plenty of providers, are perfectly capable of reading a codebase and pulling out the same problems, and there is a mountain of evidence that they do, every day. Anthropic say as much themselves: the capability is “widely available from other models (including OpenAI’s GPT-5.5)” and “is used every day by the defenders who keep systems safe.” I’d already arrived at that conclusion from my own keyboard before I read their statement. Fable was excellent. It was not unique. Hold that thought, because the whole argument turns on it.

It kept slipping out of my hands

The other thing I learned in my one day is that having Fable and using Fable were not the same thing.

I set my main working thread to Fable and got on with it. What I didn’t know, because nothing on screen told me, is that partway through the evening it had quietly handed me back to Opus. The only reason I know now is that the session log records it in black and white:

2026-06-12T06:57:22Z {"type":"fallback","from":{"model":"claude-fable-5"},"to":{"model":"claude-opus-4-8"}}
2026-06-12T18:50:08Z {"type":"fallback","from":{"model":"claude-fable-5"},"to":{"model":"claude-opus-4-8"}}

A whole evening of work I thought I was doing on Fable was, in fact, Opus wearing Fable’s badge. The audit itself launched on the wrong model first; I only caught it because I happened to be watching the workflow panel, killed it, and relaunched it on Fable, where it chewed through an entire five-hour quota in about forty minutes, then spent $50 of usage credits I’d been saving in about five more. Even the run that worked was visibly flaky: of the 282 little agents that audit fanned out into, well over half failed outright and had to be retried.

Then, in the small hours, it started refusing entirely. My tooling caught the moment before I did:

Now failing instantly. Fable appears to be temporarily unavailable for subagents (the first three succeeded). The user explicitly required Fable, so I won’t downgrade… rather than silently switch models.

It managed three of the fixes before it went, each one green on tests, the race detector and the linter. Three real improvements to my code, written by Fable, sitting in my git history. The other three were finished by Opus, because by morning there was nothing left to finish them with.

Capable, and almost impossible to build on

There was a second wall, and I hit it before any of this, on the day Fable launched, when I tried to make it go-tool-base’s default model.

Most of what you build on top of a model isn’t a chat window. You need it to hand your code an answer in a fixed shape, the same fields in the same places every time, so the program on the other end can rely on what comes back. The usual way to guarantee that is to force the model’s hand: you don’t ask politely for the structure and hope, you require it, so a wrong-shaped answer fails outright instead of quietly slipping through.

Fable won’t be forced. Ask it to commit to a guaranteed structure and it declines, flat out. As I understand it the reasoning is a safety one: letting anyone compel a model into a precise, mandated output is itself a lever, a way to march it toward saying something it shouldn’t. Reasonable enough on paper. In practice it meant the most capable model I’d touched couldn’t drive the structured parts of my own tool, and by that first afternoon I’d quietly set the default back to Opus. It was the same refusal, I realised later, that had collapsed half of that audit’s agents.

And it is not a niche complaint. Guaranteed structure is a hard requirement for a vast swathe of what people are actually building on these models. Not everyone is making another Claude Code. Plenty of us are wiring models into systems that have to get a clean, predictable contract back every single time, and a model that reserves the right to freestyle the shape of its answer is one you simply cannot put in that seat.

The part they banned is my bread and butter

So let’s be precise about what got pulled, because the precision is the whole point.

Anthropic describe the government’s concern as “a narrow potential jailbreak, which essentially consists of asking the model to read a specific codebase and fix any software flaws.”

Read that again. Reading a codebase and fixing its flaws. That is not some dark-web misuse I have to strain to imagine. That is my bread and butter, the literal, boring, defensive job I had Fable doing in the open, on my own project, when the shutters came down.

And here is where that earlier point earns its keep. If the banned capability were unique to Fable, you could at least follow the logic, however much you disagreed. But it isn’t, and it isn’t even close: give Opus enough time, enough budget and a patient enough hand on the prompts, and it would get to most of the same findings in the end. Fable just did it more efficiently, a difference of degree, not of kind. So banning one company’s model, for something every competitor ships and every blue team already relies on, makes precisely nobody safer. The exploit-writers keep their tools. The defenders lose one of theirs.

When the thing you have banned is available everywhere else, the ban has stopped being about safety. It is theatre. And given who is currently in charge of the theatre, it has the distinct whiff of a knee-jerk reaction, dressed as a national security triumph, by people who do not appear to understand the tool they are confiscating.

Who I’m not angry at

I want to be careful where I point this, because it would be lazy to spray it around.

I’m not angry at Anthropic. They put Fable through more than a thousand hours of external testing, with US government agencies and the UK’s AI Safety Institute among the people kicking the tyres, before it ever reached me. They satisfied every requirement put in front of them, and when the order came they complied under protest while saying, plainly, that applying this standard across the board “would essentially halt all new model deployments for all frontier model providers.” I’m a daily Claude user and an advocate for the work, and I am not going to hang the US administration’s decision around the neck of the company that did the diligence and then got told to switch the lights off anyway.

I’ll allow them one small dig, and there was nothing quiet about it. Moving Fable behind a paywall on the 22nd was openly announced and planned well ahead, and the free window was never charity. It was a taster: a few days of the new addiction on the house, enough to hook the punters, before the price went up. That is a bit of a dick move, however neatly it tests in a spreadsheet. Moot now, mind, with no model left to charge for.

I’ll even grant the other side its strongest point. A government looking at agentic systems that can chain reconnaissance into working exploits has something real to be twitchy about. I get the worry. I just don’t accept that yanking one vendor’s model, for a thing every vendor does, is a coherent answer to it.

There is a grim irony in how we got here, and it loops back to something I wrote in the spring. When Anthropic first showed Mythos off, I called the fanfare what it looked like: a closed model sold on a press release, a result you couldn’t independently check, marketing until proven otherwise. Fable 5 was Anthropic finally answering that, handing the rest of us something we could actually test. But all those years of selling Mythos as too dangerous to let out were marketing too, and that half landed rather better than they can have wanted. The US administration appears to have swallowed it whole and pulled the lever. Anthropic have ended up a victim of their own hype, and the reaction that hype provoked is, there is no gentler word for it, ludicrous.

What it comes down to

The lesson I’m taking from my one day isn’t about how clever Fable was. It’s about how little that cleverness is worth if you can’t rely on the thing being there.

I couldn’t trust which model I was actually talking to from one hour to the next. I couldn’t trust it to stay up for a full overnight run. And it turns out I couldn’t trust it to still exist by the weekend. You cannot evaluate, depend on, or build a workflow around a model that gets silently swapped out one evening and switched off by the state a few days later. Capability was never the hard part. Availability is.

And underneath all of it sits the thing I keep coming back to. A classifier cannot tell a defender from an attacker, because the two of them type the same commands. It turns out a government export control can’t tell them apart either. The only thing that ever could is a human being, paying attention, who can be held responsible for the judgement. There wasn’t one of those anywhere in this loop. There was a letter, sent at 5:21pm, and by morning the best tool I had for keeping my own code honest was gone, with a polite link where it used to be.

The goblin that wouldn't stay dead

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

Turn one, the player swings, the die comes up 20, and my AI dungeon master narrates the goblin falling silent, leaving the player alone in the corridor. Good. Turn two, another roll, a 6 this time, and the same dungeon master cheerily has the goblin “dance back” out of the dark to take another swing. The goblin I’d just watched die was up and fighting again, and the model didn’t so much as blink.

I didn’t feel cheated, or even surprised. I felt the small, familiar thud of oh, yeah, I forgot that bit. Because the model hadn’t gone rogue. It had done exactly what a language model does. The gap was mine.

This was the war story behind part four of the go-tool-base tutorial, the AI dungeon master. The tutorial shows the clean, final design and quietly moves on. It doesn’t show the three different ways I got it wrong first, which is a shame, because the wrong turns are where the actual lesson is.

Why a dungeon master at all

A word on why I was even here. I was trying to prove the chat component of the framework to myself. There’s a voice that pipes up whenever I build anything in this space, “LangChain exists, who do you think you are?”, and the answer I keep landing on is that LangChain is enormous and I wanted something small enough to hold in your head. The tutorial was the test: could a newcomer wire AI into a CLI with it and come out the other side with something that actually behaves?

That last word is the whole problem. A tutorial has to leave you holding something dependable, and dependability is the one thing AI fights you on. I also wanted it to be fun, a thing someone might keep poking at after the tutorial ends, maybe even the hook that gets a person other than me to use the framework. I batted hook ideas around and liked none of them, until the obvious one landed: I run a tabletop game on the odd weekend, so make the AI the dungeon master. Gamify the thing. Then watch it raise the dead.

Strike one: nothing to enforce

The first version was the naive one. I gave the model a roll tool, because the one thing you absolutely cannot let a language model do is pick its own numbers, and otherwise let it narrate freely. The conversation history carried from turn to turn, so it remembered the fight. I assumed remembering was enough.

It isn’t. Remembering and being held to it are different things. The history told the model a goblin had died; nothing stopped it writing the goblin back in when the next turn’s narration wanted a bit of jeopardy. Memory is not a constraint. The model will happily contradict its own past if you’ve given it room to, and I had given it nothing but room.

Strike two: a tool to read the state

The obvious fix, and I do mean obvious, the kind you reach for without thinking, was to give the model a state tool so it could check who was alive before it narrated. Hand it the facts on request and surely it’ll stop making them up.

What it actually did was dither. Handed a tool it could call to look things up, it called it. And called it. And called it again, turning a turn over in its hands without ever committing to an action, burning through its step budget on lookups and leaving the player staring at nothing. I’d cured the lying by inventing paralysis. A tool the model can call is a tool it will call, often instead of doing the thing you actually wanted.

Strike three: refereeing its own dice

When I did get it reading state cleanly, the third failure crept in, and this one was subtler. Once the model could see the goblin’s hit points, it started deciding the fight. It would read that the goblin had 12 HP and just narrate a killing blow, hits and damage and all, without calling the roll or attack tools at all. Why ask the dice when you can see the board and write whatever outcome the story wants? Give a model enough context and it stops being a narrator and starts being a referee, which is precisely the job I’d built tools to keep out of its hands.

The fix was less, not more

Three failures, and notice the shape of my fixes: each one added something. More memory, then a tool, then more context. Every instinct said the model needed more to work with. Every time, the extra capability was the new way to be wrong.

So I went the other way. The truth lives in a plain Go struct that I own, not the model. There’s no state tool to dither on, because the loop simply prepends the current state to every turn’s input, fresh, so the model never has to ask and never gets to drift. The mechanics, the dice and the damage, live in Go functions the model has to call, and the system prompt says in as many words that it must not decide a hit or damage itself. The model is left with exactly one job: narrate. The prose is its to invent. The maths, the state and the shape of the result are not.

That’s the line that turned three bugs into a feature. You don’t make a language model reliable by giving it more to work with. You make it reliable by giving it less to be wrong about.

The freedom I chose not to give it

There’s a real tension in that, and I want to name it rather than pretend the boxed-in version is the only true one. At my own table the rules are guidelines, not guardrails. I ignore them, bend them, improvise, reach for the “rule of cool” when the moment’s better for it. A great AI dungeon master would have that same freedom, and a few out there genuinely do, Old Greg’s Tavern is a lovely example of how far the free-form version can go.

But that freedom costs far more than a tutorial can spend, and it buys unpredictability I was specifically trying to teach people to avoid. So I made a deliberate trade: guardrails instead of guidelines. Simple, but not so simple it’s boring. The player still gets a “not on rails” game, they can try anything and the DM copes, but every outcome that matters runs through code I trust. That’s the right shape for a tutorial, and, not by coincidence, the right shape for most AI features you’d actually ship.

What the goblin taught me

The thing I keep coming back to is that the model never misbehaved. It resurrected the goblin because I gave it the freedom to. It dithered because I gave it a button to press. It refereed because I let it see the board. Every failure was a permission I’d handed over without meaning to. The reliability didn’t come from a cleverer prompt or a bigger model, it came from working out, one dead goblin at a time, exactly how little the model needed to be trusted with.

If you want the version where it all works first time, the tutorial has it, the tool-calling and the typed turns wired up properly. This was the road there. The goblin, you’ll be glad to hear, now stays down.

Generate a command from a script or a sentence with go-tool-base

Thu, 11 Jun 2026 00:00:00 +0000

You’ve got a Python script that already does the job. It’s sat in a tools/ directory somewhere, it works, and every few weeks someone copies it onto a laptop that doesn’t have the right version of pandas and it falls over. You’d like it to be a proper subcommand of your tool, a real Go binary you can ship, but porting it means the cobra wiring, the options struct, a test file, and a fight with the linter before any of it lands.

Or you don’t even have the script. You’ve just got a sentence in your head: “something that pings a list of URLs and tells me which ones are slow.” The logic is five minutes of thought; the boilerplate around it is the afternoon.

gtb generate command is built for exactly that gap. Hand it a script or hand it a sentence, and it writes the Go, the tests and the docs, then sends an autonomous agent through the result to make sure the thing actually builds, passes its tests and survives golangci-lint before it ever reaches your working tree.

Two ways in, the same files out

There are two flags, and they’re mutually exclusive:

--script <file> converts an existing bash, Python or JavaScript script.
--prompt "<text>" (or a path to a file) generates from a plain-English description.

Both land in the same place. A generated command called csv-stats gives you:

pkg/cmd/csv-stats/cmd.go: the cobra registration. This one is read-only; the generator owns it and will regenerate it.
pkg/cmd/csv-stats/main.go: the implementation, where your logic lives and where you’re free to edit.
pkg/cmd/csv-stats/main_test.go: a test file.
docs/commands/csv-stats/index.md: AI-written docs for the command.

The provider and model come from your config (ai.provider) or the --provider / --model flags. Everything below was generated with Claude Opus. We’ll take each in turn.

From a script: `csv_stats.py` becomes `csv-stats`

Here’s the script I want as a native subcommand. It reads a CSV and reports, per column, the row count, how many values are empty, and min/max/mean for the numeric ones. Nothing exotic, but enough that porting it by hand is a chore. Copy it into a file called csv_stats.py if you want to follow along:

#!/usr/bin/env python3
"""Summarise a CSV file's columns.

For every column it reports the row count and how many values are empty; for
columns whose values are numeric it also reports min, max and mean. A single
column can be selected with --column.

usage: csv_stats.py [--column NAME] <file.csv>
"""
import argparse
import csv
import sys


def is_number(value):
 """True if value parses as a float."""
 try:
 float(value)
 return True
 except (TypeError, ValueError):
 return False


def summarise(path, only_column=None):
 with open(path, newline="") as handle:
 reader = csv.DictReader(handle)
 if reader.fieldnames is None:
 print("error: empty CSV", file=sys.stderr)
 return 1

 columns = list(reader.fieldnames)
 if only_column is not None:
 if only_column not in columns:
 print(f"error: no such column: {only_column}", file=sys.stderr)
 return 1
 columns = [only_column]

 counts = {c: 0 for c in columns}
 nulls = {c: 0 for c in columns}
 numbers = {c: [] for c in columns}

 for row in reader:
 for c in columns:
 value = row.get(c, "")
 counts[c] += 1
 if value is None or value.strip() == "":
 nulls[c] += 1
 elif is_number(value):
 numbers[c].append(float(value))

 header = f"{'column':<20}{'count':>8}{'nulls':>8}{'min':>12}{'max':>12}{'mean':>12}"
 print(header)
 print("-" * len(header))
 for c in columns:
 nums = numbers[c]
 if nums:
 cmin = f"{min(nums):.2f}"
 cmax = f"{max(nums):.2f}"
 cmean = f"{sum(nums) / len(nums):.2f}"
 else:
 cmin = cmax = cmean = "-"
 print(f"{c:<20}{counts[c]:>8}{nulls[c]:>8}{cmin:>12}{cmax:>12}{cmean:>12}")
 return 0


def main():
 parser = argparse.ArgumentParser(description="Summarise a CSV file's columns.")
 parser.add_argument("csvfile", help="path to the CSV file")
 parser.add_argument("--column", help="only summarise this column")
 args = parser.parse_args()
 return summarise(args.csvfile, args.column)


if __name__ == "__main__":
 sys.exit(main())

One command points the generator at it:

gtb generate command \
 --name csv-stats \
 --short "Summarise CSV columns" \
 --script ./csv_stats.py

Your browser doesn't support embedded video; the demo converts csv_stats.py into a Go command and the repair agent builds, tests and lints the result.

What lands is not a transliteration. The Python kept everything in one function; the Go that came out is decomposed into named pieces, opens the file through the project’s injected filesystem (props.FS, an afero Fs) rather than os, and reports through the structured logger rather than print:

func summarise(fs afero.Fs, path, onlyColumn string) ([]string, error) {
	handle, err := fs.Open(path)
	if err != nil {
		return nil, errors.Wrapf(err, "failed to open CSV file %q", path)
	}
	defer func() {
		_ = handle.Close()
	}()

	reader := csv.NewReader(handle)
	reader.FieldsPerRecord = -1

	columns, indexByName, err := readColumns(reader, onlyColumn)
	if err != nil {
		return nil, err
	}

	stats := make(map[string]*columnStats, len(columns))
	for _, c := range columns {
		stats[c] = &columnStats{numbers: []float64{}}
	}

	for {
		record, readErr := reader.Read()
		if readErr != nil {
			if errors.Is(readErr, io.EOF) {
				break
			}

			return nil, errors.Wrap(readErr, "failed to read CSV record")
		}

		accumulate(stats, columns, indexByName, record)
	}

	return formatReport(columns, stats), nil
}

That decomposition, into readColumns, accumulate, formatReport, summaryValues and a couple of small formatting helpers, is the interesting part, and it didn’t come for free. The first thing the agent did after writing the code was build it, test it, and lint it. golangci-lint’s cyclop rule flagged a single fat summarise function well over its complexity ceiling of 10. So the agent read the file back, split the work into focused functions, and ran the checks again. It only stopped once the build, the tests and the linter were all clean. The tidy shape above is the agent arguing with the linter and winning, not the model’s first guess.

Then it just runs. In the demo I scaffolded the project without the init feature, so the tool reads sensible defaults and needs no config step, and csv-stats sample.csv prints real per-column counts, nulls and numeric stats (with the default features you’d run toolbox init, or pass --config, first). The full generated command, the three files and nothing else, is here: csv-stats-command.tar.gz.

From a sentence: a URL health-checker

No script this time. Just a description of the command I wish I had. --prompt takes a raw string, but a description with any detail to it is easier to read, and to keep, in a file, so I dropped it in healthcheck-prompt.txt:

Concurrently GET a list of URLs and report each one’s HTTP status and latency.

Flags:

--timeout: the per-request timeout

--file: read URLs from a file, one per line

--json: machine-readable output

Use httptest in the tests so they need no network.

The prompt describes what I want the command to do, including how the flags should behave. The flags themselves I declare up front with --flag (more on why that split matters below), and point the generator at the file:

gtb generate command \
 --name healthcheck \
 --short "Check URL health concurrently" \
 --flag "timeout:duration:per-request timeout:false:t:false:5s" \
 --flag "file:string:read URLs from a file, one per line" \
 --flag "json:bool:machine-readable output" \
 --prompt ./healthcheck-prompt.txt

Your browser doesn't support embedded video; the demo builds a concurrent URL health-checker from a natural-language description, then self-repairs until it builds clean.

And the flags feed straight in. RunHealthcheck reads the URL file from opts.File, the deadline from opts.Timeout, and the output format from opts.Json, then fans the requests out across goroutines, each writing into its own slot, exactly the way you’d write it by hand:

func RunHealthcheck(ctx context.Context, props *props.Props, opts *HealthcheckOptions, args []string) error {
	urls, err := collectURLs(props.FS, opts.File, args)
	if err != nil {
		return errors.Wrap(err, "failed to collect URLs")
	}

	if len(urls) == 0 {
		return errors.New("no URLs provided; pass URLs as arguments or via --file")
	}

	timeout := opts.Timeout
	if timeout <= 0 {
		timeout = defaultTimeout
	}

	client := &http.Client{Timeout: timeout}

	results := make([]result, len(urls))

	var wg sync.WaitGroup

	for i, u := range urls {
		wg.Add(1)
		go func(idx int, target string) {
			defer wg.Done()

			results[idx] = checkURL(ctx, client, target, timeout)
		}(i, u)
	}

	wg.Wait()

	return reportResults(props, opts.Json, results)
}

I asked for the tests to use httptest so they’d need no network, and they do. Each case spins up a local server, so go test is hermetic and the agent’s own test run during repair stays self-contained, and it wrote cases for the flags too, this one driving --json:

func TestRunHealthcheck_JSONOutput(t *testing.T) {
	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
		w.WriteHeader(http.StatusNotFound)
	}))
	defer srv.Close()

	p := newTestProps()
	opts := &healthcheck.HealthcheckOptions{
		Timeout: 5 * time.Second,
		Json: true,
	}

	err := healthcheck.RunHealthcheck(context.Background(), p, opts, []string{srv.URL})
	if err != nil {
		t.Fatalf("unexpected error: %v", err)
	}
}

Same as before, it builds and runs: point it at a few URLs and it GETs them concurrently, reporting each status and latency. The full generated command is here: healthcheck-command.tar.gz.

What “self-repair” actually means

The agent isn’t a single shot at the model with a hopeful prompt. It’s a loop with real tools: it reads the project layout, reads the files it needs, and runs go build, go test and golangci-lint. When something fails, it reads the relevant code, rewrites it, and runs the checks again. It only declares success once all three pass with nothing outstanding. The repair agent’s instructions are deliberately blunt on that last point: a clean build and passing tests don’t count as done if the linter still has something to say.

A few flags shape how it runs:

--max-steps N raises the agent’s reasoning budget. The default is plenty for a command like these two, but a genuinely hairy conversion can run long, and this stops it stopping short.
--agentless skips the agent entirely and uses the older retry loop, if you’d rather keep the generation cheap and do the polishing yourself.
--non-interactive withholds the agent’s ability to ask you a question mid-run. It defaults on when the CI environment variable is set, so the thing never blocks a pipeline waiting for an answer that isn’t coming.

Flags you declare, logic it writes

The --timeout, --file and --json arrived as real flags on the command, but not because the prompt mentioned them. Flags are the generator’s job, not the prompt’s, and that split is deliberate. You declare each one with --flag (or the interactive wizard), as I did above, and the generator wires it onto the options struct and into the read-only cmd.go registration, which hands that struct straight to your Run function. The prompt is left to describe behaviour: what --timeout should bound, what --file should read, what --json should change.

So the agent, told exactly which option fields exist, wrote its logic against opts.Timeout, opts.File and opts.Json rather than inventing anything, and the finished command’s --help lists them with the 5s default and the -t shorthand I asked for. Leave the --flags off and it still works: the generator hands the agent an empty options struct, and it keeps those values as locals with sensible defaults, ready for a flag to be wired in later.

The one thing you don’t do is hand-edit cmd.go: it’s regenerated every time you add a flag or change the command, so reach for --flag, never the file. When a generation finishes, the quickest sanity check is the command’s own --help, which shows the flags it actually exposes.

One thing to keep in mind: the model isn’t deterministic. Run the same prompt twice and you’ll get two slightly different commands. If the first one isn’t quite right, regenerate, or nudge the prompt. Treat the output the way you’d treat a capable colleague’s first PR: read it, run it, and own what you merge.

And is it the best possible code, the best design? Probably not. That depends on the model you can afford to point at it, how much detail you put in the prompt, and a bit of luck on the day. What you can count on is a working starting point: something that builds, has tests, and uses proper Go idioms and the project’s own patterns, instead of a blank file and an afternoon of boilerplate. From there it’s yours to shape.

Where that leaves you

The generator does the boilerplate and has the argument with the linter so you don’t have to. What it can’t do is decide whether the command it built is the command you actually wanted. That part is still yours, which is rather the point. The full docs for both flags live in the AI conversion guide and the command generation reference, and they’re the place to go when you want the flags the prompt didn’t.

Why I still write code

Wed, 10 Jun 2026 00:00:00 +0000

By any sensible reading of an org chart, I have no business being in this file. I’m a Head of Software Engineering. My calendar reckons I should be in a room somewhere talking about headcount and roadmaps. Instead it’s late, everyone sensible has logged off, and I’m three retries deep into a release that refuses to tag itself, muttering at a Rust workspace I built with my own hands.

So why am I here? I’ve been asking myself a version of that question for about twenty-five years, and I think I’ve finally got an answer. It’s just not a flattering one.

I’m a builder, and that isn’t really a choice

Strip away the job titles and I’m a builder. I like to make things, I like to solve problems, I like to learn how something works by taking it apart and putting it back together slightly differently. That urge predates every role I’ve ever held and it has survived all of them. In jobs where I wasn’t allowed to scratch it, I went and built in the open instead, which is a polite way of saying open source has spent years absorbing energy my day job wouldn’t take.

I’ll go further, because being coy about it helps no one: it’s closer to an addiction than a hobby. I don’t fully switch off. The current outlet, when I’m not in a terminal, is converting a campervan, which is just software engineering with worse error messages and a real risk of electrocution. The shape of the thing changes. The compulsion doesn’t.

Underneath the building there’s a less charming engine, and I might as well name it: a fairly grim case of impostor syndrome. I wrote about it years ago when I stopped calling myself “Dev in Charge”, and a decade on it hasn’t gone anywhere. The only thing that ever quiets the anxiety is staying genuinely good at the thing, and staying good at the thing means using it. I’m a firm believer in use it or lose it. People say technical skill is like riding a bike, you never forget. Maybe. But step away for a few years and when you climb back on, someone’s bolted a jet engine to the frame and moved the pedals. The bike doesn’t wait for you.

What it actually buys

Here’s the part that justifies the indulgence, because on its own “I enjoy it” isn’t a reason to stay technical as a leader, it’s a reason to have a hobby.

The load-bearing belief is simple, and it’s the one line I’d carve into the desk: I will never ask an engineer to do something I’m not willing to do myself. Everything good about staying hands-on flows from that. Because I’m still in the work, I can give my engineers proper support, the right tools and a clear path, rather than guessing at what they need from a slide. I can steer them through a genuinely hard technical call instead of nodding along. I can sniff out a duff estimate, mine or theirs, because I know what the work actually costs. And I can hold them to account with a straight face, because the accountability runs both ways. They answer to me for what they ship, and they get to hold me to account for what I contribute. That second half is the bit a lot of technical leaders quietly drop, and it’s the half that earns you the right to the first.

The bill, and who paid it

I’d be selling you a fairy tale if I stopped there, so here’s the cost, and some of it is steep.

The obvious one is burnout. I’ve been there more than once over the years, and it’s the single biggest reason I now pitch myself deliberately as a Technical Leader rather than an Engineering Manager. I can do the manager stuff, the HR and the planning and the project-management bollocks, and after enough years in the role I do it well, because it demanded that I did. But competence isn’t appetite. Given the choice I’ll take a technical problem or a bit of mentoring over running the process around either, every time, and spending your days on work you’re good at but don’t much enjoy is its own slow road back to the wall. Sticking to my strengths isn’t ego, and it isn’t an admission I can’t do the rest. It’s self-preservation, learned the hard way.

The steeper bill came due at home. When my kids were small I poured my own time into pushing my skills and chasing the next rung, even starting my own agency. Between that and the burnout, I missed big chunks of their early years, and that is one of the real regrets of my life. I’m not going to dress it up or hide it behind a lesson. It was my decision, I made it, and I own it. I’m immensely proud of the people they’ve grown into, and since their mum and I separated I’ve put everything I have into giving them a stable home, the builder instinct quietly turning into a nest-building one, which is the better use of it. I put this here, plainly, because if you’re reading this with a young family asleep upstairs, I’d sooner you heard it from someone who got the balance wrong than learn it the way I did. The code will still be there next year. They won’t be five next year.

And there’s a smaller, daily cost that I still haven’t fully mastered: knowing when to put the keyboard down. A builder who can’t stop building is exactly the person who becomes the bottleneck, disappears down a rabbit hole, or hoards the interesting problem that would have stretched someone on the team. Stepping back to let them solve it, when every instinct I have is screaming to just fix the bloody thing, is genuinely one of the hardest skills I’ve had to learn, and some days it still feels like walking a knife edge. Open source is a big part of how I manage that. It’s a release valve, somewhere I can let the compulsion run with no brakes on, precisely so I’m not stealing the meaty work off the people I’m meant to be growing.

Does it still count when the robot types?

Fair challenge, given the year. I build solo now with an AI pair, to the point where it’s changed how I branch and release. So when a model writes a good chunk of the actual characters, am I still “writing the code”?

I think I’m doing it more than ever, and I’m certainly learning faster. My typing is genuinely terrible, a quarter-century of practice and still mostly thumbs, so being freed from being the typist is no loss at all. What’s left when you take the keystrokes away is the part that was always the point: reading, reviewing, judging, steering. I can review more code, faster, than I ever could when I was the one hammering it out, and I can run several projects at once by pointing my judgement at each in turn. That is leadership work and engineering work at the same time, which is rather the whole thesis.

It did not come free, mind. I was elbow-deep in AI and ML long before GPT made it fashionable, and I’ve seen the messy version up close. Getting to the point where the tools are good enough and I’ve built the guardrails and habits that make them safe took a long time and a lot of getting it wrong. Owning the judgement when the machine does the typing is harder than it sounds, not easier. The typing was never the hard bit.

What I’d actually put my name to

Not that every leader should write code. Plenty of excellent ones don’t, and they’re brilliant at the parts of the job I’m middling at. The narrower, truer claim is the only one worth making: I lead better when I stay in the work, because it’s the only way I know to support, steer and be held to account without faking any of it, and because I meant that line about never asking for what I won’t do myself.

Staying technical isn’t the job. It’s the thing that lets me do the job honestly. I’m a builder who learned, slowly and at a price I’d rather have not paid, how to keep building without it costing the people around me what it once cost the people closest to me. That’s the balance I’m still working at. I suspect I always will be.

Anything under an 8

Mon, 08 Jun 2026 00:00:00 +0000

I read the news about the National Vulnerability Database over a coffee that went cold while I sat there muttering at my phone. The short version: the NVD, the free public catalogue that quietly props up half the security tooling you and I run every day, is going under in slow motion. And the more I dug into why, the worse the taste in my mouth got.

I’m an open-source person. I think of myself as part of that community, and the NVD is one of those public goods the whole community leans on without ever really thinking about it. So my first reaction wasn’t clever or measured. It was a kick in the teeth.

The carcass and the vultures

Here’s where things actually are. In February 2024 the NVD had around 13,000 unprocessed vulnerabilities sitting in a queue waiting to be analysed. By the end of 2025 that backlog had passed 27,000. This April, NIST effectively admitted it can’t dig out: everything published before 1 March 2026 that hadn’t been enriched got swept into a bucket marked “Not Scheduled”, and going forward only the highest-risk entries get the full treatment. The rest you’re on your own with.

The reasons are grimly ordinary. The Cybersecurity and Infrastructure Security Agency stopped funding the programme in 2024. The enrichment contract lapsed that same February, and despite NIST having two years’ notice it needed a replacement, the database limped along understaffed until late November. And the volume kept climbing regardless: 48,185 CVEs in 2025, roughly 131 a day, with forecasts of the annual figure topping 60,000, getting on for ten times what it was a decade ago. No money, a fumbled handover, and a firehose. That’s the whole story.

The bit that turns my stomach is what comes next. When a free public good fails, the gap doesn’t stay empty. It gets filled, and it gets filled by people selling something. There are already commercial vulnerability databases that are better resourced and more current than the NVD, and the moment the free one is visibly on the floor, every one of them sees a market. Plenty of those subscriptions cost more in a year than a small open-source project will see in donations in its lifetime. So the catalogue the little projects relied on most is exactly the one about to be priced out of their reach. Vultures circling a carcass, and the carcass is something we all built on.

The number we never checked

And then I read the part that stopped me blaming everyone else.

A Department of Commerce Inspector General audit went through the NVD’s work and found that NIST’s own severity scores matched independent assessors only 12% of the time. Read that again. Not that NIST was wrong 88% of the time, that’s not quite what it says, but that two competent parties looking at the same vulnerability landed on the same severity barely one time in eight. The score was never an objective fact handed down from on high. It was always an estimate, a judgement call, the kind of thing reasonable people disagree about most of the time.

Which is awkward, because I have spent years treating that number as gospel. And I know I’m not alone, because I’ve watched whole engineering organisations do the same thing in writing. More than one large employer I’ve had bakes the CVSS score straight into policy: anything scored 8 or above blocks the build and gets a meeting, and anything under an 8 goes through at an engineer’s discretion. When time is money, and it always is in those places, “it’s only a 6.4, ship it” is the easiest decision you’ll make all week. I’ve made it. I’ve made it without opening the advisory, without checking whether the vulnerable code path was even reachable in what we’d built, on the strength of a single number that, it turns out, two experts wouldn’t have agreed on anyway.

So before I get cross about the funding, I have to sit with my own part in this. We took a contestable estimate and bolted it to the door as a gatekeeper. We turned “a rough signal worth a closer look” into “the closer look”, and then we stopped looking. The database didn’t promise us a safety net. We just decided it was one and stopped checking underneath.

Don’t blame the robots for this one

There’s an easy villain on offer here, and I want to wave you off it. It would be tidy to say AI did this, that the flood drowning the NVD is a tide of machine-generated slop, the same dynamic I wrote about when curl’s bug bounty buckled under unverifiable reports. It’s tempting, it’s topical, and it’s mostly wrong.

The people who actually crunch the numbers are clear that the surge is largely legitimate growth. There are now more than 484 CVE Numbering Authorities, far more organisations reporting far more bugs far more thoroughly than they did a decade ago. That isn’t a quality collapse, it’s the system working as designed and simply getting bigger than its funding. Pinning it on AI would be scapegoating, and scapegoating the robots for an underfunding-and-mismanagement problem is just a way of letting the people who defunded it off the hook.

None of which means AI gets a free pass. It just isn’t the arsonist. The same machine-assisted discovery tools that found genuine bugs are also forecast to push CVE volumes higher still, and yes, one of the tools named in that forecast is the very one I poked fun at over curl. AI is an accelerant on a fire that was already burning for thoroughly human reasons. It’s a beat in this story, not the spine.

The version I’m betting on

Where does this leave the working engineer? In a harder spot than before, because the easy answer stopped being easy. My usual line, the one I keep ending these pieces on, is that the diligence is the job: pin, lock, audit, and read the actual advisory instead of trusting a number. All of that still holds. But it just got more expensive, because the data underneath the diligence is thinner and, as it turns out, was shakier than we let ourselves believe.

So I’m not going to pretend there’s a clean fix. This problem won’t solve itself, and it won’t be solved by any one of us. It needs all of us to actually support the services we depend on, with money, with contributions, with attention, so the public goods that underpin our craft are still standing in ten years. That’s the dull, grown-up part.

But I’ll end this one looking up rather than down, because for once I can. I think the next few years bend towards safer software almost in spite of us. Modern languages are quietly closing off whole categories of vulnerability at the source: every memory-safety bug that a borrow checker refuses to compile is one that never reaches a database to be mis-scored in the first place, which is rather the point of building a framework that contains no unsafe. Used with proper guidance instead of left to spew slop, AI can be a genuine help finding and triaging the things that do slip through. And the junior engineers we keep sawing off the bottom rung are exactly the people who, mentored by the greybeards before they retire, could build the next generation of vulnerability identification that the current model clearly can’t sustain.

As for the vultures… it’s a coin toss. A lot of firms will look at the NVD on its back and see a land grab. I’d love to be proved an optimist and watch at least one of them stand tall, take all that better-resourced data and open it to open-source projects for nothing, because it’s the right thing to do and because the whole industry drinks from that well. One of them doing the decent thing would be worth more than all the press releases about responsible AI put together.

The catalogue is wobbling. The number was never as solid as we treated it. Neither of those is the end of the world, as long as we stop outsourcing our judgement to a free service we never funded and never checked, and start paying, in every sense, for the foundations we build on. Boring, unfashionable, and the only thing that ever works. I think we’re up to it.

The greybeards' edge was never typing

Wed, 27 May 2026 00:00:00 +0000

I have a retirement plan, and it is gloriously low-tech. A cabin, some trees, a woodstove, and a firm rule that no wifi symbol ever appears within a mile of me again. I think about it more than is probably healthy.

There’s a snag, though, and it’s the same one the whole industry is currently pretending it can’t see. For me to vanish into the woods, somebody has to be able to do my job after I’ve gone. And right now, collectively, we are working very hard to make sure nobody can.

The boost, and the drag

I wrote the other day about how AI made producing plausible work nearly free while verifying it stays expensive and human. Point that same lens at a team and something uncomfortable falls out. It isn’t mine; it belongs to Mark Russinovich and Scott Hanselman of Microsoft, who laid it out in Communications of the ACM: agentic coding tools give a senior engineer an AI boost, multiplying what they ship, because a senior has the judgement to steer and verify the output. The same tools give an early-career engineer an AI drag, because they don’t have that judgement yet, and the machine hands them far more rope than they can hold.

The cold incentive writes itself, and they name it: hire seniors, automate juniors. It isn’t hypothetical, either. Meta cut 8,000 roles last week, in a round the Times filed under mounting AI casualties. For any single quarter you care to look at, the maths is impeccable.

The bill is just deferred

Here’s the line the spreadsheet leaves off. The grindy work a junior used to cut their teeth on, the small fixes, the boring migrations, the read-the-stack-trace-and-figure-it-out, is exactly the work AI now does. So the proving ground is gone. And the entry-level seats where they’d have stood on it are the ones being cut. Squeezed from both ends at once: no reps, and nowhere to take them.

Russinovich and Hanselman put the consequence plainly. Without early-career hiring the talent pipeline collapses, and you arrive at a future with no next generation of experienced engineers. The seniors you’ll be desperate for in 2032 are the juniors you declined to train in 2026. The bill doesn’t vanish. It just falls due long after the people who cut the cheque have moved on.

How to manufacture a world of AI slop

I named the last piece for its villain; let me name this one’s too. Raise a generation that can produce with AI but was never taught to validate, and here is what you get: people shipping machine-built products at speed with no instinct for where the output is quietly wrong, because they never had to be wrong the slow way first. Software nobody genuinely understands, human-written and AI-written alike, and a steady leak of trust out of all of it.

That isn’t a productivity problem. That’s a world of AI slop, and not in one project’s inbox this time but everywhere at once. We’d have automated our way clean out of the one job AI cannot do for us: knowing when not to trust the machine.

It’s a choice, and it’s yours

Andrew Murphy put it with more bite than I’d quite dare: AI didn’t kill your junior pipeline, you did. He’s right. This isn’t weather. Nobody is making you do it. It’s a decision, taken quarter by quarter, and a decision is a thing you can take differently.

The fix isn’t complicated, it’s just unfashionable. Keep hiring early-career engineers. Say out loud that they cost you capacity at first, and treat their growth as an actual goal rather than something meant to happen by osmosis. Russinovich and Hanselman call it preceptorship at scale: senior mentorship, deliberately structured, turning the ordinary day’s work into teachable moments.

And the proving ground can be rebuilt, just not where it stood. If AI does the writing now, the apprenticeship moves to the reviewing. Put juniors in the loop on the machine’s output and have them hunt for the subtle wrongness, the way a scanner is an argument, not an order. That’s how judgement gets built now: not by grinding out the work, but by verifying it. Which, as luck would have it, is the single most valuable thing anyone on your team can learn to do.

The part that’s on the greybeards

This is where I stop letting the companies wear all the blame, because some of it is mine, and yours. Verification is a craft, and crafts pass from person to person or not at all. I know where every one of my own AI misfires comes from: I gave it too little context, or too much rope, and didn’t check the result closely enough. The tool rarely went rogue. The gap was always my diligence. That’s not a confession, it’s the curriculum, and it’s precisely the judgement a junior can only earn by sitting in the loop beside someone who has already made those mistakes.

So the senior engineer’s job has quietly changed underneath us. It was never really the typing. It was knowing when something is off, and what the customer actually needs, and now it is also handing that on, deliberately, while there’s still time to. Mentor and guardian first; fastest prompt in the room a distant second.

The ladder you’re standing on

There will always be something AI can’t do well enough, and for a good while yet it’s the thing that matters most: being the accountable human who genuinely understands what’s needed and can be held to it when it goes wrong. A simulation can be enormously convincing. It cannot be responsible.

Which brings me back to my cabin. I do want it one day, the trees and the woodstove and the blissful disconnection. But I only get to go if the work outlives me, and the work only outlives me if the people do. So the last useful thing my generation does, before we shuffle off to find our trees, isn’t shipping a little more code. It’s making sure there’s somebody left who can tell when the machine is wrong. Pull the ladder up behind us and there’ll be nobody to notice the rot, and no cabin quiet enough to make that sit right.

AI didn't kill curl's bug bounty. The bounty did.

Tue, 26 May 2026 00:00:00 +0000

In January, Daniel Stenberg shut down curl’s bug bounty. The headlines wrote themselves, and they all said the same thing: AI killed it. A flood of machine-generated slop drowned the maintainers, so they pulled the plug.

That’s true, as far as it goes. It’s also the wrong lesson, and the right one is sitting in plain sight in the same project, in the same few months.

Volume without validation is the attack

curl had run its bounty since April 2019. Over its life it paid out more than $100,000 for 87 genuine vulnerabilities, a thoroughly good return for one of the most depended-on pieces of software on the planet. Then the reports stopped being reports. The confirmation rate, the share of submissions that turned out to be a real bug, had historically sat north of 15%. By 2025 it was below 5%. Fewer than one in twenty submissions were worth anything, and the rest still had to be read.

That last part is the whole problem. A bogus report doesn’t announce itself. Someone has to open it, take it seriously, try to reproduce it, and work out that it’s nonsense, and that someone is a human being with a finite number of hours and a project to run. Stenberg put it plainly: the slop “take[s] a serious mental toll to manage and sometimes also a long time to debunk.” The submitter spends seconds. The maintainer spends an afternoon. Do that at volume and it stops being noise and becomes an attack, a denial-of-service aimed not at curl’s servers but at its maintainers’ attention. No exploit required. Just plausibility, in bulk.

The bounty was the accelerant, not the AI

So far this is the story everyone tells. Here’s where I get off the bus.

The instinct is to blame the AI for the slop. But look at what a bounty actually is. It’s a cash prize, and curl’s was priced for the thing it wanted: the hours and the judgement a skilled human pours into finding a real flaw. That pricing made complete sense right up until the cost of producing something that looked like a finding collapsed to nearly nothing.

That’s what AI changed. Not the supply of bugs. The supply of plausible-looking bug reports. Put a cash prize on “looks like a finding”, then make “looks like a finding” free to generate, and you haven’t got a bug bounty any more. You’ve got a slot machine. Stenberg said he’d started to sense “a bad faith attitude” in the reports, and of course he had. The incentive was openly inviting it.

So the death spiral was structural, not bad luck. The moment generating plausible reports went free, any cash bounty became a magnet for spray-and-pray, and the only open questions were how fast it would rot and whether you’d close the programme or just let the rewards quietly wither. The AI was the match. The bounty was the petrol. We have been pointing at the wrong one.

The proof: curl turned around and hired the AI

If AI were really the villain here, you’d expect curl to have slammed the door on it. It did the opposite.

In the same stretch, by AISLE’s own account, an AI security platform contributed 24 pull requests to curl, five of which earned CVEs, and the project now runs it internally for continuous review. The same tooling reportedly found all twelve zero-days in an OpenSSL release in late January. (Both of those are the tool-makers’ and a third party’s numbers rather than curl’s audited figures, so weigh them as such. But curl adopting the thing isn’t a claim. It’s a decision.)

Sit with the shape of that. curl shut down strangers being paid for AI-shaped noise, and in the same breath put AI to work as a tool its own maintainers drive. The two moves look contradictory only if you think “AI” is a single thing with a single verdict attached. It isn’t. Pointed at the problem by people accountable for the result, with no prize to farm, it found real bugs. Dangled in front of anonymous strangers chasing a payout, it produced sand.

The tell is which AI curl kept, and which it mocked

Stenberg drew that line about as sharply as a person can. When Anthropic put its security model, Mythos, in front of curl this spring, it scanned 176,000 lines of C and surfaced a single flaw, and Stenberg called the surrounding fanfare the greatest marketing stunt he’d seen. Same maintainer. Adopts one AI, rubbishes another.

The deciding factor was never whether the thing was AI. Both were. It was whether the output survived a human checking it, and whether you could check it at all. AISLE handed over pull requests and CVEs you could read and merge. Mythos arrived as a closed model and a press release, which is to say a claim the community has no way to independently test.

My bias, up front, because it runs the opposite way to what you’d expect from someone writing this: I’m a paying Claude subscriber and I lean on Anthropic’s models every working day, the one behind the spadework for this post included. I’m an advocate, not a sceptic, and AI genuinely has its place. That is exactly why the Mythos fanfare grates. Overselling a closed model to get out ahead of the competition, when the one test the public got to see turned up a single bug, is the sort of thing that chips away at trust in all of it. A result you can’t verify is marketing until proven otherwise, whoever’s logo is on the slide, and I’d rather the tools I depend on didn’t stoop to it.

The cheap half and the expensive half

Pull back from curl for a moment, because the lesson isn’t really about bounties at all. Anyone who works with these tools every day knows the same thing: when they go wrong, it’s rarely the model running off on its own. It’s the context it wasn’t given, the rope it was handed, the output nobody checked closely enough. The failure sits on the human side of the keyboard, at the one step that’s easiest to skip, which is verification.

That’s the pattern curl hit at the scale of an ecosystem. AI made one thing nearly free: producing work that looks right. It did not make the other thing a penny cheaper: confirming the work is right. That cost still falls, in full, on a person. (A scanner, I’ve argued before, is an argument, not an order; the same goes double for a model.) The bounty’s fatal mistake was paying for the cheap half and quietly assuming it had bought the expensive one. The same trap waits in code review, in hiring, in CVs read by machines, but that’s a bigger argument for another post.

Pouring sand into the machine

curl didn’t capitulate to AI, whatever the headlines decided. It stopped paying for the worthless half and started using the valuable half, and it had the discernment to tell a useful tool from a press release while it did so.

The bounty wasn’t a casualty of artificial intelligence. It was a structure that, the instant plausible output became free, could only fill with sand. Stenberg said he hopes closing it stops “more people pouring sand into the machine.” Reading the last year of his inbox, I think he’ll get his wish. The sand was only ever there because somebody left a bucket of money beside the funnel.

Building a CLI with go-tool-base, part 4: an AI dungeon master

Sat, 23 May 2026 00:00:00 +0000

I run a Dungeons & Dragons game on the odd weekend, so when I sat down to put an AI feature inside a CLI, my first instinct wasn’t a chatbot. It was: could the tool run a little adventure, with an AI as the dungeon master? It turns out that’s a near-perfect way to learn the chat client, because the thing that makes a game trustworthy, rules the players can’t break, is exactly the thing that makes any AI feature trustworthy. So this part builds mytool adventure: a tiny dungeon you play in your terminal, narrated by an AI that is firmly on a leash.

Part 3 pointed AI at your CLI from the outside (an agent driving your commands over MCP). This part goes the other way: AI inside your tool, as a feature you write. The worry everyone has about that is fair, AI output is unpredictable, and a CLI is meant to be dependable. The whole lesson here is how you square those two: you don’t hope the model behaves, you box it in with rules it can’t escape and mechanics it doesn’t get to invent.

As before, this is written against go-tool-base v0.6.0 (gtb version).

Behind the DM screen

A turn of our game looks like this: the player types what they want to do, the AI dungeon master narrates what happens and offers a few choices, and round it goes until the adventure reaches an end. The trick is where the truth lives. The model’s job is the prose, and only the prose. Everything else is yours:

The rules live in the system prompt: what the DM may and may not do.
The mechanics live in Go functions the model calls as tools (dice, combat). It never makes a number up.
The state lives in a Go struct you hand the model fresh every turn, so it never has to remember, and can’t quietly rewrite history.
The shape of each turn is a typed Go struct the model fills in, so your code always gets back something it can render, never a wall of prose to parse.

Two go-tool-base capabilities do the heavy lifting: the AI calling your Go functions, and the AI handing back a typed struct instead of text you have to regex. The game is just a fun excuse to use both at once.

Wiring a provider

The chat client (pkg/chat) is a library you import; you don’t need any special feature flag for it. It does need an API key, and it’ll find one from a few places. The simplest, for now, is the well-known environment variable for your provider:

export ANTHROPIC_API_KEY="sk-ant-..." # or GEMINI_API_KEY, OPENAI_API_KEY

That’s the bottom of the client’s lookup chain, which is fine for playing locally. For a tool you actually ship, go-tool-base has the ai feature and its mytool init wizard (the same initialiser system from part 2) to store the key properly, and there’s a whole post on where a CLI should keep your keys. For learning the client, an env var is plenty.

Scaffold the command

You know this step from part 1:

gtb generate command --name adventure --short "Play a dungeon adventure"

Everything below goes in the RunAdventure function the generator left you in pkg/cmd/adventure/main.go, plus a couple of types and helpers in the same package.

The state is yours, not the model’s

Start with the truth. The game state is a plain Go struct that you own. The model never holds it; instead you hand it the current state at the top of every turn (more on that in the loop). This is the part to grow: start small, then add rooms, items, NPCs, quest flags, whatever your adventure needs. Nothing else in the design has to change when you do.

// GameState is the single source of truth for the game. Extend it freely.
type GameState struct {
	PlayerHP int
	Location string
	Inventory []string
	Foes map[string]int // foe name -> remaining hit points
}

// summary renders the state into a line the model is given each turn.
func (g *GameState) summary() string {
	foes := make([]string, 0, len(g.Foes))
	for name, hp := range g.Foes {
		foes = append(foes, fmt.Sprintf("%s (%d HP)", name, hp))
	}
	return fmt.Sprintf("You have %d HP, at %s, carrying %s. Foes: %s.",
		g.PlayerHP, g.Location, strings.Join(g.Inventory, ", "), strings.Join(foes, ", "))
}

And the shape of a turn, the thing the model has to produce:

type Turn struct {
	Narration string `json:"narration"`
	Choices []string `json:"choices"`
	GameOver bool `json:"game_over"`
}

The dungeon master’s tools

A tool in pkg/chat is a chat.Tool: a name, a description the model reads to decide when to use it, a parameter schema, and a handler. The handler gets the model’s arguments as raw JSON and returns any value (which the framework JSON-encodes back to the model) or an error.

The simplest possible one is a die roll. This is the canonical “give the model something it’s bad at” tool, because language models cannot be trusted to roll fairly or even add up:

func rollTool() chat.Tool {
	return chat.Tool{
		Name: "roll",
		Description: "Roll a die with the given number of sides; returns 1..sides.",
		// Use an anonymous struct so the schema's properties sit at the top level,
		// which is where SetTools looks. A named type would hide them behind a $ref.
		Parameters: jsonschema.Reflect(struct {
			Sides int `json:"sides" jsonschema:"description=number of sides on the die"`
		}{}),
		Handler: func(_ context.Context, args json.RawMessage) (any, error) {
			var a struct {
				Sides int `json:"sides"`
			}
			if err := json.Unmarshal(args, &a); err != nil {
				return nil, err
			}
			if a.Sides <= 0 {
				a.Sides = 20
			}
			return rand.Intn(a.Sides) + 1, nil
		},
	}
}

That comment about the anonymous struct matters, by the way. Reflect a named type and jsonschema emits a top-level reference with the real fields tucked inside, and the tool ships with no parameters at all. An anonymous struct inlines them where the framework expects. It’s the one sharp edge in the whole exercise.

Combat is where state actually changes, so combat is a tool too. Note it takes the foe by name and looks it up in Foes, so it works for the goblin and for any creature you add later, without touching this function:

func attackTool(game *GameState) chat.Tool {
	return chat.Tool{
		Name: "attack",
		Description: "Resolve the player's attack on a named foe. Rolls to hit, applies damage.",
		Parameters: jsonschema.Reflect(struct {
			Target string `json:"target" jsonschema:"description=the name of the foe being attacked"`
		}{}),
		Handler: func(_ context.Context, args json.RawMessage) (any, error) {
			var a struct {
				Target string `json:"target"`
			}
			if err := json.Unmarshal(args, &a); err != nil {
				return nil, err
			}
			hp, ok := game.Foes[a.Target]
			if !ok {
				return map[string]any{"error": "no such foe: " + a.Target}, nil
			}
			if rand.Intn(20)+1 < 10 {
				return map[string]any{"hit": false, "foe": a.Target}, nil
			}
			dmg := rand.Intn(6) + 1
			hp -= dmg
			if hp < 0 {
				hp = 0
			}
			game.Foes[a.Target] = hp
			return map[string]any{
				"hit": true, "foe": a.Target, "damage": dmg,
				"foe_hp": hp, "defeated": hp == 0,
			}, nil
		},
	}
}

A bad target comes back as a plain error string, which the framework hands to the model so it can recover (apologise, pick a real foe) rather than crash.

That’s the whole tool set, and there’s deliberately nothing here for reading the state. The model never fetches it. Instead the loop hands it the current state at the top of every turn, which we wire up shortly. A language model has no memory you can rely on, so rather than trust it to remember the fight, you give it the truth each time.

The turn is a tool too

Here’s the neat part. The chat client won’t let a single call both run tools and return a typed struct, they’re separate modes. So instead of asking for the struct afterwards, we make submitting the turn into a tool of its own. The dungeon master ends its turn by calling submit_turn, and its handler captures the typed Turn into a variable we hold:

func submitTurnTool(out *Turn) chat.Tool {
	return chat.Tool{
		Name: "submit_turn",
		Description: "End your turn. Call this exactly once, last, with the turn's outcome.",
		Parameters: jsonschema.Reflect(struct {
			Narration string `json:"narration" jsonschema:"description=two-sentence narration of what just happened"`
			Choices []string `json:"choices" jsonschema:"description=the actions the player may take next"`
			GameOver bool `json:"game_over" jsonschema:"description=true only if the game has ended"`
		}{}),
		Handler: func(_ context.Context, args json.RawMessage) (any, error) {
			if err := json.Unmarshal(args, out); err != nil {
				return nil, err
			}
			return "turn recorded", nil
		},
	}
}

So the turn’s structure is enforced by a schema, same as any other tool’s parameters. Your loop gets a populated Turn every round, never prose.

The rules

This is where you bound the model. The system prompt is the rulebook, and it leans hard on the tools so the DM has no room to freelance the mechanics:

const dmRules = `You are the dungeon master of a short fantasy adventure. Each turn
you are given the current game state and the player's action.

Resolve the action and end the turn:
- If the player attacks, you MUST call the attack tool with the foe's name to
 resolve it. Do not decide the hit or the damage yourself.
- For any other chance event, call the roll tool and use its result.
- For simple actions, just narrate them.
- Then call submit_turn exactly once: a two-sentence narration, two or three
 choices, and game_over.

Trust the state you are given; never contradict it. A foe at 0 hit points is dead
and stays dead. The game ends when the player's hit points reach 0 (they lose), or
when the player reaches a satisfying ending. When it ends, set game_over and narrate
the finish.

Keep the tone light and quick.`

Two of those lines carry the weight. Trusting the state you are given, and never contradicting it, is what keeps the world consistent: the state is handed in fresh every turn (the next section), so the model works from the truth instead of from a memory it does not reliably have. And you MUST call the attack tool is what stops it quietly deciding hits and damage itself when it would rather just narrate. Those two are the difference between a game with rules and a model telling a story.

The loop

Now stitch it together. Create the client with the rules as its system prompt, register the tools once, and run a turn each time the player acts:

func RunAdventure(ctx context.Context, props *props.Props, opts *AdventureOptions, args []string) error {
	game := &GameState{
		PlayerHP: 20,
		Location: "the mouth of a damp cave",
		Inventory: []string{"a short sword", "a guttering torch"},
		Foes: map[string]int{"goblin": 12},
	}
	var turn Turn

	client, err := chat.New(ctx, props, chat.Config{
		SystemPrompt: dmRules,
		MaxSteps: 8, // roll/attack, then submit_turn
	})
	if err != nil {
		return err
	}

	if err := client.SetTools([]chat.Tool{
		rollTool(),
		attackTool(game),
		submitTurnTool(&turn),
	}); err != nil {
		return err
	}

	action := "I step into the cave."
	for {
		turn = Turn{}
		// Hand the model the current truth, then the player's action.
		input := fmt.Sprintf("State: %s\nThe player: %s", game.summary(), action)
		if _, err := client.Chat(ctx, input); err != nil {
			return err
		}

		fmt.Println("\n" + turn.Narration)
		if turn.GameOver {
			return nil
		}
		action, err = chooseAction(turn.Choices)
		if err != nil {
			return err
		}
	}
}

The same client runs every turn, so the conversation and the tools carry through the whole game; and the State: line you prepend is always current, because the attack tool mutated game last turn. The model is never trusted to remember, only to narrate.

The one helper I glossed is chooseAction. A bare fmt.Scanln would do, but we can do much better with almost no effort, and make a point while we’re at it. The framework already leans on Charm’s huh for its init wizard, you met it in part 2, so we’ll use the same library for a proper menu, with one deliberate addition:

func chooseAction(choices []string) (string, error) {
	const other = "__other__"

	opts := make([]huh.Option[string], 0, len(choices)+1)
	for _, c := range choices {
		opts = append(opts, huh.NewOption(c, c))
	}
	opts = append(opts, huh.NewOption("Something else...", other))

	var pick, custom string
	form := huh.NewForm(
		huh.NewGroup(
			huh.NewSelect[string]().
				Title("What do you do?").
				Options(opts...).
				Value(&pick),
		),
		// A second step that only appears when the player chose "Something else".
		huh.NewGroup(
			huh.NewInput().
				Title("Describe your action").
				Value(&custom),
		).WithHideFunc(func() bool { return pick != other }),
	)
	if err := form.Run(); err != nil {
		return "", err
	}

	if pick == other {
		return custom, nil
	}
	return pick, nil
}

The select gives the player a tidy arrow-key menu instead of typing a number, but the addition that earns its keep is the last option. “Something else…” is always there, and choosing it unfolds a second step (huh shows or hides a group with WithHideFunc) where the player types whatever they actually want to do. That free text goes straight to the dungeon master as the next turn’s input, and because the DM is an AI bound by the rules rather than a switch statement over three fixed choices, it just copes. Bargain with the goblin, search your pockets, set the cave alight: the model narrates it within the rules you gave it, rolling and applying damage through the same tools. That is the agency a scripted game can’t offer, and it’s the natural place to start building your own richer interactivity on top.

Play it

Set your key, build, and go:

export ANTHROPIC_API_KEY="sk-ant-..."
just build
./bin/mytool adventure

A turn looks like this (your wording will differ every time; the mechanics won’t):

You swing your short sword at the goblin, the blade whistling through the damp cave
air. The creature snarls as it tries to dodge your blow.

What do you do?
> Attack the goblin again
 Try to push deeper into the cave
 Retreat to the entrance
 Something else...

Your blade whistles through the air, but the nimble goblin dances back just in
time. It lunges forward with a rusty dagger in return, yet its clumsy strike only
finds empty air.

What do you do?
> Swing your sword again!
 Try to intimidate the creature
 Retreat from the cave
 Something else...

Behind that, the dungeon master called attack each turn (a hit, then a miss), the goblin’s hit points changed in the GameState you own, and the next turn handed that updated state straight back to the model. The prose is the model’s; every number is yours.

The pattern under the game

Strip the dungeon away and you’re left with the thing worth keeping. An AI feature you can ship is one where you’ve kept the model away from everything that has to be right: the rules live in the system prompt, the mechanics in typed Go tools the model must call, the state in a struct you hand it fresh each turn rather than trust it to remember, and the output in a struct it fills in rather than free text. Do that and the model’s unpredictability is confined to exactly where you want it, the wording, and walled out of everywhere you don’t, the maths, the state, the shape of the result.

Two honest limits worth knowing. There’s no temperature dial on the client (the setting that would let you turn the model’s randomness down), so you can’t make the prose reproducible; you make the mechanics reproducible instead, which for most features is what you actually needed. And a tool calling loop is several round-trips to the model per turn, so it’s not free, keep MaxSteps tight for anything interactive.

That’s the foundation, and the state struct is already sized for more than one fight: it carries a location, an inventory and a map of foes you’ve barely touched. Add a move tool that updates Location, a use_item tool that reaches into Inventory, a second creature in Foes, even a give_quest flag, and the adventure grows without the architecture changing. The model just gets more tools to call and more truth to read. Saved games come nearly free, too: the client can snapshot and resume a conversation. Next part leaves AI behind and gets the tool ready to look after itself: shipping signed self-updates, so a new release reaches your users safely. Until then, go explore the cave.

Building a CLI with go-tool-base, part 3: expose your CLI to AI agents

Fri, 22 May 2026 00:00:00 +0000

“Make it work with AI” is the request that lands on your desk with a thud and no further detail. The first time it landed on mine I braced for a treadmill of integration work: an adapter for this assistant, a wrapper for that one, one per client, forever. Then I looked at the hello command we built back in part 1. It has a name, a one-line description, and (once you give it some) typed, documented flags. That is exactly the shape an AI agent needs to call a tool. You already did the hard part.

This part wires that up: turning the CLI you’ve been building into something an AI assistant can drive, with no AI code of your own. The how-it-works behind it is in your CLI is already an AI tool; here we just use it.

A version note, as in the earlier parts: this is written against go-tool-base v0.6.0 (gtb version). The tool is young and moving, so if you’re on a newer release and a command or its output has shifted, check there first.

The translator you already have

An AI agent that wants to call local tools needs three things: a list of named operations, a description of each so it knows when to reach for them, and a typed parameter schema for each so it knows how to call them. A good CLI is already all three. The only missing piece is a translator between “this is a CLI” and “this is a set of tools an AI can call”, and that translator is the Model Context Protocol (MCP), an open standard every serious assistant now speaks.

Your tool already ships it. mcp is one of the default features, so it’s been in your binary since you scaffolded in part 1, no flag required. Check:

./bin/mytool mcp --help

You’ll see subcommands you never wrote. The rest of this part is just three of them.

See what the agent sees

Before you connect anything, look at what your tool would expose. This writes the tool definitions to a file:

./bin/mytool mcp tools

{
 "tools": [
 {
 "name": "mytool_hello",
 "description": "Say hello",
 "inputSchema": {
 "type": "object",
 "properties": {}
 }
 }
 ]
}

That’s your hello command, seen from an agent’s side of the glass. The name is your tool’s name and the command path joined with an underscore; the description is the Short you gave it in part 1; the inputSchema is empty because hello has no flags yet. Add a flag and it shows up here as a property, with the type and help text you already wrote. There’s no second schema to keep in sync, because the command tree is the schema.

A few things are deliberately left off this list: hidden and deprecated commands, pure command groups that don’t do anything themselves, and the mcp, help and completion plumbing. So mcp tools doubles as an audit: it’s exactly what an agent can reach, and nothing else.

Run the server

One command turns the whole thing on:

./bin/mytool mcp start

It doesn’t print a banner and march off doing things. It sits quietly, speaking MCP as JSON-RPC over standard input and output, waiting for an assistant to talk to it. You won’t run this by hand much; the assistant launches it for you. But it’s worth knowing what happens when the agent calls one of your tools: the server re-runs your own binary with the arguments the agent supplied, captures the output, and hands it back. The agent isn’t poking at your internals. It’s running mytool hello, the same command a human would, and getting the same result.

Point an assistant at it

The quickest way is to let the tool write the client config for you. For Claude Desktop:

./bin/mytool mcp claude enable

There are cursor and vscode variants too. Restart the assistant and your CLI is in its toolbox.

If you’d rather wire it by hand (or your client isn’t one of those three), the config is small. Point the client at your binary with mcp start as its arguments, using the absolute path:

{
 "mcpServers": {
 "mytool": {
 "command": "/absolute/path/to/bin/mytool",
 "args": ["mcp", "start"]
 }
 }
}

Claude Desktop keeps that in claude_desktop_config.json (under ~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows); Cursor uses ~/.cursor/mcp.json; VS Code’s Copilot reads github.copilot.mcpServers in your settings. The shape is the same everywhere. From here, ask the assistant to say hello and watch it call mytool_hello.

The agent’s reach is exactly your CLI’s reach

This is the part worth being calm about. Exposing your CLI over MCP doesn’t widen its surface by an inch. The agent can call the commands you shipped, with the parameters you defined, and nothing else. It can’t invent a command or pass a flag you never wrote. The boundary of what it can do is the boundary you drew when you built the tool, and mcp tools shows you that boundary in full. If there’s a command you don’t want an agent touching, mark it hidden and it drops off the list.

For a long-running or remote setup there’s also ./bin/mytool mcp stream, which serves the same tools over HTTP instead of stdio; the mcp reference has the details. For most desktop assistants, start over stdio is all you need.

What it comes down to

You turned the CLI you’ve been building into an agent-callable tool with one command and zero lines of AI code, because the real work, naming your operations and documenting their inputs, you finished the moment your --help was any good. Every command you add from here is a new tool the agent gets for free.

Next part goes the other way: instead of letting an assistant drive your tool from outside, we put AI inside it, wiring up a provider and building a feature against go-tool-base’s chat SDK. Until then, add a command or two and watch them appear in mcp tools. The agent’s toolbox grows as your CLI does.

Technical CV writing is still hard, and now a robot reads it first

Fri, 22 May 2026 00:00:00 +0000

Seven years ago I wrote a post called Technical CV writing is hard, pulled my own CV apart, and explained every choice in it. I even bragged that it converted to a first interview about eighty per cent of the time, then added “watch me now jinx myself for the future”. Reader, I jinxed myself. I’m back on the market, the same CV that served me for two decades went out into the world, and what came back was a sort of stunned silence. Not even rejections. Just nothing.

The CV that suddenly stopped working

The thing about that silence is how specific it was. Some applications behaved exactly as they always had: a human read the CV, liked it or didn’t, and replied like a person. Others went into a void. And the void had a pattern to it. It was the bigger, more process-heavy outfits, the ones you’d bet good money have an Applicant Tracking System and an “AI-assisted screening” line item in some HR budget.

That’s when the penny dropped. My CV wasn’t failing to impress anyone. It wasn’t reaching anyone. The first thing reading it wasn’t a person at all.

The reader changed, and I hadn’t noticed

I’ve made this exact point on this blog before, only about software: half your users don’t have eyes. A CLI tool’s output has two audiences, the human at the terminal and the script parsing the output, and they want completely different things. It turns out a CV is now precisely the same. It has two readers, and the first one is a machine.

A human recruiter reads a CV the way I designed mine to be read: narrative, personality, a sense of the person. An ATS or an AI screen does nothing of the sort. It parses for structure, for keyword density, for recency, for numbers it can latch onto. My CV was a beautifully tailored sales pitch aimed squarely at a human who, increasingly, never gets to see it, because a parser in front of them scored it and quietly binned it first.

Everything that made it a good human document was, to the machine, either invisible or actively confusing.

So I asked an AI what the AI hated

There’s an irony here I’m choosing to enjoy rather than resent. The way I worked out what the filters object to was to sit down with Gemini, hand it my CV, and ask it to read the thing the way a recruitment AI would and tell me where it tripped. Using one AI to get past another. Fight fire with fire.

The one instruction I was firm about, and I’ll come back to it, was that the CV had to stay recognisably me. I wasn’t asking Gemini to launder my career into something generic and machine-shaped. I was asking it to help me keep as much of my own voice and judgement as possible, while making the thing easier for an AI to approve and a human to enjoy. There’s a practical edge to that, too: the screening tools are increasingly tuned to spot the patterns of generated text and weight them down, so a CV that reads as though a model wrote it can trip the very filter you were trying to please, quite apart from leaving the human at the end of it cold.

With that ground rule set, the hurdles it surfaced were genuinely illuminating, and a bit humbling given I’d written a whole confident blog post about how to do this.

The skills tables are worse than useless. My CV led with two lovely tables: Management Skills and Technical Skills, each with a level and years of experience. Clean and scannable for a human. To a lot of parsers, a table is a trap: they flatten it into a jumble and lose the structure entirely. Worse, listing “20+ years” against nearly everything triggers what I can only call the recency trap. Modern screening looks for skills that show up in your recent job descriptions, not in a header table. A language sitting in my skills table but not in my last two roles reads as stale or unverified, no matter how many years I claimed next to it. Gemini put it plainly: “if a tool sees Golang in a top table but doesn’t see it explicitly mentioned in your last two job descriptions, it assumes the skill is stale or unverified.”

“I have a passion for what I do” is noise. My opening profile statement, which I was rather proud of, is exactly the sort of thing a screening tool discards wholesale. As Gemini noted, these tools “completely ignore subjective self-assessments … because they cannot be measured or verified.” It wants a dense, factual summary full of the nouns it’s searching for, right at the top.

My numbers thin out the further back you go. My recent roles are full of the data these tools love: a 75% reduction in deployment times, three thousand-odd Kubernetes clusters, a GitLab instance with four hundred thousand repositories. My older roles, written years ago in a more narrative style, are all “oversaw the delivery of solutions” with not a metric in sight. The machine reads that as a career that got vaguer over time, which is the opposite of true.

Four pages is at least two too many. Parsers weight the first page or two most heavily. My education and the foundational stuff sat on pages three and four, where the algorithm barely bothers to look.

It couldn’t work out what I am. This was the sharp one. With “pre-sales”, “client management” and “Managing Director” sitting next to deep technical keywords, the classifier genuinely can’t decide whether I’m a commercial manager who used to code or a hands-on engineer who drifted into management. As Gemini described it: “the algorithm gets confused … It struggles to classify you: Are you a commercial manager who used to code, or a hands-on techie who got pushed into management?” So it does the safe thing and matches me to neither.

What I’m actually changing

Knowing the hurdles, here’s what the rebuild looks like. This is the part I want to be useful, so it’s concrete.

The tables are gone. In their place is a “Core Expertise” section, plain text the parser can read, grouped so my leadership sits next to my technical stack. And I’ve done the thing 2019-me was too much of a show-off to do: tiered it honestly. Instead of “Expert+” against everything, there’s a primary tier of what I actually do day to day, a proficient tier I can deploy without blinking, and a frank “familiar, not current” tier for the languages I last touched in anger a decade ago. That honesty isn’t just decency. A wall of “expert at everything” reads as noise to a machine and as bluster to a human, and I’d been doing both.

The subjective profile is replaced with a keyword-rich professional summary that says, in the first two lines, exactly what I am and at what scale.

The keywords that mattered have been woven down into the recent role bullets, so the parser sees them where it trusts them. And I’ve reframed the people-management and pre-sales language toward technical enablement and architectural advisory, because what I’m actually chasing is the technical-leader sweet spot: the person who owns the architecture and mentors the engineers, without the HR admin and the sales pitches. The CV now points at that, deliberately, so the classifier stops dithering.

There’s also a more personal beat in here. A previous employer handed me a role with a “VP” title, sold to me as exactly the technical-leadership job I’d been chasing. It wasn’t. The title turned out to be a pay-grade bracket rather than a description of the work, the work itself was hands-on firefighting with little of the leadership or empowerment I’d been promised, and I moved on within a few months. To a screening AI, that pairing is doubly awkward. A “VP” title files me as a meeting-heavy executive and rules me out of the hands-on Principal and Lead roles I actually want, and a sub-six-month stint trips the flight-risk flag that some trackers quietly score you down for. So the fix is to stop letting the inflated label do the talking: describe the functional reality of the work, retitle it to the technical track it actually was, and let the scale of what I wrestled with speak instead of the job title. Titles, it turns out, are for the pay band. The bullets are for the truth.

Keeping myself in it

Back to that ground rule. Every one of these changes is in service of getting past the machine to the human behind it, and neither reader is well served by a CV with the person scrubbed out of it. The screen, increasingly, is trained to notice generic generated phrasing and mark it down; the human, always, would rather read something with a pulse. So the keywords go in, the structure gets fixed, the metrics come forward, and the voice stays mine. No “results-driven synergistic leveraging of cross-functional paradigms” that nobody would ever say out loud. That was the whole point of doing it this way: let the AI help reshape the structure a parser cares about, while the words stay mine, so what comes out is easier for a machine to approve, easier for a human to enjoy, and still unmistakably written by me. Optimising for the filter and sounding like myself turned out not to be in conflict at all.

I genuinely don’t know if this works yet

Here’s the part that makes this a post and not a victory lap. I don’t know if any of this lands. The old CV converted at around eighty per cent, on my own possibly-generous reckoning, right up until it abruptly didn’t. The new one is going out now, into the same market and the same filters that were stonewalling me a fortnight ago.

So this is a promise as much as a post. I’m going to keep count, the way I should have all along, and come back with the actual numbers: did reshaping my CV for a reader with no eyes genuinely move the needle, or did I just make it uglier and learn nothing? Either way you’ll get the truth, because a follow-up that only reports good news isn’t worth writing. Watch this space, and if you’re sending CVs into the same silence, maybe try reading yours the way a machine would first. It’s a deeply odd exercise, and I suspect it’s now an essential one.

Supporting a provider, or actually using it

Sat, 02 May 2026 00:00:00 +0000

If your CLI tool talks to an AI model, you don’t want to hard-wire one vendor. So you reach for a single client interface over several providers, which is the right call. The trap is the next step: build that interface on only what every provider has in common, and you quietly throw away the very features that made you want a particular provider in the first place. rust-tool-base’s rtb-ai refuses to make that trade.

The pull toward one interface

If your CLI tool talks to an AI model, hard-wiring one vendor is a poor bet. One user has an Anthropic key, another an OpenAI key. Someone’s on Gemini. Someone runs Ollama locally because their data can’t leave the building. Someone points at an OpenAI-compatible endpoint from a provider you’ve never heard of. You don’t want a separate code path for each, so you want one AiClient that all of them slot behind.

rtb-ai gets that unification from the genai crate, which already speaks to Anthropic, OpenAI, Gemini, Ollama and OpenAI-compatible endpoints. One interface, five providers, the tool author picks one in config. The Go sibling makes the same bet: go-tool-base’s chat package also unifies several providers, behind an interface deliberately kept to four methods. So far this is the obvious design, and if it were the whole design there’d be nothing to write about.

What “unified” quietly costs you

Here’s the catch in any unified interface. It can only expose what every provider behind it has in common.

The common subset is plain chat. Messages go in, text comes out, optionally streamed token by token. That’s real and it’s useful and every provider does it. But the common subset is also the floor, and the features that make a particular provider worth choosing are almost never on the floor. They’re the things only that provider does.

Anthropic is the sharp example, because it has three features that matter and not one of them is common-subset.

Prompt caching. You can mark the stable parts of a request, the system prompt and the tool list, as cacheable. The provider keeps them warm, and on the next turn you aren’t billed to re-send and re-process text that didn’t change. On a long agent loop, where the same large system prompt rides along on every single turn, that’s a substantial saving in both cost and latency.

Extended thinking. The model works through a hard problem in a visible, budgeted reasoning pass before it commits to an answer, and you can see that reasoning.

Citations. Structured references back to source material in the response.

A client built strictly on the common subset can’t express any of those. It has no field for them, because four of the five providers wouldn’t know what to do with the field. So a purely lowest-common-denominator client would “support” Anthropic and then use it badly, leaving its best features unreachable. Support as a checkbox, not as the point.

The escape hatch

rtb-ai’s answer is to not choose. It runs two implementations under one interface.

For OpenAI, Gemini, Ollama and OpenAI-compatible endpoints, calls route through genai, the unified path. For Anthropic, every method drops to a direct reqwest implementation straight against the Messages API. Same AiClient on the surface, a different implementation underneath, selected by which provider the config names.

And the request type has deliberate room for the difference:

pub struct ChatRequest {
 pub system: Option<String>,
 pub messages: Vec<Message>,
 pub temperature: Option<f32>,
 pub max_tokens: Option<u32>,
 /// Anthropic-only: enables prompt caching at every stable point.
 /// Ignored on non-Anthropic providers.
 pub cache_control: bool,
 /// Anthropic-only: extended-thinking budget. `None` disables.
 /// Ignored on non-Anthropic providers.
 pub thinking: Option<ThinkingMode>,
}

Set cache_control and the Anthropic-direct path inserts cache breakpoints at the three stable points: the system prompt, the tool list, and the first message. Set thinking and it adds the thinking block, and streaming surfaces a separate ThinkingToken event so you can show the reasoning apart from the answer. On a non-Anthropic provider, both fields are simply ignored. The interface carries them; only the implementation that understands them acts on them.

A hatch, not a leak

It’s worth being precise about why this isn’t the thing it superficially resembles, which is a leaky abstraction.

A leaky abstraction is one where implementation details bleed through that you didn’t intend and can’t reason about. The abstraction quietly fails to abstract, and you’re left guessing which provider you’re really talking to.

This is the opposite of that. The two Anthropic-only fields aren’t a leak. They’re named, documented as Anthropic-only, inert everywhere else, and right there in the public type for anyone to see. The interface is uniform for the common case and deliberately, visibly non-uniform at exactly the points where uniformity would have cost you the good features. You opt into provider-specifics by setting a field. You stay fully portable by leaving it at its default. Nothing bleeds; you decide.

The same design line explains what does stay in the unified path. Structured output, chat_structured::<T>, sends a JSON Schema derived from your Rust type with the request and validates the reply against it before handing you a typed T. That’s a portability win that costs nothing across providers, so it belongs in the common interface. The split isn’t “Anthropic versus the rest”. It’s “features that are free to unify go in the unified path; features that aren’t get a designed door”. Prompt caching and extended thinking get the door, because flattening them away would be the expensive kind of convenient.

To sum up

A CLI tool that integrates AI wants one client over several providers, and a unified interface can only expose what those providers share. The shared floor is plain chat, and the features worth choosing a provider for, like Anthropic’s prompt caching, extended thinking and citations, are never on the floor.

rtb-ai keeps both. genai provides the unified path across five providers; an Anthropic-direct reqwest path drops below the abstraction for the features genai can’t reach, and ChatRequest carries the Anthropic-only fields openly, ignored elsewhere. Uniform where uniformity is free, with a designed escape hatch where it isn’t. That’s the difference between supporting a provider and actually using it.

A configurable AI endpoint is an attack surface

Sun, 19 Apr 2026 00:00:00 +0000

“Let users point at their own AI endpoint” is one of those config options that looks completely harmless on the way in. People want it, for perfectly good reasons. Then you sit with it for a minute and realise you’ve handed every user a loaded gun and pointed it vaguely at their own API key.

Why you offer it at all

There are real reasons to let someone set a custom base URL. They’re running a local model and want localhost:11434. They’re behind a corporate proxy that fronts the real provider. They’re on Azure’s flavour of OpenAI, which lives at a different host. They’ve a self-hosted gateway doing rate-limiting. All reasonable, all things a framework should support rather than fight.

The bit that’s a loaded gun

Here’s what the config option quietly decides: the base URL is where your credential goes. The API key rides along in an Authorization header on every request, to whatever host that URL resolves to. So the moment the endpoint is user-configurable, the destination of your secret is user-configurable too.

And users do user things. They paste a URL from a gist that turned out to be a honeypot. They leave http:// on the front, so the key crosses the wire in plaintext. They copy https://user:token@host/v1 not realising the userinfo changes who they actually authenticate to. They never edit the https://api.example.com/v1 placeholder and wonder why the key’s been posted to a domain they don’t own. None of that is malice. It’s what happens when the destination of a secret is a free-text field.

Validate before the first byte leaves

So every chat.New routes through ValidateBaseURL before the provider is built. The threat model is written at the top of pkg/chat/baseurl.go: an operator who can influence config could “redirect chat-provider traffic to an attacker-controlled HTTPS host and capture the Authorization header.” The checks run cheapest-first: a length cap, no ASCII control characters, must parse, no userinfo, https only, a host must be present, and the host mustn’t be a placeholder.

The userinfo rule is the sharp one:

if parsed.User != nil {
	// Reject any userinfo, with or without password. Never log
	// the URL itself because it contains the credential.
	return errors.WithHint(ErrInvalidBaseURL,
		"base URL must not contain credentials; use the Token field instead")
}

The placeholder check rejects example.com and friends and any subdomain of them, so the unedited https://api.example.com/v1 from a setup wizard never reaches the wire and hits some typosquatted lookalike. And the HTTP escape hatch is test-only by construction: the AllowInsecureBaseURL field that permits plain http is tagged json:"-", so a config file physically cannot set it. This all came out of the 2026-04-17 security audit, finding M-3.

rust-tool-base enforces the same at its own boundary: validate_base_url rejects userinfo, any scheme but https (bar a test-only allow_insecure), and documentation placeholder hosts like example.com.

What it can and can’t do

It won’t stop a user who deliberately points the tool at a malicious HTTPS host they genuinely chose. If someone is set on sending their own key somewhere bad, validation can’t read their mind.

What it stops is the accidents: the plaintext slip, the userinfo confusion, the placeholder nobody changed. Those aren’t theoretical, they’re the ones that happen to careful people on ordinary days. Storing the key well is one job (where a CLI keeps it), stopping it leaking through a log is another, and this is the third side of the triangle: once you’ve stored it and stopped it leaking, make sure you don’t send it somewhere daft.

Testing code that calls an LLM: yes, you actually can

Wed, 08 Apr 2026 00:00:00 +0000

“You can’t test code that calls an AI.” I’ve heard it said with great confidence, and it’s half right, which is the most dangerous kind of right. You genuinely can’t assert on what a non-deterministic model says. But the model isn’t your code, and the bits sitting either side of it most certainly are.

“You can’t test AI code”

It’s a fair worry. Your command calls an LLM. The LLM returns something slightly different every run. A test that asserts response == "..." is broken before you’ve finished typing it. So the conclusion arrives quickly: the AI path can’t be tested, leave it uncovered.

Which is a shame, because the AI call is usually the riskiest line in the whole command.

The conclusion is also wrong. It mistakes “I can’t test the model” for “I can’t test my code”. The model is not your code. Your code is the two pieces sitting on either side of it.

Your code is a prompt and a handler

Strip the command down to what it actually does:

It builds a prompt. It assembles a system prompt, the user’s input, perhaps some context, and sends it.
The model does something. This is not your code.
It takes the response and does something with it. It parses it, branches on it, prints it, stores it.

Steps one and three are entirely yours, and entirely deterministic. The same inputs build the same prompt and handle the same response the same way, every single time. That’s testable. Step two is the only part that isn’t, and step two was never yours to test in the first place.

So the job is to pin step two to a known value, and then test one and three properly.

Test the prompt: snapshot it

Step one produces a prompt, and a prompt is just a string, which means you can pin it.

Both frameworks lean on snapshot testing here. go-tool-base uses a golden-file approach: the prompt your code generates is recorded to a file, and the test re-generates it and compares against that file. rust-tool-base does the same with insta, snapshotting the request body the client would send.

The reason this matters is that the prompt is load-bearing and quietly easy to break. You refactor how context gets assembled. Without noticing, you’ve changed the wording, or the ordering, or dropped a line the model was leaning on. Nothing fails to compile. The behaviour just drifts, silently.

A snapshot test catches exactly that. It fails, it shows you the diff between the old prompt and the new one, and it makes you stop and make a decision. Was this change intended? If yes, you accept the new snapshot and move on. If no, you’ve just caught a bug before it shipped. Either way the prompt never changes by accident, which for AI code is most of the battle.

Test the handler: mock the response

Step three needs a response to handle, and in a unit test you don’t get that response from the real model. You supply it.

go-tool-base ships generated mocks for the ChatClient interface. A test builds a mock client, tells it “when Ask is called, return this canned value”, and runs the command against it:

mockClient := mock_chat.NewMockChatClient(t)
mockClient.EXPECT().
 Ask(mock.Anything, mock.Anything, mock.AnythingOfType("*main.Analysis")).
 RunAndReturn(func(_ context.Context, _ string, target any) error {
 *(target.(*Analysis)) = Analysis{Severity: "critical"}
 return nil
 })

Because the interface is only four methods, that mock is trivial to set up and complete by construction. rust-tool-base takes the same idea one layer down: HTTP-bound tests use wiremock, which stands up a fake server returning a canned response body. The client makes a real HTTP request; it just goes to a fake endpoint the test controls.

Either way, step two is now fixed to a value you chose, which makes step three deterministic. And that unlocks the tests that actually matter: given a malformed response, does the command fail gracefully? Given a rate-limit error, an empty answer, a field missing? Those are the cases a live model almost never hands you on demand, and a mock hands you every time, on the first run.

This is, incidentally, the same discipline as the test-mocking work elsewhere in the framework: the dependency is injected, so the test gets to decide what it does.

What you deliberately don’t test

One boundary worth stating. None of this tests whether the model gives good answers. That question is real, but it’s a different activity (evaluations, run as their own suite) and not something to mix into the unit tests.

The unit suite’s job is your code: that it builds a sound prompt, and that it handles every shape of response correctly, including the ugly ones. Keep that well away from “is the model clever today”. A unit test that depends on the model being clever is a unit test that fails when the weather changes, and a flaky test just teaches people to ignore the whole suite.

What it comes down to

Code that calls an LLM is testable; the model is not, and those are different statements. Your code is a prompt builder and a response handler, both deterministic, with the model sat in between.

go-tool-base and rust-tool-base converge on the same approach. Snapshot the prompt, with golden files or insta, so a refactor can’t change what you send without a test noticing. Mock the response, with generated ChatClient mocks or a wiremock server, so tests run with no network and you can feed in the malformed and error cases a real model won’t reliably produce. Leave “are the answers any good” to a separate evaluation suite. Test the two halves you own, and the non-determinism in the middle stops being an excuse to leave the riskiest line uncovered.

The AI provider that isn't an API

Mon, 06 Apr 2026 00:00:00 +0000

go-tool-base’s chat package puts five AI providers behind one interface. Four of them are exactly what you’d guess: HTTP calls to OpenAI, Claude, Gemini, and anything OpenAI-compatible. The fifth one isn’t an API at all. It shells out to a binary.

That sounds like a slightly mad thing to want, right up until you’ve worked somewhere the network says no.

The fifth provider shells out

The chat package speaks to five providers through one ChatClient interface. Four of them are what you’d expect: HTTP requests to OpenAI, to Claude, to Gemini, to any OpenAI-compatible endpoint. The tool author picks one in config, and the rest of the code never knows the difference.

The fifth, ProviderClaudeLocal, is different in kind. It doesn’t make an HTTP request at all. It shells out. It runs the claude CLI binary as a child process, passes the prompt in, and reads the answer back from the binary’s output.

That sounds like an odd thing to want until you’ve been stuck in the environment it was built for.

Why you’d want that

Picture a corporate network with its egress locked right down. Outbound HTTPS to api.anthropic.com is blocked by policy. A tool built on go-tool-base that uses AI would simply fall over there. It tries to reach the API, there’s no route, and that’s the end of the feature.

But the developer at that machine has the claude CLI installed, and has run claude login. That binary is permitted. It’s an approved, managed tool, and it has its own sanctioned path out. The direct API call is blocked; the claude command is not.

ProviderClaudeLocal is what bridges those two facts. If your tool’s AI calls go through that already-blessed binary instead of straight at the API, they work, in an environment where the direct call cannot. That’s the whole reason the provider exists. It isn’t faster (a real API call has lower latency) and it isn’t more capable. It’s for the place where the API call simply isn’t an option, and “isn’t an option” is a surprisingly common place to find yourself inside a large organisation.

What it costs

It’s worth being straight about the trade, because ProviderClaudeLocal is the reduced-capability provider.

It doesn’t do tool calling. It doesn’t do parallel tools. It doesn’t stream. Those need a live, structured connection to the model’s API, and a subprocess that runs once and prints an answer is not that. What it does support is plain chat and structured output, the latter through the binary’s own --json-schema flag.

So the positioning, and the package’s documentation says exactly this, is: prefer the API providers when you can reach them, because they’re lower latency and feature-complete. Reach for ProviderClaudeLocal when API access is restricted. You accept the narrower capability set as the price of working at all. For a tool whose AI feature is “answer a question” or “return a structured analysis”, that price is often nothing you’d even notice. For one built on an agentic tool-calling loop, it’s a real limitation, and you’d know to expect it.

How it stays behind the same interface

Here’s the part that makes it pleasant rather than a special case to maintain. Despite being a subprocess and not an API, ProviderClaudeLocal is still a ChatClient. Your feature code calls Chat and Ask exactly the way it would for any other provider.

Everything that makes a subprocess provider awkward stays inside the provider. Spawning the binary, feeding it the prompt, parsing its output, capturing stderr and surfacing it when the binary exits non-zero, and threading multi-turn continuity through session identifiers passed back on the next call with --resume: all of that is the provider’s problem, and all of it sits behind the interface. The code in your tool that uses AI doesn’t know, and has no way to find out, that this particular provider is a child process rather than an HTTPS call.

That’s a unified interface genuinely earning its place. It’s easy to put a uniform face on four things that already work the same way underneath. The real test of the abstraction is whether something that works in a completely different way, a subprocess instead of a socket, can still slot in without the caller changing a line. Here it can. You swap one config value, and a tool that talked to an API now talks through a binary, and nothing downstream so much as blinks.

The bottom line

go-tool-base’s chat package puts five providers behind one ChatClient interface, and ProviderClaudeLocal is the one that isn’t an API. It runs the locally installed, pre-authenticated claude CLI as a subprocess.

It exists for the locked-down environment where outbound HTTPS to the AI API is blocked but the claude binary is allowed: there, AI features keep working where a direct call would fail. The trade is a narrower capability set (no tool calling, no streaming, plain chat and structured output only) so you prefer the API providers when you can reach them and fall back to this when you can’t. And because it’s still a ChatClient, all the subprocess machinery stays hidden, and your code uses it without knowing it’s there. That last part is the real test of an abstraction: a provider that works in an entirely different way still slots in unchanged.

AI conversations you can resume

Sat, 04 Apr 2026 00:00:00 +0000

An AI conversation is, fundamentally, its own history. The model’s next answer depends on everything said so far. And a CLI tool, by its very nature, forgets everything the moment it exits. Put those two facts together and you get the problem: run an AI command, exit, run it again, and you’re talking to someone who’s never met you.

A CLI forgets everything

A long-running service keeps its state in memory for as long as it runs. A CLI tool doesn’t get that luxury. It starts, does one thing, exits. The next invocation is a brand-new process with no memory of the last one.

For most commands that’s exactly right, and you wouldn’t want it any other way. But an AI conversation is a different kind of beast, because a conversation is its history. The model’s next answer depends on everything said so far. Run an AI command, exit, run it again, and you’ve started a fresh conversation with someone who’s never met you. For an interactive assistant, or any AI workflow that unfolds across several invocations, that’s plainly the wrong behaviour. The user expects to pick up where they left off.

Save and restore

The chat package handles this through a PersistentChatClient interface. Like streaming, it’s an optional capability discovered with a type assertion, sitting beside the four-method core rather than bloating it. A client that supports persistence also satisfies this interface:

if pc, ok := client.(chat.PersistentChatClient); ok {
 snapshot, err := pc.Save()
 // store the snapshot somewhere
}

A snapshot is a serialisable value that captures the conversation. You store it. Next run, you load it, Restore it onto a fresh client, re-register your tools, and call Chat again. “Where were we?” works, because the model is handed back the whole history.

A snapshot is opinionated about what it carries

The interesting part is what a snapshot does and doesn’t contain, because that’s a series of deliberate decisions.

It carries the messages, the system prompt, the model name, and tool metadata: the names, descriptions and parameter schemas of the tools that were registered.

It does not carry tool handlers. Handlers are code, not data; you can’t serialise a function meaningfully, so after a restore you re-register them with SetTools. The snapshot remembers that a tool called read_file existed and what its shape was; it doesn’t try to remember the Go function behind it.

And it does not carry API tokens. This is the one to dwell on. A snapshot is a file. A file gets synced, backed up, copied between machines, attached to a support ticket by a user trying to be helpful. A snapshot that carried the API key would be a credential leak the moment it left the laptop it was made on. So the snapshot never contains a token, at all. On restore, the client picks the credential up again the ordinary way, from the environment or the keychain. The conversation and the secret are kept in separate places on purpose, and only one of them is ever in the file.

Encrypted at rest, if you want it

The package ships a FileStore that writes snapshots as JSON files, with 0600 permissions in a 0700 directory, and it can encrypt them. Pass WithEncryption a 32-byte key and snapshots are written with AES-256-GCM.

That option exists because a conversation can hold sensitive content even when it holds no credential. The log a user pasted in for analysis, the source file they asked the model to review, the internal details tucked into their questions: none of that is an API key, and all of it might be something you’d rather not have sitting in plain JSON in a backup somewhere. Encryption at rest covers it.

The FileStore is also careful about the snapshot identifiers it’s handed. An ID has to be a canonical UUID, and the resolved file path is checked to lie inside the store directory, so a snapshot ID arriving from an untrusted source (a CLI flag, a request payload) can’t be bent into a path-traversal that reads or writes somewhere it shouldn’t. Persisting conversations adds a small filesystem surface, and the store treats it as exactly that.

The short version

A CLI tool forgets everything between invocations, which is correct for most commands and wrong for an AI conversation, because a conversation is its history.

go-tool-base’s chat package lets you persist one. PersistentChatClient saves a snapshot you can store and restore later, picking the conversation back up where it ended. The snapshot is deliberate about its contents: messages, system prompt and tool metadata yes; tool handlers no, because they’re code you re-register; API tokens never, because a snapshot is a file and a file travels. The built-in FileStore can encrypt snapshots at rest with AES-256-GCM and validates snapshot IDs against path traversal. Resumable conversations, without the conversation file turning into a place secrets leak from.

An AI agent that has to make the build pass

Thu, 02 Apr 2026 00:00:00 +0000

Most AI code generation works on a charming little principle I’ll call generate-and-hope. The model writes the code, the model stops at the closing brace, and whether the thing actually compiles is left as an exercise for you. For a snippet you paste into an editor, fine. For a whole generated command, that’s just outsourcing the disappointment.

go-tool-base does something I’m rather happier with: the AI has to make the build pass before it’s allowed to claim it’s done.

Generate and hope

The usual shape of AI code generation is this. You ask for code, the model produces it, and the model’s job ends at the closing brace. Whether it compiles, whether the tests pass, whether the imports even resolve, none of that has been checked. The model produced something that looks right. You find out whether it is right when you build it.

For a snippet you paste into an editor, that’s perfectly fine. The compiler tells you in a second. But go-tool-base’s generator, driven by gtb generate command --script or --prompt, produces a whole command: the implementation, its tests, the lot. “Generate and hope” at that scale means handing the user a project that may or may not build, and quietly making them the one who finds out which.

Drafting is only step one

So the generator doesn’t stop at drafting. Writing the first version of the implementation and its tests is step one of two. Step two is an autonomous repair agent.

Once the draft is on the filesystem, a separate agent takes over. It’s an LLM running in a loop, but a loop aimed at one narrow, checkable job: make this project build and pass its tests. It isn’t asked to be creative. It’s asked to get to green.

A fixed set of tools, and no shell

The agent is not handed a shell. It’s given a fixed, defined set of tools and nothing else. Three of them let it explore and edit the project: list_dir, read_file, write_file. Four of them let it verify the project:

go_build runs the build and captures the compiler errors.
go_test runs the tests and captures the failures.
go_get resolves a missing dependency.
golangci_lint runs the project’s linter.

That restriction is the design, not a limitation of it. The agent can’t delete arbitrary files, can’t reach the network, can’t run anything that isn’t on the list. It has exactly what it needs to make code compile and nothing it would need to do damage. Its file writes are confined to the project directory by an explicit path check, so even write_file can’t go wandering up into /etc. A coding agent you’d actually let near a filesystem is one whose abilities are an allowlist, not a denylist. (I keep coming back to that principle through this series… safety as a boundary you draw, not a behaviour you hope for.)

The loop

The repair loop is a ReAct loop, the same reason-act-observe shape as the tool-calling loop, only this time pointed at a goal:

The draft is on disk.
Verify: run go_build and go_test.
If verification failed, read the error logs, the compiler error or the failing test.
Reason about the cause: an undefined variable, a missing import, a wrong signature.
Act: call write_file to patch the code, or go_get to add the dependency.
Loop. Steps two to five repeat until the project is green, or the agent hits its bounded step limit.

What makes this work is treating the error output as feedback rather than as a failure to log and walk away from. A compiler error is the single most useful sentence you can hand a model that’s trying to fix code. It says what’s wrong, and usually where. The loop feeds it straight back in, and the model fixes against it.

Verification changes what “done” means

Here’s the real shift, and the agent’s own documentation puts it well: the agent “doesn’t just say it fixed a bug; it uses a Test tool to verify the fix before reporting success.”

A generate-and-hope model reports success when it finishes writing. It has no idea whether the code works, and it isn’t really claiming otherwise. “Done” means “I produced text”. The repair agent reports success when go_build and go_test actually pass. “Done” means “the build is green”. Those are two completely different claims, and only the second is worth anything to the person who asked for the command.

That’s the line between an AI that’s a creative writer and an AI that’s a collaborator you can hand a task to. And when the agent can’t reach green, when it spends its whole step budget and the project is still broken, the generator fails safely: it leaves the best-attempt code in place, commented out so the project still compiles, and tells the user what to finish by hand. There’s also an --agentless flag for anyone who’d rather have a plain single-shot retry than the multi-step agent. The default, though, is the agent, because the default should be code that’s been checked.

Where this leaves us

Most AI code generation generates and hopes: the model writes code and the user discovers whether it works. For a whole generated command, that pushes a may-or-may-not-build project onto the user.

go-tool-base’s generator drafts the command and then hands it to an autonomous repair agent. The agent has a fixed set of tools (explore and edit the project, build it, test it, lint it, fetch dependencies) and no shell at all, with file writes confined to the project directory. It runs a ReAct loop, reading each error and patching against it, until the build is green or it exhausts its steps. The point is what “done” comes to mean: not “the model finished writing”, but “the build passes”. Only one of those is a claim worth trusting.

Stop regex-ing the LLM's prose

Tue, 31 Mar 2026 00:00:00 +0000

Ask an LLM a question and it hands you back prose. Lovely to read, miserable to program against. You wanted the one number buried in the middle of it, and now you’re writing a regular expression to fish a word out of three well-written paragraphs that phrase themselves slightly differently every single time you run them.

There’s a much better way, and it’s the difference between forever interpreting an LLM and actually building on one.

The problem with a paragraph

You ask an LLM to analyse a log file and tell you the severity of what it found and a suggested fix. It comes back with three well-written paragraphs. Somewhere in there is the word “critical”, and somewhere is the fix.

Your program now has to extract those two facts from prose, and prose has no contract. The next run, the model phrases it differently. It leads with a caveat. It says “severe” where last time it said “critical”. It puts the fix first. Anything that worked by finding “critical” in the text is now quietly wrong, and you didn’t change a line. Parsing free text for structured facts is a game you lose slowly.

What you actually wanted was never a paragraph. It was a value: a thing with a severity field and a fix field, that you can branch on and store and pass around like any other.

Ask for the struct, not the prose

go-tool-base’s chat package draws the line with two methods. Chat gives you text. Ask gives you a struct.

You define the Go type you want back:

type Analysis struct {
 Severity string `json:"severity"`
 Fix string `json:"fix"`
}

var result Analysis
err := client.Ask(ctx, "Analyse this log file: "+logText, &result)

The framework generates a JSON Schema from that struct, sends it to the model as the required response format, and unmarshals the reply straight into result. You never lay a finger on the prose. You get result.Severity and result.Fix, typed, ready to use. If you want the model’s answer to drive a switch statement, this is the method that lets it.

The struct is the schema is the contract

The detail that makes this hold up over time: you don’t write the schema. The struct is the schema.

The framework derives the JSON Schema from your type. In go-tool-base that’s GenerateSchema[T](); in rust-tool-base the schema comes from your Rust type through schemars. (Yes, there’s a Rust sibling now. I’ll introduce it properly in a few weeks, but it keeps gatecrashing these posts because the two frameworks deliberately share ideas.) Either way there’s one definition, your type, and the schema is just a projection of it.

That matters, because otherwise two things have to agree. There’s the schema you tell the model to obey, and there’s the type you unmarshal the answer into. Hand-write the schema and those two can drift: add a field to the struct, forget to add it to the schema, and the model is never told to produce it, so it silently never appears. Deriving the schema from the type collapses the two into one. They can’t disagree, because there’s only one of them.

Both frameworks, with one extra step in Rust

go-tool-base does this with Ask and a ResponseSchema set on the client config. rust-tool-base does it with chat_structured::<T>, where T is any type that’s both deserialisable and JsonSchema.

rust-tool-base adds one step worth calling out. Before it deserialises the model’s reply into your T, it validates the raw response against the schema with a JSON Schema validator. That splits the failure into two distinct, named cases: the response didn’t match the schema, or it matched the schema but still wouldn’t deserialise. A model that returns subtly wrong JSON fails loudly and specifically, with an error that tells you which of those happened, instead of quietly handing you a zero-valued struct that you end up debugging an hour later.

When you’d reach for it

The line is simple, and it’s about who reads the answer.

If a human reads the answer, prose is right. Chat, free text, let the model write well. A summary, an explanation, an interactive reply: leave all of those as prose.

If a program consumes the answer, you want a value. Classification, extraction, a code review scored out of a hundred with a list of issues, a yes-or-no with reasons: anything where the next thing that happens is your code branching on the result. There, Ask and chat_structured turn the LLM from something you have to interpret into something that returns a value, and a typed value is a thing you can actually build on.

To sum up

An LLM returns prose by default, and prose has no contract, so a program that picks structured facts out of it breaks the moment the model rephrases.

Structured output asks for the value instead. You define a struct, the framework derives a JSON Schema from it, the model is constrained to that shape, and you get a typed result. go-tool-base’s Ask and rust-tool-base’s chat_structured both work this way, with the schema derived from your type so the schema and the type can’t drift; rust-tool-base additionally validates the response against the schema before deserialising. Use it whenever the answer feeds code rather than a human. It’s one of the four methods that make up go-tool-base’s small chat interface, and it’s the one that makes an LLM safe to program against.

Letting the AI call your Go functions

Sun, 29 Mar 2026 00:00:00 +0000

An AI that can only produce text can describe your system. An AI that can call your Go functions can actually operate it. That gap, between describing and doing, is the difference between a chatbot and something genuinely useful, and crossing it comes down to one fiddly mechanism: tool-calling, and the loop that drives it.

Talking about the system versus operating it

Wire an AI provider into a CLI command and you get something that can talk. Ask it a question, get a paragraph back. Useful, up to a point.

But notice the ceiling. An AI that can only generate text can describe things. It can tell you what it would do. What it can’t do is look at the actual current state of your system, or take a real action, because it has no hands. It’s reasoning in a vacuum about a world it can’t reach out and touch.

The thing that gives it hands is tool-calling. You hand the AI a set of functions it’s allowed to call. Now, mid-conversation, it can decide it needs to read that file before it can answer, or run that query, or check that status, and actually go and do it, and then reason about the real result. The AI stops describing your system and starts operating it.

The loop is the hard part

Tool-calling has a shape, and the shape is a loop. The literature calls it ReAct: Reason, Act, Observe.

The AI reasons about the prompt and decides whether it needs a tool.
If it does, it acts, asking for a specific tool with specific arguments.
Your code runs the tool and feeds the result back. The AI observes that result.
Round again. Reason about the new information, maybe call another tool, maybe several. Keep going until the AI has what it needs and produces a final text answer with no more tool calls.

Conceptually simple. Tedious and error-prone to implement by hand every single time: parsing the model’s tool-call requests, dispatching to the right function, marshalling arguments in and results out, feeding observations back in the exact format the provider expects, knowing when to stop, and not looping forever if the model gets itself stuck.

That orchestration is pure plumbing, and it’s identical for every tool and every command. So you can probably guess what’s coming: go-tool-base’s chat package owns it. You don’t write the loop. You write the tools.

Defining a tool

A chat.Tool is four things: a name, a description, a parameter schema, and a handler. The description is what the AI reads to decide whether to use the tool, so it’s worth writing well. The schema describes the arguments, and you don’t hand-write it. You write a tagged Go struct and let it generate:

type ReadFileParams struct {
 Path string `json:"path" jsonschema_description:"Relative path to the file"`
}

The struct is the contract. The framework derives the JSON Schema the AI is given straight from those tags, so the schema and the Go type the handler receives can’t drift apart, because they share a single source. The handler is then just an ordinary Go function that takes those parameters and returns a result.

You register your tools with SetTools, call Chat, and that’s the whole of your involvement. The framework runs the ReAct loop and Chat returns the AI’s final text answer once the loop settles.

Two details that show it was built for real use

A couple of decisions in the loop tell you it’s meant for production, not a demo.

Tool errors don’t abort the conversation. When a handler returns an error, the framework doesn’t crash the loop. It hands the error back to the AI as a string, as just another observation. That’s deliberate, and it’s right. A real agent should be able to call a tool, watch it fail, and react: try different arguments, take a different route, or tell the user it couldn’t manage it. A loop that aborted on the first tool error would be far more brittle than the model driving it.

The loop is bounded. There’s a MaxSteps limit, default 20. An AI that gets confused could otherwise call tools forever, and a CLI command that never returns is a worse failure than a wrong answer. The cap guarantees the command terminates. The agent gets room to genuinely work a problem across many steps, but not infinite room to flail about in.

There’s also parallel tool execution: when the model asks for several tools in a single step (three independent file reads, say) the framework runs them concurrently rather than one after another, because there’s no reason to make the AI sit and wait out a sequence of things that don’t depend on each other.

Boiling it down

A text-only AI can describe your system; an AI that can call your functions can operate it. Bridging that gap means tool-calling, and tool-calling means the ReAct loop (reason, act, observe, repeat) whose orchestration is fiddly, identical every time, and not a problem worth solving twice.

go-tool-base’s chat package runs the loop for you. You define chat.Tool values (name, description, a tagged parameter struct that generates its own schema, a handler), call SetTools and Chat, and get the final answer. Tool errors go back to the AI as observations so it can recover, and a MaxSteps cap guarantees the command always terminates. You write Go functions. The framework turns them into things an agent can reach for.

Nobody reads the manual

Sun, 29 Mar 2026 00:00:00 +0000

Let me describe the actual lifecycle of a user meeting your CLI tool, because it’s a bit humbling. They run it. It doesn’t quite do what they expected. They run it again with --help. They get a wall of monospaced flag descriptions, skim it, don’t find the thing they wanted, and either give up or go and ask a human who already knows.

Your documentation might be magnificent. It doesn’t matter, because the user never reached it.

The manual loses on location, not quality

That’s the lifecycle, and notice exactly where it breaks. The documentation might be excellent. It might answer their precise question in full. It doesn’t matter, because it’s on a website, in another window, behind a search box, and the user is here, in the terminal, mid-task. The docs lost not on quality but on location. They simply weren’t where the work was.

go-tool-base’s answer starts with a decision about location: the documentation gets embedded into the binary itself. Your docs/ folder ships inside the tool, the same way its default config does. Wherever the tool is installed, the docs are right there alongside it, no network, no browser. That embedding is what makes everything else possible, and there are two things built on top of it.

A browser, in the terminal

The first is the docs command, and it’s not --help with extra steps. It launches a proper Terminal User Interface, built on Bubble Tea.

It has a sidebar, structured from the project’s own mkdocs.yml, so the docs are a navigable tree rather than one flat scroll. Markdown renders with real formatting through Glamour (colour, tables, lists, headings) instead of collapsing into monospaced soup. There’s live search across every page, regex included.

Compared with man and --help, the difference isn’t a nicer coat of paint. man gives you linear scrolling and grep; this gives you a structured tree, rich rendering and real search. It’s the documentation experience a modern developer expects, except it followed the tool into the terminal instead of demanding the user leave it.

A documentation assistant that won’t make things up

The second thing built on the embedded docs is the one I find genuinely transformative: docs ask.

The user doesn’t navigate anything. They just ask:

mytool docs ask "how do I point this at a self-hosted server?"

and get a direct, specific answer. Under the hood, the framework collates the tool’s embedded markdown and hands it to the configured AI provider (Claude, OpenAI, Gemini, Claude Local, any OpenAI-compatible endpoint) as the context for the question.

Now, “an AI answers questions about my tool” should immediately make you nervous, and the correct thing to be nervous about is hallucination. An AI that confidently invents a flag that doesn’t exist, or describes behaviour the tool simply doesn’t have, is worse than no assistant at all, because the user trusts it.

This is where embedding the docs pays off a second time, and it’s why I keep stressing that the corpus is closed. The model is instructed to answer only from the tool’s actual documentation, and the context it’s handed is exactly that documentation and nothing else. It isn’t drawing on a vague memory of similar tools from its training data. It’s answering from this tool’s real, shipped, version-matched docs. The corpus is small, closed and authoritative, which is the combination that keeps the answers honest. “Zero hallucination by design” isn’t a slogan about the model. It’s a property of bounding what the model is allowed to look at, which is the same instinct I leaned on with the mcp command: the safety comes from the boundary you drew, not from trusting the AI to behave itself.

There’s a nice second-order effect, too. The answer is always about the version of the tool the user actually has, because the docs were embedded into that build. No mismatch between a website documenting the latest release and the slightly older binary sitting on the user’s machine.

The upshot

Documentation usually loses to --help not on quality but on location: it’s in a browser, and the user is in the terminal. go-tool-base embeds the docs into the binary and surfaces them two ways: a docs command that’s a real TUI browser with a sidebar, rich markdown and search, and docs ask, which answers natural-language questions using the embedded docs as context.

Because that context is the tool’s own closed, shipped documentation and the model is told to use nothing else, the assistant stays grounded, and it’s always describing the exact version the user is holding. The fix for unread documentation was never to write more of it. It was to put it where the work happens and let it answer back.

An AI interface that fits on one screen

Fri, 27 Mar 2026 00:00:00 +0000

The moment you decide a CLI tool should talk to an LLM, there’s a strong gravitational pull towards reaching for LangChain, or one of its many relatives. It’s the obvious move. It’s also, for most CLI work, a bit like hiring a removals firm to carry a single box up the stairs.

Let me explain why go-tool-base went the other way, and what “the other way” actually looks like.

The instinct, and why it overshoots

When you add AI to a tool, the instinct is to reach for the big general-purpose framework. LangChain and its relatives are capable, and they exist for a real need: orchestrating complex multi-step AI applications, with retrieval pipelines, memory stores, chains of calls, whole fleets of agents.

Now look at what a CLI tool actually needs from an LLM. It needs to send a prompt and get text back. Sometimes it wants structured data back instead of prose. Sometimes it wants to let the model call a few of the tool’s own functions. That’s pretty much the whole list.

Pulling in a framework built to orchestrate retrieval and agent swarms in order to do that is a poor trade. You take on a large new vocabulary of concepts, a wide dependency surface, and a great deal of abstraction you’ll never touch, all to perform three or four operations. The framework isn’t wrong. It’s just answering a far bigger question than the one a CLI tool is asking.

What go-tool-base chose instead

go-tool-base didn’t reach for a framework. The decision is on the record in its own design notes: before a single line was written, LangChain Go, go-openai, Vercel’s AI SDK and around ten other options were evaluated, and not one of them matched what a CLI framework actually needs. So the chat package was built deliberately small.

How small? The entire core ChatClient interface is four methods:

type ChatClient interface {
 Add(ctx context.Context, prompt string) error
 Chat(ctx context.Context, prompt string) (string, error)
 Ask(ctx context.Context, question string, target any) error
 SetTools(tools []Tool) error
}

Add appends a message to the conversation. Chat sends a prompt and returns text. Ask sends a prompt and returns a typed Go struct, the model’s answer unmarshalled straight into a value you defined. SetTools hands the model a set of your own functions it’s allowed to call. That’s the whole surface. Downstream code that uses AI never holds anything larger than this, and never has to know which provider is behind it.

The package’s own documentation has a word for this: right-sized. Large enough to solve genuine provider-abstraction complexity, small enough that the full interface fits on a single screen.

“Thin” is not the same as “does little”

This is the part worth being precise about, because “four methods” can sound like “barely does anything”, and that’s the wrong read entirely.

Behind those four methods sits genuinely awkward work. Five providers (OpenAI, Claude, Gemini, a locally installed claude binary, and any OpenAI-compatible endpoint) each with a different wire API, all normalised behind the one interface. A tool-calling loop. Structured output via JSON Schema, made to behave consistently across providers that each express it differently. Error normalisation. Token chunking.

The point of a thin abstraction is not that there’s little underneath it. It’s that the interface stays small while the implementation quietly absorbs the complexity. Four methods on the surface; five provider integrations and a tool-calling loop below the waterline. The thinness is a property of what the caller sees, not of what the package does. A reach-for-LangChain decision gets that backwards: it exposes the caller to all the machinery, whether or not the caller will ever need it.

The core stays small even as features grow

There’s a neat detail in how chat keeps the interface from creeping. The package also supports streaming responses and conversation persistence, both of which are real features with real surface area. Neither of them is in the four-method core.

Instead they’re separate, optional interfaces. A streaming-capable client also satisfies StreamingChatClient; a persistable one also satisfies PersistentChatClient. Code that wants those capabilities does a type assertion to ask for them, and code that doesn’t simply never sees them. So the common path stays four methods forever. New capabilities arrive as opt-in interfaces alongside the core, not as new methods bolted onto it. The thing that fits on one screen keeps fitting on one screen.

Extensible without forking, testable without a network

Two more properties keep the package small without making it limiting.

It’s extensible. The provider list isn’t closed. A RegisterProvider call lets any package contribute a new provider, and chat.New will route to it. You add a backend without forking pkg/chat or sending a patch upstream.

And it’s testable. The package ships generated mocks. A downstream tool’s AI features can be tested against a mock ChatClient returning canned responses, with no network, no API key, and no flakiness. Because the interface is four methods, that mock is trivial to set up and complete by construction. A sprawling framework interface is a sprawling thing to fake; a four-method one is not. (I’ll come back to testing AI code properly in a later post, because it deserves a whole article of its own.)

The right size

When a CLI tool needs AI, the instinct is a large framework like LangChain. For orchestrating retrieval pipelines and agent swarms, that’s exactly the right tool. For sending a prompt, getting a struct back, and letting the model call a few functions, it’s enormous overkill.

go-tool-base’s chat package is the deliberate alternative, chosen only after LangChain Go and a dozen others were weighed up and rejected. Its core ChatClient interface is four methods. Underneath sit five normalised providers, a tool-calling loop, structured output and error handling, but the caller sees four methods and never learns which provider is active. Streaming and persistence are opt-in interfaces beside the core, not additions to it. It extends without forking and tests without a network. Right-sized: the complexity is real, but it lives under the interface rather than in it.

Your CLI is already an AI tool

Thu, 19 Mar 2026 00:00:00 +0000

“Make it work with AI” has become one of those requests that lands on a developer’s desk with a thud and not much further detail attached. My instinct, the first time, was to brace for a big lump of integration work… a bespoke adapter for this assistant, another for that one, a treadmill of little wrappers stretching off into the distance.

Turns out I’d already done most of the work. So have you, if your CLI tool is any good. Let me explain what I mean.

You already described your capabilities

Stop and think for a second about what a well-built CLI tool actually is. It’s a set of named operations, each with a human-readable description, each taking a set of typed, named, documented parameters. You wrote all of that already, because a CLI without it is unusable by people.

Now look at what an AI assistant needs in order to call a tool. A set of named operations. A description of each, so it knows when to reach for them. A typed parameter schema for each, so it knows how to call them.

It’s the same list! A good CLI is already, structurally, a description of a set of capabilities. The information an AI agent needs isn’t extra work you have to go and do. It’s work you finished the moment your --help output was any good.

The only thing missing is a translator. Something that takes “this is a CLI” and presents it as “this is a set of tools an AI can call”.

MCP is that translator, and it’s a standard

The temptation, when you want your tool to be AI-usable, is to sit down and write an integration. A little adapter for Claude Desktop. Another for Cursor. Another for whatever turns up next month. Each one a bespoke wrapper, each one a thing to maintain, and the list never stops growing because new assistants keep appearing. That’s the treadmill I was bracing for.

The Model Context Protocol exists to kill that list. MCP is an open standard for how an AI model discovers and calls local tools. Implement it once and your tool works with every assistant that speaks it. Write once, not once-per-client.

So go-tool-base implements it once, in the framework, for everyone. (That’s rather the theme of this whole series, if you hadn’t spotted it yet… do the annoying thing once, properly, in a place where every tool inherits it.)

The `mcp` command, and the mapping it does for free

Every tool built on go-tool-base inherits a built-in mcp command. Run it:

mytool mcp

and the tool starts a JSON-RPC server over standard I/O, speaking MCP. That’s the whole user-facing surface. One command.

Behind it, the framework walks your Cobra command tree and maps it straight onto MCP tool definitions:

Each command becomes a tool.
Each command’s short description becomes the tool’s description, the text the AI reads to decide whether this is the tool it wants.
Each command’s flags and arguments become the tool’s JSON Schema parameters.

There’s no second schema to write and then keep in sync (and we all know how well “keep these two things aligned by hand” tends to go). The command tree is the schema. Add a new command to your CLI and it’s a new tool for the agent, automatically, with the description and flags you already gave it. Nobody has to remember to update an MCP manifest, because there’s no separate MCP manifest to forget about.

Configuring an assistant to use it

On the assistant’s side it’s just as undramatic. You tell your AI client (Claude Desktop, Cursor, anything MCP-aware) to launch mytool mcp. From then on the assistant:

Starts your tool in MCP mode when it boots.
Discovers every command as a callable tool.
Calls the right one, with the right parameters, when a user’s request needs it.

Your CLI tool has quietly become something the AI can pick up and use, mid-conversation, on its own initiative.

The safety property worth noticing

Now, “let an AI run things on my machine” is rightly a sentence that makes people nervous. It makes me nervous, and I built the thing. So it’s worth noticing the constraint sitting quietly in this design.

The AI can only call what you defined. The tools it sees are exactly the commands in your tree, and the parameters it can pass are exactly the flags and arguments you declared, validated against the JSON Schema generated from them.

It can’t invent a command. It can’t pass a parameter you never defined. The boundary of what the agent can do is the boundary of what your CLI does, and you drew that boundary already, back when you built the tool. Exposing the CLI over MCP doesn’t widen the surface one inch. It just makes the existing surface reachable. The AI isn’t running things. It’s running your commands, the ones you wrote, tested and shipped, and nothing else.

The gist

A CLI tool, built properly, is already a structured description of a set of capabilities: named operations, descriptions, typed parameters. Which is also exactly what an AI agent needs in order to call a tool. The gap between the two is only a translator, and writing a bespoke one per assistant is a treadmill you don’t need to step onto.

go-tool-base puts the translator in the framework. Every tool gets an mcp command that serves the command tree over the Model Context Protocol… commands become tools, descriptions become descriptions, flags become JSON Schema parameters, with no second schema to maintain. Point any MCP-aware assistant at it and your CLI is an agent-callable tool, bounded to exactly the commands you shipped.

You did the hard part when you built a good CLI. MCP just opens the door you’d already framed.

AI on PHP Boy Scout

I filed a feature request into my own framework

The bridge I was about to vendor

A feature request, against myself

Two sessions, one dependency

The one rule that came with it

The truest test of a framework

The off-switch was never a button

I came to this a sceptic

A Golden Retriever with a keyboard

“Agents that work while you sleep”

The off-switch was never a button

It gets harder as it gets better, not easier

The agent said SUCCESS. The linter disagreed.

What “done” meant to the agent

The instruction that made lint optional

The fix was words, not code

Leave it better, not just building

The interpreter we forgot to sandbox

Not a new attack, a new doorway

Markdown is a programming language now

You can’t just read it more carefully

Signing won’t save you here

So whose job is it?

The most dangerous machine is the one on your desk

The rung we sawed off

The rung, and who’s standing on it

It was never about efficiency. It was about cost.

The bit that should frighten you

It’s a split, not a collapse

Day zero

The end I’m holding

Everyone wants Rust's safety, nobody wants Rust

What everyone’s actually after

Rust didn’t invent any of this

Credit where it’s due: C# is doing this properly

A contract is not a guarantee

Discipline never scaled, and that’s not an insult

The part that changed my mind

None of this means rewrite everything in Rust

What it comes down to

They switched it off while it was fixing my code

Three days late to the only model that mattered

Good, but let’s not get carried away

It kept slipping out of my hands

Capable, and almost impossible to build on

The part they banned is my bread and butter

Who I’m not angry at

What it comes down to

The goblin that wouldn't stay dead

Why a dungeon master at all

Strike one: nothing to enforce

Strike two: a tool to read the state

Strike three: refereeing its own dice

The fix was less, not more

The freedom I chose not to give it

What the goblin taught me

Generate a command from a script or a sentence with go-tool-base

Two ways in, the same files out

From a script: csv_stats.py becomes csv-stats

From a sentence: a URL health-checker

What “self-repair” actually means

Flags you declare, logic it writes

Where that leaves you

Why I still write code

I’m a builder, and that isn’t really a choice

What it actually buys

The bill, and who paid it

Does it still count when the robot types?

What I’d actually put my name to

Anything under an 8

The carcass and the vultures

The number we never checked

Don’t blame the robots for this one

The version I’m betting on

The greybeards' edge was never typing

The boost, and the drag

The bill is just deferred

How to manufacture a world of AI slop

It’s a choice, and it’s yours

From a script: `csv_stats.py` becomes `csv-stats`