Skip to content
Docs menu

The agent's tools

The tools the venom agent can call beyond reading, editing and running commands, when each is offered, what it can reach, and the tests it runs after edits.

View .md

Besides pi's built-in read, bash, edit and write (and grep, find, ls, off by default), venom gives the agent the tools below. Every call goes through the permission engine: read-only tools are allowed in every mode, including plan mode, and your deny rules still apply to them and to what they return. Tool output from outside (files, web pages, command output) is marked as untrusted content and scanned for prompt injection.

The tool list is fixed when a session starts, so the model's cached prompt prefix stays the same from turn to turn: a tool that only makes sense in some repositories is switched on once at start, or not at all. /context shows what the tools cost in the prompt; --tools and --exclude-tools change the set (see Flags).

Asking you

Tool What it does
ask_user Ask you one to four multiple-choice questions for decisions that are yours. You can always answer in your own words. With nobody to ask (print mode, an SDK host without an asker) it returns at once and tells the model to decide and state its assumption. venom serve sends it to its client as a question event.
todo The checklist the model keeps for multi-step work (see Plan mode).
task Delegate to a subagent (see The terminal UI).

Finding code

Tool When it is offered What it does
repo_map Any git work tree, with read active A map of the repository from a persistent index: files with their exported symbols, imports, importers and covering tests, filtered by path, lang (ts, go, python, rust), symbol, tests and limit (default 40, at most 200). Files rank by PageRank over the import graph. The index lives under ~/.venom/index/<repo hash>/ and only changed files are re-read.
code_search Large repositories (enough tracked files that rg gets slow), or any repository when the orchestrator has a local venom-embed route One tool with modes: map (start here), symbol (definitions), refs (uses), text (ranked files with lines), related (files tied by imports) and semantic (with embeddings). While the index builds, it falls back to rg. venom index builds the semantic index by hand.
find_references A workspace with files an installed language server handles Every use of a symbol, from its language server: scope-aware, unlike grep.
rename_symbol Same Rename a symbol and all its uses in every file through the language server. The rename is checked and approved as one apply_patch (every file as an edit, one approval) and written atomically; nothing is written when any file is refused or changed meanwhile.
recall Always Search this session's hidden tool outputs (masked by compaction or /forget) and compaction summaries for an exact value, name or error no longer in view, instead of re-running a command. Returns snippets with file and line range. Local, nothing written.
skill_search When skills are loaded Look up skills by name or topic; the system prompt lists skills compactly and the model reads a match's SKILL.md before following it. * lists them all.

VENOM_TOOL_DIRS (a PATH-style list) is searched first for language servers and formatters.

Knowing its limits

Tool What it does
capacity What the agent has left before it plans: the time, the context window and where compaction starts, this session's spend against its budget, your key's spend today and this month against its budgets with reset times, the last rate limit, and free subagent slots. The one network call is GET /v1/usage to your endpoint, cached for a minute.
tool_status Which tools work right now, why not, and the fix: a dropped MCP server, an unpaired browser extension, the permission mode, the sandbox, a missing secret. The tool list itself never changes mid-session; this answer does.
venom_tool_loadout Internal: never declared to the model. It keeps MCP and plugin tools behind tool_search once their schemas together pass a size threshold, so a session with many MCP servers doesn't pay for every schema on every request. The tools still run when called by name.

The web

Both web tools exist only when the session is online: --offline (or VENOM_OFFLINE=1) removes them.

Tool What it does
web_fetch GET an http(s) URL as text: HTML as Markdown without the page chrome, JSON indented, no JavaScript. A capped number of characters per call, offset reads on, find (a case-insensitive regex) returns only matching lines.
web_search Search the web: title, URL and snippet per result.

web_search tries its backends in order: the orchestrator's /v1/search (on by default), your SearxNG, Venom Search on the Venom Cloud you signed in to, Brave, Tavily, then DuckDuckGo (no key). Configure them in venom.yaml or the environment:

Key Environment What it does
search.orchestrator VENOM_SEARCH_ORCHESTRATOR on (default) asks the orchestrator first; off uses only the direct backends.
search.url VENOM_SEARCH_URL Your SearxNG, for example http://127.0.0.1:8888.
search.brave_key_env BRAVE_API_KEY by default The name of the variable holding the Brave Search key (never the key itself).
search.tavily_key_env TAVILY_API_KEY by default The same for Tavily.
search.rerank VENOM_SEARCH_RERANK on re-ranks results with the decision model; off by default.

From a project's venom.yaml, the search keys need the project to be trusted. SearxNG is metasearch: it queries public engines, so it is opt-in.

The browser

With Chrome, Chromium, Edge or Brave installed, the agent gets browser_navigate and, from its first call, the full set of browser tools (see Flags for --chrome and friends). Three of them:

Tool What it does
browser_parallel Run one task on several sites at once: each sub-task gets its own agent and browser window (at most 6 at a time) and replies with the fields you name; the result is one merged table with each tab's cost.
browser_replay Run a recorded browser script by name with no model calls. Record one with /browser record <name>; a step that fails hands the browser back to the model, and save_fix: true saves the fixed script. With no name it lists the scripts.
har Inspect a HAR network capture: list its entries or show one. Credentials, cookies and token-like values are redacted. Loaded with the browser tools.

Tests the change can affect

Tool or command What it does
test_impact Map the git diff to the tests it can affect and return the commands to run them: Go packages through the package graph, vitest through vitest related, pytest through the import graph; a changed manifest or config means that project's whole suite. Offered in git work trees with a Go module, a vitest package or a Python project. It runs nothing: the model runs the commands with bash, under the permission gate.
venom test-impact [<range> | --base <ref>] [--json] [--run] The same from the shell. <range> is a..b or a...b; --base maps the work tree against a ref (default HEAD: uncommitted and untracked files); --json prints the plan (venom.test-impact/v1); --run runs the commands, one project after another, unsandboxed like any command you type, and exits 1 if any fails.

Tests after edits. After a turn that changed files, venom runs the affected tests in the background while the model keeps working, and tells the model about failures at its next turn. Passing runs say nothing. The commands go through the permission engine: one your rules allow runs, one they would ask about is asked once per suite in a terminal (skipped headless), one they deny never runs. To have tests run unattended, allow the command, for example bash(go test:*). venom.yaml's tests keys set this up: tests.on_edit (auto or off), tests.max_seconds (default 60) and tests.flaky_after (default 3).

Flaky tests. A test that fails and then passes with no code change is recorded locally; after tests.flaky_after occurrences venom proposes an issue and files it only when you say yes. venom flaky lists them (see venom flaky).

Troubleshooting

Symptom Cause and fix
No web_search or web_fetch The session is offline (--offline, VENOM_OFFLINE=1, or offline mode switched on).
cannot reach the search backend at … VENOM_SEARCH_URL points at a SearxNG that isn't running.
SearxNG answers 403 Enable json under search.formats in its settings.yml.
No find_references No language server for the workspace's languages is installed, or not on PATH (VENOM_TOOL_DIRS).
A tool fails but is listed Ask the agent to call tool_status, or run venom doctor.