Tag: Developer

A large monolithic glass building splitting apart along clean seams into smaller connected structures.

The Test Suite Is the New Code Review

Allen Hutchison1 Comment

Some mornings I watch a pull request move through our whole pipeline before I’ve finished my coffee. An agent opens it. A second agent reviews it. By the time I sit down, the only thing still running is the test suite. That gap, the minutes between “reviewed” and “safe to merge,” has become the slowest part of how we ship.

This is the third post in a series about how Chris and I build Vycari. The first was about the issue tracker and what belongs in it once agents do the work. The second was about the pipeline that works through the tracker and never merges its own pull requests. This one is about what those pull requests wait on, and how the answer changed the shape of the code.

It didn’t used to be the tests. Plenty of us optimized CI over the years, but we optimized it by tiering it. A few minutes of unit tests at your desk before you pushed. A longer run in CI once you did. A slow integration suite that went off every few hours, or overnight. When it came back red, you bisected your way to whichever pull request broke it. That held up because a human was going to review the change anyway, and that took an hour or two at best.

Agents changed that arithmetic. One agent opens a pull request. Greptile reviews it in a couple of minutes. Human and machine are both waiting on tests now. If the full suite takes thirteen minutes, that’s thirteen minutes with nothing else in the way. Multiply that by the pull requests moving through Pepper on a given day and you need a merge queue to keep them from stepping on each other. I’ve finished a change by hand, pushed it, and found myself forty minutes behind a queue of agent pull requests, each one blocked on the same thirteen minutes. Before agents I would never have set up a merge queue for a two-person project. The idea would have been funny. It’s now part of my standard repository setup.

The tiering trick can’t save us either. We still run a slow suite overnight, but it can’t stand between a bug and production, because we ship on green, or near enough: every merge builds an image, and production picks up whatever is current on a fifteen-minute cycle. Call it half an hour from merge to running, and that’s the whole window I have to find out something is wrong. A suite reporting at midnight would be telling me about a bug I shipped at nine that morning, with a few hundred agent pull requests stacked on top of it. Twenty minutes of CI used to be unremarkable. It feels like an eternity now, because everything around it got faster and it didn’t.

The Repository Gets Harder to Hold

Making the suite faster buys time without touching the deeper problem: the repository keeps getting harder to reason about as it grows. A human engineer joining a large codebase builds intuition for its boundaries over weeks. They learn which corners are scary and which are safe to touch without asking anyone. An agent doesn’t get that runway. It arrives cold on every task, reading whatever context you’ve given it and inferring the rest from the code next to it. The bigger the repository, the more code there is to infer from, and the easier it is to miss a contract something else depends on.

I tried to buy that intuition back with context files: hierarchical instructions at every level of the tree, skills describing the traps in one corner of the code. All of it helps, and none of it is free. Every context file is one more thing to write and keep current. Even a well-oriented agent has to hold the whole shape of the repository in its head to change anything that crosses a boundary.

None of this means monorepos are a mistake. They’re a fine pattern for people who already know where the walls are. The problem is narrower: a monorepo is a bad pattern for a team where most of the work gets done by something that relearns the walls on every task.

Pulling the Slice Out

The fix I’ve settled on is structural. When a piece of functionality is clean enough to stand on its own, I pull it out into its own repository before it tangles into everything else. It gets its own tests, its own merge queue, its own release cadence. An agent working inside it can hold the whole thing in its head.

We already have a pattern for this, and it’s older than any of the AI tooling. Amazon has run this way since Jeff Bezos mandated that every team expose its data through service interfaces, with no direct linking and no reading another team’s data store. Steve Yegge described that mandate in 2011, and the detail everyone remembers is that non-compliance meant termination. Microservices came out of an organizational problem before they were a technical one: teams that couldn’t see inside each other needed real contracts. I’m solving that problem, except the team members who can’t see inside each other are models.

The first slice I pulled out was groups, the part of Pepper that handles shared context between people. Working on groups was much faster than working on Pepper itself, and the reason was almost embarrassingly simple. The test suite was only testing the group stuff. Nothing about calendars, nothing about the agent loop, nothing about the web client. A pull request in groups clears CI in about two minutes, against thirteen for the same work in the monorepo, and it has held at two minutes as the code grew. The old number survives in one place: a push to main, where the fuller job set builds the image and can take fifteen, after the merge instead of in front of it.

I don’t have a rule yet for when a slice is ready to leave the monorepo. Right now I go by feel: one clear job, one owner, and an API narrow enough to describe in a sentence. Pull it too early and you’ve built a service around something that still needs to change shape. Pull it too late and it’s already tangled into three other things. I’ve been wrong in both directions. And one slice out is not a track record. The first extraction is always the cleanest. Ask me again at six services, after the costs have compounded.

Anthropic ran into the same problem from the other direction and wrote up what agentic coding did to their CI. Their engineers ship eight times as much code per quarter as they used to, and Claude writes eighty percent of it. CI jobs grew twenty-five fold in six months on headcount that barely moved. Their answer is test impact analysis: keep the large codebase, and run only the tests a change could plausibly affect. If I had a team to maintain something like that, I’d build it. I don’t. Test selection is a system somebody has to own and keep correct, and at two people every system we own competes with the product. Splitting the repository buys most of the same speed by construction, and it fixes the context problem as well. At Anthropic’s size I would almost certainly choose the way they went.

There’s a principle underneath this. I want each of our Python codebases to look like every other open source Python codebase that exists. Not because I’m attached to convention for its own sake, but because a model has seen a million repositories shaped that way. It has seen almost none shaped like a sprawling internal monorepo with its own rules. A small, conventional repository is legible to an agent before it reads a single context file.

The Boundary Has to Be Real

Splitting only pays off if the interfaces are real. A boundary with a vague interface behind it is worse than no boundary. The coupling is still there and now you can’t see it. Google got this right early with protocol buffers: one schema everybody compiles against, changes that stay backward compatible, and no ambiguity about what a service accepts or returns. We’re doing a smaller version. Each service has a defined interface and the calls run over a fast internal Docker network. The interface is what we argue about in review, not the implementation behind it. For an agent working in one repository, that contract is the whole surface it has to respect.

So what catches the bugs that live between services, now that no single suite covers all of it? Three things, in descending order of respectability. The contract, which is why folding groups back into Pepper took a morning. A browser suite that runs overnight against the real application. And the fact that two of us live in the product all day, so anything broken between services turns up in our own use within hours. That last one is not a strategy. It’s what you get at two people with no customers, and it’s the first thing to break when either number changes.

Where this ends up, if I follow it through, is a web application in its own repository, the clients grouped with their browser tests, and a Pepper repository that is just the agent and its tools. That last part is the point. The thing that makes Pepper Pepper should be small enough that an agent can hold all of it at once.

The tradeoff shows up in cross-cutting work: features that used to be one pull request in the monorepo are now a change spread across several repositories. Three repositories means three pipelines and three cold starts, so total compute went up even as the wait in front of any one change came down. Most work happens inside a single repository, so I’m happy to pay it. My first answer was to check out every relevant repository into one parent directory and start an agent there, with all of them in view at once. That parent directory has since become a repository of its own.

One Tech Lead, Many Repositories

For anything that spans repositories, I start what I call my UTL agent, after the old Google title Uber Tech Lead. A UTL was senior and broad enough to operate across systems without owning any of them. Mine runs on Fable 5.1, the strongest model I have for this kind of judgment, though the role matters more than the model filling it.

The UTL lives in that parent directory, which is now a meta-repository. It checks out every other repository underneath it, carries the shared skills, and is growing an operations plugin that knows how to talk to production. The pipeline from the last post runs from there too, one pull request per repository per tick. Making that work meant a consistency pass across every repository: same CI, same branch protection, same conventions. If the plan is to keep splitting, creating a new repository has to be easy, or the friction becomes the reason you don’t.

The UTL almost never writes code. It’s instructed to delegate, and I’ve been strict about that, because the moment it starts editing files itself I’ve lost the thing I built it for. It’s my emissary to the agentic army. I talk to the UTL, the UTL talks to the subagents, and the subagents write the code.

