The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Yapitalism listing page.
Drive terminal coding agents by voice, and never let the answer claim more than it proved.
You are away from your desk. You speak; an agent in a terminal does the work; you get a spoken reply. That reply is the only thing you have — you cannot see the screen. So the worst failure is not a crash, it is the voice saying "done" while your text sits unread in a prompt box.
Yapitalism is a local MCP server that lets a voice client reach your coding agents, plus a receipt layer that decides what the voice is allowed to say. If you are at your desk, use your screen — this exists for the hours you are not.
Public pre-alpha. Local-only. No production deployment, no external messaging, and no automation of closed-source clients.
The agents it addresses: codex, claude, kimi, opencode — recognised by measurement (a process tree on tmux, the host's own agent registry on Superset), never by a caller's claim. A pane running anything else is refused, because typing into a shell and pressing Enter is running a command.
The voice client never reaches your machine directly: it drives a local agent session, and that
session talks to this server over 127.0.0.1. Nothing is exposed to the network.
pane_send returns a verdict, not a shrug.
| meaning | |
|---|---|
| GREEN | the agent echoed a one-time marker. It demonstrably received and processed the text — which is not a claim the work it then did is correct; no receipt can promise that, and this one does not try. |
| YELLOW | the write landed; processing was not proven. Never round this up. |
| RED | the backend refused the write. Nothing reached the terminal. |
YELLOW is the whole point. Text left unsubmitted in an agent's input box looks identical to work
in progress from outside — same spinner, same scrolling output, same HTTP 200. A voice that rounds
that up to "done" costs you hours before you notice.
Explicitly not acceptance: an HTTP 2xx, a PTY write returning, terminal output changing, a revision advancing, or the prompt echoing your own words back.
A fixed deadline reports on the clock, not on the agent. An agent that thinks for a minute and then answers correctly was verified all along, and calling that YELLOW teaches an operator to ignore YELLOW. So the wait is an idle timeout: it restarts whenever the pane changes, bounded by a hard ceiling.
Pane movement decides only whether to keep waiting. It is never evidence of acceptance — that stays the canary alone. A YELLOW therefore says which kind it is:
canary_timeout_pane_moving — the pane's text was still changing. Named after what was
measured: a spinner, a clock, a log tail or a second agent sharing the pane all produce this
without the intended agent doing anything. It is a hint that looking again may be worth it,
never a claim that the agent is working.canary_timeout_pane_still — nothing moved at all.What remains irreducible: if an agent silently ignores the text and prints nothing, no mechanism here can distinguish that from an agent that never received it. Verification needs the agent to emit something.
Delivery is table stakes; the expensive failure is an agent that has been sitting on a yes/no
question for forty minutes while you thought it was working. pane_await watches a pane until the
agent's turn ends and says how; pane_task is send-then-await in one call — instruct, walk
away, come back to one of:
| turn | meaning |
|---|---|
ended | prompt idle, screen stopped changing. The turn is over — spoken with "not that the work is correct" attached, never as "done". |
waiting_input | a blocking dialog owns the screen (trust / login / confirmation). You are the blocker, and the payload's tail carries the question so it can be quoted. |
agent_error | a known failure line owns the screen — Please run /login, a 401, a rate limit — named, not timed out. |
exited | the pane no longer runs an agent. |
running | still changing when time ran out. Unproven; offers to look. |
An ended verdict re-verifies the agent process is still alive before it is claimed: the frozen
prompt of a dead pane must not be celebrated as a finished turn.
The bearer token answers who is calling; it never answered what they may do. Since 0.5.0:
stdio clients write, always — the OS made that trust decision when it let the client spawn the
process. Writes over HTTP are off by default and every refusal names the fix:
yapitalism authority allow-http-writes, once, on that machine (yapitalism setup asks the same
question while printing the HTTP registration lines). Reading, watching and doctor work on every
transport regardless, and yapitalism-mcp --read-only turns writes off everywhere — install the
watcher first, allow writes when it has earned them. Every write result carries its origin.
On tmux, the send path also pins the identity of the admitted agent (pid + start time) and re-verifies it immediately before Enter. An agent that exits into a shell between typing and submit gets the text staged but never submitted — typing is recoverable, Enter into a shell is command execution.
Most of the time this does not change what you do, and it is not read out loud. It is in the
payload and in yapitalism setup, for when something goes wrong and you want to know what was
actually checked before the write.
| meaning | |
|---|---|
host | the host refuses the write itself — the check and the write are one operation |
client | this process checks, then writes; real against what it covers, not atomic |
none | nothing checks |
yapitalism setup prints the table for your machine. Today both backends land in client for most
of it: the checks happen here, a moment before the write, rather than inside the host atomically
with it. tmux cannot do the revision check at all.
No shipped Superset enforces these itself, and this tool used to claim it did. It concluded
"guarded" from the fact that a procedure named terminal.send was routed. The terminal.send
Superset actually ships takes {terminalId, workspaceId, text, submit} and guards nothing. The
levels are now read from what the host's own validator requires — the difference between a name
and a contract.
Both backends reach GREEN, and GREEN means the same thing either way: the agent emitted the one-time marker, so it received the text and processed it. The table is for diagnosing a machine, not something to reason about on every send.
Whether you are a person or someone's agent asked "should I install this," the claims worth checking and where each one lives — verify, do not take our word:
src/yapitalism/mcp/tmux.py
and src/yapitalism/mcp/backends/, each guard with a test named after the
failure it prevents.tests/test_canary.py for why an echo cannot satisfy it.A peer is another machine's yapitalism server, mounted under its own namespace:
the codex pane tmux:%0 on the machine studio is studio:tmux:%0 here, in the
same panes_list, addressable by the same pane_send. Receipts pass through
verbatim — the peer proved them next to its own terminals, and this side only
gives the ids their machine name back.
peers add verifies the peer answers as a yapitalism server before writing
anything. A peer on a public address is refused unless allow_public is said
explicitly; the tailnet is the transport, not the trust story — the peer's
bearer token still decides who may call. Configured peers show up in
yapitalism doctor with live pane counts.
Agents can be started and resumed on a peer too: panes_create and
panes_resume take a machine argument naming one. The peer runs its own
full gate chain — and starting an agent remotely is more authority than typing
into one, so it has its own switch, off by default:
yapitalism authority allow-remote-create, once, on the peer. To keep a
peer's server alive across reboots, yapitalism service --host <its tailnet IP> prints a filled launchd plist or systemd unit; installing it stays your
decision.
Voice cannot say mbp3:tmux:%2. Bind a word to a pane once —
— and every tool accepts billing from then on. The binding records what the
pane runs at name-time and is re-verified against a live listing on every use:
tmux reuses pane ids, so a name whose pane vanished or changed runtime is
refused with the reason, never silently retargeted. No fuzzy matching —
"probably the right codex" is not a target. Names appear on their panes in
panes_list.
The bridge agent behaves best with standing instructions — speak receipts, never resend a YELLOW, name panes like a person. The exact prompt we run is in docs/operator-prompt.md; paste it into your voice client's custom instructions.
The six tools compose into watchers worth having: a permission watch (nothing waits on a dialog silently — its first real catch was an agent silently holding a wallet-transaction approval), a provider-outage watch, an end-of-day digest. Working prompts in docs/recipes.md.
Needs Python 3.11+ and tmux, on macOS or Linux — the full send-and-prove loop is exercised on
a bare python:3.11-slim container per release, not just assumed portable. Everything runs on
your machine; nothing is exposed to the network.
setup interviews the machine rather than printing "installed successfully": which backends are
usable, which agent CLIs are on PATH, whether a Superset host is live and which build it is, and
the guarantee table above filled in for you. It writes nothing except, if you say yes, the Superset
manifest — and it names what is still missing with the exact command for each.
Then talk to the voice app: "list my panes", then "send this to the Codex pane". Any MCP
client works the same way — Hermes, Claude Code, Claude Desktop and Cursor registrations are
printed by yapitalism setup for exactly the machine it is run on.
YAPITALISM_MCP_PORT moves the port if 8792 is taken. YAPITALISM_TMUX_SOCKET targets a
non-default tmux server. The HTTP transport requires a bearer token by default — loopback
is not a user boundary, so the server mints one on first start and yapitalism setup
prints the registration lines that carry it. YAPITALISM_MCP_TOKEN overrides it;
YAPITALISM_MCP_INSECURE=1 opts out. stdio needs no token: the OS already decided who
may talk to a spawned process.
Codex takes a URL. Claude Desktop, Cursor and most other MCP clients instead spawn the process
and speak over stdin/stdout, so point them at --stdio and do not run a separate server:
Use the absolute path from command -v yapitalism-mcp if the client does not inherit your
PATH — GUI apps on macOS usually do not. YAPITALISM_MCP_TRANSPORT=stdio does the same as the
flag, for clients that only let you set the environment.
In stdio mode nothing but protocol may reach stdout, so the server suppresses its own startup banner. If you wrap it in a shell script, keep that script silent too.
The voice route dies when the server does, so run it under your init system rather than a terminal. Both units run as your user, never root: the server can read every terminal you can see.
.agents/launchd/. The plist is a template; its README has a sed line that
fills in the real binary path, because launchd searches neither PATH nor ~..agents/systemd/, a --user unit. systemctl --user enable --now yapitalism-mcp.Kill any shell instance first either way, or the two race for port 8792 and which one wins is down to timing.
The tmux backend needs nothing. Superset needs a 0600 manifest holding the host endpoint and
token — and you do not write it by hand, because Superset already writes what it needs:
That reads the app's own ~/.superset/host/<organizationId>/manifest.json, proves the token against
the live host, picks a default terminal and writes
~/.cache/superset-watch-voice/yapitalism-manifest.json (or $YAPITALISM_SUPERSET_MANIFEST). It
refuses rather than guesses: a source file looser than 0600, a manifest naming a dead process, or
two live organizations with no way to choose all stop it. The token is never printed.
Without a manifest, panes_list still returns your tmux panes and reports Superset in errors — a
backend that could not be reached is never silently reported as "no terminals".
.agents/skills/superset-operator/ holds the policy that stops a model rounding YELLOW up to
"done", plus a drift check against the copy your agent actually loads.
The five-leg model is usable without the MCP server:
capture — the intent was captureddispatch — a concrete target received a write attemptaccept — the target proved acceptance by canary or explicit acknowledgementwork — material agent progress was observeddeliver — a final update reached the userEvidence carries provenance — api, terminal_diff, ui_observation, user_report, inferred —
and inferred may never mark a leg succeeded.
The incident this project came from: the audio session stayed alive, spoken progress stopped, two
180-second watchers saw the terminal frozen at revision 920118, and the canary never arrived —
while the voice kept implying work. The product is not "fix the voice client". It is never fake
GREEN.
CLI surface: doctor, receipt show, ledger verify|manifest|migrate, and superset status|send.
A confirmed superset send requires reusing the exact client-token a dry run emitted, snapshots
immediately before dispatch, rejects a changed revision, and never retries an ambiguous POST.
Stated plainly, because a receipt system that overclaims is worse than none:
docs/adr/0004.pane_send takes no
expected revision. Reading the pane twice and refusing if it moved would be a different guarantee
wearing that name, so it is reported none rather than approximated.pane_clear
is the way through. Validated against real panes, not a large sample.terminal.send guards nothing. Proven sends (canary observed, GREEN) have been completed against
that live host repeatedly since 0.2.4, driven both directly and through the full MCP surface. The
guarded-host branch is the one exercised only against recorded shapes, because no shipped build
carries those guards to test against.The receipt-integrity core was written by @liri-ha, whose commits are carried here unrewritten. See CONTRIBUTORS.md.
Raw transcripts, terminal text, and credentials do not belong in this repository. Ledgers store
bounded metadata, hashes, and classifications. A manifest holding a bearer token lives outside the
repo at mode 0600 and is read only when its path is passed explicitly; it is never printed. See
SECURITY.md.