---
title: Design decisions (ADRs)
description: One line per architecture decision record, saying what venom decided and why it matters to you.
section: reference
order: 70
audience: [operator, builder, agent]
sources: [docs/adr/README.md]
features: [reference.adr]
---

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 {#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.

## Related

- [Research behind the design](/docs/reference/research.md)
- [Architecture, ports and contracts](/docs/reference/architecture.md)
