> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/yocxy2/claurst/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Warning>
  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.
</Warning>

### Parameters

<ParamField path="command" type="string" required>
  Shell command to execute.
</ParamField>

<ParamField path="timeout" type="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).
</ParamField>

<ParamField path="description" type="string">
  Human-readable summary of what the command does, shown in the permission prompt.
</ParamField>

<ParamField path="run_in_background" type="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.
</ParamField>

<ParamField path="dangerouslyDisableSandbox" type="boolean">
  Override the sandbox for this single call. Requires the user to have sandbox mode configured; has no effect if sandbox is not enabled.
</ParamField>

### Return value

<ResponseField name="stdout" type="string" required>
  Standard output from the command.
</ResponseField>

<ResponseField name="stderr" type="string" required>
  Standard error from the command.
</ResponseField>

<ResponseField name="interrupted" type="boolean" required>
  `true` if the command was killed due to timeout or user interruption.
</ResponseField>

<ResponseField name="backgroundTaskId" type="string">
  Task ID when `run_in_background` is `true`.
</ResponseField>

<ResponseField name="returnCodeInterpretation" type="string">
  Human-readable explanation of the exit code when it is non-zero.
</ResponseField>

<ResponseField name="isImage" type="boolean">
  `true` when stdout contains base64-encoded image data.
</ResponseField>

### 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**.

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

### 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

```json theme={null}
{
  "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

<ParamField path="command" type="string" required>
  PowerShell command or script block to execute.
</ParamField>

<ParamField path="timeout" type="number">
  Maximum execution time in milliseconds.
</ParamField>

<ParamField path="description" type="string">
  Human-readable description shown in the permission prompt.
</ParamField>

<ParamField path="run_in_background" type="boolean">
  Launch as a background task. Not available when `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1`.
</ParamField>

<ParamField path="dangerouslyDisableSandbox" type="boolean">
  Override sandbox mode for this call.
</ParamField>

### 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

```json theme={null}
{
  "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

<ParamField path="url" type="string" required>
  Fully-qualified URL to fetch (HTTP or HTTPS).
</ParamField>

<ParamField path="prompt" type="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.
</ParamField>

### Return value

<ResponseField name="url" type="string" required>
  Final URL after any redirects.
</ResponseField>

<ResponseField name="code" type="integer" required>
  HTTP status code.
</ResponseField>

<ResponseField name="codeText" type="string" required>
  HTTP status text (e.g. `"OK"`, `"Not Found"`).
</ResponseField>

<ResponseField name="result" type="string" required>
  Processed content: Markdown-converted HTML, or a model-generated summary when the content was too large.
</ResponseField>

<ResponseField name="bytes" type="integer" required>
  Response size in bytes.
</ResponseField>

<ResponseField name="durationMs" type="number" required>
  Time to fetch and process the response.
</ResponseField>

### 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

```json theme={null}
{
  "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

<ParamField path="query" type="string" required>
  Search query. Minimum 2 characters.
</ParamField>

<ParamField path="allowed_domains" type="string[]">
  Restrict results to these domains (TypeScript implementation only).
</ParamField>

<ParamField path="blocked_domains" type="string[]">
  Exclude results from these domains (TypeScript implementation only).
</ParamField>

<ParamField path="num_results" type="integer" default="5">
  Maximum number of results to return (Rust implementation).
</ParamField>

### Return value

<ResponseField name="query" type="string" required>
  The query that was executed.
</ResponseField>

<ResponseField name="results" type="object[]" required>
  Array of search results, or a string message when no results were found.

  <Expandable title="result properties">
    <ResponseField name="title" type="string">
      Page title.
    </ResponseField>

    <ResponseField name="url" type="string">
      Page URL.
    </ResponseField>

    <ResponseField name="snippet" type="string">
      Short excerpt relevant to the query.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="durationSeconds" type="number">
  Time taken to complete the search (TypeScript implementation).
</ResponseField>

### 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

```json theme={null}
{
  "query": "tokio async runtime rust tutorial"
}
```

```json theme={null}
{
  "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
}
```