Skip to main content

​
Overview

WarpGrep is a code search agent that uses a multi-turn conversation to explore repositories. The model has its tools (grep_search, read, list_directory, glob, finish) built in — you do not need to pass a tools array in your requests.

​
Model

Use morph-warp-grep-v2.1 as the model identifier.

​
Message Format

WarpGrep uses a structured format in the initial user message with flat absolute paths: 
<repo_structure>
/home/user/myproject
/home/user/myproject/README.md
/home/user/myproject/package.json
/home/user/myproject/src
/home/user/myproject/src/auth
/home/user/myproject/src/auth/login.py
/home/user/myproject/src/db
/home/user/myproject/src/utils
/home/user/myproject/tests
/home/user/myproject/config.py
/home/user/myproject/main.py
</repo_structure>

<search_string>
Find where user authentication is implemented
</search_string>

​
Format Components

  • <repo_structure>: Flat list of absolute paths — repo root first, then all files/directories to depth 2. No indentation, no tree characters, no trailing / on directories.
  • <search_string>: Natural language description of what code to find

​
Example Request

import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://api.morphllm.com/v1",
});

const repoRoot = "/home/user/myapp";
const repoStructure = `${repoRoot}
${repoRoot}/src
${repoRoot}/src/auth
${repoRoot}/src/api
${repoRoot}/src/models
${repoRoot}/tests
${repoRoot}/package.json`;

const searchQuery = "Find where JWT tokens are validated";

const response = await openai.chat.completions.create({
  model: "morph-warp-grep-v2.1",
  messages: [
    {
      role: "user",
      content: `<repo_structure>\n${repoStructure}\n</repo_structure>\n\n<search_string>\n${searchQuery}\n</search_string>`
    }
  ],
  temperature: 0.0,
  max_tokens: 2048
});

// Response has tool_calls — execute locally and continue the loop
const toolCalls = response.choices[0].message.tool_calls;
See Direct API Access for the full protocol details including tool execution and multi-turn flow.

​
Multi-Turn Conversation

WarpGrep uses built-in tool calling (up to 6 turns). The agent will:
  1. Turn 1: Analyze your search query and call tools (grep_search, list_directory, glob) to explore
  2. Turns 2-5: Refine search based on results, read specific files
  3. Final turn: Call finish with code locations
You execute tool calls locally and return results as {role: "tool", tool_call_id: "...", content: "..."} messages.

​
Request Parameters

ParameterTypeRequiredDescription
modelstringYesMust be morph-warp-grep-v2.1
messagesarrayYesArray of conversation messages
temperaturenumberNoRecommended: 0.0 for deterministic results
max_tokensnumberNoRecommended: 2048
Tools are built into the model — you do not need to pass a tools parameter. The model will return tool_calls automatically.

​
Response Format

The agent responds with structured tool_calls: 
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "morph-warp-grep-v2.1",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "",
      "tool_calls": [
        {"id": "chatcmpl-tool-abc123", "type": "function", "function": {"name": "grep_search", "arguments": "{\"pattern\": \"jwt|JWT\"}"}},
        {"id": "chatcmpl-tool-def456", "type": "function", "function": {"name": "list_directory", "arguments": "{\"command\": \"ls src/auth\"}"}}
      ]
    },
    "finish_reason": "tool_calls"
  }],
  "usage": {
    "prompt_tokens": 1180,
    "total_tokens": 1245,
    "completion_tokens": 65
  }
}
After you execute tools and return results, the agent continues until it calls finish.

​
Available Tools

WarpGrep uses five tools:
  • grep_search: Search for regex patterns across files
  • read: Read file contents with optional line ranges
  • list_directory: Explore directory structure
  • glob: Find files by name/extension pattern (sorted by mtime)
  • finish: Submit final answer with code locations
See the Direct API Guide for complete tool specifications.

​
SDK Integration

For easier integration, use the WarpGrep SDK components:

​
Error Codes

Direct API Guide

Build your own WarpGrep harness

Python Implementation

Complete Python guide with examples