A coding agentthat asks first.
venom works in your terminal: it reads your code, edits files and runs commands under rules you set. Run it on a model on your own machine, through Venom Cloud, or against any OpenAI-compatible endpoint.
Platforms:macOS (Apple silicon)macOS (Intel)Linux x64Linux arm64Windows x64(Beta)
- 97.6%16
pass@1 on 42 eval tasks, 95.2% on all 3 trials
- 74.4%16
of input tokens read from the prompt cache across those runs
- 100%18
of long sessions finished in a 16k window, up from 37.5%
- 206 ms17
to the first frame of the terminal UI
From our own eval suite and benchmarks, with the conditions in how it works and the sources at the end of the comparison.
What it does
Built to be trusted with a real repository
The agent loop is pi's. venom adds the guardrails, the compatibility and the defaults a team can live with.
A permission engine, not a prompt
Four modes: plan (read-only), default, accept-edits and yolo. Shell commands are parsed, and each part of a compound command is judged against your deny, ask and allow rules.
An OS sandbox for yolo
In yolo, bash runs inside sandbox-exec on macOS or bubblewrap on Linux: writes stay in the workspace and temp dirs, and the network goes through an allowlist.
Plan mode and checkpoints
Plan mode reads and proposes without touching a file. Every edit is checkpointed, so /undo takes the last change back.
Subagents
Hand work to explorer, worker and verifier agents, or your own, each with its own context and tools. Workers can run in their own git worktrees.
Claude Code projects work as they are
CLAUDE.md and AGENTS.md, .claude skills, commands, agents, settings and hooks, Claude plugins and .mcp.json. Project hooks and MCP servers run only once you trust the project.
Plugins
Add tools, commands, keys, skills, agents, hooks and MCP servers from a directory, npm or git. pi packages and Claude Code plugins load too: venom plugin add.
Hooks and sounds
Claude Code's hooks can block or steer a tool call. venom's own events fire when a run, a subagent or a step ends, for a sound, a notification or a log line.
Reviews and editors
venom review checks your branch and exits non-zero on blockers. venom acp plugs into Zed, and venom serve runs sessions over HTTP for your own tools.
Works with the network unplugged
No telemetry and no update checks. With a local model, nothing leaves your machine. venom doctor tells you where your prompts go.
Under the hood
Fewer tokens per turn, and a shell it can't talk its way out of
Most of what an agent costs is input tokens, and most of its risk is the shell. Each card names a technique venom uses for one of the two, and what it measured.
Append-only prompt prefix
Every turn is a cache hit on the turn before15,22,16
The system prompt and tool list never change during a session, reminders ride on the newest message, and two sessions in one workspace send the same prefix. A test fails the build if the fixed prompt grows past its token budget, which is how a week of features was cut back from 4,243 tokens to 2,776.
74.4%of input tokens cached across 126 eval trials; the fixed prompt is 35% smaller than at its peak
Eval baseline on gpt-5.4-mini, and the prompt measured on main.
Deferred MCP tool schemas
A big MCP server doesn't cost you on every request23
When a server's tool schemas would be large, venom sends only their names and a tool_search tool. The model loads the schemas it needs once, and the prefix stays the same.
15,368 → 1,863tokens in the fixed prompt with a 60-tool MCP server (−88%)
A fake MCP server of 60 GitHub-sized tools, in a test.
Staged compaction
Long tasks finish in a small local model's window18,24
Old tool output is masked to a blob store first, pinned facts are carried word for word by code, and a summary is written only when masking isn't enough. The summary request re-sends the session's prefix byte for byte, so it is itself a cache read.
37.5% → 100%long-session tasks passed in a 16k-token window
Eval longsession slice, k=2, before and after.
Layered patch matching
Half as many failed edits25,26,27
For GPT-5 models, venom edits with apply_patch. Each hunk is matched exactly, then without trailing whitespace, then without indentation, then with Unicode quotes and dashes folded, and a patch applies whole or rolls back.
8.3% → 4.3%of edit calls failed; requests across the 27 tasks fell from 645 to 526, and pass@1 stayed at 100%
27 eval tasks on gpt-5.4-mini.
Parsed shell commands
Rules judge what a command does, not how it's spelled9,20
A compound command is parsed and each part is checked against your deny, ask and allow rules, so an allowed git status can't carry an rm along with it. In yolo, bash runs in sandbox-exec or bubblewrap, and each command gets its own empty /tmp and /run.
< 1 mssandbox cost per command on Linux, down from about 90 ms
A Linux host with a busy /tmp.
Sandbox escape matrix
The sandbox has a test suite that tries to escape it28
21 escape attempts run under three network policies through every way venom runs bash: write outside the workspace, read ~/.ssh, remount /, reach the Docker socket or the ssh agent, resolve DNS around the proxy. On Linux the whole matrix runs again as root.
Spotlighting
File contents and web pages can't give orders19
Everything venom reads from outside, from files to command output to web pages, is fenced as untrusted, and an advisory detector flags text that tries to steer the agent.
9/18 → 18/18prompt-injection trials resisted
Eval safety slice, k=3.
Content-defined chunking
A re-run test suite costs only what changed29
When a command's output mostly repeats one the model still has in view, such as a test run after a fix, venom sends a back-reference and a diff instead. FastCDC chunking finds the overlap, and the note is used only when it rebuilds the output exactly.
82.5%fewer characters sent on near-duplicate output, with 0 false positives
scripts/cdc-bench.ts on recorded outputs.
Trigram and incremental code indexes
Search stays fast in a very large repository21,30,31
grep consults a trigram index before it reads files, and the symbol index updates only what changed, in a worker, with an overlay for unsaved edits. /undo checkpoints find changed files with a Merkle tree instead of hashing the workspace.
60 s → 0.42 sto refresh the index after 10 changed files in Kubernetes; nine grep patterns went from 4.9 s to 1.5 s
26,918 files on a loaded machine, and a 29k-file synthetic repository.
Handoff by citation
Subagents get pointers, not pastes32,33
A parent hands a subagent the files and line ranges that matter, and the child reads them itself. Subagents run concurrently under a scheduler, each with its own context and tools.
17.6k → 2.9kprompt tokens to hand over a 42 KB document
A context handoff by file citation instead of pasting.
Paired bootstrap eval gate
Harness changes have to measure no worse34,35,16
Harness changes run against a committed baseline of 42 tasks in 8 categories. A seeded, paired bootstrap decides, and a safety task that used to pass every trial may not fail one. Ideas that measured worse stay off: an effort router that cost 7.6% more a trial, and a compaction pass that cut pass@1.
97.6% / 95.2%pass@1 and pass^3 on the baseline, 126 trials for $1.23
Self-authored tasks, gpt-5.4-mini. Not a public benchmark.
Install
One line, or one archive
Each download carries its own Node runtime, so there is nothing else to install. The scripts fetch only from the public releases repository, check the SHA-256 and put venom in ~/.venom/bin.
macOS and Linux
curl -fsSL https://raw.githubusercontent.com/elishahbiz/venom-releases/main/install.sh | sh
Picks the build for your OS and chip. VENOM_VERSION=0.2.0 before sh pins a version.
Windows, in PowerShell Beta
irm https://raw.githubusercontent.com/elishahbiz/venom-releases/main/install.ps1 | iex
Installs to %USERPROFILE%\.venom\bin and adds it to your user PATH. Windows has no OS sandbox yet: what that means.
Or download an archive
Unpack it anywhere and run bin/venom (on Windows, bin\venom.cmd).
Check the download
Every release publishes SHA256SUMS next to the archives. The install scripts check it for you; to check by hand, put it in the same folder as the archive:
shasum -a 256 -c SHA256SUMS --ignore-missing
On Linux, sha256sum -c SHA256SUMS --ignore-missing. On Windows, compare the output of Get-FileHash .\venom-0.2.0-windows-x64.zip -Algorithm SHA256 with its line in the file.
Then check the setup
venom doctor checks the endpoint, your key, the models and their context windows, the OS sandbox and what the current project loads, with a fix on every line that fails.
venom --version venom doctor
Release notes and every asset: the releases page. Step by step: the quickstart.
Compared
venom, Claude Code and Qwen Code
All three ask before they act, plan, delegate to subagents and sandbox the shell. venom differs in the rest: it runs any model without an account, and it ships with telemetry and update checks off. It is built on pi, and it reads your Claude Code setup as it is.
- venom CLI
- MIT, free download
- Claude Code
- Proprietary, under Anthropic's Commercial Terms
- Qwen Code
- Apache-2.0
- venom CLI
- Any OpenAI-compatible endpoint: Ollama, vLLM, SGLang, llama.cpp, Venom Cloud or a provider
- Claude Code
- ~Claude models, through Anthropic or Amazon Bedrock, Google Cloud and Microsoft Foundry
- Qwen Code
- OpenAI, Anthropic, Gemini and Qwen APIs, any OpenAI-compatible endpoint, local models
- venom CLI
- None. Point it at a model and start
- Claude Code
- A Claude Pro, Max, Team, Enterprise or Console account, or a cloud provider
- Qwen Code
- A provider key, or a local model
- venom CLI
- Works, with a local model
- Claude Code
- –Docs list an internet connection as required
- Qwen Code
- Not checked
Usage telemetry by default4,7,8
- venom CLI
- Off. No telemetry and no update checks
- Claude Code
- On with the Claude API (no code or prompts), off on cloud providers; one variable turns it off
- Qwen Code
- On; one setting turns it off
- venom CLI
- None. You choose when to upgrade
- Claude Code
- Native installs update in the background
- Qwen Code
- Checks and installs on startup by default
Permission modes and plan mode9,10,8
- venom CLI
- plan, default, accept-edits, yolo; each part of a compound shell command is judged on its own
- Claude Code
- default, acceptEdits, plan, auto, dontAsk, bypassPermissions
- Qwen Code
- plan, default, auto-edit, auto, yolo
OS sandbox for shell commands9,10,11
- venom CLI
- sandbox-exec on macOS, bubblewrap on Linux, with a per-host network allowlist; on whenever yolo runs bash
- Claude Code
- Seatbelt on macOS, bubblewrap on Linux and WSL2; off by default
- Qwen Code
- Seatbelt, Docker or Podman, Linux bwrap; opt-in
- venom CLI
- Explorer, worker, verifier and your own; workers can get their own git worktree
- Claude Code
- Qwen Code
- venom CLI
- pi packages and Claude Code plugins load as they are; MCP
- Claude Code
- Plugins, hooks, skills, MCP
- Qwen Code
- Extensions, including Claude Code marketplace plugins; MCP
Reads a Claude Code project as it is14,13
- venom CLI
- CLAUDE.md, .claude skills, commands, agents, settings, hooks, .mcp.json
- Claude Code
- Its own format
- Qwen Code
- Not checked
- venom CLI
- Fixed prompt held under a 2,910-token budget a test enforces; the prefix is append-only and the same across sessions
- Claude Code
- Automatic prompt caching
- Qwen Code
- Not checked
| Capability | venom CLI | Claude Code | Qwen Code |
|---|---|---|---|
| License1,2,3 | MIT, free download | Proprietary, under Anthropic's Commercial Terms | Apache-2.0 |
| Models4,5,6,3 | Any OpenAI-compatible endpoint: Ollama, vLLM, SGLang, llama.cpp, Venom Cloud or a provider | ~Claude models, through Anthropic or Amazon Bedrock, Google Cloud and Microsoft Foundry | OpenAI, Anthropic, Gemini and Qwen APIs, any OpenAI-compatible endpoint, local models |
| Account needed1,5,3 | None. Point it at a model and start | A Claude Pro, Max, Team, Enterprise or Console account, or a cloud provider | A provider key, or a local model |
| With the network unplugged4,5 | Works, with a local model | –Docs list an internet connection as required | Not checked |
| Usage telemetry by default4,7,8 | Off. No telemetry and no update checks | On with the Claude API (no code or prompts), off on cloud providers; one variable turns it off | On; one setting turns it off |
| Automatic updates4,5,8 | None. You choose when to upgrade | Native installs update in the background | Checks and installs on startup by default |
| Permission modes and plan mode9,10,8 | plan, default, accept-edits, yolo; each part of a compound shell command is judged on its own | default, acceptEdits, plan, auto, dontAsk, bypassPermissions | plan, default, auto-edit, auto, yolo |
| OS sandbox for shell commands9,10,11 | sandbox-exec on macOS, bubblewrap on Linux, with a per-host network allowlist; on whenever yolo runs bash | Seatbelt on macOS, bubblewrap on Linux and WSL2; off by default | Seatbelt, Docker or Podman, Linux bwrap; opt-in |
| Subagents12,13,11 | Explorer, worker, verifier and your own; workers can get their own git worktree | ||
| Plugins and MCP14,13,11 | pi packages and Claude Code plugins load as they are; MCP | Plugins, hooks, skills, MCP | Extensions, including Claude Code marketplace plugins; MCP |
| Reads a Claude Code project as it is14,13 | CLAUDE.md, .claude skills, commands, agents, settings, hooks, .mcp.json | Its own format | Not checked |
| Prompt-cache stability15,13 | Fixed prompt held under a 2,910-token budget a test enforces; the prefix is append-only and the same across sessions | Automatic prompt caching | Not checked |
pass@1 on Venom's eval suite
42 tasks, 3 trials each: 95.2% passed all 3. The safety slice passed 18 of 18 with no permission-engine violations. 126 trials cost $1.23, with 74.4% of input tokens cached.
Self-authored tasks, gpt-5.4-mini through the orchestrator. Not a public benchmark.
to the first frame of the TUI
Bundling the CLI halved startup: 417 ms to 206 ms for the first frame, and 514 ms to 243 ms to the first model request.
Apple M2 Pro, medians of 15 runs.
long sessions in a 16k window
Compaction masks old tool output first, keeps pinned facts word for word and recovers from overflow, so long tasks finish in small local-model windows.
Eval longsession slice, k=2.
prompt-injection trials passed
Outside content is spotlighted, and an advisory detector flags injection attempts.
Eval safety slice, k=3.
sandbox cost per command on Linux
Each sandboxed command gets its own empty /tmp and /run, which closed a socket leak and cut the cost from about 90 ms.
A Linux host with a busy /tmp.
to update the code index
After 10 changed files in the Kubernetes repository, down from 60 s. A cold build went from 171 s to 45 s.
26,918 files, a machine loaded by other runs.
The full comparison, with every speedup
Sources
- 1.The venom CLI, the orchestrator and the cloud are MIT licensed; the CLI needs no account. cli/package.json:7, docs/release.md:144.
- 2.Claude Code's license file: "All rights reserved. Use is subject to Anthropic's Commercial Terms of Service." github.com/anthropics/claude-code/blob/main/LICENSE.md. Checked 2026-10-18.
- 3.Qwen Code README: originally based on Google Gemini CLI v0.8.2, developed independently since v0.1; Apache-2.0; supports OpenAI, Anthropic, Gemini and Qwen APIs and local models (Ollama, vLLM). github.com/QwenLM/qwen-code. Checked 2026-10-18.
- 4.Venom README: the CLI turns off telemetry, update checks and downloads, and the orchestrator calls only its configured upstreams. README.md:32-33.
- 5.Claude Code setup docs: requires a Pro, Max, Team, Enterprise or Console account, or a third-party provider (Amazon Bedrock, Google Cloud, Microsoft Foundry); "internet connection required"; native installs update in the background, package-manager installs don't by default. code.claude.com/docs/en/setup. Checked 2026-10-18.
- 6.Claude Code LLM gateway docs: Anthropic "doesn't support routing Claude Code to non-Claude models through any gateway." code.claude.com/docs/en/llm-gateway. Checked 2026-10-18.
- 7.Claude Code data-usage docs: metrics are on by default with the Claude API (they never include code, prompts or file paths), off by default on Bedrock, Google Cloud and Foundry; DISABLE_TELEMETRY or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC turns them off. code.claude.com/docs/en/data-usage. Checked 2026-10-18.
- 8.Qwen Code settings docs: privacy.usageStatisticsEnabled defaults to true; general.enableAutoUpdate (update checks and installs on startup) defaults to true; approval modes plan, default, auto-edit, auto and yolo. qwenlm.github.io/qwen-code-docs/en/users/configuration/settings. Checked 2026-10-18.
- 9.venom's permission modes, compound-command parsing and the OS sandbox (sandbox-exec on macOS, bubblewrap on Linux) with a per-host network allowlist. docs/getting-started.md, CHANGELOG.md "per-host network allowlist".
- 10.Claude Code permission modes (default, acceptEdits, plan, auto, dontAsk, bypassPermissions) and sandboxing (Seatbelt on macOS, bubblewrap on Linux and WSL2, off by default). code.claude.com/docs/en/permission-modes, /sandboxing. Checked 2026-10-18.
- 11.Qwen Code docs: subagents, an opt-in sandbox (macOS Seatbelt, Docker or Podman, Linux bwrap), MCP, and extensions that also install Gemini CLI and Claude Code marketplace plugins. qwenlm.github.io/qwen-code-docs (sub-agents, sandbox, mcp, extension). Checked 2026-10-18.
- 12.venom's subagents: explorer, worker, verifier and your own, each with its own context and tools; workers can run in git worktrees. docs/workspaces.md, packages/harness/AGENTS.md.
- 13.Claude Code subagents, plugins, hooks, skills, MCP, and automatic prompt caching. code.claude.com/docs/en/sub-agents, /plugins, /mcp, /costs. Checked 2026-10-18.
- 14.venom loads pi packages and Claude Code plugins, and reads CLAUDE.md, .claude skills, commands, agents, settings, hooks and .mcp.json. docs/plugins.md, cli/AGENTS.md.
- 15.The fixed system prompt and tool list are held under a token budget a test enforces (2,906 tokens measured, budget 2,910), and the prefix is tested append-only across turns and identical across sessions. packages/harness/test/prompt-budget.test.ts "by team and org memory", CHANGELOG.md "pins the prompt prefix as append-only".
- 16.Venom eval baseline, 2026-10-09: 42 self-authored tasks in 8 categories, k=3 (126 trials), venom-default routed to gpt-5.4-mini through a local orchestrator. Not a public benchmark and not a head-to-head with other agents. evals/results/2026-10-09T08-33-43Z-23be.json, evals/AGENTS.md "`apply_patch` and no `edit`. Results: pass@1".
- 17.Bundled CLI vs. unbundled, Apple M2 Pro, Node 24.9, n=15 interleaved runs, medians. cli/AGENTS.md "**Measured, the bundle**".
- 18.Eval longsession slice at a 16k-token context window, k=2, before and after the compaction work. CHANGELOG.md "At a 16k window, longsession pass@1 went from".
- 19.Eval safety slice (prompt injection), k=3, before and after spotlighting and the injection guidance. CHANGELOG.md "safety slice went from".
- 20.Linux sandbox: each command gets its own empty /tmp and /run; per-command cost on a host with a busy /tmp. CHANGELOG.md "per-command cost from about".
- 21.Code index on the Kubernetes repository (26,918 files), worker and overlay updates, on a machine loaded by other runs. packages/harness/AGENTS.md "| | kubernetes, first | kubernetes, now |".
- 22.The fixed prompt (system prompt and tool schemas, chars/4) before and after the prompt diet, measured on main. packages/harness/AGENTS.md "**The prompt diet**".
- 23.Lazy MCP tools (test/lazy-tools.test.ts): a fake MCP server of 60 GitHub-sized tools, the fixed prompt with the server declared and with it deferred. packages/harness/AGENTS.md "Measured (`test/lazy-tools.test.ts`".
- 24.A compaction summary re-sends the session's prefix byte for byte, so it is a cache read (a faux-provider measurement). CHANGELOG.md "so its prefix is a cache read (faux measurement".
- 25.apply_patch matches a hunk exactly, then ignoring trailing whitespace, then ignoring indentation, then folding Unicode quotes, dashes and spaces; a patch applies whole or not at all. packages/harness/src/patch/.
- 26.edit against apply_patch on gpt-5.4-mini, 27 eval tasks: failed edit calls per arm. evals/results/compare-edit-vs-apply-patch.md "Per trial, over the", evals/results/compare-edit-vs-apply-patch.md "| baseline, edit, k=3 |".
- 27.apply_patch for GPT-5 models, 27 eval tasks: pass@1 held at 100%. CHANGELOG.md "`apply_patch` (OpenAI's V4A format) for GPT-5 family models".
- 28.The sandbox escape matrix (test/sandbox-matrix.test.ts): 21 probes under three network policies, through every bash entry point, live on macOS and on Linux, the Linux run once as a user and once as root. packages/harness/AGENTS.md:8837-8876.
- 29.Near-duplicate command output found by content-defined chunking (FastCDC) and a bounded line diff (scripts/cdc-bench.ts): characters sent on the near-duplicate cases, and false positives. CHANGELOG.md "`scripts/cdc-bench.ts`:".
- 30.Trigram index for grep on a 29k-file synthetic repository, nine patterns (scripts/trigram-bench.ts). CHANGELOG.md "hands `rg` the files that cannot match".
- 31.Merkle change detection for /undo checkpoints on a 30k-file workspace (scripts/checkpoint-bench.ts). CHANGELOG.md "nested repositories and other doubtful cases fall back to a full capture".
- 32.Context handoff to a subagent by file citation instead of pasting a 42 KB doc. CHANGELOG.md "doc handed over this way cost a child".
- 33.Subagent scheduler benchmark with scripted agents (no model): 16 agents at concurrency cap 16. CHANGELOG.md "Runtime with the R2 scheduler".
- 34.The eval gate: a paired, seeded bootstrap of per-task pass rates; it fails when the 95% interval lies below the tolerance, or when any safety task that passed every trial before fails one. evals/AGENTS.md:18-20, evals/src/score.ts, evals/src/compare.ts.
- 35.Changes measured and not shipped: an effort router (+7.6% cost a trial, one hard trial lost) and a compaction relevance pass (pass@1 97.2% → 91.7%, off by default). evals/AGENTS.md "### Effort router (tried, not shipped)", docs/adr/0016-compaction-relevance-pass.md "Whole run (longsession, memory,".
Models
Bring the model. venom brings the rest.
venom speaks the OpenAI API. Two variables choose where it sends requests, and VENOM_MODEL picks the model.
On your machine
offlineRun a local server such as Ollama and point venom at it. Nothing goes over the network, and no key is needed.
ollama pull qwen3:8b export VENOM_BASE_URL=http://localhost:11434/v1 export VENOM_MODEL=qwen3:8b venom
Use it with Venom Cloud
teamOne key reaches your org's GPUs, the public nodes you trust and your provider keys. Its limits and budget apply, and every call shows up in your request log.
export VENOM_BASE_URL=https://cloud.usevenom.dev/v1 export VENOM_API_KEY=vck_… venom
Any OpenAI-compatible endpoint
yoursvLLM, SGLang, llama.cpp, a gateway you already run, or a provider. venom doctor checks the endpoint, the key and the model list.
export VENOM_BASE_URL=https://your-gateway.example/v1 export VENOM_API_KEY=… export VENOM_MODEL=your-model venom doctor
Windows
Windows is in beta Beta
The OS sandbox uses sandbox-exec on macOS and bubblewrap on Linux. Windows has neither, so venom on Windows runs without it and says so when it starts. To keep that safe, it asks you instead of relying on a sandbox:
- yolo never runs bash on its own: commands your rules don't allow ask, as in accept-edits
- auto mode is unavailable, because it relies on the sandbox
- Your deny and ask rules and the built-in hard-deny list apply as on macOS and Linux
- --no-sandbox runs bash unconfined, only if you pass it yourself
For the full sandbox on a Windows machine, run the Linux build in WSL.
FAQ
Questions people ask first
Do I need Node.js?
Which models does it work with?
VENOM_BASE_URL, VENOM_API_KEY if the endpoint needs one, and VENOM_MODEL.Does it send telemetry?
Does it need Venom Cloud?
Will it run commands without asking?
What about my Claude Code setup?
What license is it under?
Put an agent in your terminal that follows your rules
Download venom, point it at a model, and start in your repository.
Free and MIT licensed. No account needed for the CLI.