Project setup, memory and onboarding commands
Set a project up for venom, keep its memory, index its code, and help new people learn a codebase with tours, explanations and answers that cite their sources.
venom init # AGENTS.md and starter permission rules for this project
venom explain src/billing # an onboarding tour of one module
venom tour --dry-run # plan and cost of an architecture tour
venom ask "how do refunds work?" # an answer with its sources
venom memory # what venom remembers about this projectvenom init
venom init [--yes] [--dry-run] [--no-permissions] [--model <id>] [instructions…] analyses the project (read-only) and writes a short AGENTS.md: commands, layout, gotchas. An existing AGENTS.md is refined; a project with only CLAUDE.md gets that refined. It also proposes .venom/permissions.json allow rules for the test, build and lint commands it found, and .gitignore entries for venom's local state.
| Option | What it does |
|---|---|
--yes, -y |
Accept the proposals without asking. An existing memory file is not overwritten: the proposal goes to <name>.venom-proposed. |
--dry-run, -n |
Print what would be written; write nothing. |
--no-permissions |
Don't propose .venom/permissions.json. |
--model <id> |
The model for the analysis (default VENOM_MODEL, then venom-default). |
instructions… |
Extra guidance, for example "focus on the API package". |
In a terminal each file's diff is shown and you choose; without one, nothing is written unless --yes. /init in a session does the same.
venom explain
venom explain <path> [--refresh] [--model <id>] [--json] writes an onboarding tour of one module: what it is for, its entry points, key types, how data flows through it, where its tests are, and the gotchas. A read-only agent writes it (it reads files, never edits). The result is cached in ~/.venom/explain until a tracked file under <path> changes; --refresh writes a new one anyway. --json prints {ok, path, hash, cached, model, createdAt, files, text}.
venom tour
venom tour [path] [--out <file> | --print] [--gear <name> | --model <id>] [--max-usd <n>] [--exclude <dir>] [--dry-run] [--full] [--json] writes an architecture tour for new joiners from the repo map and the repository's docs: components, entry points, data flow, how to run and test, key files, with mermaid diagrams. It goes to docs/TOUR.md (or <path>/TOUR.md) and is regenerated incrementally: only the parts whose facts changed go back to the model.
| Option | Default | What it does |
|---|---|---|
path |
the whole repository | A directory to tour. |
--out <file> |
docs/TOUR.md |
Write here instead. |
--print |
off | Print the tour; write nothing. |
--gear <name> |
normal |
The gear whose smart tier writes the prose. |
--model <id> |
none | A model instead of a gear's. |
--max-usd <n> |
0.5 |
Stop before a request that would pass this spend. A local model with no list price costs nothing. |
--dry-run |
off | The plan and the cost estimate; nothing is sent or written. |
--full |
off | Regenerate every part. |
--exclude <dir> |
none | Leave a directory out (repeatable); fixtures, vendor, dist and node_modules always are. |
--json |
off | Machine-readable result. |
The facts are gathered locally with no model, and the text sent to the model is secret-scrubbed. Exit 0 on a tour, 1 when nothing could be toured or the cap stopped it early, 2 on usage.
venom ask
venom ask "<question>" [--cloud-only | --local-only] [--gear <name>] [--json] answers a question from what your team knows, with the sources cited: your organisation's memory, team library and the session summaries you may open on Venom Cloud (needs venom cloud login), and the markdown docs of this checkout (README, docs/, docs/TOUR.md).
| Option | What it does |
|---|---|
--cloud-only |
Send no passages from this checkout. |
--local-only |
Call nothing: print the best matching passages of this checkout. |
--gear <name> |
Answer with this gear's summary model (default: your organisation's default gear). |
--json |
Print the answer as JSON. |
The answer comes from the summary model, so it is cheap, and a question nothing matches costs nothing. The same works in Slack (/venom ask) and on the console's Ask page.
venom onboard
| Command | What it does |
|---|---|
venom onboard [list] [--path <name>] [--json] |
Your organisation's first tasks for new members, and where you are. |
venom onboard next [--path <name>] |
Start the next step. |
venom onboard done <step>, venom onboard undo <step> |
Mark a step you do by hand (reading the tour) done, or take it back. |
The steps run on your own repositories (read the tour, run the tests, fix a good first issue, ship a small PR) and tick themselves when the work shows up: a finished session, a session that changed files, a merged pull request. Pull request and issue steps need tasks.lookup: gh in venom.yaml. --path picks one of your organisation's onboarding paths. Needs venom cloud login.
Memory
venom keeps a project's auto-memory: a MEMORY.md index of typed memory files, loaded into each session's prompt, which the agent reads and writes with its memory tool (actions list, read, save, update, delete, verify, prune, sync, propose; scopes me, team, org). Claude Code's memory for the same project is read too.
| Command | What it does |
|---|---|
venom memory [list] |
This project's memories: venom's, then Claude Code's (read-only). |
venom memory show <name> |
One memory file. |
venom memory edit <name> |
Open it in $EDITOR (a Claude Code memory is copied to venom's directory first). |
venom memory rm <name> [--yes] |
Delete one of venom's memories. |
venom memory path |
Where the memory files are. |
venom memory sync [--base <ref>] [--apply] [--commit] [--pr <n>] [--check] [--json] |
Which AGENTS.md/CLAUDE.md updates the branch's change needs. --apply makes the edits with the model, --commit commits them, --pr <n> puts a "Memory updates" section in that pull request, --check exits 1 while an update is pending. |
venom memory org [refresh] [--json] |
Your organisation's approved facts from Venom Cloud. |
venom memory propose "<fact>" [--team | --repo] |
Propose a fact to your organisation; an admin approves it in the console. --team scopes it to your key's key group, --repo to this repository. |
In a session: /memory [show|edit|forget|path] <name>, /memory org, /memory propose <fact>, and /memory-sync.
| Key | Default | What it does |
|---|---|---|
memory.auto |
on |
off: no index in the prompt, no memory tool, no /memory. |
memory.dir |
~/.venom/projects/<slug>/memory |
Where the memory files go (absolute, ~/… or relative to the project root). From a project file it needs the project to be trusted. |
memory.max_index_lines |
200 |
Index lines loaded into the prompt (at most 12 KiB either way). |
memory.org_dir |
none | A shared directory of organisation-wide memory every machine reads. Team memory needs no setting: it is <project>/.venom/memory, committed to git. |
venom index
venom index [--status | --query <text> [--limit <n>]] [--json] manages the semantic code index of this git work tree (.venom/index/), which the agent's code_search uses in its semantic mode. With no flags it brings the index up to date (only changed files are re-read and only new chunks embedded); --status shows what is stored and the embedding model; --query prints the nearest chunks (--limit, default 10). Embeddings come from the orchestrator's venom-embed route, and only when every target of that route is local; without it the command says so and exits 1, and the agent searches with grep.
venom lessons
| Command | What it does |
|---|---|
venom lessons [list] [--all] [--json] |
The lessons this project learned from closed tasks, best supported first (--all: rejected ones too). |
venom lessons show <id> |
One lesson with its evidence. |
venom lessons reject <id> |
Keep it out of the prompt from the next session. |
Each lesson has a cue, an action and the evidence behind it. Lessons load into the system prompt at the next session start as guidance, never as a permission. The record is local: .venom/lessons.json.
Troubleshooting
| Symptom | Cause and fix |
|---|---|
venom init wrote nothing |
No terminal to choose in: add --yes, or --dry-run to see the proposal. |
venom tour stops early |
--max-usd was reached; raise it, or --dry-run for the estimate. |
venom ask uses only local docs |
Not signed in to Venom Cloud (venom cloud login). |
venom index exits 1 |
The orchestrator has no all-local venom-embed route. |