Tools

superclaw exposes exactly 7 tools to the model. Each tool has a typed input contract, enforced limits, and a predictable output format. No tools can be added at runtime.

Tool overview

Name	Category	Description
fetch_url	Network	Fetch a URL over HTTPS
web_search	Network	Search the web and return top results
read_file	Filesystem	Read a file from the workspace
write_file	Filesystem	Write or overwrite a file
patch_file	Filesystem	Replace a string in an existing file
list_files	Filesystem	List files and directories
run_bash	Process	Execute a shell command

fetch_url

tool

Fetches the content of a URL over HTTP/HTTPS. Returns the response body as plain text or Markdown (after HTML stripping). Counts against max_fetch_calls.

Parameters

Name	Type	Required	Description
url	string	yes	The full URL to fetch (must be https://).
max_bytes	integer	no	Truncate response at this byte count. Default: 65536.

Example input

json

{
  "url": "https://example.com/article",
  "max_bytes": 32768
}

Notes

Retries up to 3 times with exponential backoff on 429, 500, 502, 503, 504. Follows up to 5 redirects. Strips scripts, styles, and nav elements from HTML.

web_search

tool

Performs a web search and returns the top results as a list of title, URL, and snippet. Uses the configured search backend (Brave by default). Counts against max_fetch_calls.

Parameters

Name	Type	Required	Description
query	string	yes	The search query.
max_results	integer	no	Number of results to return. Default: 5, max: 10.

Example input

json

{
  "query": "Go 1.23 range over func proposal",
  "max_results": 5
}

Notes

Requires BRAVE_API_KEY or equivalent env var depending on the configured provider. If no search backend is available, the tool returns an error rather than falling back silently.

read_file

tool

Reads a file from the workspace and returns its contents as a string. Path must be within work_dir.

Parameters

Name	Type	Required	Description
path	string	yes	Relative or absolute path within work_dir.
max_bytes	integer	no	Truncate at this byte count. Default: 131072.
encoding	string	no	File encoding. Default: utf-8.

Example input

json

{
  "path": "src/main.go"
}

Notes

Attempting to read outside work_dir returns a permission error. Binary files are detected and rejected. Use list_files first if you are unsure of the structure.

write_file

tool

Writes or overwrites a file in the workspace. Creates parent directories as needed.

Parameters

Name	Type	Required	Description
path	string	yes	Relative or absolute path within work_dir.
content	string	yes	Full file content to write.

Example input

json

{
  "path": "summary.md",
  "content": "# Summary\n\nThis project does X, Y, and Z..."
}

Notes

Overwrites silently. Use patch_file if you only need to modify specific lines. Path must be within work_dir.

patch_file

tool

Applies a targeted edit to an existing file: replaces the first occurrence of old_string with new_string. Safer than write_file for partial edits.

Parameters

Name	Type	Required	Description
path	string	yes	Path to the file to edit (must exist).
old_string	string	yes	The exact string to find and replace.
new_string	string	yes	The replacement string.

Example input

json

{
  "path": "config.go",
  "old_string": "const maxRetries = 3",
  "new_string": "const maxRetries = 5"
}

Notes

Fails if old_string is not found. Replaces only the first occurrence. For multi-line replacements, include the surrounding context in old_string to ensure uniqueness.

list_files

tool

Lists files and directories under a given path. Returns a structured tree up to the specified depth.

Parameters

Name	Type	Required	Description
path	string	no	Directory to list. Default: work_dir root.
depth	integer	no	Maximum directory depth to recurse. Default: 2, max: 5.
include_hidden	boolean	no	Include dotfiles. Default: false.

Example input

json

{
  "path": "src",
  "depth": 3,
  "include_hidden": false
}

Notes

Does not return file contents. Use read_file to read individual files. Respects .gitignore if present in work_dir.

run_bash

tool

Executes a shell command in the workspace directory. Returns stdout, stderr, and exit code.

Parameters

Name	Type	Required	Description
command	string	yes	The shell command to run.
timeout_seconds	integer	no	Per-command timeout. Default: 30, max: 120.
env	object	no	Additional environment variables as key-value pairs.

Example input

json

{
  "command": "go test ./... -count=1",
  "timeout_seconds": 60,
  "env": {
    "CGO_ENABLED": "0"
  }
}

Notes

Runs as the same user as the superclaw process (non-root in Docker). No interactive TTY. Network access is available unless restricted by the container network policy. The working directory is always work_dir.

Restricting the tool allowlist

By default, all 7 tools are available to the model. Use the tools field in superclaw.json to restrict which tools the model can call:

json

{
  "tools": ["read_file", "write_file", "list_files"]
}

The model is informed of the restricted tool set in its system prompt. If it attempts to call an unlisted tool, the runtime returns a tool error and continues the loop.