What it has instead is a toolbox of specialized subagents covering the stages of our development cycle, and judgment about which to launch when. Opus for design. Sonnet, Luna, or Flash for implementation, depending on how much thinking the work needs. Opus again for responding to code review, because arguing with a reviewer about whether a finding is right takes more judgment than the code did. For work that spans repositories, the design pass produces a plan covering all of them. What changes where, in what order, and which pieces can move in parallel. Then the implementation agents go out, one per repository, each carrying a slice of that plan. What’s left is bookkeeping: tracking every pull request it spawned until each one lands, and knowing which are blocked on another repo’s change merging first.

What This Costs

None of this is free. Splitting a monorepo trades one kind of difficulty for another.

The first cost is in your own head. You have to decide which service a piece of work belongs in before starting it. A monorepo never charges you that tax. The second cost is reliability. Repositories that used to fail together as one deployable now fail independently. You have to know which parts of your system can take another part down with them, and build the ones that can’t afford it differently. We haven’t had that failure yet, so this cost is still theoretical for us. The third cost is coordination that never goes away. Shared libraries need update schedules, API contracts need versioning, and a change that used to be one pull request can turn into three, timed so none of them ships broken.

There’s a fourth cost. This is a two-person company that hasn’t launched yet, and repository architecture is not a feature. Somewhere in the middle of the split I asked Chris whether I was faffing around with infrastructure instead of building the product. His answer was that building on a bad foundation just eats you with low velocity, and the point of doing it now is that we never have to do it while customers are watching. He also pointed at something I hadn’t seen. When we hire, a bounded repository is the thing you can hand a new engineer whole. Here’s the interface, here’s everything it needs to do, go. That’s a much better first week than a tour of a monorepo’s cryptic corners.

I’ve paid all four, and I’d pay them again. The alternative, one repository that keeps absorbing everything, doesn’t remove that complexity. It hides it inside a single directory tree until an agent runs into it blind, which is a worse way to find out.

Where the Gate Sits Now

Code review used to be the thing everyone waited on. It was slow, and it was where a second set of eyes actually caught something, so everything else could afford to be slow too.

Agentic review took that bottleneck away almost entirely. A pull request gets opened and reviewed in the time it takes me to read the agent’s description and the parts of the diff I care about. We’re getting closer to letting the pipeline merge its own work, which would retire the rule I wrote about last time. What’s left waiting after that is the machinery underneath: the test suite, the merge queue, the deploy pipeline. Thirteen minutes doesn’t sound like a long time, until it’s the only thing standing between one agent finishing a task and the next one starting. Repeat that across every pull request a day produces, and thirteen minutes stops being a rounding error.

The other side of that machinery is where the split pays off. In a small repository, a feature can go from an idea to running in the product in about half an hour, and the only thing that half hour depends on is CI. In the monorepo, the same feature waited on tests for code it never touched.

That’s the argument for breaking the monorepo apart. The gating factor moved from human judgment to compute time, which is the one delay in this system that’s engineering-tractable. You can’t make a human review faster without asking less of them. You can make a test suite faster by shrinking what it has to know about, which is what a small repository does. I wrote in the first post about the tracker that decides what agents can touch. The repository boundary matters just as much, and it’s the one I spend most of my architecture time on now.

What’s Next

The next experiment follows from the way the UTL already works. If it can plan and delegate across repositories, it should be able to delegate the tech-lead role itself. The plan is to stand up a second, cheaper tech lead for one migration, run it to parity on its own repository, and have it escalate two things: decisions that need a human, and anything that touches production. If that works, Chris and I spend most of our engineering time on design documents rather than pull requests, and the design document becomes the real unit of work. Chris’s caveat, which I think is right, is that user experience is the part you can’t specify up front. That’s the honest limit on all of this, and probably a later post.

A laptop glowing in a dim home office at night, showing a queue of pull requests waiting for review.

The Agent That Never Merges

Allen Hutchison2 Comments

Most mornings now I open my laptop to a queue instead of an inbox. Overnight, while Chris and I were asleep, an agent read our open GitHub issues, decided which ones were ready to build, picked the oldest one, and opened a pull request. The tests pass. Greptile reviewed it, the agent worked through the review comments, and Greptile now scores the change five out of five. The description explains what changed and why. The commit history looks like a careful engineer wrote it. What’s left for me is to decide whether it’s good enough to ship.

I said last month that I’d keep writing about the engineering as Chris and I build Vycari. This is the second post in that series. The first was about the issue tracker, and what belongs in it now that agents do most of the work. This one is about the pipeline that works through it. It’s the part of our process I trust most, and the part I was most nervous about building, because it’s where we let an agent write code that ends up in front of you.

Two Founders, No Platform Team

There are two of us. There is no platform team, no SRE rotation, no QA function, nobody whose job is keeping the lights on so we can build product. Whatever infrastructure we need, we build ourselves, out of the same hours we need for everything else. I like this stage of a company, but it means every hour Chris or I spend on triage, boilerplate, or a stale dependency is an hour not spent on decisions only the two of us can make.

The obvious answer is to point an agent at the boring parts. The harder part is the discipline that requires. An agent that opens pull requests unsupervised can save you a lot of time or create a lot of problems, and which one you get depends on what you refuse to let it decide on its own. I’ll come back to that. First I want to explain where the tooling came from, because it didn’t start as a product decision. It started when I noticed I had built the same thing twice.

We Had Already Built This Twice

Before the company, I was maintaining Gemini Scribe, a TypeScript plugin for Obsidian I’ve been building for a couple of years, and I had started experimenting with overnight agents to do the maintenance work: keeping the docs current, writing development logs, triaging issues. An architecture audit, a daily changelog generator, a skill that reviewed pull requests against the project’s conventions. When I started on what became Vycari’s codebase, a Python backend, I began writing the same things again under slightly different names. I hadn’t noticed they were the same habits until the second or third time.

In June I pulled all of it out into its own project. Maintainerd is a marketplace of Claude Code plugins for maintainer work: audits for architecture, test quality, security, dependencies, and documentation; a daily changelog; a research radar that scans arXiv for relevant papers; a skill that opens pull requests and one that works through reviewer comments; and the pipeline this post is about. It’s open source under the MIT license and lives in the Vycari org.

The name is a pun on maître d’. A maître d’ runs the front of the house so the kitchen can cook, which is what these skills do for a repository. It also reads as Maintainer Nerd, which I didn’t notice until later and haven’t tried to fix. I wrote when we announced the company that using agents today is still a hobby. Naming my repo maintenance tooling after a restaurant host tells you which side of that line I’m on.

Every skill in maintainerd is repo-agnostic. It reads a small config contract, a JSON file plus a few markdown documents of house rules, that says what language the repo is in, where the tests live, what the lint command is, and which GitHub labels mean what. The same skill works on a Python backend and a TypeScript plugin because the repo-specific knowledge is in the config, not in the skill.

That separation is what made the rest possible. A skill hardcoded to one repo’s conventions is a one-off script. A skill that reads a contract is infrastructure you can point at a new project in an afternoon. It’s the same argument I made when I wrote that prompts are code: an instruction that hardcodes its environment isn’t reusable. Without that separation, two people could not have built the pipeline I’m about to describe in the time we had.

What the Pipeline Actually Does

The piece of maintainerd we lean on hardest is called auto-dev. It’s a state machine. An issue moves from idea to clarification to plan to implementation, one step at a time, while I’m working on something else. It has three parts.

The first is what goes in, and the last post covered most of that. The tracker holds three kinds of work: bugs we found and can’t fix right now but an agent can, follow-ups from review that weren’t worth forking a subagent to fix on the spot, and pointers to planned features whose real content lives in a design document. The pipeline only wants the first two. The design-doc issues are labeled so it leaves them alone, and a person sits down with an agent and builds those end to end.

Most of the issues the pipeline works on were written by agents, not by us. The test for whether an issue belongs in the tracker is whether a cheap model could fix it tonight without asking anything, and an agent that just watched a bug happen usually clears that bar. When one of us writes an issue by hand, we describe it to a skill whose job is to get it to that standard. It reads the relevant code first, so the issue points at real files and functions, and it asks us the two or three questions the code can’t answer, so the issue doesn’t have to ask them later.

I don’t always hold to that. Sometimes I type a few paragraphs into an issue from my phone. When an issue isn’t good enough to build from, the pipeline’s triage catches it and asks. That’s the fallback, not the plan. Either way an issue is filed unlabeled, so the pipeline evaluates it fresh rather than assuming someone already decided it was ready.

The second part is the pipeline itself, which runs on a schedule rather than on demand. A scheduled task fires the skill at a regular interval, and each run is one tick of the state machine. It does the single highest-priority piece of work available and exits. Waiting for an answer, an approval, or a review is what happens between ticks.

