github_warpsearch Tool
Relevant source files
The following files were used as context for generating this wiki page:
The github_warpsearch tool provides grounded code context search for public GitHub repositories. It leverages Morph's hosted WarpGrep engine to search indexed public repositories without requiring the user to clone them locally. This tool is specifically designed for exploratory questions regarding how open-source libraries, SDKs, or frameworks work internally.
Within the oh-my-pi-plugin-morph project, this tool is registered as a read-only extension tool. It is preferred over web searches or standard documentation fetching, particularly when documentation URLs are unreachable or when implementation-level details are required from the source code directly.
Sources: src/tools/warpgrep.ts:32-47, README.md:12, README.md:65-71
Execution Logic and Data Flow
The tool execution involves resolving a repository locator, performing a pre-flight repository lookup, and then executing the remote WarpGrep search via the Morph API.
Repository Resolution and Pre-flight
Before calling the Morph API, the tool validates and resolves the repository target from the provided parameters. It supports two primary formats: owner/repo strings or full GitHub URLs. A pre-flight check using lookupGitHubRepository is performed to ensure the repository exists and is accessible. If the repository is not found, the tool attempts to fetch suggestions to guide the user toward the correct repository name.
Sources: src/tools/warpgrep.ts:168-185, test/morph.test.ts:446-455
Search Execution
The primary search logic utilizes the warpGrep.searchGitHub method from the Morph SDK. This process is wrapped in a raceAbort mechanism to ensure that the operation can be promptly cancelled if the underlying AbortSignal is triggered.
The flow ensures repository validity before consuming remote API resources.
Sources: src/tools/warpgrep.ts:187-210, test/morph.test.ts:742-788
Configuration and Parameters
The tool's behavior is influenced by environment variables and the specific parameters provided during the tool call.
Environment Variables
| Variable | Default | Description |
|---|---|---|
MORPH_API_KEY | Required | Morph API key used for authentication. If missing, the tool returns setup guidance. |
MORPH_WARPGREP_GITHUB | true | Enables or disables the registration of the github_warpsearch tool. |
MORPH_WARPGREP | true | If enabled, the tool description includes a note suggesting codebase_warpsearch for local files. |
Sources: src/config.ts:1-29, README.md:27-38, src/tools/warpgrep.ts:152-154
Input Parameters
The tool accepts a set of parameters defined using Zod for validation.
| Parameter | Type | Description |
|---|---|---|
search_term | String | Natural language query describing what to find (e.g., "How does retry logic work?"). |
owner_repo | String (Optional) | GitHub repository in owner/repo format. |
github_url | String (Optional) | Full GitHub repository URL. |
branch | String (Optional) | Specific branch to search; defaults to the repository's default branch. |
Sources: src/tools/warpgrep.ts:139-150
Result Formatting and Security
Search results from Morph are processed to ensure they are readable and safe for the agent to consume.
XML-like Enveloping
The results are formatted using <file> tags that include the file path and line ranges. To prevent malicious repositories or search results from breaking the formatting or injecting instructions, all file paths and contents are escaped for XML metacharacters.
Sources: src/format.ts:153-171, src/format.ts:187-213
Sequence of Result Generation
The following sequence describes how a successful search result is compiled and returned.
The formatter filters for valid contexts, checking for plausible paths and non-empty content before enveloping.
Sources: src/tools/warpgrep.ts:212-214, src/format.ts:173-213
Routing and Usage Policy
The project implements a "Morph-first" routing policy. When MORPH_API_KEY is configured, the system prompt is updated via a routing hint to prioritize github_warpsearch over web searches or manual documentation fetching for public code internals.
- Use Case: "How does the authentication flow work in
vercel/next.js?" - Guidance: Prefer this tool when documentation URLs return 404s or when deep implementation details of an open-source dependency are needed.
- Limitation: This tool is for remote public repositories only. For the current checked-out workspace,
codebase_warpsearchmust be used instead.
Sources: src/routing.ts:57-59, src/routing.ts:77-79, src/tools/warpgrep.ts:32-47
Error Handling
The tool distinguishes between repository resolution failures and search execution failures:
- Resolution Failure: Occurs if the repository cannot be found on GitHub. The tool provides a list of suggested repositories under the same owner to prevent "guessing" loops by the agent.
- Search Failure: Occurs if the repository exists but the Morph search fails (e.g., API timeout or internal error). In this case, the tool explicitly states that the repository was reachable but the search failed.
Sources: src/tools/warpgrep.ts:119-128, src/tools/warpgrep.ts:193-200, test/morph.test.ts:805-824
Summary
The github_warpsearch tool provides an efficient, agentic way to explore public GitHub codebases without local cloning. By integrating Morph's indexing with strict pre-flight repository validation and XML-safe result formatting, it offers a secure and reliable mechanism for agents to understand the internal workings of external dependencies and libraries.