Worker Tools

Workers are task-focused processes with no conversation context. They get a specific job, appropriate tools, and report back when done. Workers operate within a sandboxed workspace directory.

shell

Execute shell commands within the sandboxed workspace environment.

command

string

required

The shell command to execute. Runs with sh -c on Unix or cmd /C on Windows.

working_dir

string

Optional working directory where the command should run. Must be within the workspace boundary.

timeout_seconds

integer

default:60

Maximum time to wait for the command to complete (1-300 seconds)

success

boolean

Whether the command succeeded (exit code 0)

exit_code

integer

The command exit code

stdout

string

Standard output from the command

stderr

string

Standard error from the command

summary

string

Formatted summary of the command output

Example

{
  "command": "cargo test --all",
  "working_dir": "project",
  "timeout_seconds": 120
}

Output is truncated if it exceeds the maximum tool output size. Use file redirection for large outputs.

file

Read, write, or list files within the workspace directory. All paths are restricted to the workspace boundary.

operation

string

required

The file operation: "read", "write", or "list"

path

string

required

The file or directory path. Relative paths are resolved from the workspace root. Absolute paths are accepted only if they fall within the workspace.

content

string

Content to write to the file (required for write operation)

create_dirs

boolean

default:true

For write operations: create parent directories if they don’t exist

success

boolean

Whether the operation succeeded

operation

string

The operation performed

path

string

The file/directory path

content

string

File content (for read operations)

entries

array

Directory entries (for list operations). Each entry has name, entry_type (“file”, “directory”, or “other”), and size in bytes.

error

string

Error message if the operation failed

Example: Read a file

{
  "operation": "read",
  "path": "src/main.rs"
}

Example: Write a file

{
  "operation": "write",
  "path": "output/results.json",
  "content": "{\"status\": \"complete\"}",
  "create_dirs": true
}

Example: List directory

{
  "operation": "list",
  "path": "src"
}

Identity files (SOUL.md, IDENTITY.md, USER.md) are readable but cannot be modified through file operations. Symlinks within the workspace are blocked for security.

exec

Run subprocesses with full control over arguments and environment variables. Sandboxed to the workspace directory.

program

string

required

The program or binary to execute (e.g., “cargo”, “python”, “node”)

args

array

default:[]

Arguments to pass to the program (array of strings)

working_dir

string

Optional working directory for the execution. Must be within the workspace.

env

array

default:[]

Environment variables to set. Each entry has key and value fields.Blocked variables (for security): LD_PRELOAD, LD_LIBRARY_PATH, DYLD_INSERT_LIBRARIES, DYLD_LIBRARY_PATH, PYTHONPATH, PYTHONSTARTUP, NODE_OPTIONS, RUBYOPT, PERL5OPT, PERL5LIB, BASH_ENV, ENV

timeout_seconds

integer

default:60

Maximum time to wait (1-300 seconds)

success

boolean

Whether the execution succeeded

exit_code

integer

The exit code

stdout

string

Standard output

stderr

string

Standard error

summary

string

Formatted summary of the output

Example

{
  "program": "cargo",
  "args": ["build", "--release"],
  "working_dir": "project",
  "env": [
    {"key": "RUST_BACKTRACE", "value": "1"}
  ],
  "timeout_seconds": 300
}

browser

Browser automation via headless Chrome. Supports navigation, element interaction, screenshots, and page observation using an accessibility-tree based reference system.

action

string

required

The browser action to perform:

"launch": Start the browser (required before other actions)
"navigate": Navigate to a URL
"open": Open a new tab
"tabs": List all open tabs
"focus": Switch to a tab by target ID
"close_tab": Close a tab
"snapshot": Get accessibility tree with element references
"act": Interact with an element
"screenshot": Capture a screenshot
"evaluate": Run JavaScript (if enabled)
"content": Get page HTML
"close": Shut down the browser

url

string

URL for navigate/open actions. Must be http or https. Private/loopback IPs and cloud metadata endpoints are blocked for security.

target_id

string

Tab target ID for focus/close_tab actions

element_ref

string

Element reference from snapshot (e.g., “e3”) for act/screenshot actions

act_kind

string

Kind of interaction for the act action:

"click": Click an element
"type": Type text into an element
"press_key": Press a keyboard key (e.g., “Enter”, “Tab”)
"hover": Hover over an element
"scroll_into_view": Scroll element into viewport
"focus": Focus an element

text

string

Text to type for act:type

key

string

Key to press for act:press_key (e.g., “Enter”, “Tab”, “Escape”)

full_page

boolean

default:false

Take full-page screenshot instead of viewport only

script

string

JavaScript expression to evaluate (requires evaluate_enabled in config)

success

boolean

Whether the action succeeded

message

string

Human-readable result message

title

string

Page title (when available)

url

string

Current URL (when available)

elements

array

Snapshot data from accessibility tree. Each element has ref_id, role, name, description, and value.

tabs

array

List of open tabs with target_id, title, url, and active status

screenshot_path

string

Path to saved screenshot file

eval_result

object

JavaScript evaluation result

content

string

Page HTML content (truncated if >100KB)

Example: Navigate and interact

// 1. Launch browser
{"action": "launch"}

// 2. Navigate to site
{"action": "navigate", "url": "https://example.com"}

// 3. Get interactive elements
{"action": "snapshot"}

// 4. Click a button (using ref from snapshot)
{
  "action": "act",
  "act_kind": "click",
  "element_ref": "e5"
}

// 5. Type into a search box
{
  "action": "act",
  "act_kind": "type",
  "element_ref": "e2",
  "text": "search query"
}

// 6. Take a screenshot
{"action": "screenshot", "full_page": true}

Always run snapshot before interacting with elements to get current element references. References are cleared on navigation.

set_status

Update your worker status to give the channel visibility into your progress. Status appears in the channel’s status block.

status

string

required

A concise status message describing your current progress (1-2 sentences). Maximum 256 characters.

success

boolean

Whether the status was set

worker_id

string

Your worker ID

status

string

The status that was set (may be truncated)

Example

{
  "status": "Running test suite... 24/42 tests passed so far"
}

Use set_status periodically during long-running tasks so the user knows you’re making progress.

read_skill

Read the full content of an installed skill. Useful for accessing skill instructions, examples, and bundled resources.

skill_name

string

required

Name of the skill to read

content

string

The full skill content with variables resolved

base_dir

string

The skill’s base directory path

Example

{
  "skill_name": "github"
}

web_search

Search the web using Brave Search API. Returns relevant results with titles, URLs, and descriptions.

query

string

required

The search query

count

number

default:5

Number of results to return (1-20)

freshness

string

Time filter: "day", "week", "month", "year"

country

string

default:"us"

Country code for localized results (e.g., “us”, “uk”, “de”)

results

array

Array of search results with title, url, description, and published_time

Requires brave_search_key configured in your agent’s config. Get a free API key at https://brave.com/search/api/

Example

{
  "query": "Rust async programming patterns",
  "count": 5,
  "freshness": "month"
}

email_search

Search email messages via IMAP. Returns matching messages with headers and content.

query

string

required

Search query (IMAP SEARCH syntax)

folder

string

default:"INBOX"

Email folder to search

max_results

number

default:10

Maximum number of results to return

messages

array

Array of email messages with subject, from, date, and body

Requires email configuration (IMAP host, credentials) in messaging.email config section.

Example

{
  "query": "FROM [email protected] SINCE 1-Jan-2024",
  "folder": "INBOX",
  "max_results": 5
}

Channel Tools - reply, branch, spawn_worker, route, send_file
Memory Tools - memory_save, memory_recall (branch only)
System Tools - task management, worker inspection

CLI Commands

Configuration

Tools

shell

Example

file

Example: Read a file

Example: Write a file

Example: List directory

exec

Example

browser

Example: Navigate and interact

set_status

Example

read_skill

Example

web_search

Example

email_search

Example

Build docs developers (and LLMs) love

CLI Commands

Configuration

Tools

​shell

​Example

​file

​Example: Read a file

​Example: Write a file

​Example: List directory

​exec

​Example

​browser

​Example: Navigate and interact

​set_status

​Example

​read_skill

​Example

​web_search

​Example

​email_search

​Example

​Related Tools

Build docs developers (and LLMs) love

shell

Example

file

Example: Read a file

Example: Write a file

Example: List directory

exec

Example

browser

Example: Navigate and interact

set_status

Example

read_skill

Example

web_search

Example

email_search

Example

Related Tools