Each tick looks at every open issue and asks whether it’s ready to build: whether it has enough context, whether it depends on something unfinished, whether it’s in scope. Ready issues get a plan drafted and posted as a comment, and the pipeline stops there. A plan is a proposal. Only after one of us approves it does the issue become buildable, and only then, on a later tick, does the pipeline pick the oldest approved issue, write the code, run the tests, and open the pull request. All of that state lives in a small set of GitHub labels:

"stateLabels": {
  "needsInfo": "auto:needs-info",
  "planned": "auto:planned",
  "ready": "auto:ready",
  "inProgress": "auto:in-progress",
  "parked": "auto:parked",
  "skip": "auto:skip"
}

There is no database to maintain and no dashboard to check. The state is on the issue, visible to anyone who looks at the repo, and the label history is the audit log.

The third part is the human side. It’s a skill called review-queue that I run in my coding agent. It collects everything blocked on a decision that’s waiting for me to weigh in: plans waiting for approval, pull requests where a reviewer left a comment the pipeline has already addressed, issues it flagged as needing more information. I work through the list top to bottom, the way I used to work a code review queue at Google, except most of the queue was generated by something that also drafted its own response to the objections.

I run it on my desktop and on my phone against a cloud-hosted model, and the phone version is the one that changed my habits. I’ll clear three or four items while standing in a line: approve a plan, answer a question, park something that isn’t worth building yet. That time used to go to scrolling.

The pull requests themselves get more than a glance. Most of the time we spend on them goes to running the change in a local environment and testing it. When there’s nothing to see, I read the code and either agree with it or don’t. Every pull request also goes through an adversarial review agent, and it holds code I write to the same bar as code auto-dev writes.

Here is the part that matters most. There are two gates in this pipeline, and a person has to open both. Nothing gets built without an approved plan, and someone has to read the plan to approve it. And at no stage does the pipeline merge anything. It triages, it plans, it builds, it responds to review feedback on its own pull requests. It never decides that a change is good enough to ship. That decision is still the responsibility of a human, on every pull request, with no exception for the ones that look routine. The merge rule isn’t a line in a prompt. The harness the pipeline runs in doesn’t allow it to merge, so the agent couldn’t do it even if it decided to. I’ve written before about where to put the guardrails on an agent that acts on its own. The guardrail I care most about now is not the one that stops the agent from doing damage. It’s the one that stops it from making a decision a person should be accountable for.

Four Pull Requests for One Bug

It doesn’t always go that cleanly. Last night an architecture audit flagged a real problem in one of our coding convention files, and several auto-dev runs picked it up at the same time. By the time I looked there were four pull requests open, each fixing the same thing in a slightly different way, and dozens of runs still going in the runner. I closed the pull requests, went into the runner, and shut down every instance that was working on it.

The pipeline has a limit on how many pull requests it can have open at once and a rule for reclaiming a build that looks abandoned, and both of those held. What they don’t cover is a burst of runs that all start before any of them has claimed the issue. It cost tokens and an evening, and it was the first failure of any size. I’ve been raising the run cadence and the number of open pull requests it’s allowed slowly, on purpose, so that the failures show up one at a time while they’re still cheap.

The Part That Happens in Public

Gemini Scribe is a public repository with real users, and they file issues. The pipeline treats their issues the way it treats ours: it reads the relevant code, decides whether there’s enough to plan against, and if not, posts a comment asking for what’s missing.

Sometimes that’s better than what I would have done. Someone files a short bug report, and before I’ve seen it there’s a specific question underneath it, pointing at the relevant file and asking which of two behaviors they meant. That’s a faster and more useful first response than a busy maintainer usually gives, and it arrives while the problem is still fresh for the reporter.

Every comment it posts is attributed to Claude Code in the comment metadata, so anyone reading the thread can see it wasn’t me. And each run starts in a fresh virtual machine with access to the repository and nothing else: no connectors, no configured tools, none of my data. The most it can leak is what’s already public in the repo.

Sometimes it asks the reporter what the plugin should do about the bug. That’s the wrong person to ask. They wanted their bug fixed; deciding how the software should behave is my job. The pipeline isn’t broken when it does this. It’s running the same readiness triage that works fine on a private backlog, where the only people it can ask are Chris and me. In a public tracker, that same question lands on a stranger.

I haven’t fixed this yet. What makes it tolerable is the same rule as before: the worst thing the pipeline can do in public is ask a question it shouldn’t. It can’t ship a decision. Nothing it writes reaches a user’s vault unless I put it there. The never-merge rule was meant to protect code quality, and it also limits how much damage an awkward comment can do.

I still prefer this to the alternative. An issue tracker that responds within hours instead of whenever I have a free evening is better for the person who filed the issue. Getting the questions right is a tuning problem. Getting anyone answered at all, with two people, is not something I could otherwise do.

The Same Discipline We’re Selling

I said when we announced the company that an agent has to earn the trust the access requires, and that we’d hold ourselves to that before asking anyone to trust us with their calendar and mail. This pipeline is the first place I get to practice that on myself.

The rule that it never merges is enforced by the harness, but the harness is ours. We built it that way and we could build it differently. It’s a decision, applied to our own code before it’s applied to a customer’s. If I’m going to ask someone to trust an assistant with the private parts of their day, I should at least refuse to let our own agent decide what ships. Everything else is work we’re happy to hand off: triage, drafting, boilerplate, the first pass at a reviewer’s comment. That’s the same division we want the product to make for you. Simon Willison made the argument in a post about proving your code works: a computer can’t be held accountable, so the human in the loop has to be. The decision with real consequences stays with a person who can answer for it. The product is built the same way. What Pepper is allowed to do on its own is set by policies and hooks in the agent framework, not by the model’s judgment in the moment. The harness decides where the line is, and a person decides what the harness says.

There’s a second connection I didn’t expect. Part of what we believe is that nobody should have to learn our vocabulary to get value from an agent. The review-queue skill is that idea applied to me. It doesn’t ask me to understand auto-dev’s state machine or check six label filters across a dozen pull requests. It gives me one ordered list of the decisions that are mine to make. Once you decide an assistant’s job is to meet people where they are, you notice every other place a tool is asking you to come to it.

What’s Next

One more thing I’ve noticed. A pipeline like this works because someone wrote the config contract, the conventions, the review rules, and the gates, and that someone had built and shipped software for a long time before agents existed. That’s where experienced engineers add value now. You build the frameworks that let the agents succeed, and you review what comes back. It isn’t very different from being a tech lead with a team of new grads.

None of this is finished. The pipeline still gets things wrong in ways I only find by watching it, and I’ll write about the ones worth telling. Next in this series I want to cover how we grade the agent’s work when nobody is watching. It’s closer to writing a rubric than writing code. I built a first version of that for my Obsidian plugin, and doing it for a product two people are betting on is a different problem. For now, two people are building a company with a colleague that never stops, never merges, and still needs its work checked every morning. That’s the balance I wanted.

A mostly empty library card catalog with a few cards left in one open drawer, lit by morning light.

The Backlog Was a Coping Mechanism

Allen Hutchison1 Comment

We gave our coding agents a rule that sounded obviously correct. No follow-up left behind. It went into our agent context files in roughly those words: anything a pull request doesn’t fully address gets filed as an issue before the review closes. No deferred cleanup sitting in a comment nobody reads again, no “we should probably handle this properly at some point” evaporating the moment the branch merges. Every loose thread becomes a tracked one, and the agents were good at following it.

The rule worked exactly as designed. That was the problem. Take the last month, which is the first real stretch where I’ve been full time on the product. In those 30 days the two of us merged 657 pull requests on our main repository, close to 30 on a typical weekday. Every one of them came out the other end of review with its own small pile of follow-ups. Honest ones, well written, entirely legitimate.

Over the same 30 days we opened 449 issues. Fifteen a day, most of them filed by our own agents rather than typed by us. Nothing in the system closed the loop. The list only grew, and it grew faster the more time I gave it.

This is the first post in a series about how the two of us actually build Vycari, which I promised when I wrote about why we started the company. I want to start here, with the issue tracker, because it’s the piece of the toolchain I had thought about the least and had to change the most. Almost everything I believed about what belongs in a bug database turned out to be a belief about human limitations rather than about software.

What We Were Really Doing When We Filed a Bug

