Skip to content
Docs menu

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.

View .md
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 project

venom 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.