GitHub Grounded Source Integration

Relevant source files

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

• src/github.ts
• src/tools/warpgrep.ts
• src/config.ts
• src/format.ts
• src/routing.ts
• test/morph.test.ts

The GitHub Grounded Source Integration is a core feature of the Morph plugin that allows AI agents to perform agentic, natural-language searches over public GitHub repositories without requiring local cloning. It utilizes Morph's hosted WarpGrep service to provide grounded code context, enabling agents to understand the internal implementation details of external libraries, SDKs, and frameworks.

This system bridges the gap between high-level documentation and actual source code by providing a tool-based interface for repository resolution, search execution, and result formatting. It is specifically designed to handle common developer queries about library internals, such as authentication flows or error handling logic, especially when official documentation is insufficient or missing.

Sources: src/tools/warpgrep.ts:25-45, README.md

Core Architecture and Data Flow

The integration operates through the github_warpsearch tool. When an agent invokes this tool, the system follows a multi-step process: resolving the repository identity, performing pre-flight validation via the GitHub API, executing the remote search through the Morph SDK, and formatting the returned code snippets for the agent's consumption.

System Sequence Flow

The following sequence diagram illustrates the interaction between the AI Agent, the Morph Plugin, the GitHub API, and the Morph WarpGrep service.

The diagram shows the logic for resolving repository locators and the fallback mechanism for suggesting alternatives when a repository is not found.
Sources: src/tools/warpgrep.ts:160-220, src/github.ts:147-170

Repository Resolution Logic

The system supports two primary ways to identify a target repository: an owner/repo string or a full GitHub URL. The resolvePublicRepoLocator function normalizes these inputs into a canonical owner/repo format while enforcing strict validation rules.

Supported Locators and Validation

Parameter	Type	Format/Constraint	Description
owner_repo	String	^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$	GitHub repository in "owner/repo" format.
github_url	String	`https://github.com/owner/repo%60	Full URL to the repository.
branch	String	Optional	Specific branch to search; defaults to repository default.

Sources: src/github.ts:101-144, src/tools/warpgrep.ts:145-155

Implementation Details

• Regex Validation: Repository strings are validated against GITHUB_OWNER_REPO_PATTERN to ensure they match standard GitHub naming conventions.
• URL Parsing: For github_url inputs, the system verifies the hostname is github.com or www.github.com and extracts the first two path components as the owner and repository name.
• Timeout Management: GitHub API calls are wrapped in withGitHubTimeout, defaulting to a 10-second limit defined by GITHUB_RESOLVER_TIMEOUT.

Sources: src/github.ts:39, src/github.ts:117-135, src/config.ts:11

Search Execution and Morph Integration

Once the repository is resolved and verified as public, the search is offloaded to the Morph SDK's warpGrep.searchGitHub method.

WarpGrep Search Parameters

The search request includes:

• searchTerm: The natural language query from the user.
• github: The canonical owner/repo locator.
• branch: The optional target branch.

Sources: src/tools/warpgrep.ts:200-204

Result Formatting and Security

The integration uses formatWarpGrepResult to transform raw code contexts into a structured Markdown response. This includes:

• XML Envelope: File contents are wrapped in <file path="..." lines="..."> tags.
• Escaping: To prevent prompt injection or breakout from the XML structure, the system uses escapeXmlText and escapeXmlAttr to sanitize file paths and code contents.
• Line Mapping: Specific line ranges are displayed for each context to help the agent navigate the code.

// Sanitization example from src/format.ts
function escapeXmlText(value: string): string {
  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
}

Sources: src/format.ts:133-145, src/format.ts:153-170

Error Handling and Suggestions

A key feature of the GitHub integration is its proactive error handling for missing repositories. Instead of a simple "not found" error, the system attempts to guide the agent toward the correct repository.

Suggestion Generation

If a direct lookup fails with a 404, the system invokes fetchGitHubRepoSuggestions. This function:

1. Tokenizes the Search Term: Breaks the user's search query into relevant keywords.
2. Generates Multiple Queries: Constructs up to 4 search variants (e.g., user:owner, repoName, ${repoName} ${tokens}).
3. Aggregates Results: Calls the GitHub Search API (/search/repositories), sorts by stars, and de-duplicates results.
4. Limits Output: Returns up to 5 suggestions based on GITHUB_REPO_SUGGESTION_LIMIT.

Sources: src/github.ts:51-100, src/github.ts:175-230, src/config.ts:14

Configuration and Availability

The availability of GitHub Grounded Source Integration is controlled by environment variables and the presence of a valid Morph API key.

Variable	Default	Description
MORPH_API_KEY	None	Required. If missing, the tool returns setup guidance.
MORPH_WARPGREP_GITHUB	true	Toggle for enabling/disabling the github_warpsearch tool.
GITHUB_REPO_API_URL	https://api.github.com/repos	Base URL for repo metadata lookups.
GITHUB_REPO_SEARCH_URL	https://api.github.com/search/repositories	Base URL for repository suggestions.

Sources: src/config.ts:1-15, src/routing.ts:40-60

Conclusion

The GitHub Grounded Source Integration provides a robust mechanism for AI agents to interact with public codebases. By combining strict input validation, remote agentic search via WarpGrep, and a proactive suggestion system for unresolved repositories, it ensures that agents have access to accurate, grounded source code context while maintaining security through XML escaping and safe path resolution.