Tools

Tools give agents the ability to interact with the host system, the web, and external services. Enable tools per-agent in the agent editor.

Available Tools

shell

Execute shell commands on the host machine. Commands run as the SwarmClaw process user with the same permissions.

• Use case: Build projects, run scripts, manage files, install packages
• Security: Full shell access. Only grant to trusted agents.
• Output: stdout and stderr are captured and returned to the agent

process

Manage long-running shell processes started by shell.

• Use case: Poll build logs, keep dev servers running, send stdin, stop hung jobs
• Operations: list, status, poll, log, write, kill, clear, remove
• Behavior: Works with process IDs returned when shell commands run in background/yield mode

files

Read files and list directory contents.

• Use case: Inspect codebases, read configuration, explore project structure
• Operations: read_file, write_file, list_files, send_file, copy_file, move_file
• Optional destructive op: delete_file (off by default unless explicitly enabled)
• Limits: Large files are truncated to avoid context overflow

edit_file

Create new files or apply targeted edits to existing files.

• Use case: Write code, update configs, patch files
• Operation: edit_file (single exact-match search/replace)
• Behavior: Requires oldText to match exactly once, reducing accidental broad rewrites

web_search

Search the web and return structured results.

• Use case: Research, fact-checking, finding documentation
• Backend: Configurable search provider (default: DuckDuckGo)
• Returns: Title, URL, and snippet for each result

web_fetch

Fetch a URL and extract its content as clean text or markdown.

• Use case: Read articles, pull API docs, scrape data
• Behavior: HTML is converted to readable text, stripping nav/ads
• Limits: Response size is capped to avoid context overflow

http_request

Make direct HTTP API requests from the agent.

• Use case: Call REST endpoints, hit internal services, verify webhooks, inspect API responses
• Methods: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
• Controls: Custom headers, request body, timeout, optional redirect following
• Returns: status code, selected response headers, and response body (binary payloads are summarized)

git

Run structured Git operations from an agent tool call.

• Use case: Inspect repo state, stage files, review diffs/logs, create commits, push/pull branches
• Actions: status, log, diff, commit, add, push, pull, branch, checkout, stash, merge, clone, remote, tag, reset, show
• Safety behavior: validates repository context (except clone) and disables interactive terminal prompts

delegate

Enable CLI delegation tools for complex coding tasks.

• Delegation tools: delegate_to_claude_code, delegate_to_codex_cli, delegate_to_opencode_cli, delegate_to_gemini_cli
• Use case: Delegate multi-step coding work to a specialized CLI agent
• Requirements: install and authenticate the target CLI (claude, codex, opencode, and/or gemini)
• Behavior: each delegate tool runs its CLI in non-interactive mode and returns explicit timeout/exit diagnostics when delegation fails
• Long-running work: delegate now supports handle-based background flows with status, list, wait, and cancel actions for longer autonomous jobs

spawn_subagent

Delegate a focused subtask to another SwarmClaw agent and receive its response in-line.

• Use case: hand off specialized work (for example, "security review this diff") while keeping parent context concise
• Inputs: target agentId, subtask message, optional working directory override
• Behavior: creates an internal orchestrated sub-chat thread and can either return inline results or a persisted delegation handle for longer-running jobs
• Guardrail: recursion depth is capped to prevent unbounded agent nesting

browser

MCP browser automation powered by Playwright.

• Use case: Navigate websites, fill forms, take screenshots, scrape dynamic content, and complete longer browser-based workflows
• For Claude CLI agents: Passes --mcp-config with the browser server config
• For LangGraph agents: Spawns a Playwright MCP subprocess
• Higher-level actions: read_page, extract_links, extract_form_fields, extract_table, fill_form, submit_form, scroll_until, download_file, complete_web_task, and verification helpers
• Persistence: browser profiles persist cookies, storage, tabs, recent observations, screenshots, and downloads per chat/session
• Requirement: Playwright must be installed (npx playwright install)

canvas

Present live HTML/CSS/JS content to users in a chat-side canvas panel.

• Use case: interactive previews, generated dashboards, UI prototypes, visual artifacts tied to chat context
• Actions: present, snapshot, hide
• Canvas API: GET/POST /api/canvas/:sessionId for reading/updating current canvas content (sessionId path param retained for compatibility)
• Behavior: canvas updates push over WS so open clients refresh immediately

memory

Store and retrieve long-term memories that persist across chats.

