# Why Plexus Matters

CLIs are for humans. Agents aren't humans.

## The Problem with "Just Shell Out"

When an agent uses a CLI tool today, it's:

1. **Guessing** the command exists on the host
2. **Hallucinating** flags from training data that may be stale or wrong
3. **Parsing stdout** with regex or vibes, hoping the output format didn't change between versions
4. **Getting no structured feedback** — just an exit code and a text blob
5. **Unable to stream** — it blocks until the process exits, then reads everything at once

This works for stable, simple commands. `git status` hasn't changed in a decade. But agents live at the edges — long-running tasks, multi-step workflows, unfamiliar tools — and that's exactly where "shell out and parse" falls apart.

## What Plexus Changes

Plexus makes the machine-to-machine interface first-class:

- **Discovery**: The agent doesn't guess what's available. It asks the server, and gets a typed schema back. Every method, every parameter, every return type — described and navigable at runtime.
- **Structured I/O**: Parameters go in as typed JSON. Events come back as typed JSON. No parsing `grep` output. No hoping a flag still exists.
- **Streaming**: The agent sees progress in real-time. It can react to partial results, show the user what's happening, or cancel if things go wrong. Not "wait 30 seconds then read a wall of text."
- **Composition**: An agent can resolve a handle from Arbor, pass it to Cone, get back a conversation — across plugins, with stable references that survive restarts and version bumps. Try doing that by piping CLIs together.
- **Supervision**: The loopback system lets a parent agent approve what a child agent is doing. There is no CLI equivalent of hierarchical permission delegation.

## The Analogy

Humans went through this transition already. We used CLIs for decades. Then we got structured APIs (REST, gRPC, GraphQL), and suddenly everything composed better — services talked to services without screen-scraping each other's terminal output.

Plexus is that same transition, but for agents instead of humans. The protocol, the discovery mechanism, and the streaming model are all designed around the assumption that the primary consumer is an autonomous agent that needs to:

- Understand what's available (schema discovery)
- Use it correctly (typed parameters and returns)
- React in real-time (streaming events)
- Coordinate across capabilities (handles and cross-plugin references)
- Be supervised while doing so (loopback, permission chains)

## Comparison: Provisioned Environment vs. Capability Runtime

Systems like environment provisioners (install 30 CLI tools on a VPS, point agents at them) solve a real problem: getting agents running somewhere with tools available. But "installed on the PATH" is not "understood by the agent."

| Dimension | Installed CLIs | Plexus Activations |
|-----------|---------------|-------------------|
| Discovery | Agent guesses or is told | Agent queries schema at runtime |
| Parameters | Flags parsed from `--help` or hallucinated | Typed JSON with JSON Schema |
| Output | Unstructured text (stdout) | Typed streaming events |
| Errors | Exit code + stderr blob | Structured error events with recoverability flag |
| Progress | Silence until completion | Real-time streaming (Progress, Data, Done) |
| Composition | Pipes and temp files | Handles with stable UUIDs across plugins |
| Versioning | Hope the binary didn't change | Content-hashed schemas, semver-stable plugin IDs |
| Supervision | None | Parent-child permission delegation |

The provisioned environment is the machine. Plexus is what makes the machine's capabilities legible to agents.

## The Bet

Today, agents are mostly spicy autocomplete that occasionally runs `npm test`. Shelling out works fine for that.

The bet Plexus makes is that agents are about to do much more — long-running tasks, multi-step workflows, coordinating with each other, operating on real-world systems — and when they do, "shell out and parse stdout" stops being charming and starts being a bottleneck. Plexus builds the infrastructure for that next step: a runtime where every capability is self-describing, streaming, composable, and supervisable.