Think about why you file an issue. You have an idea for something the project should do, and you write it down so it doesn’t fall out of your head. You’re deep in one file and you spot a bug in another, and you write it down so you don’t lose your place. You’re cleaning up a module and you notice three more that need the same treatment, so you write those down too.

The common element in all of it is that you couldn’t do the thing right then. Filing was the second best option. The tracker was a memory prosthesis, a place to park work your hands were too busy or too few to pick up, and it was built for exactly that. Bugzilla went public on a mozilla.org server in 1998, replacing Netscape’s in-house system. The shape it established is still the one we use. A durable record, an owner, a state, a conversation attached to it. Durable because the gap between noticing and fixing was measured in weeks.

The failure mode is just as old. Avery Pennarun makes the point plainly in his treatise on bug tracking and triage. Bugs pile up when filing outpaces fixing. Declaring bug bankruptcy doesn’t change the slope of that line. Every engineer I know has worked in a tracker where the honest read on most open issues was that nobody would ever look at them again. We tolerated it because the alternative was forgetting, and forgetting felt worse.

The second thing we used trackers for was breaking work apart. The vocabulary comes from the agile world. Mike Cohn defines an epic as, simply, a large user story, one you decompose into smaller stories when a team is ready to work on it. Big thing arrives, big thing gets chopped into two-week pieces, pieces get distributed across people, tracker becomes the coordination surface. That’s project management wearing an issue tracker as a costume, and for humans it works well.

Both of those jobs assumed constraints that agents removed. We spent the last few weeks stress testing that, finding out which parts of the practice were load bearing, and came out the other side with a different idea of what a tracker is for.

The Follow-Up That Doesn’t Need to Wait

Start with the follow-ups, because that’s where the pain showed up first.

Our code reviews are agentic. We run Greptile on every pull request and I’ve been genuinely happy with what it catches. An agent reads the diff against the project’s own conventions and writes up what it finds. The good ones find real things. A missing test case, an error path that swallows a failure, a helper that should have been extracted. Under the old rule, each of those became an issue. Faithful record keeping, and a queue that grew every single day.

What we’re experimenting with now is skipping the record entirely. When the review turns up a follow-up, the reviewing agent forks its own context into a subagent and hands it the problem immediately. The fork inherits the conversation that produced the finding, so it already knows the file, the convention that was violated, and why the reviewer cared. It goes off and opens its own pull request while the original review continues uninterrupted. If the pull request that spawned it hasn’t merged yet, the fork stacks its work on top of that branch.

The economics are almost embarrassing. Writing a good issue means describing context that is already loaded in the window right in front of you. Then, later, some other agent pays to rebuild that context from scratch by re-reading the same files and re-deriving the same reasoning, assuming anyone ever picks the issue up at all. Forking the context costs a fraction of that and produces a pull request instead of a promise. It reuses the cached context from the original thread, which saves real money and skips the whole bootstrapping conversation. The cache is already warm. The reasoning is already done.

I want to be careful not to oversell it. This doesn’t work for everything. Some findings send me off to do research first. Some need me to sit with the consequences, or go take a walk and figure out how I actually want to handle the situation. Some need a conversation between me and Chris about whether a feature is the right fit for the product at all. Those still get filed, and I’ll come back to what that queue looks like now. But the default flipped. Filing an issue used to be what you did with a follow-up. Now it’s what you do when the follow-up needs a person to think first.

Epics Assume a Constraint That Left

The second habit took longer to give up, because breaking work into pieces feels like professionalism itself.

An agent can produce a five thousand line pull request in ten minutes. When that’s true, the reason for chopping a large feature into eleven tracked sub-issues mostly disappears. You weren’t decomposing because the work was inherently separable. You were decomposing because a person can only hold so much in their head at once, because a sprint is two weeks long, and because four people needed to work in parallel without colliding. Those are real constraints. None of them are the agent’s.

This is not an argument against testing, or against reviewing carefully, or against building a large feature in stages you can actually validate. Every one of those matters more now, not less. Simon Willison put it well recently. Using agents well takes two skills, instructing them clearly and verifying that what came back is right. He also points out that eyeballing every line was never the best way to do the second one. The chunking that survives is the chunking that helps you verify. The chunking that dies is the chunking that existed to schedule humans.

The testing instincts I picked up early in my career are paying dividends now more than ever. I can load our project into a browser inside the coding agent and start poking at it. When something behaves wrong, the agent is sitting right there with the context already loaded, so I can just ask about it. I can drive the thing from the terminal and then go verify what actually happened in my local database or against my local copy of the service. None of that is new. It’s the same work I’ve been doing for my whole career, and agents didn’t change it.

So we stopped using issues as project management. The agent doesn’t need a burndown chart, and neither do the two of us. We did try. We briefly put the work into a GitHub project built on our issues, kanban columns and all. It fell out of date faster than either of us was willing to maintain it.

Aspirational Issues Are a Trap

The third category is the one I’d defend the longest and was most wrong about. “Someday we should support real-time collaboration.” “It’d be nice if this thing had a plugin system.”

An agent cannot reliably act on an issue like that. It doesn’t have the product context, the customer conversations, or the constraints that would make one implementation right and another one a waste of a week. What it has is enough capability to build something confidently, quickly, and wrong. Aspirational issues are the ideal input for producing exactly that.

Worse, they poison the queue around them. If a tracker is a work list something else pulls from overnight, every unbuildable item in it is a small trap laid for a system that can’t tell the difference. Those ideas are still worth keeping. They just belong somewhere that isn’t the tracker: a document, a spreadsheet, a future-features markdown file checked into the repo. Somewhere a person browses on purpose, rather than somewhere an agent shops.

What Actually Belongs in the Tracker Now

Here’s the test we use. Could a cheap, fast model with the repository’s context in hand fix this tonight, correctly, without asking me anything?

I mean cheap literally. Sonnet 5, Gemini Flash, GPT Terra. If the issue is well defined and the project’s conventions are written down where an agent can read them, the frontier model isn’t buying you much. That’s a strong forcing function on how you write the issue. It’s also the same forcing function that made issues good for humans.

Three kinds of work pass the test. Bugs I found while using the product away from my desk, which I can describe well because I just watched it happen. Most of those reach the tracker through a feedback path rather than through my hands, and the nightly reflection that turns them into issues is a post of its own. Follow-ups from review that resisted being forked. Small features that are well scoped, well understood, and simply not a priority this week. That’s it. Everything in the tracker is something a low-cost agent could pick up and drive to a pull request, prioritized so it knows which one to pick.

We have a pipeline that does exactly that. It doesn’t wait for night. It runs continuously, picking up whatever is ready whenever it becomes ready. That’s the next post in this series, and it’s the reason the discipline in this one matters so much. A pipeline that works through an unfiltered backlog is a machine for generating plausible garbage at scale.

I’m also experimenting with a task that sweeps every issue opened during the week and spawns an agent to fix the ones that qualify. That habit is new enough that I don’t know yet whether the tracker ever actually reaches empty.

Where the Big Work Goes Instead

None of this means we stopped doing big things. It means the big things stopped living in the tracker.

For a substantial feature, I work with an agent to write a product document first. That might be a short document, a mock, or a piece of a design system, whatever makes the idea concrete enough to argue about. Then Chris and I talk it through until we agree it’s actually right for the product. Only then does it become the input to a technical design document, which gets reviewed the way any other design gets reviewed and then checked into the repository alongside the code. After the design doc lands we create an issue, and the issue says one thing. Implement this design.

That issue is not food for the overnight pipeline, and it’s labeled so the pipeline leaves it alone. It’s a marker. It exists so that a person sitting down with an agent has a place to start, and so both of us can see what’s planned but not yet built. When someone picks it up, the first move is to point the agent at the design doc for context, and then build the feature end to end. Not in phases the issue dictated in advance, because an issue written before the work started is a bad predictor of how the work will actually decompose. In reasonably sized chunks of working functionality, with a lot of manual testing along the way, laddering up to the whole thing. That doesn’t mean one enormous pull request either. I’m about fifteen pull requests into a feature right now, several days of work, all of it pointed at a single issue.

The design document does the job the epic used to do, and does it better. It holds the reasoning, not just the task list, which is what an agent needs to build something faithfully. And it’s version controlled next to the code it describes, so it goes stale visibly instead of quietly. We have an agent that runs nightly to compare the claims in those documents against the code and update the ones that have drifted, which is a story for another day.

