Design decisions (ADRs)
One line per architecture decision record, saying what venom decided and why it matters to you.
Venom records each significant design choice as an architecture decision record (ADR) in docs/adr/. They live in the source repository; this page lists what each one decided. When behaviour surprises you, the matching ADR usually explains the trade-off.
| ADR | Decision |
|---|---|
| 0001 | The CLI is a distribution of pi, not a fork: exact-pinned pi packages, extended through pi's extension API. |
| 0002 | The agent harness is a separate library (@venom/harness) so other apps can embed it; UI stays out of it. |
| 0003 | Harness sessions over HTTP and Server-Sent Events (venom serve), with an OpenAPI contract. |
| 0004 | pi's compaction thresholds scale with the model's context window instead of fixed token counts. |
| 0005 | venom is also an Agent Client Protocol agent (venom acp) for Zed and other editors. |
| 0006 | After a compaction, pi's context gauge shows venom's estimate instead of going blank. |
| 0007 | The CLI is bundled with esbuild, the way pi bundles its own release, for fast start-up. |
| 0008 | --chrome drives a browser over the Chrome DevTools Protocol from the harness, not through an MCP server. |
| 0009 | An agent runtime built like a small operating system: processes, signals and scheduling for subagents. |
| 0010 | Context is managed as a memory hierarchy, with content identity and spill to disk. |
| 0011 | pi's abort reaches the agent runtime as SIGINT to the whole process tree. |
| 0012 | Decision providers give typed, advisory decisions; they are never the final authority on a permission or a merge. |
| 0013 | The agents panel is a non-capturing overlay pi draws in the top right. |
| 0014 | Copying text goes through pi's selection-copy hook. |
| 0015 | A reading width for the transcript, set through pi's TUI children. |
| 0016 | A typed relevance pass runs before each compaction summary. |
| 0017 | Venom Cloud is a Next.js control plane on Vercel and Neon; Go daemons are the data plane and only dial out. |
| 0018 | Attachment chips in the editor, through pi's editor segmenter. |
| 0019 | A proposed upstream change to pi: session projection per boundary handler. |
| 0020 | pi's fullscreen frames are kept out of the terminal's scrollback. |
| 0021 | No KV-cache sharing across mesh daemons for now; session affinity covers the need until there is hardware to measure on. |
| 0022 | Subagents can run in the background, be resumed and be stopped, through the one task tool. |
| 0023 | The public mesh: verifiable sampling, signed receipts and quality-of-service checks for daemons run by strangers. |
| 0024 | Sessions hand off between machines under a lease with an epoch, so only one machine writes. |
| 0025 | Blast-radius scopes limit what unattended agents may touch. |
| 0026 | An agent-to-agent protocol relayed through the cloud, dial-out only. |
| 0027 | Organisation policy is distributed as a signed envelope (venom.policy/v1). |
| 0028 | Venom Cloud as a hosted, multi-tenant service; orgs' own provider keys are sealed in its vault. Self-hosting is unchanged. |
| 0029 | Daemons can serve as a build and test farm through a gate dispatch kind. |
| 0030 | The console reads board and merge-queue state through venom serve (GET /v1/board). |
| 0031 | The desktop daemon's auto-update is opt-in and off by default. |
| 0032 | The user's own Chrome is driven through an extension over a relay venom hosts, not through MCP. |
| 0033 | An organisation MCP registry is carried in the signed policy; the laptop does the sign-in. |
| 0034 | The browser relay is encrypted with the pairing code rather than TLS. |
| 0035 | venom's browser tools are offered to other agents over MCP (venom browser mcp). |
| 0035 | One-step cloud login: browser device login, a per-org signing key, trust on login, policy sync at start. Two records share this number. |
| 0036 | The browser extension in Edge as is, and in Firefox through its own driver. |
| 0037 | Kubernetes support is plain kustomize manifests, not an operator. |
| 0038 | A reply cut off at max_tokens is recovered by an escalated retry that continues from the partial reply. |
| 0039 | Idempotency keys for MCP tools/call go in _meta, working around a gap in pi's client. |
| 0040 | A contract for agents that edit venom: live tasks only propose, PRs have a size cap, some paths are protected. |
| 0041 | Tools do not start while a response is still streaming; pi's extension API cannot do it cleanly. |
| 0042 | A vetted model catalog served by the orchestrator (GET /api/models/providers/{id}); pi's consumer side waits upstream. |
| 0043 | Realtime voice agents as a cascaded pipeline in venom serve, streaming speech-to-text in the orchestrator, phone lines through Asterisk. |
| 0044 | Voice uses OpenAI's audio API in front of every speech provider, with one adapter file per wire format. |
Measured negative results
Decisions that were measured and found not worth it are kept rather than deleted: as a closed draft pull request, or as a feature that ships off by default with its numbers. ADR 0021 is an example of a decision not to build something yet.