Skip to main content

Agent Tools

@baleybots/agent-tools provides host coding tools — filesystem, bash, and scoped workspace access — for Baleybots processors. These are concrete tools you attach to a Baleybot tool loop.

This is not the BAL package. For pipeline composition DSL, see BAL tools. For defining your own tools, use tool() from @baleybots/core.

Install​

bun add @baleybots/agent-tools @baleybots/core zod

Peer dependencies: @baleybots/core >=0.0.1-alpha.100, zod ^4.3.6.

Exports​

ExportPurpose
bashTool, createBashToolRun shell commands (cwd-relative)
readFileTool, writeFileTool, editFileToolFile read / write / patch
listDirectoryTool, fileInfoToolDirectory listing and metadata
createFilesystemToolsThe five filesystem tools bound to a root directory

Subpath imports are available: @baleybots/agent-tools/bash and /filesystem.

Scoped workspace​

Bind tools to a project directory so paths resolve inside it:

import { Baleybot, Output } from '@baleybots/core';
import { createBashTool, createFilesystemTools } from '@baleybots/agent-tools';
import { z } from 'zod';

const workingDir = '/path/to/project';
const tools = {
bash: createBashTool({ workingDir }),
...createFilesystemTools({ root: workingDir }),
};

const coder = Baleybot.create({
name: 'coder',
goal: 'Help edit this repository. Use read_file and edit_file before changing code.',
tools,
output: Output.object({
schema: z.object({ summary: z.string() }),
}),
});

const result = await coder.process('Find the main entry point and describe what it does.');
console.log(result.summary);

createFilesystemTools({ root }) returns read_file, write_file, edit_file, list_directory and file_info. Paths resolve against root and must stay inside it; a function root is read on every call. createBashTool({ workingDir }) returns bash, which runs with workingDir as its cwd (the cwd is not a sandbox).

Options on createFilesystemTools:

  • ignoreFilter trims list_directory output (explicit reads and writes are not blocked).
  • elevateRoot names a second root a call reaches with outside_workspace: true; such a call always needs approval.
  • describe replaces the model-facing description of a tool, by tool name.

Unscoped tools​

Use individual exports when the host already manages cwd or you want one capability:

import { Baleybot } from '@baleybots/core';
import { bashTool, readFileTool } from '@baleybots/agent-tools';

const bot = Baleybot.create({
name: 'dev',
goal: 'Run commands and read files in the current working directory.',
tools: { bash: bashTool, read_file: readFileTool },
});

Where these are used​

Shared by the CLI, the agent server (apps/server), and any host that needs filesystem/bash access without re-implementing path validation. Coding tools moved out of @baleybots/tools (now BAL-only) in alpha.171 — see Alpha 171 migration.

  • Tools — core tool() helper and stopWhen
  • BAL tools — declarative pipeline DSL (different package)
  • MCP — remote tools from MCP servers