Tools System

All 21 built-in tools that the AI agent can use to interact with the filesystem, execute code, search the web, and more.

Tool Categories

📁

File Operations (5)

Read, write, edit, multi-edit, and delete files

🔍

Search & Discovery (4)

Glob search, grep, list directory, repo map

▶

Code & Execution (3)

Shell exec, file run, code verify

🌐

Web Access (2)

Fetch URLs, search the web

🧠

Intelligence (2)

Codebase search, view diff

🛠

Agent Control (3)

Sub-agent, todo tracking, system info

File Operations

file_read

Reads files from the filesystem. Supports text files with optional offset/limit for reading specific line ranges, image files (returns base64 for LLM description), and PDF files.

Parameters:
  path: string      — Absolute or relative file path
  offset?: number   — Starting line number (1-based)
  limit?: number    — Number of lines to read

file_write

Creates or overwrites files. Automatically creates parent directories if they don't exist. Requires write permission.

Parameters:
  path: string      — File path to create/overwrite
  content: string   — Full file content to write

file_edit

Performs find-and-replace edits on files. Uses a multi-strategy matching approach: exact match → trimmed match → case-insensitive → whitespace- ignored. This makes edits robust against minor formatting differences.

Parameters:
  path: string        — File to edit
  old_string: string  — Text to find
  new_string: string  — Replacement text

multi_edit

Applies multiple edits to a single file atomically. Edits are applied in reverse order to preserve line positions. All edits succeed or none do.

Parameters:
  path: string    — File to edit
  edits: Array<{
    old_string: string
    new_string: string
  }>

file_delete

Deletes files with permission checking and safe guards. Requires explicit delete permission from the user.

Parameters:
  path: string    — File path to delete

Search & Discovery

glob_search

Finds files matching glob patterns. Respects .gitignore rules and returns paths sorted by modification time.

Parameters:
  pattern: string   — Glob pattern (e.g., "**/*.ts", "src/**/test.*")
  path?: string     — Directory to search in (default: cwd)

grep_search

Searches file contents with full regex support. Case-insensitive option available.

Parameters:
  pattern: string       — Regex pattern to search for
  path?: string         — Directory to search in
  include?: string      — File glob filter (e.g., "*.ts")
  case_insensitive?: boolean

list_dir

Lists directory contents with file type indicators. Enhanced replacement for ls.

Parameters:
  path: string    — Directory path to list

view_repo_map

Generates a structural overview of the repository as an indented tree view. Useful for understanding project layout at a glance.

Parameters:
  path?: string     — Root directory (default: cwd)
  depth?: number    — Max depth to traverse

Code & Execution

shell_exec

Executes shell commands with path extraction and destructive command detection. Extracted paths are checked against read/edit/delete permission rules before execution.

Parameters:
  command: string     — Shell command to execute
  timeout?: number    — Timeout in milliseconds (default: 30000)

Destructive Command Detection

Commands containing operators like rm -rf, git reset --hard, or DROP TABLE are flagged and require explicit user approval.

file_run

Auto-detects the programming language of a file and runs it with the appropriate interpreter. Supports 14 languages: JavaScript, TypeScript, Python, Ruby, Go, Rust, Java, C, C++, PHP, Bash, Perl, Lua, and Swift.

Parameters:
  path: string      — File path to execute
  args?: string[]   — Command-line arguments
  timeout?: number  — Timeout (default: 30000ms)

code_verify

Runs syntax and type checking on the current project. Detects the project type (TypeScript, ESLint, etc.) and runs the appropriate checker.

Web Access

web_fetch

Fetches content from URLs, extracts the main text, and returns it. Domain access is controlled by the sandbox network configuration.

Parameters:
  url: string    — URL to fetch

web_search

Searches the web using DuckDuckGo (no API key required). Returns titles, URLs, and snippets.

Parameters:
  query: string    — Search query

Intelligence

codebase_search

Performs intelligent search across the indexed codebase. Combines FTS5 full-text search (35%) and vector embedding similarity (65%) for comprehensive results.

Parameters:
  query: string     — Natural language or keyword query
  path?: string     — Scope search to a directory

view_diff

Shows git diffs for working changes, staged changes, or specific commits.

Parameters:
  type?: string    — "working", "staged", or a commit hash

Agent Control

sub_agent

Spawns an independent sub-agent for parallel research tasks. Sub-agents have their own conversation context but share the same tool set.

Parameters:
  prompt: string    — Task description for the sub-agent
  name?: string     — Identifier for the sub-agent

todo

Manages task tracking with status management (pending, in_progress, completed). Visible to the user for progress tracking.

Parameters:
  action: string    — "add", "update", "complete", "list"
  task?: string     — Task description
  id?: string       — Task ID for updates

system_info

Queries the agent's own runtime state: current permissions, sandbox configuration, available tools, and active settings.

Adding a New Tool

To add a new tool to the system:

Create the tool file in packages/core/src/tools/

import { BaseTool, ToolDefinition } from "./registry";

export class MyNewTool extends BaseTool {
  definition: ToolDefinition = {
    name: "my_new_tool",
    description: "What this tool does",
    parameters: {
      type: "object",
      properties: {
        param1: { type: "string", description: "..." },
      },
      required: ["param1"],
    },
  };

  async execute(params: { param1: string }): Promise<string> {
    // Implementation
    return "result";
  }
}

Export from packages/core/src/index.ts

export { MyNewTool } from "./tools/my-new-tool";

Add an instance of your tool to the registry setup function so it becomes available to the agent.