Tools reference

Tools are the actions Claude can take: read a file, run a command, search the web, start a subagent. You rarely invoke them yourself, but you name them constantly, in permission rules, subagent tool lists, skill frontmatter and hook matchers. This page gives the exact names and explains how each tool behaves, so that when Claude does something surprising you can see why.

To add new tools, connect an MCP server. Skills do not add tools; they run through the existing Skill tool.

The full list

The Prompts? column describes Manual (default) permission mode for paths inside your working directories. Three caveats:

• In auto mode a classifier makes most of these decisions instead of you.
• File tools marked "No", such as Read, still prompt for paths outside your working and additional directories.
• Bash is "Yes", but a built-in list of read-only commands runs without asking (see Permissions).

Files and code

Shell and processes

Agents, planning and coordination

Web

Scheduling, notifications and sharing

MCP plumbing

Ask Claude "what tools do you have?" for a conversational list in a running session, and use /mcp for exact MCP tool names. The advisor is a server-side API tool, not a Claude Code tool, so it has no name you can use in rules or matchers.

Naming tools in rules and hooks

Tool names appear in permissions.allow and permissions.deny (and /permissions), the --allowedTools and --disallowedTools flags, the Agent SDK's allowedTools and disallowedTools, a skill's allowed-tools frontmatter, and a hook's if condition. All use the form ToolName(specifier), where the specifier format depends on the tool:

Tools not in that table (such as ExitPlanMode) take only the bare name. Pattern rules are explained on Permissions.

Two interactions to know:

• An Edit(...) allow also grants read access to the same paths.
• A Read(...) deny also blocks Edit and Write there, including creating new files, since both need to read back what they change (edits from v2.1.208, writes from v2.1.228).

Hook matcher fields use bare tool names, not the parenthesised form; see Hooks for matcher syntax and each tool's tool_input fields.

Agent

Agent starts a subagent in a fresh context window. It works autonomously and returns only its final result; the parent never sees its intermediate calls. Under agent teams, an Agent call with a name can start a teammate instead, which reports through team messages.

• Turn limit. Set maxTurns in the subagent definition. Hitting it marks the result as partial, and Claude can resume the subagent to continue.
• Forks. Where fork mode is on, the same tool starts forked subagents, which inherit the whole conversation, usually run in the background, and still raise permission prompts in your terminal.

Which tools a non-fork subagent gets depends on its tools and disallowedTools:

Tools never available to subagents are never granted, whatever the list says, and SubagentHandback is added automatically where its conditions apply. If none of a tools list matches anything usable, the call usually fails with an error naming the entries (see Errors).

Starting a subagent does not prompt; its own tool calls are checked against your rules as it runs. Subagents run in the background by default except in certain cases. Foreground subagents prompt exactly as the main conversation does. Background ones surface prompts in your main session, labelled with the subagent's name, and Esc denies just that one call. To limit reach up front, narrow tools (dropping Bash, for instance) or use deny rules. See Subagents.

AskUserQuestion

Claude uses it to put a decision to you as multiple choice. Pick an option, or type your own answer via Other or the notes field; typed answers are relayed neutrally so Claude follows them literally, including "wait" or "explain first".

Questions stay open until answered. To let unanswered questions eventually close, set askUserQuestionTimeout to 60s, 5m or 10m (in user settings or Question auto-continue timeout in /config). On timeout, any selected options are submitted and Claude is told you may be away, so it proceeds on its own judgement and may ask again later. A countdown shows for the last 20 seconds, any key restarts the timer, and the timer pauses while the terminal reports its window as focused. It never runs in background sessions, screen reader mode or under Remote Control, and permission prompts (plan approval included) never auto-resolve.

Bash

Each command runs in its own process.

What carries over between commands

• Working directory. A cd in the main session persists to later commands as long as it stays inside the project or an additional directory. Leave those and the shell resets to the project, adding Shell cwd was reset to <dir> to the result. Subagents never carry cd over. CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1 makes every command start in the project.
• Environment variables do not persist: an export disappears after its command.
• Aliases and functions do: at start-up Claude Code sources ~/.zshrc, ~/.bashrc or ~/.profile and applies the resulting aliases, functions and shell options to every command.

