Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/badlogic/pi-mono/llms.txt

Use this file to discover all available pages before exploring further.

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
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
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
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
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,
});