---
title: The agent's tools
description: 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.
section: cli
order: 90
audience: [user, builder, agent]
sources: [packages/harness/src/extensions/ask.ts, packages/harness/src/extensions/capacity.ts, packages/harness/src/extensions/code-search.ts, packages/harness/src/extensions/repo-map.ts, packages/harness/src/extensions/lsp-symbols.ts, packages/harness/src/extensions/recall.ts, packages/harness/src/extensions/tool-status.ts, packages/harness/src/extensions/lazy-tools.ts, packages/harness/src/extensions/net-capture.ts, packages/harness/src/extensions/browser-tasks.ts, packages/harness/src/extensions/browser-parallel.ts, packages/harness/src/extensions/web.ts, packages/harness/src/extensions/test-impact.ts, packages/harness/src/compat/skills.ts, docs/test-watch.md]
features: [cli.tool-ask-user, cli.tool-browser-parallel, cli.tool-browser-replay, cli.tool-capacity, cli.tool-code-search, cli.tool-find-references, cli.tool-har, cli.tool-recall, cli.tool-rename-symbol, cli.tool-repo-map, cli.tool-skill-search, cli.tool-tool-status, cli.tool-venom-tool-loadout, cli.web, cli.test-impact, cli.test-watch]
---

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](/docs/cli/flags.md#resources)).

## Asking you {#ask-user}

| 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](/docs/cli/plan-mode.md#tools)). |
| `task` | Delegate to a subagent (see [The terminal UI](/docs/cli/tui.md#agents-panel)). |

## Finding code {#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 {#capacity}

| 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 {#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](/docs/cloud/search.md#from-the-cli) 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 {#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](/docs/cli/flags.md#tools) 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 {#test-impact}

| 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](/docs/cli/insight-commands.md#flaky)).

## Troubleshooting {#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`. |