• Use case: Remember facts, preferences, and context between conversations
• Operations: store, search, list, get, delete, link, unlink
• Scoping: Supports both shared memory and agent-scoped memory
• Extras: References, image attachments, and linked-memory traversal

image_gen

Generate images from prompts and return upload/download links.

• Tool: generate_image
• Use case: Create mockups, concept art, diagrams, social assets, and visual drafts
• Providers: OpenAI, Stability, Replicate, fal.ai, Together, Fireworks, BFL, or custom OpenAI-compatible endpoints (configured in plugin settings)
• Options: prompt, size, quality, optional output filename
• Behavior: generated images are saved under uploads and returned as /api/uploads/... links

email

Send outbound email from agents via SMTP.

• Tool: email
• Actions: send, status
• Use case: Incident updates, proactive status summaries, customer follow-ups
• Inputs: to (string or array), subject, body, optional html
• Config: SMTP host/port/auth/from settings in plugin settings

calendar

Manage calendar events for Google Calendar or Outlook.

• Tool: calendar
• Actions: list, create, update, delete, status
• Use case: Scheduling meetings, checking conflicts, updating event details, cleanup
• Providers: Google Calendar API or Microsoft Graph (Outlook)
• Config: provider, tokens, and calendar settings in plugin settings

mailbox

Inbox automation over IMAP/SMTP.

• Tool: mailbox
• Actions: status, list_messages, list_threads, search_messages, read_message, download_attachment, reply, wait_for_email
• Use case: Search inboxes, read inbound mail, download attachments, send replies, and wait durably for matching messages
• Config: IMAP/SMTP host/auth/from settings in plugin settings, with fallback to configured email connector details when available

ask_human

Human-in-the-loop requests and approvals.

• Tool: ask_human
• Actions: request_input, request_approval, wait_for_reply, wait_for_approval, list_mailbox, ack_mailbox, status
• Use case: Pause autonomous work for explicit human feedback or approval, then resume from durable wait handles
• Behavior: backed by session mailbox envelopes and approval records

document

Document parsing, OCR, and stored-document retrieval.

• Tool: document
• Actions: status, read, metadata, ocr, extract_tables, store, list, search, get, delete
• Use case: Read PDFs, Office docs, OCR-able images, HTML, CSV/TSV/XLSX, ZIP listings, and plain text files
• Behavior: extracts text/tables locally and can store searchable document text for later lookup

extract

Schema-driven structured extraction.

• Tool: extract
• Actions: extract_structured, summarize, status
• Use case: Convert unstructured text or files into validated JSON using the active session model/provider
• Behavior: combines well with browser, document, and crawl when the agent needs records rather than prose

table

Tabular data loading and transformation.

• Tool: table
• Actions: read, load_csv, load_xlsx, summarize, filter, sort, group, pivot, dedupe, join, write, status
• Use case: Spreadsheet-style processing for CSV, TSV, JSON, and XLSX inputs without shell/Python detours
• Behavior: supports inline row arrays or file-backed tables and can persist output tables back to disk

crawl

Multi-page site crawling and batch extraction.

• Tool: crawl
• Actions: crawl_site, follow_pagination, extract_sitemap, dedupe_pages, batch_extract, status
• Use case: Research across many related pages, follow pagination, dedupe crawled content, and feed page sets into structured extraction
• Behavior: bounded same-origin crawling by default with optional page-list input

wallet

Manage the agent's own Solana wallet.

• Use case: Check balance, fetch address, send SOL, review recent transactions
• Tool: wallet_tool
• Safety: Per-transaction and daily limits are enforced; optional user approval gate before sends
• Storage: Private keys are AES-encrypted in local storage and never exposed by wallet APIs

sandbox

Run code in an isolated sandbox environment when custom code is actually needed.

• Use case: Data processing, calculations, file generation, custom parsing, one-off scripts
• Languages: JavaScript, TypeScript (via Deno)
• Tools: sandbox_exec (run code), sandbox_list_runtimes (check available runtimes)
• Isolation: Deno runs with --deny-env, scoped read/write to the sandbox directory, and network access
• Artifacts: Files created in the sandbox are returned as downloadable artifact URLs
• Timeout: Configurable per execution (default 60s, max 300s)
• Guidance: Prefer http_request for straightforward REST/JSON APIs. For recurring automations, prefer a focused plugin plus schedules over repeated sandbox runs.
• Requirement: Deno must be installed for sandbox_exec. If it is unavailable, the tool reports guidance instead of falling back to Node or Python.

