Built-in Tools

Tools use the Vercel AI SDK tool() helper with Zod schemas. OpenHarness ships a set of built-in tools that you can use as-is, compose, or replace entirely.

Filesystem Tools

Create filesystem tools by passing a provider to the factory function:

import { createFsTools, NodeFsProvider } from "@openharness/core";

const fsTools = createFsTools(new NodeFsProvider());

This returns the following tools:

Tool	Description
`readFile`	Read file contents (supports line offset/limit for large files)
`writeFile`	Write content to a file (creates parent directories automatically)
`editFile`	Find-and-replace within a file
`listFiles`	List files and directories (optionally recursive, paginated for large listings)
`grep`	Regex search across files (automatically skips `node_modules`, `.git`, paginated for large match sets)
`deleteFile`	Delete a file or directory

Bash Tool

The bash tool runs arbitrary shell commands via bash -c:

import { createBashTool, NodeShellProvider } from "@openharness/core";

const { bash } = createBashTool(new NodeShellProvider());

Features:

Configurable timeout (default 30s, max 5min)
Automatic output truncation for large results
Captures both stdout and stderr with exit code

Using Tools with an Agent

Pass tools directly to the agent constructor:

const agent = new Agent({
  name: "dev",
  model: openai("gpt-5.4"),
  tools: { ...fsTools, bash },
});

You can selectively include tools — for example, a read-only agent:

const readOnlyAgent = new Agent({
  name: "explore",
  model: openai("gpt-5.4"),
  tools: {
    readFile: fsTools.readFile,
    listFiles: fsTools.listFiles,
    grep: fsTools.grep,
  },
});

Providers

The provider interface decouples tool logic from the runtime environment. The built-in NodeFsProvider and NodeShellProvider work in Node.js, but you can implement the interfaces for other environments:

Virtual filesystems for testing
E2B sandboxes for isolated execution
Cloudflare Workers for edge deployment
Daytona for managed dev environments

FsProvider Interface

interface FsProvider {
  readFile(path: string): Promise<string>;
  writeFile(path: string, content: string): Promise<void>;
  exists(path: string): Promise<boolean>;
  stat(path: string): Promise<FileStat>;
  readdir(path: string): Promise<DirEntry[]>;
  mkdir(path: string, options?: { recursive?: boolean }): Promise<void>;
  remove(path: string, options?: { recursive?: boolean }): Promise<void>;
  rename(oldPath: string, newPath: string): Promise<void>;
  resolvePath(path: string): string;
}

ShellProvider Interface

interface ShellProvider {
  exec(
    command: string,
    options?: {
      timeout?: number;
      cwd?: string;
      env?: Record<string, string>;
    }
  ): Promise<ShellResult>;
}

The built-in NodeFsProvider includes safety guards like file size limits and binary file detection. NodeShellProvider captures exit code, stdout, and stderr with output size limits.

Todo Tools

Create session-scoped todo tools with a pluggable store:

import { createTodoTools, InMemoryTodoStore } from "@openharness/core";

const todoStore = new InMemoryTodoStore();
const todoTools = createTodoTools({
  sessionId: "chat-123",
  store: todoStore,
});

This returns:

Tool	Description
`todowrite`	Replace the current todo list with an updated ordered list
`todoread`	Read the current todo list for the session

Todo items use typed statuses (pending, in_progress, completed, cancelled) and priorities (high, medium, low). If priority is omitted, it defaults to medium. When used with sessionEventsToUIStream(), successful todowrite calls emit a data-oh:todo.updated part so UI integrations can update without parsing raw tool output.

Getting Started

Core Concepts

Tools

Advanced

UI Integration

Resources

Filesystem Tools

Bash Tool

Using Tools with an Agent

Providers

FsProvider Interface

ShellProvider Interface

Todo Tools

​Filesystem Tools

​Bash Tool

​Using Tools with an Agent

​Providers

​FsProvider Interface

​ShellProvider Interface

​Todo Tools

Filesystem Tools

Bash Tool

Using Tools with an Agent

Providers

FsProvider Interface

ShellProvider Interface

Todo Tools