Activate virtualenvs or conda environments before launching. For persistent variables, point CLAUDE_ENV_FILE at a script before launching, or fill it from a SessionStart hook (see Hooks).

Timeouts

Claude picks per-command timeouts itself via the timeout parameter. Two variables shape what it can choose for foreground commands:

• BASH_DEFAULT_TIMEOUT_MS: used when Claude passes no timeout. Default two minutes.
• BASH_MAX_TIMEOUT_MS: caps what Claude can request; the effective ceiling is the larger of this and the default. Default ten minutes.

PowerShell reads the same two variables. For background commands in time-limited sessions, timeout instead sets how long it may run in the background.

Output

Output streams to a working file as the command runs; more than 5 GB kills it. What Claude sees depends on whether the result counts as a failure:

Exit code 1 counts as success only for commands where it is benign: grep, rg, egrep, fgrep, find, diff, test, [, git diff and git grep. Others (pgrep, jq -e, cmp) count as failures even though exit 1 is informational for them.

• BASH_MAX_OUTPUT_LENGTH sets the read-back window (default 30,000, ceiling 150,000). Useful for long build logs. It does not raise the inline ceiling.
• The bashOutputMaxChars setting (v2.1.261) sizes both the inline ceiling and read-back window for successful results, up to 128,000, and when set, BASH_MAX_OUTPUT_LENGTH is ignored.

Background commands

For dev servers and watchers, Claude sets run_in_background: true and carries on. Manage them with /tasks; once you stop one there (or from a connected client such as the desktop app) Claude, or the subagent that started it, moves on.

When they stop. A command started by a foreground subagent ends with that subagent's run. Ones started by the main conversation or a background subagent keep running after a final response until they exit, are stopped, or hit a time limit. In -p runs, background commands end shortly after the final result (see Headless).

Time limits. In unattended sessions (-p, Agent SDK apps, CI, cloud) background Bash and PowerShell commands are limited; local sessions you drive from a terminal, the desktop app or VS Code are not (the limit exists from v2.1.285 and has been unattended-only since v2.1.288). A command started in the background gets 30 minutes, or its timeout, up to 2 hours. A command moved to the background gets 30 minutes from the move. At the limit it is stopped with Background command "<description>" was stopped after reaching its background time limit, and Claude can restart it with a longer timeout.

To raise the limits (they can only go up): BASH_DEFAULT_TIMEOUT_MS above 1800000 replaces the 30-minute default; BASH_MAX_TIMEOUT_MS above 7200000 (or a default above that) raises the 2-hour maximum.

Auto-backgrounding. A foreground command that reaches its timeout is moved to the background instead of being killed, unless it starts with sleep. The result says so, as in Command did not complete within its 120s timeout and was moved to the background, with the task id and output path. Any cd, pushd, popd or chdir inside a moved command does not carry over, and the result says the session directory is unchanged. CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 and bare mode disable this, so commands stop at their timeout.

Memory cap on Linux and WSL

CLAUDE_CODE_TOOL_MEMORY_LIMIT=4G (v2.1.233) caps the combined memory of the session's Bash, PowerShell and Monitor commands (Monitor included from v2.1.246) using a memory cgroup, so a runaway build cannot starve the session.

• Sizes are bytes or use K, M, G, T. 0, off, false, no or none disables it; unreadable values such as 4e9 are ignored.
• If the cgroup cannot be set up, commands run uncapped and claude --debug explains why.
• The outcome is fixed for the process lifetime; relaunch to apply changes.
• When the cap is exceeded, the kernel kills a command and nothing in its result mentions the cap.

CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE (v2.1.246) lists other process kinds to exempt: mcp, lsp, hooks, plugin, helper (Claude Code's own helpers such as git) and agent (child Claude Code processes such as teammates). none caps everything; all-new caps only Bash, PowerShell and Monitor. Unknown names are ignored. If unset, the set of capped kinds comes from server-delivered configuration and may change, so set it if you need stability. Hooks that can block or change an action, and MCP servers they call, are always exempt, so the kernel can never kill a gatekeeper and accidentally allow what it was blocking.

Edit

Exact string replacement: an old_string becomes a new_string. No regex, no fuzzy matching.

A path matched by a Read deny rule is refused outright, including new files (v2.1.208). Otherwise three checks apply:

1. Read first. Claude must have read the file in this conversation, and a read cut short with a PARTIAL view notice does not count. Opus 4.6, Haiku 4.5 and older always require it; newer models may edit an unread file if reading it would not need a prompt and Read is available.
2. Exact match, down to whitespace and indentation.
3. Unique match. If old_string appears more than once, Claude adds context until it is unique, or sets replace_all: true.

A file changed on disk since Claude read it can still be edited if old_string matches the current content exactly and once, and the file can be read without prompting; the result notes the outside changes so Claude re-reads before dependent edits. Otherwise Claude re-reads first. (Before v2.1.208, any unread or externally changed file was refused.)

Viewing a single file with cat, nl, bat, batcat, head, tail, sed -n 'X,Yp', grep, egrep, fgrep or rg, with no pipes or redirects, also counts as reading it for this purpose. That affects eligibility only, not permissions.

EndConversation

This tool ends the session, and Claude uses it only as a last resort against sustained abuse after redirection and a clear warning have failed, or when you explicitly ask for a demonstration and confirm. Frustration, swearing, a task going badly or harmful requests (which Claude simply declines) do not qualify. It mirrors claude.ai's ability to end a small subset of chats.

After it fires, the session is locked: prompts and most commands return Claude ended this conversation. Start a new session (or /clear) to continue., and only /clear, /resume, /help, /exit and /feedback work. The lock is recorded in the transcript, so resuming keeps it (history is not deleted), and resuming an ended session with -p exits with code 1.

It never prompts and PreToolUse hooks do not run for it. Deny and ask rules naming it, --disallowedTools and --tools cannot remove it while any other tool remains, because a safeguard the session can switch off is no safeguard. If your rules remove every other tool and also match it (as "*" does), it is removed too, unless an allow rule names it explicitly. Subagents never get it; background tasks may see it but calling it ends nothing.

It only exists when all of these hold: v2.1.213 or later; a model of Opus 4.8, Sonnet 5, Fable 5 or later in those families; an interactive terminal session (including a claude session in an IDE terminal, as JetBrains uses), so not -p, the Agent SDK, the VS Code panel, GitHub Actions or cloud sessions; not --bare; and not on Bedrock, Claude Platform on AWS, Agent Platform, Foundry or a cloud gateway.

Glob and Grep

On Windows both tools are in the default set. On macOS, Linux and WSL they are left out, and Claude searches with find and grep through Bash instead. In Claude's shell those run embedded bfs and ugrep, and they reach your hooks and rules as Bash calls.

They come back on those platforms when:

• you name Glob or Grep in --tools (you get what you list) or --allowedTools (naming either restores both), or the SDK equivalents. Settings-file allow rules do not count;
• Bash is removed from the session by a deny rule, --disallowedTools or --restricted;
• a subagent lists them in tools without Bash (for that subagent, or for the session if it runs as the main agent via --agent).

Permission is decided before Claude Code checks whether the search path exists, so a prompt for a path does not prove it exists.

Glob uses standard glob syntax: **/*.mdx, app/**/page.tsx, *.{yml,yaml}. Results are sorted by modification time and capped at 100, with a truncation flag if hit. It does not respect .gitignore by default; set CLAUDE_CODE_GLOB_NO_IGNORE=false to change that. Null bytes in pattern or path return an error.

Grep uses ripgrep's regex syntax, so metacharacters need escaping: to find map[string]any{} you need map\[string\]any\{\}. Patterns, globs or types ripgrep rejects return its diagnostic as an error (before v2.1.208, they wrongly returned No files found). It respects .gitignore; to search an ignored file, pass its path. Output modes:

• files_with_matches (default): paths only.
• content: matching lines with file and line numbers. An offset past the last match returns No entries at this offset.
• count: per-file counts plus a total that covers every match, even when head_limit or offset truncate the list.

Claude can filter with glob (**/*.vue) or type (py, rust), and match across lines with multiline: true.

LSP

Once you install a code intelligence plugin for your language (and the server binary itself), the LSP tool reports type errors and warnings after every edit, so Claude fixes them without a separate build, and Claude can call it to jump to definitions, find references, get type information, list a file's symbols, search workspace symbols, find implementations and trace call hierarchies. It is inactive without a plugin, inactive in cloud sessions, and returns an error for files whose server cannot start.

Monitor

Monitor lets Claude watch something and react without pausing the conversation: tail a log for errors, poll CI until a job changes state, watch a folder, follow a long script, or listen to a WebSocket. Usually Claude writes a small script, runs it in the background and gets each output line as an event, interjecting when something happens.

• Each watch has a deadline: 5 minutes by default, 30 at most, and 10 at most in a single-prompt -p run. At the deadline Claude gets one notice and can restart the watch.
• Stop it by asking Claude, or by ending the session. Stopping a subagent from /tasks stops its monitors.
• Command watches use Bash permission rules. In auto mode, allow rules naming Monitor are set aside like other broad allow rules so the classifier reviews each command.
• Not available on Bedrock, Agent Platform or Foundry, when DISABLE_TELEMETRY or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC is set, or on Windows without Git Bash.

Plugins can declare monitors that start automatically; see Plugin components.

WebSocket watches

Instead of command, a watch can take a ws input (never both):

Each text message becomes one event, even if multi-line. Binary frames arrive as a placeholder like [binary frame, 512 bytes]. A message over 1 MiB ends the watch (so subscribe to a filtered feed if you can), and a socket close ends it with the close code. timeout_ms applies, and TaskStop ends it early.

Opening a socket prompts (or is decided by the classifier in auto mode), with no "don't ask again for this host" option. URLs resolving to private, link-local or cloud metadata addresses are denied, as are hosts in sandbox.network.deniedDomains, and with allowManagedDomainsOnly in managed settings, anything outside the managed allowlist.

NotebookEdit

Edits one Jupyter cell at a time by cell_id, never by string replacement. Modes: replace (default) overwrites the cell; insert adds a cell after the target, or at the start if no id is given, and needs cell_type of code or markdown; delete removes it. Rules use Edit(...) paths, so Edit(analysis/**) covers notebooks there.

PowerShell

Runs PowerShell commands natively rather than via Git Bash.

{
  "env": { "CLAUDE_CODE_USE_POWERSHELL_TOOL": "1" }
}

On Windows it prefers pwsh.exe and falls back to powershell.exe (5.1), and PowerShell becomes Claude's primary shell, with Bash still available for POSIX scripts if Git Bash is installed. It starts with -ExecutionPolicy Bypass at process scope, so scripts and modules work on default installs without touching machine policy; Group Policy still applies, and CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1 honours the effective policy instead.

PreToolUse hooks receive the command in tool_input.command like Bash; match Bash|PowerShell in shell-inspecting hooks.

Bash deny rules switch PowerShell off. On Windows with Git Bash, any Bash deny rule (scoped like Bash(git push *) or bare) disables the PowerShell tool for the session without warning, because Bash rules do not govern PowerShell and Claude could otherwise do there what you denied. Keep PowerShell by setting CLAUDE_CODE_USE_POWERSHELL_TOOL=1 or adding a scoped PowerShell(...) rule. A rule removing all of Bash leaves no shell at all.

Other shell settings: "defaultShell": "powershell" routes your ! commands through PowerShell (needs the tool); "shell": "powershell" on a command hook runs that hook in PowerShell regardless; shell: powershell in skill frontmatter runs its !`command` blocks in PowerShell (needs the tool). The Bash working-directory rules, including CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR, apply here too.

Exit codes treated as non-failures: 1 from grep, rg, egrep, fgrep, findstr and git grep (no matches) and from git diff (differences); robocopy 0 to 7. From v2.1.214 on Windows, exit 1 from where.exe, fc.exe and diff.exe is a valid negative answer when the command printed output (silenced forms like where.exe /Q still count as failures); > and >> write UTF-8 on 5.1; piped stdin to native commands is UTF-8; error output has no ANSI escapes; and a child waiting on stdin gets end-of-file rather than hanging.

Preview limitations: profiles are not loaded, and sandboxing is unsupported on Windows.

Read

Returns a file with line numbers; Claude always uses absolute paths.

• A whole-file read over the token limit returns the first page with a PARTIAL view notice explaining how to continue with offset and limit. An explicit offset or limit that is still too large is an error.
• With an explicit limit, reading stops as soon as the range cannot possibly fit and errors, suggesting a smaller range or Grep for gigantic single lines (from v2.1.208, which fixed out-of-memory crashes on huge lines).
• Empty files return a notice saying so; an offset past the end reports the line count.
• Directories are not readable; Claude uses ls.

Beyond text:

• Images come back as visual content. Large ones are resized and recompressed; anything still over 500 KB is re-encoded as reduced-quality JPEG at the same dimensions. For fine detail, ask Claude to crop first (ImageMagick via Bash, say).
• PDFs under about 10 pages are read whole; longer ones in ranges via pages (e.g. "3-8"), at most 20 pages at once. Ranges need pdftoppm from poppler (brew install poppler, apt-get install poppler-utils, or a poppler build on PATH for Windows), otherwise you get pdftoppm is not installed.
• Notebooks return every cell with outputs. Files over 100 MB are refused with advice on reading a slice via the shell.

SendFeedback

From v2.1.238 Claude can draft feedback about Claude Code itself (when something keeps failing, when it cannot help, when a mistake is pointed out, or when you ask) and queue it under ~/.claude/feedback/drafts/. Nothing is sent until you choose.

A card appears above the prompt: 1 reviews, 2 twice sends as written, 0 dismisses (the draft stays queued). After a dismissal you are asked whether to turn the feature off, until you have declined twice. At most three cards appear per session by default (server-adjustable); after that, or with feedbackDrafts: "quiet", you just see a count in the footer.

/feedback with no argument opens the queue across all sessions. There you can edit title, area and details; choose Send transcript yes or no (it defaults to yes when the session's transcript is still available); and send, discard or keep. w opens the normal feedback dialog. Sending uses the same path and retention as /feedback (see Data usage) and deletes the local draft; it includes your text, environment details (version, OS, model), recent API request ids, and the transcript only if you left it on in review. Sending from the card never includes the transcript, and your working directory is never sent.

Drafts expire after 30 days or cleanupPeriodDays if shorter; the queue holds 10, dropping the oldest. /exit with this session's drafts still queued asks whether to review or discard them.

Turn it off with Claude-drafted feedback in /config (writes feedbackDrafts) or CLAUDE_CODE_SEND_FEEDBACK=0 for a session; admins can set feedbackDrafts in managed settings. It is absent from -p, SDK and cloud sessions, third-party providers, sessions with DISABLE_FEEDBACK_COMMAND=1, any non-empty CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC or no feature-flag fetching, and organisations that disabled product feedback, use Zero Data Retention or have the HIPAA configuration. If a ZDR session still offers it, drafts stay local and sending fails with a message about custom data retention policies.

Task tools

TaskCreate, TaskGet, TaskUpdate, TaskList (and TodoWrite, used instead when CLAUDE_CODE_ENABLE_TASKS=0) are provided by default only on Claude 3.x models, Opus 4 to 4.7, Sonnet 4 to 4.6 and Haiku 4.5 (from v2.1.268). Newer models track multi-step work without a written checklist, and the tool definitions cost context. Unrecognised model ids, such as custom names behind an LLM gateway, also go without.

To opt in on other models: CLAUDE_CODE_ENABLE_TODO_TOOLS=1 claude (every model and provider), name one in --allowedTools, list them in --tools alongside the other built-ins you need, or use the SDK's allowedTools/tools. Background and cloud sessions always have them. Subagents get them only if your session has them; in-process teammates follow your session, while split-pane teammates are separate processes decided by their own model. Without them, agents coordinate by messages rather than a shared task list.

WebFetch

Takes a URL and a prompt. It fetches the page, converts HTML to Markdown, and usually runs your prompt against it in a separate model call, so Claude receives the extraction, not the raw page. That makes it lossy by design: "the page does not mention X" may just mean the prompt did not ask. Re-fetch with a sharper prompt, or curl through Bash for the raw page.

Behaviour worth knowing:

• localhost and dotless hostnames are refused before any request, with advice to use curl.
• HTTP is upgraded to HTTPS.
• Large pages are truncated before processing.
• Responses are cached for 15 minutes; CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS changes that (v2.1.233).
• Downloads (including redirects) must finish within five minutes; CLAUDE_CODE_WEBFETCH_DEADLINE_MS changes it, 0 removes it (v2.1.268).
• Cross-host redirects are not followed; Claude gets the target and fetches it separately.
• An overloaded extraction call is retried with backoff, then fails as an error.
• Requests carry a User-Agent beginning Claude-User and an Accept header preferring Markdown.

Permissions. In Manual and acceptEdits modes, WebFetch prompts unless the domain is covered by your rules or a built-in set of preapproved documentation domains. Every fetch also passes a domain safety check first (see Data usage). The prompt offers Yes (this fetch only), Yes, and don't ask again for <domain> (saves a WebFetch(domain:...) allow rule to .claude/settings.local.json; hidden under allowManagedPermissionRulesOnly), and No, and tell Claude what to do differently. WebFetch(domain:*) allows everything. auto and bypassPermissions skip prompts except where an explicit ask rule matches. Explicit rules beat the preapproved set, so you can block or require prompts for those domains. claude.ai artifact links may also ask to read the artifact (see Artifacts).

Sandboxed commands do not inherit the preapproved domains; add them to allowedDomains or a WebFetch(domain:...) rule (which the sandbox honours). WebFetch never reads the sandbox allowlist in return.

Availability. CLAUDE_CODE_DISABLE_WEB_FETCH=1 turns it off (v2.1.285). For Team and Enterprise sign-ins not using an LLM gateway (and sessions whose plan cannot be determined), WebFetch waits for the organisation policy fetched from api.anthropic.com at start-up. If it is missing, /status shows whether the Organization policy line failed to load and lists web fetch among the features waiting; claude doctor checks the same outside a session. Once a permitting policy loads, the tool appears without a restart.

WebSearch

Searches Anthropic's web search backend and returns titles and URLs only; Claude follows up with WebFetch to read pages. One call may run up to eight backend searches as it refines. Claude can restrict with allowed_domains or exclude with blocked_domains, but not both in one call. Overload errors are retried with backoff. Rules take no specifier, only bare WebSearch. The backend is fixed; for another provider, add an MCP search server.

Available on the Claude API, Claude Platform on AWS and Foundry; on Agent Platform with Claude 4 and later models; not on Bedrock.

Per-session cap. From v2.1.212, an interactive session gets 200 searches across the main conversation and all its subagents (so research fan-outs share it). At the cap, calls quietly return a notice telling Claude to work with what it has, or to ask you to raise the limit. CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION changes the cap (positive integers only; it cannot be disabled), the allowance refills at about 100 per hour (CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR), and /clear resets it unless work that can still spawn subagents, such as a running workflow, survives the clear.

Write

Creates a file, or replaces an existing one wholesale; it never appends or merges. Overwriting an existing file requires a prior read on Opus 4.6, Haiku 4.5 and older models. Newer models may overwrite an unread file under the same conditions as Edit. Notebooks, and files only partially read, always require the read. New files never do. (Before v2.1.228 every model required it.) The single-file Bash viewing commands listed under Edit count as reads. For partial changes Claude uses Edit.

Related

• Permissions
• Hooks
• Subagents
• MCP
• Environment variables