Skip to content
Docs menu

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.

View .md

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#123

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