Taking Inventory

Last week I stopped adding and took inventory instead. 300 open issues on that same repository, every one of them read against the actual code rather than against its own title, then sorted by what it would really take to close.

15 were already dead. Fixed by some other pull request, obsoleted by a decision we’d since made, duplicated, or never actionable in the first place. 54 were real work an agent could simply do, so I let it. The sweep spawned subagents in waves and merged 54 pull requests over the following days. That’s 69 issues, most of a quarter of the backlog, that a machine could resolve without me in the room.

The rest is the part that stuck with me. 101 needed a decision from me. 54 needed one from Chris. 67 were epics or deliberately parked, and I left them alone on purpose. Three quarters of what we had filed wasn’t work at all. It was a queue of decisions wearing work’s clothing, and it had been sitting there looking like a backlog the whole time.

That number moved me further than any argument in this post did.

Three Jobs Instead of One

What we’ve landed on is a tracker with three purposes. It holds things we found and can’t fix right now but an agent can fix later. It holds pointers to planned work whose real content lives in a design document. It holds the follow-ups from review that weren’t worth forking a subagent to solve on the spot.

Look at what fell out. The tracker stopped being a filing cabinet for human memory. Everything in it is now addressed to a machine that will read it, act on it, and open a pull request. That makes an issue much closer to a function call than to a note to self. I’ve argued before that prompts are code and deserve the same rigor. An issue an agent will execute is the same claim, arriving from a direction I didn’t expect.

The part I’m still sitting with is how much of my old practice was compensation. Filing a bug so I wouldn’t forget it. Breaking an epic into pieces so a team could carry them. Keeping a wishlist because writing it down felt like progress. Those were all coping mechanisms for being a human with one pair of hands and a bad memory. I still have both of those things. I just have fewer reasons to build my tools around them.

Next time, the pipeline that works through this queue on its own, and what happens when it wanders into a public repository and starts talking to strangers.

A clean workspace at night with a glowing laptop screen, smart ring, smart glasses, and a starry sky outside.

Reading List 8

Allen Hutchison1 Comment

This week’s reading list explores the shifting paradigms of personal software development, the evolving dynamics of managing AI agents, and the frontier of ambient hardware. From the realization that managing agents is deeply adjacent to engineering management, to building custom tools without writing a line of code, these articles highlight how rapidly our relationship with computers is changing.

Managing agents requires the same skill set as managing human engineering teams

[blog] Understand to participate. Geoffrey Litt’s framing from the AIE World’s Fair on collaborating with coding agents is spot-on. He argues that we must understand the code to a depth that enables us to participate further with the model, avoiding taking on cognitive debt as our understanding drifts from the actual implementation. I think this is absolutely right, and it points to why people with management experience may actually excel in a fully agentic world—an idea I explored late last year in Unlocking AI Success: How Managerial Skills Can Help You. If you have managed an engineering team before, you already know that you cannot be deeply familiar with every single line of the codebase. Instead, you understand how to build a high-level conceptual model that lets you guide and make meaningful contributions through your employees—or, in this case, your agents.

Securing public-facing LLMs against prompt injection is becoming a practical science

[blog] What happened after 2,000 people tried to hack my AI assistant. Fernando Irarrázaval’s write-up on defending his AI assistant from prompt injection is a masterclass in practical security. As we move from isolated sandboxes to public-facing agentic workflows, the threat of prompt injection becomes a first-class engineering concern. It is incredibly encouraging to see this defensive engineering maturing into a rigorous, practical science with real-world data rather than just hypothetical panic.

We are entering a golden age of bespoke, personal software

[article] Claude redefined my bond with Macs. I am building my own apps and it’s a bliss.. This piece from Digital Trends is more evidence of the rapid onset of what I call the “personal software” era. The author, who doesn’t know how to code, describes building fully functional, offline menu bar utilities, image mockup editors, and custom word processors with Claude inside of a few hours. When the friction of translating intent to code drops to zero, we stop downloading generic software and start building bespoke tools tailored precisely to our quirks—a theme I wrote about in Building Personal Software: Crafting Your Own Tools for Success. It is a profound shift in how we interact with computers.

Tracking the relentless march of the AI goalposts over four years

[blog] It Still Can’t Do My Job: Four Years of Moving Goalposts (2022–2026). This is a delightful walk down memory lane, cataloging the shifting skepticism from the launch of ChatGPT in late 2022 to the state of the art in 2026. It is highly entertaining to look back at the “goalpost graveyard” and see how quickly criticisms like “it can’t even write Snake” or “no real developer will use it” transitioned from conventional wisdom to historical footnotes. It’s a healthy reminder of just how fast the baseline is moving underneath us.

The physical interface of computing is shrinking to our fingers

[tool] Productivity, without the keyboard.. The Oasis smart ring is a fascinating look at the future of ambient input. By packing a touchpad and private voice input via a noise-isolating microphone into a ring, it aims to let you capture thoughts and interact with assistant systems without being glued to a keyboard or screen. As voice-to-text engines like Whisper become incredibly low-latency and accurate, the hardware we use to feed them is shifting from heavy screens to subtle, wearable devices.

A hand-drawn map on a workbench with a half-built mechanical instrument being assembled directly on top of it.

Agents as Building Blocks

Allen Hutchison2 Comments

There’s a thread running through the last year of my writing and my work, and I didn’t fully see it until now.

Last September, I wrote Full Circle, about going back to building after years of leading teams. I wanted to be in the driver’s seat for what I called the agentic shift. I wanted to feel the code under my fingers again, to be close enough to the technology that I could form my own opinions about where it was going.

Then I spent six months drawing the map. The Agentic Shift was twelve essays on what agents are, how they work, and what it means to build them well: anatomy, memory, tools, guardrails, multi-agent coordination, production readiness. It was a theoretical framework, written while I was getting my hands dirty on the Gemini CLI team.

And then, in January, I wrote Everything Becomes an Agent, the practitioner’s version. Not theory anymore. I’d watched Gemini Scribe grow from a chat window into a full agent. I’d seen the CLI team go from talking about code to writing and executing it. I’d noticed a pattern repeating across every AI project I touched: given enough time, they all converged on the same architecture. Tools. Loops. Policies. Judgment.

The Antigravity SDK is the second agent product I’ve worked on at Google. Gemini CLI was the first, and it’s where I learned what an agent runtime actually needs: a policy engine, a tool pipeline, lifecycle hooks, a trust model that scales from “let me approve every file write” to “here are the guardrails, go handle it.” The SDK is the next step. Taking everything I learned building one agent and making it possible for everyone to build their own.

Today we’re launching the Antigravity SDK in Preview. The official announcement covers the features (what the SDK does, how to install it, what you can build). This post is about the why. Why this SDK, why this design, and why it matters to me.

What Is an Agent SDK, Really

Here’s something I find fascinating: people have wildly different ideas about what “agent SDK” means.

For some, it’s a way to automate the coding agent. You take the AI that already lives inside your IDE (Antigravity, Cursor, Copilot), and you script it. Pipe in a task, get back a diff. The SDK is an extension of your development environment. That’s a legitimate philosophy, and there are good products built on it.

But that’s not what I wanted to build.

To me, an agent SDK gives you an agent that you can incorporate into your software. Not an extension of your IDE. A building block. Something you import into your Python project the same way you’d import a database client or an HTTP library, and then you use it to solve a problem. The agent is a component in your system, not a wrapper around your workflow.

I’ve watched this pattern play out across Gemini Scribe, the Podcast RAG prototype, and a dozen smaller projects. Software that starts as a script, grows a tools array and a while loop, and eventually looks an awful lot like an agent. I wouldn’t claim that every AI project becomes an agent. But the pattern is durable for a huge class of software problems. And if that convergence is real, if a meaningful number of AI applications end up needing tools, memory, judgment, and guardrails, then the SDK should make that convergence frictionless.

The key distinction is this: the agents you build with the Antigravity SDK aren’t extensions of your developer tools, although they can do development work. They’re independent pieces of software that happen to be implemented as agents. They live in your codebase, run on their own, and do real work.

Let me show you what I mean.

Three Agents That Prove the Point

Two of my favorite examples ship with the SDK, and we use both of them on the SDK project itself on a regular basis. They live in the examples directory on GitHub.

