The agent has access to tools for filesystem operations, shell execution, web access, browser automation, knowledge management, scheduling, and sub-agent spawning. Tools are registered dynamically — some only appear when dependencies are available (e.g., browser requires Playwright).

Filesystem¶

All filesystem tools resolve paths relative to the workspace by default. Use short relative paths like data/config.json instead of full absolute paths — the tools will resolve them against the workspace directory automatically. Absolute paths (/etc/hosts) and tilde paths (~/file.txt) bypass workspace resolution and work as-is.

read_file¶

Read file contents. Respects PathGuard access control.

write_file¶

Write content to a file. Creates parent directories automatically.

edit_file¶

Replace exact text in a file. The old_text must match exactly once — if it matches zero times or more than once, the edit fails with an error.

list_dir¶

List directory contents with type indicators.

Shell¶

exec¶

Execute a shell command via asyncio.create_subprocess_shell.

Safety guards: - Deny patterns: rm -r, del /f, format, dd, shutdown, fork bomb, and more - Path guard: Detects path traversal (../), checks against PathGuard rules - Timeout: Configurable (default 60s), kills process on timeout - Output truncation: Capped at 10,000 characters

Configure deny/allow patterns in tools.exec config.

Web¶

web_search¶

Search the web via Brave Search API.

Requires BRAVE_API_KEY environment variable or tools.web.search.apiKey in config.

web_fetch¶

Fetch a URL and extract readable content using Readability.

Returns clean markdown with links preserved. HTML is processed through Readability for article extraction. JSON responses are pretty-printed. Content truncated to 50,000 characters.

firecrawl_scrape¶

Scrape a URL to clean markdown via the Firecrawl API. Better than web_fetch for JavaScript-heavy pages.

Requires FIRECRAWL_API_KEY environment variable or tools.web.firecrawl.apiKey in config.

firecrawl_search¶

Search the web and optionally scrape results.

Browser¶

browser¶

Control a web browser via Playwright. Requires playwright optional dependency:

uv pip install -e ".[browser]"
playwright install chromium

The browser launches lazily on first use and is cleaned up when the agent loop exits.

Actions:

States for wait_for: attached, detached, visible, hidden

Screenshots are saved to ~/.picobot/data/screenshots/ as PNG files, with a base64 preview returned to the agent.

Configuration:

{
  "tools": {
    "browser": {
      "headless": true,
      "timeout": 30000,
      "viewportWidth": 1280,
      "viewportHeight": 720
    }
  }
}

Set headless: false to watch the browser in action.

Knowledge Base¶

kb¶

Interface to the persistent knowledge base. See Knowledge Base for full details.

Scheduling¶

cron¶

Schedule recurring tasks. See Scheduling for full details.

Sub-agents¶

spawn¶

Launch a background sub-agent. See Sub-agents for full details.

check_subagents¶

Query sub-agent status.

Path Access Control¶

All filesystem and shell tools are governed by PathGuard. Two modes:

Unrestricted (default): All paths allowed, except those in blockPaths.

Workspace-restricted: Only workspace paths allowed, plus exceptions in allowPaths. Block list always wins.

{
  "tools": {
    "restrictToWorkspace": true,
    "allowPaths": ["/Users/me/projects"],
    "blockPaths": ["/Users/me/.ssh", "/etc"]
  }
}

Workspace-relative path resolution¶

Filesystem tools (read_file, write_file, edit_file, list_dir) resolve relative paths against the workspace directory. This means:

This saves tokens — the agent uses data/config.json instead of /home/user/.picobot/workspace/data/config.json. The system prompt tells the agent to prefer relative paths, and sub-agent preambles include the same guidance.

The shell tool (exec) also checks relative path tokens in commands against PathGuard. In workspace-restricted mode, a command like cat ../../etc/passwd is blocked because ../../etc/passwd resolves outside the workspace. URL-like strings (https://...) are not treated as path traversal.