Skip to content
Docs menu

Design decisions (ADRs)

One line per architecture decision record, saying what venom decided and why it matters to you.

View .md

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.