> ## Documentation Index
> Fetch the complete documentation index at: https://docs.morphllm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WarpGrep

> A code search subagent that finds relevant code in a separate context window. No embeddings, no indexing.

Coding agents spend [60% of their turns searching for code](https://www.cognition.ai/blog/under-the-hood-how-devin-finds-the-right-code). Each search dumps file contents into the main context window, crowding out the reasoning the agent actually needs.

WarpGrep fixes this by searching in a **separate context window**. It's a code search subagent: a dedicated LLM call that takes a natural language query, runs multiple grep and file-read operations, reasons about what's relevant, and returns matching code. Typical searches complete in under 6 seconds.

Anthropic found specialized subprocesses [improve task completion by 90%](https://www.anthropic.com/engineering/swe-bench-sonnet). And every file-editing agent hits the same failure: it rewrites a 500-line file to change 3 lines, burning tokens and introducing drift.

These aren't reasoning problems. They're mechanical problems, and they have mechanical solutions.

| Without Morph                                                                        | With Morph                                                                                            |
| ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| Agent rewrites a 500-line file to change 3 lines. Costs \~\$0.12, takes 8 seconds.   | Agent sends a 10-line edit snippet. Merged in under a second at 10,500 tok/s, 98% accuracy.           |
| `str_replace` fails when whitespace doesn't match. Agent re-reads the file, retries. | Fast Apply takes a lazy snippet. No re-reads, no exact-string matching.                               |
| Agent spends 60% of turns searching. Results fill the context window.                | WarpGrep searches in a separate context. Finds code in 3.8 steps. Main context stays clean.           |
| After 50 turns, chat history is 80% filler. Model starts forgetting.                 | Compact removes irrelevant lines at 33,000 tok/s. 50-70% reduction. Every surviving line is verbatim. |

## Capabilities

| Capability          | What it does                               |
| ------------------- | ------------------------------------------ |
| **Codebase Search** | Search local repositories on disk          |
| **GitHub Search**   | Search public GitHub repos without cloning |
| **Streaming**       | Stream search steps back in real-time      |

## When to Use WarpGrep

**Use WarpGrep when:**

* Exploring unfamiliar code ("find the auth middleware", "how does billing work")
* Finding implementations scattered across multiple files
* Locating code by description rather than exact pattern
* Search results would pollute your main agent's context window

**Use raw grep when:**

* You already know the exact string or regex you're looking for
* You need a simple one-off pattern match
* Latency under 100ms matters (WarpGrep's LLM reasoning adds seconds)
* You don't need cross-file reasoning, just matching lines

<Note>WarpGrep's SDK is TypeScript/Node.js only. Python developers can use the [raw API protocol](/sdk/components/warp-grep/direct) or the [Python guide](/guides/warp-grep-python).</Note>

## Prerequisites

Install the SDK:

```bash theme={null}
npm install @morphllm/morphsdk
```

For **Codebase Search**, you also need [ripgrep](https://github.com/BurntSushi/ripgrep). Install via your package manager (`brew install ripgrep`, `apt-get install ripgrep`, or `choco install ripgrep`). GitHub Search runs fully on the cloud, no local dependencies needed.

Get your API key from the [Morph Dashboard](https://morphllm.com/dashboard/api-keys).

<Tip>
  WarpGrep works in sandboxed environments. Use `remoteCommands` to search code in [Vercel Sandbox, Cloudflare, E2B, and more](/sdk/components/warp-grep/sandbox-execution).
</Tip>

## Quick Start

Save the following as `search.ts`:

```typescript theme={null}
import { MorphClient } from '@morphllm/morphsdk';

async function main() {
  const morph = new MorphClient({ apiKey: process.env.MORPH_API_KEY });

  const result = await morph.warpGrep.execute({
    searchTerm: 'Find authentication middleware',
    repoRoot: '.'
  });

  if (result.success) {
    for (const ctx of result.contexts) {
      console.log(`File: ${ctx.file}`);
      console.log(ctx.content);
    }
  }
}

main();
```

Install dependencies and run:

```bash theme={null}
npm install @morphllm/morphsdk
npx tsx search.ts
```

Expected output:

```
File: src/auth/middleware.ts
export function authMiddleware(req, res, next) {
  const token = req.headers.authorization;
  ...
}
```

<Tip>
  `repoRoot` is relative to where you run your script. Use an absolute path (e.g., `path.resolve('./myproject')`) to avoid searching the wrong directory.
</Tip>

## Pricing

| Type   | Price                |
| ------ | -------------------- |
| Input  | \$0.80 per 1M tokens |
| Output | \$0.80 per 1M tokens |

## Next Steps

<Card title="Add WarpGrep to Your Agent" icon="wrench" href="/sdk/components/warp-grep/tool">
  Add WarpGrep as a tool to your Anthropic, OpenAI, or Vercel AI SDK agent.
</Card>

<CardGroup cols={2}>
  <Card title="Raw Protocol" icon="code" href="/sdk/components/warp-grep/direct">
    Build a custom harness in any language
  </Card>

  <Card title="Examples" icon="folder-open" href="https://github.com/morphllm/examples/tree/main/warpgrep">
    10 self-contained examples in TypeScript and Python
  </Card>
</CardGroup>