Status: decisions applied. Date: 2026-11-06.
Goal (venom-os): An agent-friendly OS that runs mostly in the terminal as a TUI (browsers aside). The TUI and the multiplexer are where humans and AI agents are orchestrated.
Constraints: Zig 0.17, TUI first (no desktop GUI apps yet), and every component must be fully controllable by an agent (through a CLI, a socket, or MCP).
Non-goal: Venom does not build its own agent runtime or harness. We orchestrate existing agents (Claude Code, Codex, opencode, any ACP agent), the way t3code does.
1. What we take from each inspiration
| Project |
Steal |
Avoid |
| Superlogical / Rex |
Raw PTY bytes sent to every client instead of screen diffs, so the server and each client run synchronized libghostty-vt state machines and the server stays authoritative. Attach sends a minimal snapshot → ready → live bytes, with scrollback streamed afterwards, newest first; a client out of sync re-runs the handshake. Input is serialized into one writer. Each client owns its viewport, scrolling and selection. The server and CLI are one binary. run --wait, capture, events --json. OSC 7501 program status. (Pane stream: RFC-0006, COM-221.) |
No published protocol spec and no permission model. Pausing the PTY during attach (we use a byte offset per pane instead). Native GUI and remote-server parts (out of scope for now) |
| tuios |
One Unix socket where the first byte selects the protocol: binary stream or NDJSON verbs. The CLI, MCP server and tmux shim all share one verb protocol. Pane identity comes from the peer PID or a token, and each pane gets capability grants. An inbox for approvals and questions. --skill self-description. Headless tape replay. Sessions survive restarts. |
A second full emulator in the client; feature sprawl |
| t3code |
The ProviderAdapter interface: capabilities, send, steer, interrupt, approvals sent back as requests, fork, rollback. An event-sourced orchestrator split into a pure decider, a transactional outbox and an effect worker. Cursor replay for clients that reconnect. A worktree per thread, with cleanup policies. Checkpoints stored as hidden git refs. The orchestrator exposed over MCP, with scoped credentials for sub-agents. |
A separate SDK binding per vendor when a wire protocol (ACP / Codex app-server) exists |
| hermes-agent |
(We don’t build an agent, so we take only the parts relevant to orchestration.) Cron jobs that are agent tasks with a delivery target. Session lineage in SQLite with FTS5. doctor and import commands. ACP as the bridge to editors. |
Monolith sprawl |
| nullclaw |
The vtable plus comptime-assert interface pattern. -D build flags that leave subsystems out of the binary. A supervisor that restarts crashed threads with backoff. Security that fails closed: pairing, allowlists, encrypted secrets. Leak-checked tests. |
Breadth over depth; pinning one exact Zig version with no plan for upgrading |
| CLIProxyAPI |
The gateway shape: access check → selector → executor → translator. Per-credential cooldowns. Aliases. Config that hot-reloads. A management API separate from the data plane. |
Fingerprint spoofing and ToS-breaking subscription reuse. We use official channels only. |
2. The agent-friendly contract (applies to EVERY component)
- The daemon and the CLI are one binary.
venomx serve runs the daemon, and venomx <verb> is a client of it.
- Every action is a verb. A keybinding is just
bind key → verb, so anything a human can do, an agent can do with <tool> <verb> --json.
- One verb schema generates the CLI, the MCP server (
<tool> mcp), the docs and the shell completions.
--json on every command, with stable exit codes. events --json streams state changes as NDJSON.<tool> skill prints a SKILL.md, and <tool> skill install installs it into Claude Code, Codex and opencode.- Config is a ZON file plus verbs:
config get|set|check|reload|schema. Agents change config through verbs and never hand-edit ZON. config schema prints a machine-readable description of the config.
<tool> doctor diagnoses the setup and prints fixes as runnable commands.- Capability grants. Callers are identified by peer PID or a token and get scoped rights (read, write, respond, admin). The default is read-only, except in venomx, which trusts the user’s own processes until isolation is turned on (
grants.isolation, RFC-0005 section 11.1).
- Headless first. Every component works without a TUI attached.
- OSC 7501 / OSC 133 aware, for interop with Rex and tuios.
- No embedded scripting language, JIT or dynamic plugins in v1. Extension happens only through verbs, events and hooks that run executables.
3. Components (polyrepo under github.com/venom-org)
Foundations (libraries)
| Repo |
What |
venom-spec |
Protocol specs, the RFC process, the agent contract, the verb-schema format |
venom-std |
Shared Zig modules: proto (socket, framing, NDJSON verbs, event stream, grants), cfg (ZON load, validate, hot reload, config verbs), cli (verb schema → CLI, MCP and completions generator), log, secrets, xdg, interface helpers, supervisor |
venom-term |
Thin Venom API that wraps libvaxis (TUI rendering, widgets, input) and libghostty-vt (VT emulation) |
Products
| Repo |
Is |
Useful alone as |
venomx |
The multiplexer: PTYs, sessions, windows, panes, persistence and restore, snapshot plus raw-stream fan-out, OSC 7501/133 ingestion, pane identity and grants, a tmux shim, MCP |
A tmux/zellij replacement that agents can drive |
venom ⭐ |
The agent orchestrator, our second main product. Headless and event-sourced. Agent adapters (Claude Code, Codex app-server, generic ACP, opencode…). Workspaces (folders of repos), agents and turns (RFC-0018); fan-out; agent-to-agent messaging; a worktree per agent per repo; hidden-ref checkpoints and rollback (RFC-0021); approval routing and an inbox; scheduled agent jobs; an MCP server so agents can orchestrate agents. Ships its own TUI client. Uses venomx to put agents in panes when it’s available. |
A terminal-native t3code |
venom-desk |
The TUI desktop, a client of venomx: layouts, desktops (not “workspaces”, see RFC-0018), command palette, launcher, which-key, sidebar rail (sessions, git, agents), notifications, and an inbox view that shows venom’s approvals |
A tiling TUI desktop |
venom-mem |
Shared memory and knowledge store for external agents: SQLite with FTS5 and optional vectors, spaces, session lineage (RFC-0020). A skills registry comes after the MVP. CLI plus MCP. |
Persistent memory for any agent |
venom-gate (optional, later) |
Model gateway, official channels only: API keys, local models, routing and fallback, budgets and usage |
A local LLM router that agents point at through *_BASE_URL |
venom-relay (later) |
Talk to venom from Telegram, Signal or Matrix, with pairing and allowlists |
Mobile approvals and status |
Integration
| Repo |
Is |
venom-os |
The final bundle: venom-os up supervises venomx, venom, venom-desk, venom-mem and the rest. Login/session integration, curated defaults, and a catalog of TUI apps (helix, yazi, lazygit, btop…). Later: a distro image. |
venom-site |
The ecosystem website: a landing page per main product, plus each repo’s docs (docs/site/, or its README), the RFCs and the brand book, pulled in at build time. Static (Astro), to be hosted on Cloudflare Pages; rebuilt when a product repo merges. Not part of the dependency chain: nothing builds against it. |
How they compose
human ──► venom-desk (TUI desktop) ──┐
▼
agent ──► CLI / MCP ───────────► venomx (mux) ◄──── venom places agents in panes
▲ │
│ verbs / events │ adapters (ACP, Codex app-server, …)
│ ▼
venom (orchestrator) ──► Claude Code │ Codex │ opencode │ …
│
└──► venom-mem (shared memory) venom-gate (models, optional)
all built on: venom-std · venom-term (libvaxis + libghostty-vt) · venom-spec
all bundled by: venom-os
| Combination |
You get |
| venomx alone |
A tmux replacement that agents can drive |
| venom alone |
Headless or TUI orchestration of Claude Code, Codex and others |
| venomx + venom-desk |
A TUI desktop |
| venom + venomx + venom-desk |
Agents in panes, approval inbox, fleet overview |
| all + venom-os |
The agentic TUI OS |
4. Phasing
| Phase |
Deliverables |
Exit criteria |
| P0 Foundations |
venom-spec (agent contract RFC, proto RFC), venom-std (proto, cfg, cli gen), venom-term wrapper, CI template, .zigversion |
Toy daemon plus CLI plus generated MCP from one schema |
| P1 venomx MVP |
Sessions, attach/detach, splits, persistence, verbs (run --wait, send, capture, events), MCP, tmux shim, grants |
Claude Code agent teams run inside venomx; daily-drivable instead of tmux |
| P2 venom MVP |
Claude Code and Codex adapters, threads, worktrees, approvals, event log, MCP, basic TUI, venomx pane placement |
“Spawn 3 agents on 3 worktrees, approve from the CLI or TUI” |
| P3 venom-desk MVP |
Layouts, workspaces, palette, rail, inbox view |
The full human loop happens inside venom-desk |
| P4 venom-mem + more adapters |
Shared memory, ACP/opencode adapters, checkpoints and rollback |
Agents share memory across sessions |
| P5 venom-os |
Bundle, supervisor, app catalog; optional venom-gate and venom-relay |
venom-os up on a fresh machine |
P1 and P2 can overlap after P0, because venom works headless without venomx.
5. Decisions
| # |
Decision |
| 1 |
Polyrepo under github.com/venom-org |
| 2 |
Wrap libvaxis and libghostty-vt in venom-term |
| 3 |
ZON config, edited through config verbs |
| 4 |
No embedded language, scripting or JIT plugins in v1 |
| 5 |
Pin Zig 0.17 in a shared .zigversion; upgrade within N weeks of each Zig release |
| 6 |
venom-* names; venomx = mux, venom = orchestrator, venom-os = final OS |
| 7 |
Issue tracking (changed 2026-11-08): GitHub issues per repo, gathered in the org Venom OS project. Linear’s free plan ran out of issues, so open issues moved (map) and Linear stays as a read-only archive of finished work. |
| 8 |
Pane stream (2026-11-06): venomx sends raw PTY bytes, not screen diffs. Clients that show splits inside one terminal run libghostty-vt for each pane (emulating); attach --pane --raw is the fast path, where the host terminal is the only emulator. The daemon links only a headless Vt from venom-term. Spec: RFC-0006 (COM-221). |
Linear structure (historical, read-only since 2026-11-08; workspace commixon, team Commixon / COM)
The groupings below still apply as repo groups. Projects are now repos and milestones are per repo, on GitHub.
Sub-initiatives need Linear Enterprise, so the initiatives sit side by side and each project is added to several of them.
| Initiative |
Projects |
| Venom OS (I-1, Active; end goal) |
all 8 |
| Foundations (I-2, Active) |
venom-spec, venom-std, venom-term |
| Agent Contract v1 (I-3, Planned) |
venom-spec, venom-std, venomx, venom, venom-desk, venom-mem |
| Agents in Panes (I-4, Planned) |
venomx, venom, venom-desk |
| Project |
Priority |
Milestones |
| venom-spec (P-COM-8) |
High |
Agent contract RFC · Protocol & verb-schema RFC |
| venom-std (P-COM-9) |
High |
proto + cfg modules · CLI/MCP generator + toy daemon |
| venom-term (P-COM-10) |
High |
libvaxis + libghostty-vt wrapper on Zig 0.17 |
| venomx (P-COM-11) |
High |
MVP: sessions, panes, attach/detach · Agent verbs, MCP & grants · tmux shim & persistence |
| venom (P-COM-12) |
High |
Core: event log + Claude Code/Codex adapters · Worktrees, approvals & MCP · TUI client & venomx placement · Checkpoints, rollback & ACP adapters |
| venom-desk (P-COM-13) |
Medium |
MVP: layouts, workspaces, palette · Rail & inbox view |
| venom-mem (P-COM-14) |
Low |
MVP: store + CLI/MCP |
| venom-os (P-COM-15) |
Low |
venom-os up |
Workspace labels: agent-contract, protocol, tui, security, zig-upgrade.
