# Tools reference

The V3Code agent has a large set of built-in tools. Reads run automatically; anything that changes files, runs commands, or drives the browser asks for approval first (see [Modes → Approvals](/editor/modes)). This page is the reference for what actually ships.

## Files & search (read-only)

| Tool                                                            | Does                                                                    |
| --------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `read_file`                                                     | Read a file or line range, paginated, with a COMPLETE/TRUNCATED footer. |
| `ls_dir` · `get_dir_tree`                                       | List a directory / a shallow tree.                                      |
| `search_for_files` · `search_pathnames_only` · `search_in_file` | Full-text, filename, and in-file search.                                |
| `find_text`                                                     | Workspace text search with optional surrounding context lines.          |
| `read_lint_errors` · `get_build_errors`                         | Live language-server diagnostics for a file / the whole workspace.      |
| `read_skill`                                                    | Read an agent skill's full `SKILL.md` by name.                          |

## Edits (approval: edits)

| Tool                                              | Does                                                 |
| ------------------------------------------------- | ---------------------------------------------------- |
| `create_file_or_folder` · `delete_file_or_folder` | Create / delete files and folders.                   |
| `rewrite_file` · `append_file` · `edit_file`      | Replace, append to, or search-replace within a file. |
| `rename_symbol`                                   | LSP rename across the workspace.                     |

All edits pass through a shadow-workspace lint verify with rollback before hitting disk.

## Terminal, tests & sandbox (approval: terminal)

| Tool                                                                               | Does                                                                         |
| ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `run_command`                                                                      | One-shot command in a temp terminal (timeout 1–600s).                        |
| `open_persistent_terminal` · `run_persistent_command` · `kill_persistent_terminal` | Named background terminals. `read_terminal_output` reads them (no approval). |
| `run_tests`                                                                        | Run the workspace test runner.                                               |
| `run_sandbox`                                                                      | Run a JS/TS snippet in an isolated `node:vm`.                                |

## Git

Reads (`git_status`, `git_diff`, `git_log`, `git_branch`, `git_remote`, `git_show`, `git_blame`) are automatic. Writes (`git_stage`, `git_commit`, `git_push`, `git_pull`, `git_checkout`, `git_stash`, `git_merge`, `git_rebase`, `git_cherry_pick`, `git_restore`, `git_reset`) ask for approval. Hard reset is blocked.

## Context Bridge (structural intelligence)

`get_file_context`, `get_file_dependencies`, `get_symbol_context`, `get_call_graph`, `pack_context`, `get_project_briefing` — all read-only. See [Context Bridge](/editor/context-bridge) for details.

Notes: `remember` / `forget` (approval) and `list_notes` / `search_notes` (read).

## Search & recall

| Tool                                                          | Does                                                                        |
| ------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `semantic_search`                                             | Meaning-based code search over the [local index](/editor/semantic-index).   |
| `symbol_lookup` · `impact_trace`                              | Native symbol tags and change-impact tracing (when the sidecar is present). |
| `search_chat_memory` · `get_chat_session` · `get_chat_thread` | Search and read recorded chat memory.                                       |
| `deep_recall` · `get_shadow_record`                           | Break-glass search of the raw shadow archive.                               |
| `recent_edits` · `workspace_delta` · `session_diff`           | What you or the agent changed recently.                                     |
| `index_health`                                                | Semantic-index status, with optional re-scan.                               |

## Security review

| Tool            | Does                                                                                                                                                                                                                                                 |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `security_scan` | Reviews supported workspace source for suspicious data flows and compares possible findings with the previous scan journal. It helps the agent notice issues; it is not a complete security audit. See [Cyber Protection](/editor/cyber-protection). |

## Web & browser

`web_search` and `web_fetch` are read-only. `open_browser` opens an in-editor browser pane. The full Playwright automation suite (`open_browser_page`, `click_element`, `fill_form`, `run_playwright_code`, `reconstruct_page_sources`, `intercept_network`, session save/restore, …) drives real pages — the navigating/mutating ones ask for approval; reads like `read_page`, `screenshot_page`, and `get_browser_console_logs` are automatic. See [The browser](/studio/browser).

## Subagents, planning & image

| Tool              | Does                                                                                 |
| ----------------- | ------------------------------------------------------------------------------------ |
| `launch_subagent` | Background, fire-and-forget subagent; result is injected back into the thread later. |
| `run_subagent`    | Synchronous delegation that blocks and returns a result.                             |
| `update_plan`     | The agent's per-thread todo list (persists in `.v3code/active-plan.json`).           |
| `ask_user`        | Ask you a multiple-choice question.                                                  |
| `generate_image`  | Generate an image (Grok / xAI) into the workspace (approval: edits).                 |