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 field in swarmlord.jsonc.

Built-in Tools

Tool	Description
bash	Execute shell commands in the sandbox. Configurable timeout, runs in /workspace by default.
read	Read file or directory contents. Returns line-numbered output for text files, directory listings for directories.
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 up to 100 matching paths.
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. Supports merge mode for partial updates.
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.
skill	Load on-demand knowledge from deployed skills. Only available when skills are deployed.

Configuring Tools

In swarmlord.jsonc, set tools to enable or disable specific tools:

{
    "tools": {
        "bash": true,
        "read": true,
        "write": true,
        "skill": true,
        "websearch": true,
        "browser": false,
    },
}

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

{
    "tools": {
        "edit": false,
        "write": false,
    },
}

Wildcard Deny Pattern

Use "*": false to deny all tools by default, then selectively enable only the ones you need. This is the safest pattern for locked-down agents:

{
    "tools": {
        "*": false,
        "read": true,
        "grep": true,
        "glob": true,
        "websearch": true,
    },
}

The above creates a research-only agent that can search and read but never write files or run commands.

Ordering: Last-Match-Wins

Entries are evaluated top-to-bottom. Later entries override earlier ones. The wildcard "*" sets a baseline, and specific tool entries after it override it.

Correct — wildcard first, then overrides:

{
    "tools": {
        "*": false, // 1. Disable everything
        "bash": true, // 2. Re-enable bash
        "read": true, // 3. Re-enable read
    },
}
// Result: only bash and read are available

Wrong — wildcard last overrides everything:

{
    "tools": {
        "bash": true, // 1. Enable bash (gets overridden)
        "read": true, // 2. Enable read (gets overridden)
        "*": false, // 3. Disable everything — this wins
    },
}
// Result: ALL tools disabled, including bash and read

tools vs permission — Two Different Layers

These fields control different aspects of tool access and merge into a single ruleset at runtime:

Field	Controls	Values
tools	Visibility — whether the tool appears in the model's tool list	true / false
permission	Execution policy — what happens when a visible tool is called	allow / deny / ask

Both use tool names directly. tools determines what the model can see; permission determines what happens when a visible tool is called. A tool must pass both layers to execute successfully.

{
    "tools": {
        "*": false,
        "bash": true,
        "read": true,
        "write": false, // write is removed from the tool list entirely
    },
    "permission": {
        "bash": "ask", // bash is visible, but each call requires approval
        "read": "allow", // read is visible and runs without approval
    },
}

Use tools to control which tools the model knows about. Use permission when you want the model to see a tool but need runtime control over execution — for example, requiring human approval for destructive operations.

Tool Details

bash

Runs shell commands inside the sandbox. Each call executes a discrete command in /workspace by default (configurable workdir).

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. For directories, returns a listing of entries.

write

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

edit

Makes string replacements in files. Uses multiple matching strategies for resilience. Reading the file first via read is recommended. 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}). Returns up to 100 matching paths.

task

Spawns an autonomous subtask agent that shares the parent's /workspace but runs its own conversation. At most 3 subtasks run concurrently. See Multi-Agent for the full parameter reference.

todoread / todowrite

Structured task tracking within a session. todoread returns all items. todowrite creates or updates items (id, content, status, optional priority). Supports merge (default: true) for partial updates.

websearch

Web search for real-time information. Returns highlighted excerpts with titles and source URLs. Default 4 results, max 8. Use for docs lookups, package compatibility checks, and current events.

webfetch

Fetches a URL and returns extracted text content. Best for static pages, documentation, and API responses. Default 100,000 character limit. Not suited for binary content.

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. Cannot nest batch or task calls. Extra calls beyond 25 are discarded.

skill

Loads on-demand knowledge from deployed skills. The agent sees all available skill names and descriptions in the tool definition, and calls skill({ name: "..." }) to load the full content.

The skill tool is automatically omitted from the agent's tool list when no skills are deployed — zero wasted tokens.

{
    "tools": {
        "skill": true,
    },
}

Skills are defined as SKILL.md files in the skills/ directory. See CLI Reference — Skills for the full format.

Output Limits

Most tool outputs are subject to truncation: a default cap of 2,000 lines or 50 KB, whichever is hit first. Output exceeding this limit is truncated with a note indicating the full output was too large. Some tools have their own limits — batch aggregates results from up to 25 calls without the global cap, and browser content extraction has a 500,000 character limit.