termio CLAUDE.md

@AGENTS.md

termio

What termio is

A terminal-first agentic development environment, including its own remote server.

Coding agents live in terminals. termio is the place those agents run, on machines the user already owns — a laptop, a VPS, a devbox — supervised from a native Mac app and an iPhone. termiod is the durable session host that makes "on any box" one code path instead of four.

The category is crowded (Zed remote, VS Code Remote, Codespaces, Warp). That is a known and accepted cost of this position, not an oversight. Do not re-argue the positioning. Build it.

What makes it different (aim here, not at editors)

• The session lives on the box, not in the connection. Detach ≠ kill. An agent keeps working while the laptop is shut; reattach restores the exact screen. Zed and VS Code tie remote work to a live connection; termio does not.
• The user's machines, not our cloud. termio never provisions compute and never runs a hosted control plane. The code never leaves hardware the user controls — the only trust story that survives giving an agent shell access to a private repo.
• Agent-native at the protocol level. Workstream status (working / idle / needs-you / done) is a first-class protocol object, not a heuristic scraped off the screen.
• Terminal-first is a commitment, not a stage. The terminal is the interface. Chat UIs have been built and fully reverted twice. Don't rebuild them.

Architectural non-negotiables

These come from docs/design/20260730-termiod-session-protocol.md §A and §H. Violating one is a design regression, not a tradeoff:

1. Anti-100× invariant — byte delivery never blocks on host-side VT parse. The authoritative VT is a sidecar for snapshots; any per-frame grid encoder between the PTY and the pipe rebuilds the tmux tax and is rejected.
2. State sync only at boundaries — snapshots on attach / resize / resync, never per frame. grid_diff is an opt-in bad-network degrade, never the default.
3. Never embed SSH or crypto. System OpenSSH, tailnets, and OS keychains are the security team we didn't hire. The user's ~/.ssh/config is authoritative — read it, never override it.
4. One protocol, versioned and transport-agnostic. Unix socket, SSH stdio, and later QUIC carry the same framed messages. No second protocol for the phone.
5. No nested window manager in the host. One PTY per session; panes and layout are client concerns.
6. Single writer, many readers. Observers never claim the write token.