stado — sandboxed, git-native coding agent for the terminal

commitments Four principles, on every architectural decision.

// 01

Read-only repo.

Agent state lives outside your working tree. Landing is always explicit.

// 02

Tamper-evident.

No unsigned commits, no un-logged tool calls, no "trust us."

// 03

OS enforces.

Capabilities declared in the manifest. The kernel — not a promise — keeps tools in their lane.

// 04

No lossy abstraction.

Thinking blocks, prompt caching, provider-native features round-trip verbatim.

▍ 01/ git-native sessions

Every turn is a commit. Fork from any of them.

Sessions live as a sidecar bare repo with per-session tree and trace refs that grow with every turn. The history is a branching graph you can walk, resume, search, and replay — not a flat chat log. Rewind to any earlier turn into a fresh session; the parent is never modified.

refs/sessions/7a3f9c2/tree · ~/code/myproject

* turns/6  edit CHANGELOG.md            a1f2…cc91
* turns/5  bash pnpm test useScroll     9b8e…2701
* turns/4  edit src/hooks/useScroll.ts  3c4d…f80a
│  ╲
│   ╲── fork → session a4e1b0  (--at turns/4)
│        * turns/4'  alt: useSyncExternalStore
│
* turns/3  grep "useScroll" — 7 sites   6e21…0042
* turns/2  read useScroll.ts            f9aa…b1c4
* turns/1  session start                0000…7a3f

signed · ed25519 / commit trace ref · every tool call tree ref · mutating turns parent never rewritten

cmdstado session fork <id> --at turns/4

cmdstado session tree <id> # interactive picker

cmdstado session land <id> fix/strict-mode-scroll (when you're ready)

▍ 02/ plugins, not internals

Almost nothing is built in. Swap any tool.

Stado core is the runtime, capability sandbox, and signed-distribution lifecycle. fs.read, shell.bash, web.fetch, rg.search — even auto-compact — ship as signed WASM plugins. Don't like one? Rewrite it in any language that targets wasm.

fs.readwasm · goswappable

shell.bashwasm · goswappable

web.fetchwasm · goswappable

rg.searchwasm · goswappable

auto-compactwasm · goswappable

Go Zig · 800 B Rust any wasip1 ed25519 · trust-pinned

cfg[tools].overrides = { webfetch = "webfetch-cached-0.1.0" }

cmdstado plugin init my-plugin · sign · trust · install

▍ 03/ capability sandbox

Declared in the manifest. Enforced by the kernel.

Tool execution is gated through real OS sandboxing — not a promise the agent makes about itself. Subprocess networking is mediated through a CONNECT-allowlist proxy in a private netns; plugins run inside wazero with capabilities declared in the signed manifest.

os	subprocess sandbox	status
linux	landlock · bubblewrap · seccomp BPF · pasta CONNECT proxystrongest path; whole-process --sandbox-fs available	▮ shipped
macos	sandbox-exec with generated profilessame capability vocabulary; no whole-process path	▮ shipped
windows	warning-only passthroughv2: job objects + restricted tokens — phase 3.6	◐ v2 planned
wasm	wazero with manifest-declared capabilitiesfs:read · fs:write · net:<host> · exec · env	▮ shipped

▍ 04/ mcp server

Bring stado's tools to your other agent.

stado mcp-server exposes your entire installed registry over stdio MCP. Mount it in Claude Code, Codex, or anything that speaks MCP — and inherit every plugin you've signed and trusted locally.

shell.bashpersistent PTY + VT100mcp

web.clientstateful · cookie jarmcp

rg · ast-grepcode searchmcp

lsp.finddefinitions · refsmcp

your-pluginwhatever you installmcp

cmdstado mcp-server

cfg[tools].overrides applies here too

A herd of agents that keep your working tree clean.

Streamed in the TUI. Signed on the way out.

commitments Four principles, on every architectural decision.

Read-only repo.

Tamper-evident.

OS enforces.

No lossy abstraction.

Four primitives. Bend any of them to your shape.

Every turn is a commit. Fork from any of them.

Almost nothing is built in. Swap any tool.

Declared in the manifest. Enforced by the kernel.

Bring stado's tools to your other agent.

Three paths. Pick the one that fits your threat model.

Install script

Homebrew

From source

Verify what you're running.

Point it at any model. Drive it from any shell.

Terminal UI

One-shot CLI

Editor (ACP)

MCP · both ways

Headless JSON-RPC

A release you can verify from an airgapped laptop.

For the Herd!