Shell & web tools

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
}

Commands

Tools

Architecture

Shell & web tools

Bash

Parameters

Return value

Sandboxing

Auto-backgrounding

Permission behavior

Example

PowerShell

Parameters

Return value

Notes

Example

WebFetch

Parameters

Return value

Notes

Example

WebSearch

Parameters

Return value

Search backends

Example

Build docs developers (and LLMs) love

Commands

Tools

Architecture

​Bash

​Parameters

​Return value

​Sandboxing

​Auto-backgrounding

​Permission behavior

​Example

​PowerShell

​Parameters

​Return value

​Notes

​Example

​WebFetch

​Parameters

​Return value

​Notes

​Example

​WebSearch

​Parameters

​Return value

​Search backends

​Example

Build docs developers (and LLMs) love

Bash

Parameters

Return value

Sandboxing

Auto-backgrounding

Permission behavior

Example

PowerShell

Parameters

Return value

Notes

Example

WebFetch

Parameters

Return value

Notes

Example

WebSearch

Parameters

Return value

Search backends

Example