Research behind the design
The cited research venom's design decisions rest on, how references are keyed, and the study of opencode that fed the backlog.
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
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 ofmake test, fails on a key defined twice or a citation of a key that is not defined.
What to take from 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.