Shell & web tools

Execute shell commands, run PowerShell scripts, fetch URLs, and search the web.

Shell and web tools let Claude interact with your operating system and the internet. Because these tools have significant side effects, most of them trigger a permission prompt before executing.

---

Bash

Execute a shell command. On Unix/Linux systems Claurst runs commands via bash -c; on Windows it falls back to cmd /C.

Tool name: Bash
Permission: Execute — always prompts unless BypassPermissions mode

Shell commands can modify files, install software, push code, or delete data. Always review the command before approving. Destructive or irreversible commands require your explicit confirmation.

Parameters

command · string · required

Shell command to execute.

timeout · number

Maximum execution time in milliseconds. The Rust implementation uses seconds with a default of 120 s and a hard cap of 600 s. The TypeScript implementation’s default is 120 000 ms (2 minutes).

description · string

Human-readable summary of what the command does, shown in the permission prompt.

run_in_background · boolean

When true, the command is launched as a background task and a task_id is returned immediately instead of waiting for completion. Not available when CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 is set.

dangerouslyDisableSandbox · boolean

Override the sandbox for this single call. Requires the user to have sandbox mode configured; has no effect if sandbox is not enabled.

Return value

stdout · string · required

Standard output from the command.

stderr · string · required

Standard error from the command.

interrupted · boolean · required

true if the command was killed due to timeout or user interruption.

backgroundTaskId · string

Task ID when run_in_background is true.

returnCodeInterpretation · string

Human-readable explanation of the exit code when it is non-zero.

isImage · boolean

true when stdout contains base64-encoded image data.

Sandboxing

When enabled, Claurst uses platform-native sandboxing to restrict what commands can do:

Platform	Sandbox technology
Linux	bwrap (bubblewrap)
macOS	sandbox-exec
Windows	No sandbox available

Set dangerouslyDisableSandbox: true to bypass sandboxing for a single call when you know the command needs full system access.

Auto-backgrounding

Long-running commands are managed automatically:

• After 2 seconds a progress indicator is shown.
• In the TypeScript implementation, commands that run longer than 120 seconds are automatically moved to a background task. In Kairos/assistant mode the threshold is 15 seconds.

Prefer SleepTool over bash -c "sleep N" for waiting. It does not hold a shell process and can be interrupted by the user.

Permission behavior

Mode	Behavior
Default	Always prompts
AcceptEdits	Prompts for write/execute commands; auto-approves read-only commands
BypassPermissions	Auto-approves everything
Plan	All shell commands are denied

Example

{
  "command": "cargo test --lib 2>&1 | head -40",
  "timeout": 60000,
  "description": "Run unit tests and show first 40 lines of output"
}

running 12 tests
test tools::bash::tests::detect_blocked_sleep ... ok
test tools::file_read::tests::read_offset ... ok
...
test result: ok. 12 passed; 0 failed

---

PowerShell

Execute a Windows PowerShell command. Mirrors the Bash interface but targets PowerShell (pwsh on non-Windows platforms, powershell -NoProfile -NonInteractive on Windows).

Tool name: PowerShell
Permission: Execute

Parameters

command · string · required

PowerShell command or script block to execute.

timeout · number

Maximum execution time in milliseconds.

description · string

Human-readable description shown in the permission prompt.

run_in_background · boolean

Launch as a background task. Not available when CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1.

dangerouslyDisableSandbox · boolean

Override sandbox mode for this call.

Return value

Same fields as Bash: stdout, stderr, interrupted, backgroundTaskId, returnCodeInterpretation, isImage.

Notes

• Start-Sleep and bare sleep commands are detected and rejected; use SleepTool instead.
• Common PowerShell read operations (Get-Content, Get-ChildItem, Get-Process, etc.) are classified as read-only and auto-approved in AcceptEdits mode.

Example

{
  "command": "Get-ChildItem -Recurse -Filter '*.cs' | Select-Object FullName",
  "description": "List all C# source files"
}

---

WebFetch

Fetch a URL and return its content. HTML responses are converted to Markdown before being returned. Large responses may be summarized.

Tool name: WebFetch
Permission: Per-hostname rules. Pre-approved hostnames do not trigger a prompt.

Parameters

url · string · required

Fully-qualified URL to fetch (HTTP or HTTPS).

prompt · string · required

Instruction describing what to extract or summarize from the fetched content. When the response exceeds the size threshold, a Haiku model call applies this prompt to distill the content.

Return value

url · string · required

Final URL after any redirects.

code · integer · required

HTTP status code.

codeText · string · required

HTTP status text (e.g. "OK", "Not Found").

result · string · required

Processed content: Markdown-converted HTML, or a model-generated summary when the content was too large.

bytes · integer · required

Response size in bytes.

durationMs · number · required

Time to fetch and process the response.

Notes

• HTML is stripped of scripts and styles and converted to Markdown. The Rust implementation uses a manual state machine for HTML stripping.
• The Rust implementation uses a 30-second timeout and follows up to 10 redirects.
• The User-Agent sent by the Rust implementation is Claude-Code/1.0.
• Responses larger than 100 000 characters are truncated.

Example

{
  "url": "https://doc.rust-lang.org/std/fs/struct.File.html",
  "prompt": "List the main methods available on std::fs::File"
}

---

WebSearch

Search the web and return titles, URLs, and snippets.

Tool name: WebSearch
Permission: Always prompts (permission behavior is passthrough).

Parameters

query · string · required

Search query. Minimum 2 characters.

allowed_domains · string[]

Restrict results to these domains (TypeScript implementation only).

blocked_domains · string[]

Exclude results from these domains (TypeScript implementation only).

num_results · integer · default: "5"

Maximum number of results to return (Rust implementation).

Return value

query · string · required

The query that was executed.

results · object[] · required

Array of search results, or a string message when no results were found.

Show result properties

title · string

Page title.

url · string

Page URL.

snippet · string

Short excerpt relevant to the query.

durationSeconds · number

Time taken to complete the search (TypeScript implementation).

Search backends

Implementation	Backend
TypeScript	Anthropic web_search_20250305 beta tool; available on first-party, Vertex, and Foundry API providers only
Rust	Brave Search API if BRAVE_SEARCH_API_KEY is set; falls back to DuckDuckGo Instant Answer API

Example

{
  "query": "tokio async runtime rust tutorial"
}

{
  "query": "tokio async runtime rust tutorial",
  "results": [
    {
      "title": "Tokio — an asynchronous Rust runtime",
      "url": "https://tokio.rs/tokio/tutorial",
      "snippet": "Tokio is an asynchronous runtime for Rust..."
    }
  ],
  "durationSeconds": 0.8
}