tools — the tool surface available to agents

SYNOPSIS

read_file(path, [offset], [limit])             Read VFS file content
write_file(path, content)                      Create or overwrite a file
edit_file(path, old_string, new_string)        Surgical edit to an existing file
bash(command)                                  Run shell commands in sandboxed WASM shell
javascript(code)                               Execute JS with VFS and shell access
send_message(text)                             Inter-agent messaging (cone + scoops)
list_scoops()                                  List active scoops (cone only)
scoop_scoop(name, [model], [prompt])           Create a scoop (cone only)
feed_scoop(scoop_name, prompt)                 Send work to a scoop (cone only)
drop_scoop(scoop_name)                         Remove a scoop (cone only)
update_global_memory(content)                  Update shared CLAUDE.md (cone only)

PHILOSOPHY

Virtual CLIs over dedicated tools. New capabilities should be shell commands, not dedicated tools. MCP burns context tokens; CLI tools compose naturally. Prefer bash over adding a bespoke tool whenever possible.

The active tool surface is intentionally small: five base tools plus scoop-management. Everything else — browser automation, code search, file discovery, data processing — goes through bash and the 78+ commands available in the WASM shell.

BASE TOOLS

Available to all agents (cone and scoops alike).

read_file(path, [offset], [limit])

Read file contents from the virtual filesystem. Returns content as a string with line numbers. Optional offset (1-based line number) and limit (max lines) allow reading a specific range. Cone reads VirtualFS; scoops read through RestrictedFS (sandboxed to /scoops/{name}/ + /shared/).
write_file(path, content)

Write content to a file. Creates the file if it does not exist, or overwrites it if it does. Parent directories are created automatically.
edit_file(path, old_string, new_string)

Edit a file by replacing an exact string match. The old_string must appear exactly once in the file — if it matches zero or multiple times, the tool returns an error. Use this instead of write_file when making targeted changes to existing files.
bash(command)

Execute a command in a full Unix-like shell (just-bash 2.11.7 compiled to WASM). Supports pipes, redirects, chaining (&&, ;, ||), subshells, control flow, command substitution, here-docs, and more. Over 78 built-in commands including git, curl, jq, rg, grep, sed, awk, find, node -e, python3 -c, sqlite3, and open. Non-zero exit codes are returned as errors, except for expected no-match exits from grep/rg (exit 1 with empty stderr).
javascript(code)

Execute JavaScript in a persistent sandboxed iframe runtime. Variables and functions persist across calls. Top-level await is supported. Console output is captured. VFS bridge available: fs.readFile(path), fs.readFileBinary(path), fs.writeFile(path, content), fs.writeFileBinary(path, data), fs.readDir(path), fs.exists(path), fs.fetchToFile(url, path) — all async. Use fs.readFileBinary() for binary files (images, etc.) as Uint8Array.

NANOCLAW TOOLS

Scoop management and inter-agent communication.

send_message(text)

Send a message to another agent. Available to both cone and scoops. Scoops use this to report results back to the cone; the cone uses it for coordination. Messages are delivered to the cone's message queue.
list_scoops() — cone only

List all registered scoops with their names, folders, and status.
scoop_scoop(name, [model], [prompt]) — cone only

Create a new scoop. If prompt is provided, the scoop starts working immediately. See man scoop for details.
feed_scoop(scoop_name, prompt) — cone only

Send a complete, self-contained prompt to a scoop. The scoop cannot see the cone's conversation — include all necessary context, file paths, and instructions.
drop_scoop(scoop_name) — cone only

Remove a scoop and stop its work. The scoop is unregistered and its context destroyed.
update_global_memory(content) — cone only

Update the global /shared/CLAUDE.md memory file shared across all scoops. Use this instead of write_file for the shared memory file.

BROWSER AUTOMATION

There is no dedicated browser tool. Browser automation goes through bash using shell commands: playwright-cli, playwright, or puppeteer. This is intentional — composing through the shell avoids MCP token overhead and lets you chain browser actions with other CLI tools naturally.

# Take a screenshot
bash("playwright-cli screenshot https://example.com /workspace/shot.png")

# Navigate and extract text
bash("playwright-cli evaluate 'document.title' --url https://example.com")

CODE AND FILE SEARCH

Use shell commands through bash for all code and file search:

# Recursive code search with ripgrep
bash("rg 'createBashTool' /workspace/src --type ts")

# Find files by pattern
bash("find /workspace -name '*.ts' -type f")

# Search with context
bash("grep -rn 'TODO' /workspace/src")

TOOL UI

Tools can inject interactive UI elements into the chat mid-execution using the sprinkle-based tool UI system. This renders blocking inline cards — the tool pauses execution until the user interacts. Used for approval dialogs, file pickers, OAuth flows, and any tool needing user input during execution.