Give any coding-agent user a whole company of specialists instead of one generalist.
Venom scaffolds a named team of role-based AI agents — a boss, researchers, developers, reviewers, a security auditor — with shared, persistent memory, into any project. One command drops the team in; you drive it through your coding agent.
A single coding agent is one generalist: it forgets between sessions, reviews its own work, and holds one perspective.
Venom gives you a team: specialized roles, independent review gates a generalist skips, and a memory that persists across sessions and survives context resets. So you catch more, forget less, and work with more rigor.
That's the whole claim. No "10x", no magic — just structure a solo agent doesn't have. The honesty is the point: it's why you can trust the parts Venom does do.
cd your-project
npx venomkit initinit asks which coding tool you use (Claude Code, Codex, or Gemini) and what kind of work you
do, fills a project Charter, writes the memory scaffold, and installs the agents where that tool
looks for them — in under a minute, no config editing. Then open the project in that tool and give
boss-1 your first goal.
Prefer non-interactive? Name the tool and pack directly:
npx venomkit init --tool codex --pack web-app --yes # or --tool gemini / claude-codeRequirements: a coding agent you already use — Claude Code, Codex, or Gemini CLI — and Node.js ≥ 18.17. Venom is for developers comfortable in a terminal; it doesn't try to be a no-terminal GUI.
flowchart LR
A(["npx venomkit init"]) --> B["detect your<br/>coding tool"] --> C["pick a pack"] --> D["3-4 plain<br/>questions"] --> E["fill CHARTER.md"] --> F["install the team"] --> G([" ready in under a minute "])
your-project/
├── CHARTER.md # your project's constitution — identity, non-negotiables, scope (yours to edit)
├── CLAUDE.md # briefs your lead session to operate as boss-1, and loads the Charter
├── .claude/
│ ├── agents/ # your team, as individual agent files
│ └── settings.json # safe permissions (allow reads · ask before impact · deny danger)
├── agent-memory/ # the team's shared, persistent memory (SNAPSHOT, logs, lessons, ADRs)
└── .venom/
├── workflow.md # your guide to driving the team
└── install.json # install record (pack, roles, version) — used by re-init and `add`
Nothing is clobbered on re-run: your CHARTER.md, your own notes in CLAUDE.md, your existing
settings.json rules, and your live agent-memory/ are all preserved.
That's the Claude Code layout.
--tool codexinstalls the same team as anAGENTS.mdbrief plus.venom/agents/role specs;--tool geminiinstalls it asGEMINI.mdplus/venom:<role>slash-commands under.gemini/commands/venom/. Same core, same memory — mapped to each tool's native shape.
- Shared, persistent memory. Agents don't chat live — they coordinate through files under
agent-memory/, read before acting and written after. One agent's result becomes the next agent's starting point, and it all survives a context reset. Governing rule: write everything, read selectively. - Two independent review gates. Before anything is called done, it passes critics (correctness + your Charter's non-negotiables) and security (exploitability) — both read-only, both must pass. They flag and block; they never fix. You make the final call.
Every pack ships the same core four (boss-1, boss-2, critics, security) plus the full memory
tier. They differ only in the specialists:
flowchart TD
CORE["🧩 Core — in every pack<br/>boss-1 · boss-2 · critics · security<br/>+ shared persistent memory"]
CORE --> P1["web-app · 14<br/>full software team"]
CORE --> P2["data-ml · 12<br/>data + models"]
CORE --> P3["research-academic · 10<br/>advisory research room"]
CORE --> P4["writing-content · 9<br/>writing room"]
CORE --> P5["security-audit · 8<br/>threat modeling + audit"]
CORE --> P6["solo-minimal · 8<br/>lightest team"]
| Pack | Agents | Best for |
|---|---|---|
| web-app (default) | 14 | Web apps, APIs, CLIs, general software |
| data-ml | 12 | Data pipelines, ETL, model training & evaluation |
| research-academic | 10 | Literature reviews, study design, rigorous written research |
| writing-content | 9 | Articles and docs where the claims must hold up |
| security-audit | 8 | Security reviews and audits of an existing codebase |
| solo-minimal | 8 | A solo dev who wants review + memory without the full org |
npx venomkit list # see the packs and roles
npx venomkit init --pack solo-minimalYou talk to boss-1 — one point of contact, not the whole roster. You give it a goal and set the leash (how much autonomy to take); it decomposes the goal, delegates to the right specialists, runs the review gates, and brings back one reconciled recommendation. You approve what matters.
The full daily-use guide — the leash, the gates, the quality loops, a troubleshooting table, and what
to expect — is installed at .venom/workflow.md.
Behind that one conversation, the whole team is at work:
flowchart TD
You["👤 You — the owner"]
You -->|"goal + the leash (how much autonomy)"| B1["boss-1<br/>orchestrator"]
B1 -->|"one reconciled recommendation"| You
B1 <-->|"audits the big calls"| B2["boss-2<br/>independent auditor"]
B1 --> RH["research-head"]
B1 --> DH["dev-head"]
RH --> RES["researchers"]
DH --> BLD["developers · testing<br/>debugger · design · docs"]
BLD -->|"finished work"| CR["critics<br/>correctness + trust"]
BLD -->|"finished work"| SE["security<br/>exploitability"]
CR -->|"BLOCK → back to build"| DH
SE -->|"BLOCK → back to build"| DH
CR -->|"PASS"| B1
SE -->|"PASS"| B1
Only the bosses talk to you; the gates and boss-2 report to boss-1 directly. Both gates must be green before anything ships — and you make the final call.
- Not an autonomous company that runs while you sleep. Today's tools can't deliver reliable unsupervised multi-agent autonomy, and Venom doesn't pretend to. You're the driver.
- Not a productivity-multiplier with a number. It gives you structure, review, and memory — not a guaranteed multiple.
- Not infallible. The gates make the work more rigorous, not perfect. The final call is always yours.
A tool-agnostic core holds the value — the agent roles (portable Markdown), the memory protocol, the workflow, and the packs. Thin per-tool adapters map that core into whatever a specific coding tool expects. This is what lets one framework target many tools without rewriting the brain.
venom/
├── core/ # tool-agnostic: agents/, memory-template/, workflow.md, packs.json, CHARTER_TEMPLATE.md
├── adapters/
│ ├── claude-code/ # core → .claude/agents/ subagents + settings.json
│ ├── codex/ # core → AGENTS.md brief + .venom/agents/ role specs
│ └── gemini/ # core → GEMINI.md + .gemini/commands/venom/ slash-commands
├── bin/ # the venom CLI entry
└── src/ # the CLI (TypeScript → dist/; zero runtime dependencies)
Project specifics live only in the generated CHARTER.md; the agent specs stay generic and read the
Charter at runtime. Each adapter maps that one core onto its tool's native primitives — so the
team is real in each, and each adapter's README notes exactly where a tool's mechanism differs (e.g.
Claude Code trims each role's tools — the critics/security gates get no Edit/Write; Codex and
Gemini carry that as instruction plus the tool's own sandbox). Adapters ship as plain ESM modules plus
JSON/Markdown templates with no build step — so adding a tool is one file, not a rewrite.
Deeper diagrams — the core↔adapter mapping, how agents coordinate through shared memory, and the review loop — are in docs/ARCHITECTURE.md.
Core (every pack): boss-1 (orchestrator) · boss-2 (independent auditor) · critics
(correctness/trust gate) · security (exploitability gate).
Specialists (assembled per pack): research-head · dev-head · tech-researcher ·
domain-researcher · developer-1 · developer-2 · testing · debugger · design ·
technical-writer · data-engineer · ml-engineer · literature-reviewer · methodologist ·
editor · fact-checker · threat-modeler · pentester-advisor. Plus an optional marketing
add-on (venom add marketing).
venom guide [topic] New here? A plain-English walkthrough (start|memory|mcp|cli|cost)
venom init [options] Install a team into the current project
venom list Show the available packs and roles
venom add <role> Add an optional role to an existing install
venom tokens [--pack <id>] Estimate token footprint + cost across models/presets
venom models [preset] Show or switch the model preset (quality | balanced | budget)
venom memory <cmd> Inspect, view & bound shared memory (stats | search | read | compact | index)
venom mcp memory Run the opt-in MCP server (memory + agent-router tools, called at inference)
venom mcp Show how to wire the MCP server into Claude Code / Codex / Gemini
venom --version Print the version
venom --help Full help
init options:
--pack <id> web-app | data-ml | research-academic | writing-content | security-audit | solo-minimal
--roles <a,b,c> Custom roster — pick specialists; the core gates are always installed
--name <name> Project name (default: folder name)
--one-liner <text> One-line description of the project
--non-negotiables <t> Rules that must never be broken (separate with ';')
--out-of-lane <text> What the project deliberately won't do
--tool <id> claude-code (default) | codex | gemini (auto-detected if omitted)
--models <preset> quality | balanced (default) | budget — cost/quality tradeoff
--dir <path> Target directory (default: current)
--force Overwrite an existing CHARTER.md
--yes, -y Non-interactive: use flags + defaults
Token control. venom tokens estimates the per-turn and per-goal footprint and the cost across
models, and compares the presets. venom models budget downshifts the workers to a cheaper model —
per-role on Claude Code (real, in each subagent's frontmatter); a recommended session model on
Codex/Gemini. Run venom tokens before and after to see the delta.
Memory control. Shared memory is append-only, so it grows. venom memory stats shows where the
tokens are (hot read-path vs. cold archives) and flags logs over budget; venom memory compact --write
keeps the newest entries in each team log and archives the rest to log.archive.md — verbatim, never
deleted — to bound what agents read each turn; venom memory index --write refreshes INDEX.md's
entry catalog so agents scan an index instead of whole logs. Compaction is a safe dry run by default.
Honest scope: Venom doesn't own the model's inference, so these keep memory bounded and navigable —
they can't force selective reading; boss-1 (or you) runs them to keep the tier lean.
Runtime memory (opt-in MCP). For the one place Venom can help at inference, venom mcp memory
runs a small MCP server that exposes the shared memory as tools the
agent calls directly — memory_search (keyword retrieval with field weighting, so it pulls the
relevant slice instead of reading whole files), memory_read, memory_append (the write-after-turn
step, formatted so it stays compaction-safe), memory_stats, and memory_compact. It's opt-in
and zero-dependency (hand-rolled JSON-RPC, no SDK). Run venom mcp for the one-line wiring for
Claude Code, Codex, or Gemini. Path-contained to agent-memory/ (realpath-checked, no symlink escape),
and writes are lock-serialized so concurrent agents on one machine can't lose an append. (Sharing one
agent-memory/ across multiple hosts assumes unique hostnames — the usual single-machine setup is safe.)
Reach the team from chat (opt-in MCP). The same server also exposes an agent router, so from
your coding tool's chat you can see and reach the team in plain English: list_agents (your
actually installed roster + each role's purpose — it reads the install record, so a custom
--roles team routes correctly), agent_brief(role) (one agent's full spec, to act as it or brief a
subagent), route(task) (rank the installed agents that fit a task, then lay them onto Venom's
standard pass), and handoff(role, task) (hand back the agent's brief and log the delegation to
agent-memory/ so async work stays traceable). Honest scope: route is keyword/field-weighted
matching over the specs, not a model deciding — boss-1 is still the real router; this narrows the
field and never proposes an agent you didn't install. The MCP can't run an agent (it's a passive tool
provider); it hands the host the right persona and the host does the work.
Venom doesn't own the model's inference, so it can't make the model spend fewer tokens per call. What
it does, honestly, is three things: run the same work on cheaper models, keep the per-turn context
lean, and bound memory growth so a maturing project doesn't balloon the read path. Every number
below is measured from source by a rerunnable benchmark — npm run bench (writes
bench/token-savings.json) — using a char/4 token proxy and the directional prices in
core/model-rates.json. They're estimates for comparison, not a billing guarantee.
Measured on the web-app pack (14 agents, ~58k tokens of scaffolding per goal — a "goal" is modelled as
~14 agent turns, a 70%-of-team × 1.4-review-loop heuristic, so the absolute dollars scale with that):
| Lever | What it changes | Measured |
|---|---|---|
Model preset — venom models budget |
Same tokens, cheaper models | ~78% lower cost than the default preset (~$0.375 → ~$0.083 per goal); ~82% vs quality |
| Lean specs — the M2 trim | Per-turn context the agents read | Avg spec 7.8% smaller (2,219 → 2,046 tok), per-turn overhead ~4% — the specs were already tight, so this is modest and we don't inflate it |
Memory compaction — venom memory compact |
Hot read-path as the project grows | Scales with age: ~55% smaller at 50 log entries, ~96% at 550 (84.7k → 3.7k tok). Near-zero on a fresh project, large on a mature one. Byte-exact: archived + kept reconstruct the original, nothing lost |
So the numbers mean what they say:
- Cost, not inference tokens. The preset changes price, not token count.
budgetdrops every role a tier: heads and workers to Haiku-class, and the bosses and both review gates from Opus down to Sonnet — the 78% depends on that gate downshift, so it is not "cheaper with the gates untouched." If you want the correctness and security gates to stay on the strongest model, usebalanced(the default: bosses + gates on Opus, workers on Sonnet). The cost saving rests on evidence that a cheaper model holds up for extraction- and retrieval-style work; for code-heavy roles that's an extrapolation, so verify on your own work before trustingbudget— this is not a claim that all models are equal. - Compaction bounds what's read; it can't force selective reading. Venom doesn't control the
inference call — boss-1 (or you) runs
compactto keep the hot log lean. The read-path reduction is real and grows with project age. - char/4 is a proxy, and the compaction project is synthetic. The benchmark generates representative
log entries in the documented format (not a specific real project); the compaction % shifts somewhat with
entry size (the keep-ratio dominates, but larger entries push it higher), and a real tokenizer will
differ — so treat these as directional before/after comparisons, not exact figures. Run it yourself:
npm run bench. Regenerate any time — the numbers come from your checkout, not from us.
Venom is built to be extended:
- Add a pack — one entry in
core/packs.jsonreferencing existing roles. - Add a role — a portable spec in
core/agents/plus a manifest entry per adapter. - Add a tool adapter — one self-contained ESM module. Three ship today as reference
implementations:
adapters/claude-code,adapters/codex, andadapters/gemini.
See the wiring diagram in docs/ARCHITECTURE.md and the full steps in CONTRIBUTING.md.
git clone <this-repo> && cd venomkit
npm install # dev-only deps (TypeScript); the published package has zero runtime deps
npm test # builds, then runs the adapter + CLI test suites
npm run build # compile the CLI to dist/
npm run bench # rerun the token benchmark -> bench/token-savings.json (the "Token efficiency" numbers)MIT.