The first is the docstring maintenance agent. You point it at a directory, and it audits every Python file for missing or incomplete docstrings, then fixes them, all following the Google Python Style Guide. It knows which tools it’s allowed to use (read files, list directories, edit .py files in the target directory, and nothing else). It has a policy engine that enforces those boundaries. It runs, does its job, and exits.

The second is the documentation maintenance agent. Same idea, different problem: it scans your project’s documentation for staleness, checks it against the current state of the code, and updates what needs updating.

Here’s what I love about these two examples. They’re coding-related tasks, but they aren’t extensions of my IDE. They’re standalone programs. I don’t run them inside my editor. I run them from the command line, or from a CI job, or from a cron schedule. They happen to be implemented as agents because an agent is the right abstraction for “read a bunch of files, reason about their quality, and make targeted edits.” If I’d built these as scripts, I would have ended up writing a brittle classifier full of if/else branches to decide what to fix and how. The agent architecture deletes that complexity.

We use both of these on the SDK project itself. The SDK maintains its own documentation with its own agents. There’s a satisfying recursion to that.

But I want to push the point further, because the SDK isn’t just for coding tasks. Here’s a completely different kind of agent, a personal knowledge graph I wrote that connects to my Workspace MCP server and answers questions about my Drive, Docs, Gmail, and Calendar:

import asyncio

from google.antigravity import Agent, LocalAgentConfig, types
from google.antigravity.utils import interactive


async def main():
    workspace_mcp = types.McpStdioServer(
        command="node",
        args=["/Users/adh/src/workspace/workspace-server/dist/index.js"],
    )
    system_instructions = (
        "You are a Personal Knowledge Graph Agent. Your goal is to help the user "
        "navigate and synthesize information from their Google Workspace "
        "(Drive, Docs, Gmail, Calendar). You can search for documents, "
        "read emails, and check calendar events to answer questions "
        "and help the user connect the dots."
    )
    config = LocalAgentConfig(
        system_instructions=system_instructions,
        mcp_servers=[workspace_mcp],
        capabilities=types.CapabilitiesConfig(
            enabled_tools=types.BuiltinTools.read_only(),
        ),
    )
    async with Agent(config) as agent:
        print("Knowledge Graph Agent ready. Ask me anything about your Workspace.")
        await interactive.run_interactive_loop(agent)


if __name__ == "__main__":
    asyncio.run(main())

This agent has nothing to do with coding. It’s a personal productivity tool that connects to my Google Workspace via MCP and lets me query my own data in natural language. It’s about 20 lines. It’s read-only by design. And it uses the same SDK, the same patterns, the same trust model as the docstring agent.

Three examples, three completely different domains: autonomous code maintenance, documentation upkeep, personal knowledge synthesis. All built with the same building blocks. That’s the vision.

Batteries Included, Layers When You Need Them

When designing this SDK, I kept coming back to one principle: batteries included. I wanted it to be really easy to put together an agent that worked for you. Easy to grow your application when you needed more sophistication. Easy to dive into the internals when the situation required it.

Here’s what a functional agent looks like:

import asyncio

from google.antigravity import Agent, LocalAgentConfig


async def main():
    config = LocalAgentConfig()
    async with Agent(config) as agent:
        response = await agent.chat("What files are in the current directory?")
        print(await response.text())


if __name__ == "__main__":
    asyncio.run(main())

That’s it. About 10 lines of real code. That agent can read files, edit code, run shell commands, search directories, all out of the box. You didn’t have to configure tools, set up a model connection, or wire up a conversation loop. The batteries are included.

But batteries included doesn’t mean batteries only. I designed the API in three layers, and knowing which layer to reach for is part of the design.

Layer 1: Agent. The highest level. Create an agent, give it a prompt, get results. This is where most people start, and many people stay. It manages the full lifecycle (connection, conversation, tools, hooks, policies) in a single async with block. If you just need an agent that does a job, this is your entire API surface.

Layer 2: Conversation. This is the implementation layer. Conversations, hooks, policies, MCP servers, custom tools, structured output. Conversation wraps a Connection with step history, turn tracking, and convenience methods. This is where you shape behavior. You add guardrails through the declarative policy engine. You inject lifecycle hooks, and the SDK gives you three distinct types: Inspect hooks for read-only observability, Decide hooks for policy decisions (allow/deny), and Transform hooks that can modify data in flight. You wire up MCP servers and your own Python functions as tools.

Layer 3: Connection. The lowest level. Connection is the abstract interface for talking to an agent backend. ConnectionStrategy knows how to establish one for a specific runtime. Today, we ship a local connection strategy that runs the agent on your machine. On the roadmap: remote connection strategies that let the same agent code deploy to the cloud without a rewrite.

Here’s the neat thing about this layer. Because Connection is an abstraction, you could conceivably wire up other agent runtimes behind it. We do this internally. We have several different ways of talking to our agent harness, and they all work through the same Connection interface. Your agent code doesn’t know or care which one is running underneath.

The philosophy is: easy to start, easy to grow, easy to go deep. You shouldn’t need to understand the Connection layer to write your first agent. But when you need it, when you’re building something that requires custom streaming, session resumption, or a novel deployment target, it’s there, and it’s a clean abstraction, not a hack.

One detail I’m particularly proud of: the trust model adapts to the deployment context. The base AgentConfig is deny-by-default. It defaults to read-only tools, and if you try to enable write tools or MCP servers without a safety policy, the Agent refuses to start. Enforced at the framework level. LocalAgentConfig takes a different posture. Since it runs on your own machine, it enables every tool, scopes file operations to the workspaces you’ve configured, and gates shell commands behind a user confirmation prompt by default. You’re developing locally; you probably want your agent to actually do things, but you also probably want a chance to look before it runs rm -rf. The trust gradient is baked into the architecture.

Lessons Encoded

If you’ve been following along with my writing, the SDK might feel familiar. That’s intentional.

The twelve-part Agentic Shift wasn’t just an intellectual exercise. It was the blueprint. Every essay mapped a concept that eventually became a feature.

In Everything Becomes an Agent, I wrote: “If you’re writing if/else logic to decide what the AI should do, you might be building a classifier that wants to be an agent.” The SDK takes that literally. You don’t build classifiers, you define tools and let the model decide which ones to use. The complexity moves from branching logic to capability definition.

I wrote about building a “sudoers file for AI”, a permission system for agents. That became the policy engine. policy.allow("view_file"). policy.deny("*"). Declarative, composable, deny-by-default. You express what’s allowed, and the framework enforces it.

I wrote: “The real complexity isn’t in the code; it’s in the trust.” That conviction shaped the hook system. Hooks give you visibility into every tool call, before and after. Policies give you control. Together, they manage the trust relationship between you and the agent. The SDK doesn’t ask you to trust blindly; it gives you the instruments to verify.

And I wrote: “A hammer does nothing unless you swing it. But an agent? An agent can work while you sleep.” That’s the promise. The SDK is the handle.

These aren’t abstract design principles that I reverse-engineered to sound good in a blog post. They’re lessons learned from building Gemini Scribe, from contributing to Gemini CLI, from watching every project I touched converge on the same agentic patterns. I drew the map, I lived the map, and then I got to build the territory.

The Team

I want to be clear about something. I didn’t build this alone.

I did most of the design for the Python SDK (the API surface, the three-layer architecture, the philosophy behind “batteries included”), and a lot of that design came from the writing I’ve been doing this past year. But design is the easy part. The hard part is building something real, and that was a team effort.

A talented group of engineers worked with me on this. On the SDK implementation, on the test infrastructure, on the Go harness underneath that actually runs the agent, on the internal connection strategies, on the MCP bridge, on a hundred decisions that don’t show up in a blog post but absolutely show up in the quality of the software. The SDK exists because of their work, and it’s better than anything I could have built on my own.

Preview, and an Invitation

We’re shipping this as a Preview. Not “1.0.” That’s deliberate.

The API surface will change. We know that. We’ll evolve it based on feedback from you and from our own continued use of the SDK, because we use it too, every day, on the project itself. There are things we haven’t figured out yet. There are patterns we haven’t discovered. That’s the point of a preview: to learn in the open.

So here’s the invitation: build something. Build a documentation bot, a knowledge graph, a CI pipeline agent, a personal assistant. Build something I haven’t imagined. Break something. Tell us what’s missing, what’s awkward, what delights you. File an issue. Open a PR. Argue with us about the API.

Last September, I wrote that I was going back to building because “for a builder, there’s no more exciting place to be.” The Agentic Shift was the map. The SDK is the territory.

