Tools

Every swarmlord agent has access to a set of built-in tools. Tools are enabled by default — you control which ones an agent can use via the tools config.

Built-in Tools

Tool	Description
bash	Execute shell commands in the sandbox. Persistent session, configurable timeout, runs in /workspace by default.
read	Read file or directory contents. Supports text, images, and PDFs. Returns line-numbered output.
write	Create or overwrite files in the sandbox filesystem.
edit	Make targeted string replacements in existing files. Supports single and bulk replacements.
grep	Search file contents with regex. Filter by file pattern. Returns matching lines with file paths and line numbers.
glob	Find files by glob pattern (e.g. **/*.ts). Returns paths sorted by modification time.
task	Spawn a subtask agent for complex, multi-step work. Runs autonomously in its own session.
todoread	Read the current todo list for the session.
todowrite	Create or update todo items to track progress on complex tasks.
websearch	Search the web for real-time information — docs, APIs, package versions, current events.
webfetch	Fetch a URL and return its content as text or markdown. For static pages, docs, API responses.
browser	Control a headless Chromium browser. Screenshots, scraping, form filling, JS-rendered pages.
batch	Run up to 25 independent tool calls concurrently to reduce latency.

Configuring Tools

Pass a tools object when creating an agent. Each key is a tool name, each value is true (enabled) or false (disabled).

const agent = client.agent({
    instructions: ["Review code for security issues"],
    tools: {
        bash: true,
        read: true,
        grep: true,
        glob: true,
        edit: false,
        write: false,
    },
});

Tools you don't mention keep their default state (enabled). To create a read-only agent, disable the write tools:

const readOnly = client.agent({
    tools: {
        edit: false,
        write: false,
    },
});

To create a minimal agent with only shell and file reading:

const minimal = client.agent({
    tools: {
        bash: true,
        read: true,
        edit: false,
        write: false,
        grep: false,
        glob: false,
        task: false,
        todoread: false,
        todowrite: false,
        websearch: false,
        webfetch: false,
        browser: false,
        batch: false,
    },
});

Tool Details

bash

Runs shell commands in a persistent session inside the sandbox. Commands run in /workspace by default. Use the cwd option to change directories.

The sandbox comes with Node.js, Python 3, git, curl, and common CLI tools pre-installed. Install more with npm, pip, or apt.

read

Reads files and directories. Returns line-numbered content for text files. Also handles images (returns as attachments) and PDFs (extracts text). For directories, returns a listing of entries.

write

Creates or overwrites files. Use edit instead when making targeted changes to existing files.

edit

Makes exact string replacements in files. Requires that the file was read first (via read). Supports replaceAll for bulk renaming.

grep

Regex search across files. Supports include patterns to filter by file extension (e.g. *.ts). Returns file paths, line numbers, and matching content.

glob

Pattern-based file discovery. Supports standard glob syntax (**/*.ts, src/**/*.{js,jsx}). Results sorted by modification time.

task

Spawns an autonomous subtask agent. Useful for parallelizing work — the subtask runs in its own context and returns results when done.

todoread / todowrite

Structured task tracking within a session. The agent uses these to plan and track progress on multi-step work. todoread returns all items; todowrite creates or updates items with status, priority, and position.

websearch

Web search for real-time information. Returns summarized results with source URLs. Use for docs lookups, package compatibility checks, and current events.

webfetch

Fetches a URL and returns content as text or markdown. Best for static pages, documentation, and API responses. 5 MB max response, 30s default timeout.

browser

Headless Chromium control via Puppeteer. Actions: screenshot (capture PNG), content (get rendered text), scrape (extract by CSS selector), interact (click, type, scroll, then screenshot).

WARNING

The browser runs on a separate network from the sandbox. It cannot access localhost or servers running inside the sandbox — only publicly accessible URLs.

batch

Runs up to 25 independent tool calls concurrently. Useful when you need to read multiple files, run multiple searches, or perform other parallel operations. Cannot nest batch or task calls.