Tools

edge-pi provides 7 built-in tools for file system operations and command execution. Each tool is a factory function that returns a Vercel AI SDK tool() definition.

Tool Sets

Tools are grouped into pre-configured sets. You can also create individual tools with the factory functions.

import {
  createCodingTools,    // read, bash, edit, write
  createReadOnlyTools,  // read, grep, find, ls
  createAllTools,       // all 7 tools
} from "edge-pi";

const tools = createAllTools(process.cwd());

read

Read file contents with optional offset and line limit.

import { createReadTool } from "edge-pi";
const readTool = createReadTool(process.cwd());

Parameters

Name	Type	Required	Description
`path`	string	Yes	File path (relative or absolute). Supports `~` expansion.
`offset`	number	No	Line number to start reading from (1-indexed).
`limit`	number	No	Maximum number of lines to read.

Output

Truncated to 2000 lines or 50KB (whichever is hit first)
Detects image files by extension and returns a placeholder message
Includes truncation notice when output is clipped

bash

Execute shell commands in the working directory.

import { createBashTool } from "edge-pi";
const bashTool = createBashTool(process.cwd());

Parameters

Name	Type	Required	Description
`command`	string	Yes	The bash command to execute.
`timeout`	number	No	Timeout in seconds.

Output

Combined stdout and stderr, truncated to 2000 lines or 50KB
Full output saved to a temp file when truncated (path included in output)
Kills the full process tree on abort or timeout

edit

Make surgical edits to files by matching exact text and replacing it.

import { createEditTool } from "edge-pi";
const editTool = createEditTool(process.cwd());

Parameters

Name	Type	Required	Description
`path`	string	Yes	File path to edit.
`oldText`	string	Yes	Text to find. Must match exactly (or via fuzzy normalization).
`newText`	string	Yes	Replacement text.

Behavior

Exact match first, then falls back to fuzzy matching (normalized whitespace, smart quotes, dashes)
Validates that the match is unique (fails if multiple matches)
Returns a unified diff of the change
Preserves line endings (CRLF/LF) and BOM

write

Create or overwrite files.

import { createWriteTool } from "edge-pi";
const writeTool = createWriteTool(process.cwd());

Parameters

Name	Type	Required	Description
`path`	string	Yes	File path to write.
`content`	string	Yes	Content to write.

Behavior

Automatically creates parent directories if they don't exist
Overwrites existing files

grep

Search file contents with regex or literal patterns. Uses ripgrep when available, with a built-in fallback.

import { createGrepTool } from "edge-pi";
const grepTool = createGrepTool(process.cwd());

Parameters

Name	Type	Required	Description
`pattern`	string	Yes	Regex or literal search pattern.
`path`	string	No	Directory to search in.
`glob`	string	No	File glob filter (e.g., `*.ts`).
`ignoreCase`	boolean	No	Case-insensitive search.
`literal`	boolean	No	Treat pattern as a literal string.
`context`	number	No	Lines of context before and after matches.
`limit`	number	No	Maximum matches (default: 100).

Behavior

Respects .gitignore
Truncates long lines to 500 characters
Output truncated to 50KB

find

Find files by glob pattern. Uses fd when available, with a built-in fallback.

import { createFindTool } from "edge-pi";
const findTool = createFindTool(process.cwd());

Parameters

Name	Type	Required	Description
`pattern`	string	Yes	Glob pattern (e.g., `*/.ts`).
`path`	string	No	Directory to search in.
`limit`	number	No	Maximum results (default: 1000).

Behavior

Respects .gitignore
Output truncated to 50KB

ls

List directory contents with metadata.

import { createLsTool } from "edge-pi";
const lsTool = createLsTool(process.cwd());

Parameters

Name	Type	Required	Description
`path`	string	No	Directory to list (defaults to cwd).
`limit`	number	No	Maximum entries (default: 500).

Behavior

Directories are suffixed with /
Includes dotfiles
Alphabetically sorted

Custom Tools

You can add custom tools using the tools config option:

import { CodingAgent } from "edge-pi";
import { tool } from "ai";
import { z } from "zod";

const myTool = tool({
  description: "Get the current weather",
  parameters: z.object({
    city: z.string().describe("City name"),
  }),
  execute: async ({ city }) => {
    return `Weather in ${city}: Sunny, 72°F`;
  },
});

const agent = new CodingAgent({
  model,
  tools: { weather: myTool },
});