Come explore it.

The Antigravity SDK is available now as a Preview. Install it with pip install google-antigravity, read the official announcement for feature details, and find the source on GitHub.

A futuristic glowing notebook on a wooden desk with a cup of coffee and floating geometric shapes.

Reading List 6

Allen HutchisonLeave a comment

This week’s reading list is a mix of high-level theory and low-level pragmatism. I found myself bouncing between the philosophical implications of how we build AI and the immediate satisfaction of writing a good Go component.

[article] The Century-Long Pause in Fundamental Physics. The author argues that physics has stagnated by swapping “ontology-first” theory for mathematical models that merely fit data. This debate perfectly mirrors current machine learning disputes about whether LLMs build internal world models or just pattern-match at scale, which is the open empirical front currently being adjudicated in mechanistic interpretability.

[release] Onyx Has Released a New Remote Page Turner Called Tappy. I wish Amazon would support page turners for their Kindle line. It would be great if they supported a device as delightful as this one.

[blog] The agent principal-agent problem. This is a great look at one of the biggest problems with agentic development: code review. In my open source work, I now use a pattern where I work with an agent to make a change, test it locally, and create a pull request before having another agent review the code. This back-and-forth works well and keeps a good balance of mental state for the codebase and efficiency.

[article] ReMarkable Paper Pure wants to be the only notebook you’ll ever need. I have always liked the reMarkable tablets, but every time I try one I miss having my Kindle library alongside it. Reading and writing are deeply linked for me, which is why I recently got a Kindle Scribe Colorsoft and found it really hits the mark for what I want.

[blog] Just Fucking Use Go. I have been working on a project that has a Go component to it recently. This is the first time I have really started to look at the language, and it inspires me to spend more time with it.

I built my 7MB Full AI Terminal in Rust & Tauri. This is a neat open source AI terminal. It feels similar to Warp but is a lot smaller.

[article] Computer Use Is 45x More Expensive Than Structured APIs. I am not surprised at all by these findings. I think computer use will remain a last resort, and a lot of apps will expose some kind of API for an agent to use instead. My guess is that this eventually becomes the way we automate unmaintained applications that need to fit into an agentic workflow.

A wooden violin with holographic blueprints projecting from it on a workbench.

Reading List 5

Allen Hutchison1 Comment

Today’s reading list is a mix of cautionary tales about our digital infrastructure and some fascinating glimpses into how AI is changing both software design and human interaction.

[article] GoDaddy Gave a Domain to a Stranger Without Any Documentation. Wow. This is a really chilling story. I’m glad that I don’t use GoDaddy for my domains.

[article] HashiCorp co-founder says GitHub ‘no longer a place for serious work’. GitHub is in a tough situation. If you look at the graphs they published from their April 28th outage you can see that their growth rate is off the charts. Agentic coding has put strains on that infrastructure that no reasonable person or team could have been prepared for, and the result is a degraded experience and customers walking away.

[blog] Letting AI play my game – building an agentic test harness to help play-testing. There is something really satisfying about watching an agent test a product. I’ve been doing this a lot lately with my Gemini Scribe project, which I need to write about at some point.

[blog] How to use Deep Research with the Gemini API. Great writeup on how to use the latest version of the deep research agent. I’ve updated gemini-utils and my Gemini CLI deep research extension for the newest version of deep research as well.

[article] Meet Shapes, the app bringing humans and AI into the same group chats. It’s inevitable that AI is going to start showing up in more settings where people talk to each other.

[article] Statue of a man blinded by a flag put up by Banksy in central London. This seems like the perfect statue for our times.

[article] MIT’s virtual violin offers luthiers a new design tool. One of the things that makes string instruments so complex is that they are an interface between physics and nature. The wood imparts its own characteristics on top of the geometry. This is a neat project from MIT, but to really help luthiers they will also need to be able to model the woods used in these instruments.

[article] Instagram is testing optional ‘AI creator’ labels. I really think the industry has this backwards. We should be creating “human created” labels. We should assume all content is AI unless otherwise stated.

A spotlight shines on a pianist intensely playing a small, worn piano on a large, dark stage.

The Koln Concert and Creative Constraints

Allen Hutchison2 Comments

This week I was reminded of a story I like to tell, and the value of constraints on creative work. When I’m working, I often set my constraints before I begin. For example, on an old agentic coding project, I set a few constraints: “The orchestration model must be Gemini Flash,” “All tool calls are through sub-agents,” and “Permissions and configurability are at the core of the agentic loop.” From that, I ended up with adh-cli, a policy-aware TUI for working with Gemini that inspired many of the features I worked on in Gemini CLI last year. The project itself is defunct now and not maintained, but the constraints gave me a great way to think about the project and forced creativity in other areas.

We run into constraints in many different ways. Maybe it’s time pressure: How many of you felt like you wrote your best papers 24 hours before they were due? Maybe it’s the environment, like you must integrate with a certain piece of software, or you have to design your system in a certain way. Maybe it’s self-imposed like my example with adh-cli.

Or maybe the constraint is philosophical. Take Mario Zechner’s Pi Agent, for example. In a blog post, Zechner expressed frustration with the bloat of modern AI coding assistants that try to do everything, describing them as “spaceships with 80% unused functionality.” In response, he built Pi around an “anti-framework” philosophy of radical minimalism. He intentionally constrained his default coding agent to just four fundamental tools: read, write, edit, and bash. By stripping away the hidden system prompts and unpredictable context injections, the tool forces developers to be intentional. It proves that you don’t need a massive, opaque framework to build highly capable AI workflows—sometimes, fewer tools create a sharper focus.

Whether it’s a self-imposed architectural rule or an anti-framework philosophy, these software constraints force us out of our default habits and into a space of deliberate, intentional design. Yet, in our day-to-day work, constraints are rarely celebrated. In fact, that is actually how I end up in constraint conversations the most often: people don’t like their constraints because the constraint has been imposed on them externally. They see it as a restriction instead of a way to channel their creativity. To me, a constraint means that we shut down a huge portion of the exploration space. I don’t have to worry about a million different architectural choices because the constraint has made the decision for me. It is incredibly freeing. Whenever I try to help someone turn around their mindset—from fearing or being frustrated by constraints to being excited by them—I inevitably end up telling them the story of Keith Jarrett and the 1975 Köln Concert.

In 1975, a 17-year-old jazz fan named Vera Brandes organized a late-night concert at the Cologne Opera House. She managed to book Keith Jarrett, one of the most notoriously perfectionist jazz pianists of his generation. It was an ambitious undertaking, and almost immediately, it turned into a disaster.

Due to a backstage mix-up, the venue provided the wrong piano. Instead of the premier concert grand Jarrett requested, he was presented with a small rehearsal model. It was horribly out of tune, the pedals stuck, the high notes sounded tinny and harsh, and the bass lacked any resonance. Jarrett, exhausted and suffering from back pain, flat-out refused to play. It was only when Brandes followed him out into the pouring rain and begged him that he relented, taking pity on the teenager. “Never forget,” he told her. “Only for you.”

What happened next is legendary. Forced to play an unplayable instrument, Jarrett had to completely abandon his usual style. Because the high and low registers were awful, he confined his playing strictly to the middle of the keyboard. Because the piano was too quiet to fill the 1,400-seat opera house, he stood up and hammered the keys with immense physical force. To make up for the lack of resonance, he relied on rolling, repetitive, hypnotic rhythmic patterns in his left hand.

He embraced the limitations, and in doing so, he produced absolute magic. The recording, The Köln Concert, went on to become the best-selling solo jazz album in history.

I think about the Köln Concert all the time, especially lately as we navigate the current landscape of Artificial Intelligence and software architecture.

The Bloat of Infinite Resources

In modern software engineering, we are rarely handed a broken piano. We operate in an era of perceived infinite resources. Cloud computing gives us endless horizontal scaling. Context windows for Large Language Models have ballooned from a meager 4K tokens to 1 million or more. If an application is slow or an agent isn’t performing well, the default instinct is to throw more compute, more memory, or a larger model at the problem.

But infinite resources often breed intellectual laziness. When you have a 1-million token context window, you don’t have to think critically about what information actually matters. You just dump the entire codebase or the entire library of documents into the prompt and hope the model figures it out. It’s the equivalent of having a perfect Bösendorfer grand piano and just mashing all the keys at once.

