---
title: Research behind the design
description: The cited research venom's design decisions rest on, how references are keyed, and the study of opencode that fed the backlog.
section: reference
order: 230
audience: [builder, operator, agent]
sources: [docs/research.md, docs/inspiration-opencode.md, scripts/check-research-keys.sh]
features: [reference.research, reference.inspiration]
---

Venom's design choices cite evidence. The source repository keeps it in two research files; this page describes them so you can follow a citation such as "per [R23]" in a changelog, an ADR or a pull request.

## The research foundation {#research}

`docs/research.md` is a living document of several hundred references, each checked against its primary source (an arXiv abstract, official docs, a vendor model card or the author's own post) when it was added, unless marked *secondary* or *unverified*. Benchmark numbers are quoted as published, with who reported them.

| Part | What it covers |
|---|---|
| 1. Agent harness design | Agent loops, context management, compaction, subagents, tool design. |
| 2. Permissions and safety | Permission engines, sandboxing, prompt injection. |
| 3. Serving and orchestration | Inference engines, routing, prompt and KV caching, batching. |
| 4. Open-weight coding models | Models suited to sovereign deployment, with their reported results. |
| 5. Evaluation and backtesting | How to measure agent changes without fooling yourself. |
| 6. Design to evidence matrix | Every current design decision mapped to the references behind it, plus the changes the research recommends. |
| 7. Bibliography | Every reference, keyed `R1`, `R2`, ... |

Rules the project keeps:

- A design choice cites its reference key in the pull request or ADR.
- A new reference takes the next key above the highest one in use, and one source keeps one key.
- `scripts/check-research-keys.sh`, part of `make test`, fails on a key defined twice or a citation of a key that is not defined.

## What to take from opencode {#opencode}

`docs/inspiration-opencode.md` is a research note (snapshot 2026-10-09) that studied the opencode coding agent and collected evidence of which coding-agent features developers praise, ask for or complain about, from GitHub issues, Hacker News and blog posts. Its goal was a short backlog of proven ideas that fit venom, not feature parity.

It has four parts: a one-page map of opencode, a ranked shortlist (each item with evidence, where it lands in venom, effort and a sketch), what venom deliberately does not copy, and a bibliography keyed `O1`, `O2`, ... in the same style as the main research file. Opencode was read, not run, and the note records where evidence could not be gathered.

## Related

- [Design decisions (ADRs)](/docs/reference/adr.md)
- [Glossary](/docs/reference/glossary.md)
