Built-in Tools

File system and shell tools provided by Pi

Pi provides a set of built-in tools for file system operations and shell command execution. These tools are available to the agent by default.

Import

import {
  readTool,
  writeTool,
  editTool,
  bashTool,
  grepTool,
  findTool,
  lsTool,
  codingTools,
} from "@mariozechner/pi-coding-agent";

Tool Factories

All tools are created using factory functions that accept a working directory and optional configuration.

createReadTool

Create a tool for reading file contents.

createReadTool(cwd: string, options?: ReadToolOptions): AgentTool

cwd · string · required

Working directory for file operations

options · ReadToolOptions

Show properties

autoResizeImages · boolean

Auto-resize images to 2000x2000 max. Default: true

operations · ReadOperations

Custom file operations (for SSH, etc.)

Input Schema:

{
  path: string;        // File path (relative or absolute)
  offset?: number;     // Starting line (1-indexed)
  limit?: number;      // Max lines to read
}

Features:

• Reads text files and images (jpg, png, gif, webp)
• Auto-truncates to 2000 lines or 50KB
• Supports offset/limit for large files
• Images sent as base64 attachments

createWriteTool

Create a tool for writing file contents.

createWriteTool(cwd: string, options?: WriteToolOptions): AgentTool

cwd · string · required

Working directory for file operations

options · WriteToolOptions

Show properties

operations · WriteOperations

Custom file operations (for SSH, etc.)

Input Schema:

{
  path: string;     // File path (relative or absolute)
  content: string;  // File content to write
}

Features:

• Creates parent directories automatically
• Overwrites existing files
• Returns confirmation message

createEditTool

Create a tool for editing files using exact string replacement.

createEditTool(cwd: string, options?: EditToolOptions): AgentTool

cwd · string · required

Working directory for file operations

options · EditToolOptions

Show properties

operations · EditOperations

Custom file operations (for SSH, etc.)

Input Schema:

{
  path: string;          // File path
  oldString: string;     // String to replace
  newString: string;     // Replacement string
  replaceAll?: boolean;  // Replace all occurrences (default: false)
}

Features:

• Exact string matching (no regex)
• Fails if oldString not found
• Fails if multiple matches without replaceAll
• Shows unified diff of changes

createBashTool

Create a tool for executing bash commands.

createBashTool(cwd: string, options?: BashToolOptions): AgentTool

cwd · string · required

Working directory for command execution

options · BashToolOptions

Show properties

operations · BashOperations

Custom bash operations (for SSH, etc.)

spawnHook · BashSpawnHook

Hook called before spawning each process

Input Schema:

{
  command: string;      // Bash command to execute
  description?: string; // Optional description
}

Features:

• Executes in persistent shell session
• Streams output in real-time
• Preserves environment variables
• Auto-truncates output to 2000 lines or 50KB

createGrepTool

Create a tool for searching file contents using regex.

createGrepTool(cwd: string, options?: GrepToolOptions): AgentTool

cwd · string · required

Working directory for search operations

Input Schema:

{
  pattern: string;   // Regex pattern
  include?: string;  // File glob pattern (e.g., "*.ts")
  path?: string;     // Search directory
}

Features:

• Full regex support
• File filtering by glob pattern
• Returns file paths and line numbers
• Fast implementation using ripgrep

createFindTool

Create a tool for finding files by name pattern.

createFindTool(cwd: string, options?: FindToolOptions): AgentTool

cwd · string · required

Working directory for search operations

Input Schema:

{
  pattern: string;  // Glob pattern (e.g., "**/*.ts")
  path?: string;    // Search directory
}

Features:

• Glob pattern matching
• Sorted by modification time
• Works with any codebase size

createLsTool

Create a tool for listing directory contents.

createLsTool(cwd: string, options?: LsToolOptions): AgentTool

cwd · string · required

Working directory for file operations

Input Schema:

{
  path: string;       // Directory path
  recursive?: boolean; // List recursively (default: false)
}

Features:

• Shows file sizes and types
• Supports recursive listing
• Sorted output

Pre-built Tool Sets

codingTools

All tools for full file system access.

import { codingTools } from "@mariozechner/pi-coding-agent";

const tools = codingTools; // Uses process.cwd()

Includes: read, write, edit, bash, grep, find, ls

createCodingTools

Factory for creating coding tools with custom working directory.

import { createCodingTools } from "@mariozechner/pi-coding-agent";

const tools = createCodingTools("/path/to/project");

readOnlyTools

Read-only tools (no write, edit, or bash).

import { readOnlyTools } from "@mariozechner/pi-coding-agent";

const tools = readOnlyTools; // Uses process.cwd()

Includes: read, grep, find, ls

createReadOnlyTools

Factory for creating read-only tools with custom working directory.

import { createReadOnlyTools } from "@mariozechner/pi-coding-agent";

const tools = createReadOnlyTools("/path/to/project");

Example: Custom Tool Set

import {
  createReadTool,
  createWriteTool,
  createBashTool,
} from "@mariozechner/pi-coding-agent";

const cwd = "/path/to/project";

const tools = [
  createReadTool(cwd),
  createWriteTool(cwd),
  createBashTool(cwd, {
    spawnHook: (context) => {
      console.log(`Executing: ${context.command}`);
    },
  }),
];

Custom Operations

All tool factories support custom operations for remote file systems:

import { createReadTool, type ReadOperations } from "@mariozechner/pi-coding-agent";

const sshOperations: ReadOperations = {
  readFile: async (path) => {
    // SSH implementation
    return Buffer.from(await sshClient.readFile(path));
  },
  access: async (path) => {
    // Check if file exists via SSH
    if (!await sshClient.exists(path)) {
      throw new Error("File not found");
    }
  },
};

const readTool = createReadTool("/remote/path", {
  operations: sshOperations,
});