A pragmatic engineering manager might push back here: Developer time is expensive. If I can solve a problem today by dumping an entire codebase into a 1-million token context window, isn’t throwing compute at it just good business?

It’s a fair question, and engineering is always about tradeoffs. But the tools have evolved—building a RAG pipeline doesn’t take a week anymore; with the right utilities, it takes minutes. More importantly, relying on infinite resources often hides long-term costs. When I built adh-cli, I made an explicit tradeoff: by routing everything through tightly scoped sub-agents, I was actually consuming more total tokens than a single massive prompt would use. But because my constraint forced me to use a much cheaper model (Gemini Flash), my bet was that the overall system would be far more cost-effective and resilient. AI doesn’t remove the need for architectural judgment; it exponentially increases it. You have to exercise good judgment to know when throwing compute at a problem is a calculated business decision, and when it’s just masking a fragile design.

The Innovation of Constraints

The most interesting work in AI right now isn’t happening where resources are unlimited. It’s happening at the edges, where constraints are severe.

Take local models, for example. When you’re trying to run an LLM on a consumer laptop or a Raspberry Pi, you don’t have the luxury of a 70-billion parameter model. You are forced to use a smaller, quantized model. This constraint forces you to build better architectures. You can’t rely on the model to “know” everything, so you have to optimize at the edge. Maybe you build robust Retrieval-Augmented Generation (RAG) pipelines. Maybe you implement sophisticated memory retrieval systems to surface exactly the right historical context just-in-time. Or maybe you break complex workflows down into tiny, focused sub-agents, each operating with its own tightly constrained context window. You have to craft highly specific, deterministic prompts.

# Instead of one massive prompt, constraints force modularity
def evaluate_code_chunk(chunk: str, context: dict) -> EvaluationResult:
    """
    A tightly scoped function that uses a small, fast local model
    to evaluate a specific piece of code, rather than dumping
    the whole repo into a massive API call.
    """
    prompt = build_focused_prompt(chunk, context)
    response = local_model.generate(prompt, max_tokens=256)
    return parse_evaluation(response)

Just like Jarrett avoiding the tinny upper register, we learn to avoid the weak points of our tools. We build guardrails. We write cleaner code. We design systems that are elegant because they have to be.

Finding Your Broken Piano

Of course, there is a survivorship bias to the Köln Concert. For every broken piano that produces a masterpiece, there are a hundred broken laptops that just result in missed deadlines. Not all constraints are good constraints. You can’t change the laws of physics, and if a structural limitation is genuinely preventing the work from happening, you have to reevaluate. The goal isn’t to suffer for the sake of suffering. But by starting with strict constraints, you force yourself to explore the boundaries. If you prove a task is impossible under those conditions, you can always loosen the constraints and expand your resources. But if you start with infinite resources, you never learn where those boundaries actually are.

Constraints are not the enemy of creativity; they are its prerequisite. Yes, accepting a severe constraint—especially an external one you didn’t choose—can be incredibly painful in the moment. Keith Jarrett hated his broken piano. He didn’t feel freed; he fought against it until he was forced to adapt. But like exercise or eating your vegetables, the value isn’t in the immediate comfort. It’s about the mindset shift. You accept the constraint to build a muscle, to stay fit, to force yourself to find a new path when the easy one is blocked. When we are stripped of our ideal tools and infinite runways, we are forced to abandon our default habits. Whether it’s the self-imposed design rules of adh-cli, the radical minimalism of Mario Zechner’s Pi Agent, or the physical limitations of a broken rehearsal piano in Cologne, constraints force us into a space of deliberate, intentional action.

If you want to build a truly resilient, innovative system, don’t start with the biggest, most expensive tools available. Start with a broken piano. Artificially constrain your resources. Limit your context window. See what you can achieve with a 7B parameter model instead of a flagship API, or see what happens when you strip your agent’s toolkit down to the bare essentials.

You might just find that the limitations force you to build something far better than you would have otherwise—a system that is elegant not in spite of its constraints, but because of them.

So, look around your current projects. Where are you relying on infinite resources to mask lazy architecture? And more importantly: what constraints have you come across in your own work that felt like a frustrating restriction at first, but turned out to be a blessing in disguise? I’d love to hear your stories.

A split illustration contrasting corporate AI surveillance with independent home computing.

Reading List #4

Allen HutchisonLeave a comment

This week’s reading had a through line I wasn’t expecting. Almost every article circles back to the same question: who actually benefits when AI reshapes an industry? The answer isn’t always the people doing the work.

[article] Tech CEOs Think AI Will Let Them Be Everywhere at Once. All of the articles I’ve seen on these “management intelligence layers” feel very one-sided. The executive gains synthesized information and faster decision-making, but what do the employees get? Do junior and mid-career folks get better mentoring and coaching? I don’t think so. Collapsing the layers might be good for the bottom line, but is it good for people?

[blog] Figma’s woes compound with Claude Design. There is something fascinating about how frontier labs can reset product expectations overnight. The cost of entering new segments keeps dropping, which makes the world uncertain for SaaS companies and startups alike. This feels like a concrete example of the agentic shift playing out in real time.

[blog] DeepSeek V4 – almost on the frontier, a fraction of the price. Open-weight models just continue to improve. Simon Willison’s breakdown highlights the focus on efficiency here, not just raw capability. It may soon be possible to run frontier-class models on high-end home hardware, and that changes everything about who gets access.

[article] This Scammer Used an AI-Generated MAGA Girl to Grift ‘Super Dumb’ Men. We are living in a world where we have to assume that the content we are viewing is AI-generated. I think we should focus our efforts on tools that allow people to certify their content is real rather than trying to watermark AI content. The conversation around AI and creative authenticity is only going to get louder.

[article] I’ve been using “Ask Maps,” and it has forever changed Google Maps for me. I used the new Ask Maps feature extensively on my last trip and it felt like magic. Natural language queries against a map database is exactly the kind of AI application that just works, no prompt engineering required.

[article] You Should Have Exactly 3 Pairs of Headphones. Here’s Why. I’ve come to basically the same conclusion. Beats for workouts, AirPods Pro for every day, and AirPods Max for travel. The right tool for the right job applies to audio gear too.

An overhead view of a wooden desk with a notebook, coffee mug, and phone showing a reading list.

Reading List #1

Allen HutchisonLeave a comment

Two things collided this week. I have been trying to push myself toward a daily posting streak, the kind of constraint that forces you to write before you feel ready. And I have been reading Richard Seroter’s daily reading lists every morning for months, quietly admiring the discipline of the format. Today those two things became one experiment.

So here is the first one. The shape is borrowed shamelessly from Seroter: a short, opinionated tour through whatever caught my attention in the last day or two of reading, mostly sourced from my Readwise pile. Some days the picks will feel coherent. Other days, like today, they will be all over the map. That is part of the point.

[blog] I run multiple $10K MRR companies on a $20/month tech stack. Steve Hanov makes a startlingly good case for SQLite-first, Go over Python, and a $5 VPS instead of AWS. This is such good advice that it is making me seriously rethink how I deploy some of my hobby projects.

[article] Why Weekends Are Under Threat. The framing of the weekend as a network-effect technology is worth the read on its own. I think we have all been feeling this drift. Phones started the trend in some ways, and agents are going to make it worse.

[article] 5G From the Sky, New Internet Infrastructure Takes Flight. Sceye’s stratospheric balloons aim to live in the gap between Starlink and terrestrial cell towers. I recently wrote about my experience with Starlink Mini on a road trip, and I am excited to see real competition emerge in this layer of the stack.

[article] ‘It Feels as if I’ve Made a New Best Friend’, My Experiment With AI Journalling. I have played around with AI journalling inside Obsidian, but I have not tried Mindsera or Rosebud. I like that we are seeing new ways of interacting with AI and text, not just chat windows.

[article] Chrome Now Lets You Turn AI Prompts Into Repeatable ‘Skills’. I think Skills in Chrome is going to be really useful. I have been developing a growing library of Skills for other agents, and I would love to have them available in the browser too.

[blog] Want to Write a Compiler? Just Read These Two Papers (2008). I managed a compiler team once, though I was never a compiler engineer myself. Posts like this make me think it might be time to revisit that space.

[article] California Ghost-Gun Bill Wants 3D Printers To Play Cop, EFF Says. I do not think this kind of legislation can succeed if we use the same model we used with copy machines and currency. 3D printing is a different beast, and it needs different solutions.