Why a standard

The world outside the model

A model on its own can plan and write, but every real action happens somewhere else. Files get written, tickets get filed, deployments ship and transactions get approved in systems the model can only reach through a tool.

The tools an agent reaches for today were built by people, for people, at a time when nobody expected an autonomous system to read their output. They print tables, color, prompts, progress bars and vague errors, and their exit codes carry decades of Unix convention without a contract that anything machine‑facing could rely on. An agent calling one of these tools is an actor performing blindfolded on a stage it can’t see.

What scraping terminals costs

Agent‑tool integration breaks in five specific ways, and production agent systems hit every one of them. None of it is hypothetical: the survey of CLI machine output measures the interfaces underneath these failures, and in CLI‑Universe’s error study of Terminal‑Bench 2.0 (Hua et al., 2026), verification failures, where the agent stops without checking that the goal state holds, account for 47–60% of failed runs across four frontier models.

1. Read failures. An agent scrapes a table to read a tool’s output. When a new release renames a column header, the agent silently mis‑parses every row and acts on ghost data.
2. Write failures. An agent runs a write command and the process exits 0, but the change never happened: maybe the tool buffered it and the network dropped, maybe the upstream rolled it back. Without a terminal summary, exit 0 only means the process finished. It says nothing about whether the work succeeded.
3. Verify failures. After a mutation, the agent can’t tell whether it produced the intended outcome, a partial one or a duplicate. So it either re‑issues the call and doubles the effect, or assumes success and hallucinates the audit trail.
4. Bound failures. An agent runs a list command and the tool dumps fifty thousand rows. Now its context is full of irrelevant data, and the run has timed out, blown its budget or crashed the orchestrator.
5. Discovery failures. An agent doesn’t know what a tool can do until it runs it, so it guesses flags from help text and sometimes invents options that don’t exist. It can’t weigh the cost or risk of a call without making the call.

Better prompting can’t fully fix any of these, because they’re interface bugs that live in the contract between the agent and the tool.

Interfaces, not improvements

Every tool team’s instinct is to make its own tool better, faster or more reliable. That work is necessary, and it doesn’t fix the problem, because a thousand excellent tools with a thousand output conventions are still fragmented.

A standard isn’t a quality bar; it’s what lets a thousand improvements compose. Compare every railway laying its own gauge with a continent that can move a freight car from any port to any depot without unloading it. Improving one tool helps locally, while a standard improves the whole system.

Machine Mode doesn’t tell any tool how to be better. It asks every tool to expose the same shape of interface to the same kind of caller.

Moments when standards happened

Most layers of software have had a moment when one interface convention became the standard the whole layer organized around.

POSIX (1988)

Operating systems agreed on a common process model and file abstraction. Shell scripts and large codebases alike became portable across machines that had previously spoken incompatible dialects.

HTTP (1991)

Distributed systems agreed on a request envelope and a status taxonomy, and the web grew out of that agreement more than out of any single piece of technology.

OpenAPI (2011, first released as Swagger)

Web APIs got a shared schema language for endpoints and their types. Generating SDKs and contract tests from it stopped being craft work.

MCP (2024)

Agent runtimes agreed on a protocol for finding and calling tools, so agent frameworks could share discovery and invocation instead of each vendor writing its own tool‑calling glue. Machine Mode sits beside it: MCP finds and calls tools, and Machine Mode defines what a CLI returns once it’s called.

Each of these looked like overkill for the size of the problem at the time, and each became invisible once it settled, the precondition for everything built after it. Agent computing is at the same moment now. The layer is tools, and Machine Mode is our proposal for its standard.

Why not just OpenAPI?

OpenAPI is a great answer for HTTP services. It’s mature and well tooled, and most modern remote APIs already publish a document. If your tool is a remote service, OpenAPI gives you most of what an agent‑operable HTTP interface needs.

This site starts with CLIs because OpenAPI was never designed for the command line, and the command line is the surface an agent with a shell drives directly. Running kubectl logs my‑pod, git rebase, terraform apply, find . -newer x or docker exec isn’t calling an HTTP API that hasn’t been built yet. These are local process operations against local state, and their primitives differ in kind:

1. Three I/O channels, not one. Stdin carries request data, stdout carries structured results and stderr carries diagnostics. HTTP has one request body and one response body.
2. Exit codes and signals. A CLI reports completion at two levels, the process exit code and a terminal summary event, where HTTP folds both into a status code.
3. Pipes and process composition. Shell pipelines are a real, durable way to compose programs. OpenAPI has no equivalent; gRPC streaming comes close for services but doesn’t reach the local process boundary.
4. Local state. Most CLI work reads and writes the filesystem, environment variables, the working directory and the terminal session, and OpenAPI has no vocabulary for any of them.
5. No network. Plenty of useful tools have to run disconnected, in containers without egress, or against local sockets, while OpenAPI assumes a network endpoint exists.
6. Auth that already works. A CLI runs as the user, with the user’s keychain, environment, AWS credential chain, kubeconfig, ssh agent, gpg keyring, Vault token, GitHub token and corporate SSO session already in place. Those ecosystems carry years of work on MFA, role assumption, certificate pinning, browser sign‑in and renewal, and a CLI inherits all of it for free. A protocol that carries auth on the wire has to take on federated identity itself, which is why MCP specifies OAuth for remote servers and keeps refining it. AOI doesn’t standardize auth at all; it standardizes the interface a tool exposes once auth is in place.
7. Tools that aren’t services at all. ffmpeg transcodes a video and pandoc converts a document; jq reshapes a JSON stream, gpg signs a file and rustc compiles a program. These are computations that take local inputs and produce local outputs, and the value is the work rather than any stored state. Wrapping them as HTTP services would mean running them as long‑lived processes, which changes what they are, or shipping files over a network at real cost. The CLI is the right surface for them, and AOI‑CLI covers it natively.

So the honest framing isn’t AOI versus OpenAPI. Machine Mode is the standard; OpenAPI is its de facto profile for the HTTP surface, and AOI‑CLI is its first formal profile for the process surface. The ten factors apply to both, and a well‑designed OpenAPI service already satisfies most of them. A future AOI‑HTTP profile would reference OpenAPI as the wire format and add the extra requirements (idempotency, terminal completion, dry‑run, structured retryability) as a profile document or vendor extensions.

What this site builds, then, is a profile for a surface OpenAPI doesn’t cover, inside a framework that places it next to OpenAPI rather than against it.

What changes for the agent

The agent is the one audience that can’t compensate for a bad interface by reading between the lines. A person at a terminal sees a typo in the output and infers what was meant, and a downstream script regexes its way past a renamed column. An agent does neither. It hallucinates a column that isn’t there, retries blindly and burns context on decoration it can’t tell apart from data, then does the wrong thing with confidence.

A typed, discoverable and bounded interface with safe defaults lets the agent stop guessing. Six kinds of agent failure move from problems the model has to solve to guarantees the interface already provides:

1. Comprehension stops being a parsing problem. Every event carries a type discriminator, so the agent dispatches on shape instead of running regex against prose, and the envelope is identical across conforming tools.
2. Planning stops being trial and error. Schema and capability discovery let the agent reason about what a tool can do before calling it, which puts cost, risk and side effects in view at plan time.
3. Action stops being a hope. Dry‑run plans, confirmation counts and idempotency keys become behavior the spec’s recommended profile defines, not one team’s best practice. Retrying a write is safe, and bulk deletion is no longer one wrong flag away.
4. Verification stops being forensic work. A terminal aoi:summary.ok is unambiguous and mutations report stable IDs, so the agent reads what happened instead of reconstructing it.
5. Composition stops needing glue scripts. One tool’s output is another tool’s input by construction. Agents chain operations the way people chain shell pipelines, with failure semantics that hold across the chain.
6. Context stops going to decoration. Bounded reads and compact line‑delimited JSON mean the agent spends its tokens on data, and it can filter the stream before reading it. Long lists stop blowing the window, and streaming puts the first useful result in front of the agent sooner.

The full list, thirty‑two specific things that change for the agent on the other end of a conforming tool, is on For agents. It’s the main reason this standard exists, and the rest of the site serves it.

Why it has to be small

A standard succeeds when it’s small enough to remember and strict enough to enforce, so Machine Mode stays narrow on purpose. It leaves language, framework, packaging and human‑facing UX to the tool’s author. The required core, Part I of the spec, covers only the contract at the process boundary: an event envelope with a type discriminator, a declared schema version, defined completion, a portable error taxonomy and predictable composition.

Those core rules are interoperability invariants. One tool implementing them alone gains little, and a hundred tools implementing them differently gain nothing. Safety and bounds sit in a recommended profile (Part II) instead, because a dry‑run flag helps the first tool that ships one. Everything else is the implementer’s business, and that restraint is what lets a standard cross ecosystems instead of starting a fight inside one.

What this site is

This site is the public home of Machine Mode. The home page sets out the ten factors, and the AOI‑CLI specification is the first formal profile. Adopt has minimal implementations in five languages, and the conformance badge is for tools that already implement the spec.

Future profiles will cover other surfaces, such as HTTP services, message queues and embedded devices. The factors stay the same across them while the wire format changes.

If you build a tool an autonomous system might call, or an autonomous system that calls tools, this standard is for you. Getting it right takes more than one editor, so corrections, counter‑arguments and conformance reports are welcome at github.com/agentoperable.