mcp

Connect to external Model Context Protocol (MCP) servers.

• Use case: Extend agent capabilities with third-party tools, databases, APIs, or services via MCP
• Configuration: Select MCP servers per-agent in the agent editor. Servers are configured in Settings
• Behavior: Tools from connected MCP servers are injected as first-class LangChain tools alongside built-in tools
• Per-tool control: Individual MCP tools can be disabled per-agent via the tool toggles in the agent editor
• Cleanup: MCP server connections are automatically closed when the chat ends

schedule_wake

Set a conversational timer to wake the agent up in the current chat.

• Use case: Remind the agent to check back on a long-running process, follow up with the user, or revisit a topic after a delay
• Tool: schedule_wake
• Inputs: delayMinutes (1–1440) and message (reminder text passed back to the agent when it wakes)
• Behavior: Uses persisted watch jobs instead of a transient in-memory timer. Enqueues a system event and triggers a heartbeat tick when the wake fires
• Requirement: Heartbeat must be active on the chat for the wake event to be processed

monitor

System inspection plus durable watch creation.

• Tool: monitor_tool
• Actions: sys_info, watch_log, ping, create_watch, list_watches, get_watch, cancel_watch
• Use case: Inspect runtime state and create durable watches across time, HTTP, file, task, webhook, page, mailbox, and approval events
• Behavior: best paired with heartbeat-enabled chats or long-running autonomous sessions

connector_message_tool

Send proactive outbound messages via running connectors (for example WhatsApp updates from agents).

• Use case: Status updates, alerts, and proactive follow-ups outside the dashboard
• Actions: list_running, list_targets, send
• Send fields: message plus optional imageUrl, fileUrl, mimeType, fileName, caption
• Notes: Platform media support varies by connector/runtime capabilities

Platform Tools

Platform tools let agents manage SwarmClaw resources directly — creating tasks, scheduling jobs, and managing other agents programmatically.

Enable these per-agent in the Platform section of the agent editor or via the tools popover in chat.

For ongoing, agentic workflows, combine:

• orchestrator to delegate work across agents
• manage_tasks to maintain a visible execution backlog
• manage_schedules to run recurring follow-ups
• manage_agents to spin up specialist agents
• manage_connectors to keep outbound channel integrations ready

Orchestrator Capability

The orchestrator toggle controls whether an agent can delegate tasks to other agents. When enabled, the agent gets access to the delegate_to_agent tool which creates tasks on the board assigned to a target agent.

• Agents are aware of each other's capabilities and status via the agent awareness system prompt
• Delegation creates a task with optional immediate queuing
• Task results are pushed back to both the executing agent's thread and the delegating agent's thread

If an agent without orchestrator tries to delegate, it will be prompted to request access via the tool request UI.

Assignment Scope

When manage_tasks or manage_schedules is enabled, an Assign to Other Agents toggle appears in the agent editor.

• Off (default): The agent can only assign tasks and schedules to itself. It won't see a list of other agents and attempts to assign to others are blocked server-side.
• On: The agent sees all available agents and can assign tasks and schedules to any of them.

The default Assistant agent ships with this toggle on. New agents default to off for safety — you opt in to cross-agent assignment explicitly.

Tool Access Requests

When an agent needs a tool that is not enabled, it can use the request_tool_access tool to ask the user for permission. This renders an amber banner in the chat with a Grant button.

• The agent's system prompt lists all disabled tools and instructs it to request access when needed
• Granting a tool adds it to the chat's enabled plugin list immediately
• The change applies to the next message the agent sends

This allows agents to start with a minimal tool set and request additional capabilities as needed, keeping the user in control.

File Path Preview

When agents output file paths in chat (e.g. `/tmp/my-app/index.html`), they render as interactive chips with Preview or Open buttons. HTML and SVG files open in a new tab via the /api/files/serve endpoint. Other text files are served inline.

The file serve endpoint is gated by the same access key as all other API routes and blocks access to sensitive paths (.env, .ssh, credentials).

Tool Permissions

Tools are opt-in per agent. An agent with no tools enabled can only generate text responses. Grant the minimum set of tools each agent needs.

Warning: The shell tool gives the agent full command-line access to your machine. Use with caution and never expose agents with shell access to untrusted users.