codebase_warpsearch Tool

Relevant source files

The following files were used as context for generating this wiki page:

• src/tools/warpgrep.ts
• src/format.ts
• src/routing.ts
• README.md
• test/morph.test.ts
• AGENTS.md

The codebase_warpsearch tool is an agentic natural-language search utility integrated into the oh-my-pi-plugin-morph extension. It enables fast, multi-turn exploration of a local project worktree by leveraging the Morph SDK's WarpGrep capabilities. Unlike traditional grep tools that require exact string matches, this tool is designed for exploratory queries such as finding authentication flows, error handling patterns, or database configurations.

It operates within the oh-my-pi environment, providing developers and AI agents with a high-level search interface that returns relevant file sections and line numbers. The tool is preferred for broad architectural questions, while native search tools remain recommended for exact symbol lookups.

Sources: src/tools/warpgrep.ts:25-30, README.md:46-51, AGENTS.md:21-23

Architecture and Data Flow

The codebase_warpsearch tool functions as a wrapper around the warpGrep.execute method provided by the Morph SDK. When invoked, it initiates a generator-based search process that can span multiple "turns." During each turn, the tool may perform internal steps like running ripgrep, reading files, or listing directories to refine the context.

Execution Flow

The following diagram illustrates the lifecycle of a search request:

The tool ensures safety by checking for the MORPH_API_KEY before execution and monitoring an AbortSignal to allow for prompt cancellation of long-running searches.

Sources: src/tools/warpgrep.ts:57-111, test/morph.test.ts:474-489

Component Specifications

Input Parameters

The tool accepts a single parameter defined using Zod validation.

Parameter	Type	Description
search_term	string	A natural language query describing what to find in the codebase.

Sources: src/tools/warpgrep.ts:50-54

Tool Configuration and Registration

The tool is registered with specific metadata to guide the AI agent's behavior and routing.

Property	Value	Description
name	codebase_warpsearch	Unique identifier for the tool.
label	Codebase Warpsearch	Human-readable label.
approval	read	Approval tier required for execution.
note	"Searches the current project worktree..."	Appended runtime note for routing hints.

Sources: src/tools/warpgrep.ts:57-61, src/routing.ts:21-23, README.md:52

Result Formatting and XML Enveloping

Results from the Morph SDK are processed through formatWarpGrepResult. This function handles error states, empty results, and the conversion of successful matches into a structured text format.

Key formatting features include:

• XML Enveloping: File contents are wrapped in <file> tags with path and lines attributes.
• Security: XML metacharacters (&, <, >, ") are escaped to prevent repository content from breaking the formatting envelope.
• Validation: File paths are validated using PLAUSIBLE_PATH_RE to ensure they are not malformed.

Implementation Details

The core logic resides in makeWarpgrepCodebase, which manages the streaming interface of the Morph SDK.

// src/tools/warpgrep.ts:77-94
const generator = warpGrep.execute({
  searchTerm: params.search_term,
  repoRoot: ctx.cwd,
  streamSteps: true,
});

let turnCount = 0;
let result: WarpGrepResult;

for (;;) {
  throwIfAborted(signal);
  const { value, done } = await raceAbort(generator.next(), signal);
  if (done) {
    result = await Promise.resolve(value);
    break;
  }
  turnCount = value.turn;
  onUpdate?.(
    textToolResult(`WarpGrep turn ${value.turn}: ${value.toolCalls?.map((tc) => tc.name).join(", ") ?? "..."}`),
  );
}

The tool uses raceAbort to ensure that if the user cancels the operation, the generator's execution is immediately interrupted, preventing unnecessary API calls and resource consumption.

Sources: src/tools/warpgrep.ts:77-94, test/morph.test.ts:560-580

Comparison with Native Tools

The project maintains a clear "routing policy" defined in src/routing.ts and AGENTS.md to help agents choose between codebase_warpsearch and native utilities.

• Use codebase_warpsearch: For exploratory or natural-language questions where the agent needs to find context across the entire worktree.
• Use Native grep: For exact symbol, variable, or string lookups where the specific target is already known.

Sources: src/routing.ts:54-58, AGENTS.md:21-23

Summary

The codebase_warpsearch tool provides a powerful, agentic search interface for local codebases within the oh-my-pi ecosystem. By wrapping Morph's multi-turn search generator, it allows agents to resolve complex, high-level queries that would otherwise require manual grep-and-read loops. Its implementation prioritizes security through XML escaping and responsiveness via robust abort signal handling.