Cost, health and routing commands
The venom subcommands that check the setup and explain spend, routing, tool errors, wasted tokens, flaky tests and local models.
These commands run outside a session and print a report; most have a slash command that shows the same inside one. All take --json for one machine-readable object (see Print, JSON and RPC modes).
venom doctor # is the setup right?
venom cost week --by model # what did I spend, on what?
venom explain-cost latest # why did that session cost so much?
venom routes --window 1h # where did my requests go?
venom diet # where do my sessions waste tokens?venom doctor
Checks the environment, the endpoint and key, the models and their context windows, the OS sandbox, what the current project loads and where your prompts go. Each line is PASS, WARN or FAIL with a fix. Exit 1 when a required check fails.
| Option | What it does |
|---|---|
--only <sections> |
Run only these sections (comma-separated): policy, environment, cloud, orchestrator, probe, browser, sandbox, project, sovereignty. Only their required checks set the exit code. |
--probe |
Also send the default model two tiny requests: a chat (time to first token) and a structured tool call. Costs a request. |
--model <id> |
The model to probe (default VENOM_MODEL, then settings.json's defaultModel, then venom-default). |
--fix |
After the report, offer a fix for each check venom can repair, asking before each; prints the steps it can't take. |
--yes, -y |
With --fix: apply every fix without asking. |
--check-update |
Also read the latest release's version from GitHub (one small request; off by default). |
--json |
Machine-readable output. |
venom cost
venom cost # today, last 7 days, this month, then this month in detail
venom cost week --by gear
venom cost --task owner/repo#123venom cost [today|week|month|<n>d|YYYY-MM-DD] [--by <dim>] [--task <ref>] [--json] shows your spend today, over the last 7 days and this month, then the window (default this month) by gear, model (requested and served), role, task and the costliest sessions, with what the prompt cache saved and the partial responses (the client went away). Days are UTC.
| Option | What it does |
|---|---|
--by <dim> |
One breakdown: gear, model, role, day, session, project (the budget envelope's tag, x-venom-project or VENOM_PROJECT), task (the pull request, issue or tracker key: venom --task, the branch, the pull request venom opened) or outcome ($ per merged pull request, closed issue and passing test run, from GitHub through gh). |
--task <ref> |
Only one task: a pull request or issue URL, owner/repo#123, ENG-142. |
--since <t> |
The window: today, week, month, 30d or a UTC day. |
--json |
One object, {"type":"cost",…}. |
The rows come from Venom Cloud (GET /v1/usage/summary for VENOM_API_KEY) when VENOM_BASE_URL is a cloud; with the Go orchestrator or offline, from this machine's saved sessions at the bundled list prices, with the orchestrator's own totals beside them when it answers. In a session, /cost is this session's tokens and cost and /cost today|week|month [--by …] the same view as the command.
venom usage
venom usage [--json] [--session <id>]: spend and budgets for your key at VENOM_BASE_URL: today, the last 7 days and this month by model, the key's daily and monthly budgets with their reset times, today's costliest sessions, and one session with --session (its subagents rolled in). /usage shows the same for the running session.
venom explain-cost
venom explain-cost [session] [--json] [--offline]: why a session cost what it did, turn by turn: where the money went (main agent, subagents, summaries, side requests), the costliest turns, prompt-cache churn and its causes, tool outputs that weighed on later requests, reasoning tokens, the exploration the repo map saved, and tips with the numbers behind them. Priced at list price from the session's records; the orchestrator's figure is added when it answers (GET /v1/usage), unless --offline. session is an id, a prefix or latest (default: the newest in this directory). /explain-cost explains the session you are in.
venom diet
venom diet [--session <id|latest>] [--all] [--days <n>] [--json]: the biggest sources of avoidable tokens in this repository's saved sessions, each with a fix: files read again unchanged, large tool outputs re-sent on later requests, prompt-cache churn, a heavy start (system prompt, skills, MCP tool lists) and context left to grow past 150k tokens. --session looks at one session, --all at every directory, --days sets the window (default 7). Nothing leaves the machine.
venom stats tools
venom stats tools [--days <n>] [--model <m>] [--all] [--json]: per model and tool, from this repository's saved sessions: calls, error rate, the most common error kinds and p50/p95 output tokens. edit and apply_patch failures are split into no match, multiple matches and stale read. --days (default 7), --model (models whose name contains it), --all (every directory). Offline.
venom forecast
venom forecast "<task>" [--gear <name>] [--since 90d] [--json]: what a task will likely take on each gear, in tokens and dollars (p50 and p90), from the most similar tasks in your saved sessions. A gear with enough sessions of its own is measured on them; otherwise the similar tasks' sizes are priced at the gear's model. --gear limits it to one gear, --since sets the history (default 90 days). Nothing is sent to a model. venom do --forecast prints the same for a background run.
venom routes
venom routes [--window 1h|24h|7d] [--alias <a,b>] [--json]: where the orchestrator sent your requests, and why: per alias, its targets in order with their live state (ok, cooling down, circuit open, disabled), the share each served, p50 latency and time to first token, fallbacks by reason, and the latest fallbacks. --window takes any duration up to 31 days (default 24h); --json prints the orchestrator's GET /v1/routing answer. /routes [window] [alias] shows the same in a session.
venom flaky
| Command | What it does |
|---|---|
venom flaky [list] [--all] [--json] |
This repository's flaky tests, most flaky first (--all: every repository). |
venom flaky issue <n|text> [--yes] |
Show the issue it would file, ask, then run gh issue create. |
venom flaky dismiss <n|text> |
Stop proposing an issue for it. |
venom flaky clear [<n|text>] |
Forget one test, or all of this repository's. |
A flaky test is one that failed and then passed on a rerun with no code change, seen while venom ran tests in your sessions. The record is local (~/.venom/flaky/). After tests.flaky_after occurrences (default 3) venom proposes an issue; it never files one itself.
venom models
This machine's local models, through the orchestrator's admin API (VENOM_ORCH_URL, default http://127.0.0.1:8787, with VENOM_ADMIN_TOKEN).
| Command | What it does |
|---|---|
venom models [status] |
Hardware, backends, which model serves venom-default and venom-fast, strain, pulls in progress. |
venom models list [--all] |
Models for this machine: fit, memory, tokens/s, tool support, installed. --all adds ones too big for it and vLLM models. |
venom models pull <tag> [--use default|fast] |
Download an Ollama model (qwen3:14b, hf.co/<repo>:<quant>) with a progress bar. |
venom models use <tag> [--fast] |
Serve venom-default (or venom-fast with --fast) with it; pulls it first when needed. |
venom models setup |
The recommended default and fast models for this machine, pulled and selected. |
venom models rm <tag>, venom models unload <tag> |
Delete a model from Ollama; free the VRAM a loaded model holds. |
venom models gears [--window 7d] |
Per gear, what its main model measured on your requests: p50 latency, error rate, $/request. |
venom models local suggest [--days 7] [--gpu-usd-per-hour X] |
Which cloud requests of the side roles a local model could serve, with the weekly saving. |
ctrl+c during a pull stops watching; the pull goes on in the orchestrator.
Troubleshooting
| Symptom | Cause and fix |
|---|---|
venom doctor FAILs on the endpoint |
VENOM_BASE_URL must include /v1 and be reachable; run with --only orchestrator to see just that. |
venom cost shows "local" figures |
The endpoint is not a Venom Cloud, or it didn't answer; the figures are estimates at list price. |
venom routes or venom models gets 401 |
Your key or VENOM_ADMIN_TOKEN doesn't match the orchestrator's. |
venom flaky issue fails |
gh isn't installed or signed in. |