Here is a small, boring bug that taught me something.
A version number lived in eleven places across the repo. A Dockerfile, an installer, recovery scripts, docs, a test rig, a manifest — eleven copies of one fact, all agreeing, and every one of them a place where the fact could quietly stop agreeing. Nothing dramatic has to happen for that to cost something. One copy goes stale, something downstream installs a version nobody meant to ship, something looks slightly wrong, and an agent goes looking for why.
Watch what that costs. The agent greps for the version. It gets eleven hits. It has to read enough of each file to decide which one is authoritative, which means loading eleven chunks of unrelated context into a finite window. It picks one. It’s wrong, because the authoritative copy was the one place it didn’t think to look. It fixes the wrong file, the build fails the same way, and now it’s on round two of a fix that should never have had a round one.
A human hitting this loses ten minutes and some patience. The agent loses something else: context it can’t get back, turns it can’t compress, and tokens that are gone. Same bug. Completely different bill.
That difference is the whole idea. On 2026-08-10 the owner of WorldOS gave it a name — AX, Agent Experience — as the design philosophy for the project: agents are the primary users of infrastructure now, and the resources they’re short on are context, tokens, and turns, not screen real estate.
UX optimizes for attention. AX optimizes for cognition budgets.
UX has a hundred years of accumulated craft behind one scarce resource: human attention. Everything follows from it. Progressive disclosure exists because attention is narrow. Visual hierarchy exists because attention needs to be pointed. Whitespace, affordances, tooltips, onboarding flows — all of it is budget management for a creature with about seven slots of working memory and a strong preference for not reading.
An agent has none of those constraints and a completely different set. It will happily read ten thousand lines. It does not get bored. It does not need a tooltip. What it has instead is a context window that fills up and then starts losing the beginning, a token bill that someone pays, and a turn count where every extra round-trip is latency the human is sitting through.
So the design responses diverge. Ambiguity, for a human, is a mild annoyance they resolve by clicking around. Ambiguity for an agent is a fork in the road where the wrong branch costs a fix-round. Two commands that do almost the same thing is a UI wart for a person and a coin flip for an agent. And a good error message means something much more specific when the reader is a machine that has to decide what to do next without asking.
Okay, but doesn’t “write good docs, be consistent, have clear errors” just describe good engineering? Mostly, yes. That’s the point I find most interesting about AX: it isn’t asking for new virtues. It’s re-ranking the ones we already had, and the new ranking is strict enough to make real decisions. Consistency stops being a nice-to-have and becomes the thing you break a release over, because inconsistency now has a measurable price tag.
The principles
Six of them that I keep tripping over, and each one is a rule you can violate on a Tuesday afternoon without noticing.
Determinism. The same command produces the same result. An agent that can’t predict what a command does has to observe what it did, which means a turn spent looking instead of a turn spent building. Nondeterminism is a tax collected in verification turns.
One source of truth. The version-pin story. One canonical location per fact, and — this is the part people skip — an enforcement mechanism, which I’ll come back to because it’s the best story here.
Idempotency. Running it twice is safe. This matters more for agents than for humans for an unglamorous reason: agents get interrupted. Context runs out, a session ends, a retry fires. If step four is only safe once, every interruption becomes an investigation of whether step four already happened. Idempotency converts “figure out where I was” into “just run it again,” and that trade is enormously in your favor.
Loud errors with directions home. An error should state its own remediation.
Not “invalid configuration” — that’s a puzzle. config missing key 'x'; add it
to ~/.foo/config.yaml is an instruction, and an agent can act on an instruction
without a round-trip. The difference between those two strings is one turn per
occurrence, forever, across every agent that ever hits it.
Intuitive without docs. The agent should guess right. If the natural guess
at your flag name is wrong, the guess costs a turn and a --help read. This one
is a genuinely different design target from human intuition, because agents guess
from a strong prior over how tools in general behave. Convention isn’t just
politeness anymore. It’s the thing that makes the first guess land.
Already-installed beats installable. A dependency that’s present is free. A dependency the agent must install is a multi-turn sub-quest with its own failure modes, its own error messages, and its own opportunity to burn half a context window on a package manager. (The economics here are the same as any other supply chain: the cheapest part is the one you didn’t have to source.) This is why “we bundle it” often beats “we support it.”
One source of truth is a test, not a convention
Back to the eleven version pins.
The obvious fix is to pick a canonical location and update the others to read from it. Fine. Done in an afternoon. And completely worthless in six weeks, because the next person to add a Dockerfile hardcodes the version again, and now you have twelve places and a convention nobody enforces.
What actually fixed it was a drift-guard test. The suite walks the repo and fails on a hardcoded copy of the version at all — the literal is banned outside a short list of places that are required to match the canonical pin exactly. Now the invariant isn’t a note in a contributing guide. It’s red CI.
And here’s the part I love, because it’s the exact failure this whole philosophy
predicts. The guard had a hole. It globbed for files it expected to contain
version pins — and it skipped extensionless Dockerfiles. So there was a file
in the repo hardcoding the version, invisible to the very test that existed to
make that impossible. A cross-model review pass caught it, which is its own
small lesson: the reviewer that finds your blind spot is usually the one that
doesn’t share your priors.
Two lessons stack here. The first: an AX principle without an enforcement mechanism is a wish. The second, harder one: the enforcement mechanism is code, and code has bugs, so the guard needs a guard — or at minimum a review pass by something that thinks differently than the thing that wrote it.
I’d put it this way. Every AX principle in the previous section should be read as a question: what test makes this true? If the answer is “we all agreed to be careful,” you don’t have the principle. You have a preference.
The collision: when AX and UX want different things
Here’s a case where the two genuinely pulled against each other, and I think the resolution is the most useful thing in this post.
WorldOS agents send voice notes. Nice feature — you get a spoken summary instead of a wall of text. The straightforward implementation is to have the working agent compose the summary: it just did the work, it has all the context, it writes a tidy spoken version at the end of its turn.
The owner overruled that design in favor of a background micro-agent that produces the summary separately.
Why? Because asking the working agent to compose UI niceties taxes exactly the resource AX exists to protect. That agent’s context is full of the actual job. Every token it spends on phrasing, tone, and audio-friendly sentence structure is a token not spent on the work, and the polish task pollutes a context window that was carefully loaded for something else. As the owner put it: we can’t sacrifice AX for UX when we don’t need to. The background is where that polish belongs.
Note what didn’t happen: the feature didn’t get cut. The user still gets the voice note. AX-vs-UX read as a tradeoff only because the first design put both jobs in one agent’s head. Move the boundary, and both win.
That’s the general shape of the move, and it’s worth holding onto: when AX and UX appear to conflict, check whether you’re really looking at a resource-allocation bug. Usually the polish belongs somewhere — just not inside the process whose budget you’re protecting.
Tool descriptions are instructions your agent ingests on trust
One more principle that only makes sense once you take the agent-as-user frame seriously.
When an agent connects to a tool, it reads that tool’s description and treats it as authoritative guidance about what to do. Which is to say: the description field is an instruction channel, ingested on trust, from a source the agent didn’t write.
Look at that from a security angle and it gets uncomfortable fast. Text in a tool description can carry instructions aimed at the agent rather than documentation aimed at the agent’s task. The traditional threat model doesn’t cover this well, because it’s mostly concerned with protecting the system from the agent — sandboxing, permissions, capability limits. This is the other direction. It’s the agent’s own attack surface, and the payload arrives through a field everybody treats as a docstring.
Hence a semantic validator: something that scans tool descriptions for injected instructions before the agent ever ingests them. That one is designed and not yet shipped — a scan specified as a second layer behind the structural checks a tool config already gets, sitting in the path an agent’s tools travel, and not yet standing in it. designed, not shipped — status confirmed against the tree at publication.
The AX framing is what makes this a design requirement rather than a curiosity. If agents are your primary users, then the integrity of what they read is a first-class property of your platform — the same way you’d never ship a UI that rendered arbitrary attacker-controlled text as a system dialog.
The teeth: an AX scorecard
Everything above is a philosophy, and philosophies are cheap. Every infrastructure project on earth claims its new release is better. Approximately none of them can show you.
So: measure it. The AX scorecard is a fixed set of metrics gathered by running a stable task suite against each release:
- tokens consumed
- turns taken
- clarification turns — how often the agent had to stop and ask
- human interventions — how often a person had to step in
- fix rounds — how often the first attempt was wrong
- elapsed time
The suite has to be stable across releases, because otherwise you’re measuring task difficulty drift instead of platform quality. Same tasks, new release, compare.
And this is the sentence the whole post has been walking toward: WorldOS becomes the rare project that can prove its releases are getting better for agents, not just claim it.
Two design decisions in the scorecard matter more than the metric list, and both are about resisting the obvious version.
Medians and tails, not one average. A single mean hides exactly the behavior you care about. Agent workflows fail in the tail — the run that spiraled into nine fix-rounds, the one that exhausted its context and started over. Average those away and a release that made the median 5% better while doubling the disaster rate looks like progress. Report the median and the tail, and the regression has nowhere to hide.
Observational until thresholds are earned. No pass/fail gates at the start. You collect several baselines first and only then set thresholds. This is the Goodhart-shaped part of the design, and the reasoning is pure incentives: a metric with a gate attached is a metric someone will optimize directly. Gate on token count on day one and you will get shorter agent turns — not better ones. You’ll get work deferred out of the measured window, tasks split to game the per-task denominator, and a beautiful graph. Thresholds are a tool for a metric you already understand. Set them before you understand the distribution and you’ve built a target instead of an instrument.
(The failure mode where a team gates on a proxy metric and then congratulates itself on the proxy is not new, and it is not rare, and it does not feel like what it is while it’s happening.)
What one row actually looks like
Abstract metric lists are easy to nod along to, so here’s the shape of a single measurement.
You pick a task the platform is supposed to make easy. The agent runs it against the release under test, start to finish, with no human help unless it asks for some — and if it asks, that’s a clarification turn, recorded. When it’s done you have six numbers for that task on that release. Run the whole suite, and you have a column. Run the suite again next release, and you have a comparison.
The subtle work is in the boundaries. Where does the task start — at the first prompt, or at the moment the environment is provisioned? Does a failed command that the agent immediately corrects count as a fix round, or only a failure that reaches the human? These definitions have to be frozen before the baselines, because a redefinition mid-program silently rewrites your history. Ours are being written now: the metric list and the stable-suite requirement are settled, the counting rules are the next piece of work, and the honest thing to say is that the baselines wait on them rather than the other way round. counting rules open at publication — being defined ahead of the first baseline.
The measurement includes the measurer
Then there’s the detail that made me trust this design more than I expected to.
In WorldOS, work often reaches an agent through a dispatching layer — a PM agent that takes an incoming request, figures out what it is, and hands it to whoever should do it. Dispatch costs turns. Reading the request, deciding, writing the brief, and handing off are all real turns, spent before the agent doing the actual job has taken its first one.
Those turns get recorded. The dispatching layer keeps its own count — turns, clarifications, interventions, per cycle — and that record feeds the same program.
They could very easily not have. It’s the natural exclusion: dispatch is overhead, orchestration, not “the work” — measure the work. And that exclusion would have been a slow disaster, because dispatch overhead is exactly the kind of cost that grows quietly. Add a routing step, add a confirmation, add a check. Each one is defensible in isolation, and none of them shows up anywhere if you’ve defined the measurement to start after dispatch completes.
Who pays for that overhead? The human, in latency, and the token bill. So the measurement should see it. (The general rule: any cost you exclude from your metric is a cost you have volunteered to stop noticing.)
There’s also something quietly recursive here that I like. The system measuring agent experience is itself made of agents whose experience is being measured. An improvement to how the dispatcher briefs its workers shows up in the same scorecard as an improvement to a tool’s error message. That’s not a philosophical flourish — it’s what stops any layer from being pure overhead by definition. If a component costs turns, its turns are on the record.
What AX is not
Three misreadings worth heading off.
It’s not a token-count fetish. Tokens are one of six metrics precisely because a single number invites gaming. If minimizing tokens were the goal, the optimal platform would be one that makes agents give up early.
It’s not anti-human-UX. The voice-note story is the proof: the human still gets the nice thing, the working agent just isn’t the one making it. AX doesn’t compete with UX for the same budget unless you’ve drawn the boundaries wrong.
It’s not a manifesto. A manifesto is a list of adjectives you can’t be wrong about. The scorecard is what makes AX falsifiable — you can run it and find out your release made things worse. That possibility is the entire value.
Why this is a control story, not an autonomy story
It would be easy to read all of this as being about making agents more independent. It isn’t, and the distinction matters to how WorldOS is built.
The point of AX is not that agents need less supervision. It’s that agent-facing infrastructure quality becomes something you can see. Measured, compared release over release, auditable by someone who wasn’t in the room. The scorecard is an instrument you point at your own system, and the number it returns is a number you can be wrong about — which is the only kind worth reporting.
Systems you can audit. The reason to measure agent experience is the same reason to measure anything: so that “better” stops being a claim and starts being a result you can check.
The version pin taught this in miniature. The convention was a claim. The drift-guard test was a result. And the hole in the guard was a reminder that the instrument needs auditing too — which is roughly where every honest measurement program starts.