Tools

Identifier	Module	Parameters schema	Result schema	Notes
readFile	src/tools/FileTools.ts	{ filePath: string }	{ filePath: string; content: string }	Validates path with PathValidation.
writeFile	src/tools/FileTools.ts	{ filePath: string; content: string }	{ filePath: string; size: number; created?: boolean; diff?: string; stats?: DiffStats }	Computes diff and change stats.
fileExists	src/tools/FileTools.ts	{ filePath: string }	{ filePath: string; exists: boolean; type?: "file" | "directory" | "other" }	Uses fs.stat.
renderMarkdown	src/tools/FileTools.ts	{ filePath: string; includeHtml?: boolean }	{ filePath: string; isMarkdown: boolean; content: string; plainText: string; metadata: MarkdownMeta }	Parses headings, links, and code blocks.
glob	src/tools/SearchTools.ts	{ pattern: string; cwd?: string; dot?: boolean; absolute?: boolean; onlyFiles?: boolean; maxResults?: number }	{ pattern: string; matches: string[]; count: number; truncated: boolean; cwd: string }	Uses Bun.Glob.
grep	src/tools/SearchTools.ts	{ pattern: string; isRegex?: boolean; includePatterns?: string[]; excludePatterns?: string[]; contextLines?: number; maxResults?: number; searchPath?: string }	{ pattern: string; isRegex: boolean; filesSearched: number; matches: GrepMatch[]; truncated: boolean }	Executes rg via Command.
editFile	src/tools/EditTools.ts	{ filePath: string; oldString: string; newString: string; replaceAll?: boolean; preview?: boolean; force?: boolean }	{ success: boolean; path: string; size: number; diff: string; stats: ChangeStats; validation: ValidationResult; preview?: string; message?: string }	Gates risky edits; returns diff previews.
previewEdit	src/tools/EditTools.ts	{ filePath: string; oldString: string; newString: string; replaceAll?: boolean }	{ path: string; diff: string; validation: ValidationResult; recommendation: "proceed" | "review" | "abort" }	Provides dry-run preview.
listDirectories	src/tools/DirectoryTools.ts	{ path?: string; depth?: number }	{ path: string; entries: DirectoryEntry[] }	Lists files/directories with metadata.

Type definitions such as DiffStats, GrepMatch, and DirectoryEntry live alongside their modules.

Inspect schemas in code

Open each tool file to see the full schema definitions. They double as documentation—what you see in the reference table comes directly from those structs.

Examples

readFile

• Purpose: Return the contents of a file inside the workspace.

const result = yield * fileTools.readFile({ filePath: 'README.md' })
// → { filePath: "README.md", content: "...markdown..." }

writeFile

• Purpose: Write new content and compute a diff against the previous version.

const result =
  yield *
  fileTools.writeFile({
    filePath: 'src/example.ts',
    content: 'export const demo = 1;\n',
  })
// → diff + stats when changes occur

fileExists

• Purpose: Check whether a path exists and classify its type.

const result = yield * fileTools.fileExists({ filePath: 'website/docs' })
// → { filePath: "website/docs", exists: true, type: "directory" }

renderMarkdown

• Purpose: Parse markdown, return metadata, and optionally HTML.

const result =
  yield *
  fileTools.renderMarkdown({
    filePath: 'docs/build-series/overview.mdx',
  })
// → headings, links, code block counts, plain text body

glob

• Purpose: Scan the workspace with Bun's glob implementation.

const result = yield * searchTools.glob({ pattern: 'src/**/*.ts' })
// → sorted match list with truncation flag

grep

• Purpose: Use ripgrep to find content with optional include/exclude patterns.

const result =
  yield *
  searchTools.grep({
    pattern: 'Effect.gen',
    contextLines: 1,
    maxResults: 20,
  })
// → matches with surrounding context

previewEdit

• Purpose: Produce a diff and validation warnings without writing to disk.

const preview =
  yield *
  editTools.previewEdit({
    filePath: 'src/chat/ChatProgram.ts',
    oldString: 'Goodbye!',
    newString: 'See you soon!',
  })
// → { diff, validation, recommendation }

editFile

• Purpose: Apply a replacement with gating and change statistics.

const result =
  yield *
  editTools.editFile({
    filePath: 'src/chat/ChatProgram.ts',
    oldString: 'Goodbye!',
    newString: 'See you soon!',
  })
// → success flag, diff, stats; may return preview-only when validation warns

listDirectories

• Purpose: Enumerate directory entries with metadata (size, type, depth).

const result =
  yield *
  directoryTools.listDirectories({
    path: 'website/docs',
    depth: 1,
  })
// → entries: [{ name, path, type, size, depth }, ...]