Semantic Search

Search code using natural language queries. Two-stage retrieval: vector search (fast, broad) + GPU reranking (precise).

Push your code with morph.git.push() first (see Repo Storage). Embedding takes 3-8 seconds in background.

Installation

npm install @morphllm/morphsdk

Quick Start

MorphClient
Anthropic
OpenAI
Vercel AI SDK

import { MorphClient } from '@morphllm/morphsdk';

const morph = new MorphClient({ apiKey: "YOUR_API_KEY" });

// Direct search
const results = await morph.codebaseSearch.search({
  query: "How does JWT validation work?",
  repoId: 'my-project', // will use latest main
  target_directories: [],
  limit: 10,
  // Optional: search specific branch or commit
  // branch: 'develop',
  // commitHash: 'abc123...'
});

console.log(`Found ${results.results.length} matches`);

import Anthropic from '@anthropic-ai/sdk';
import { MorphClient } from '@morphllm/morphsdk';

const morph = new MorphClient({ apiKey: "YOUR_API_KEY" });
const anthropic = new Anthropic();

// Tool inherits API key from MorphClient
const tool = morph.anthropic.createCodebaseSearchTool({ 
  repoId: 'my-project',
  // branch: 'develop',
  // commitHash: 'abc123...'
});

const response = await anthropic.messages.create({
  model: "claude-sonnet-4-5-20250929",
  tools: [tool],
  messages: [{ 
    role: "user", 
    content: "Find the authentication code" 
  }],
  max_tokens: 12000
});

import OpenAI from 'openai';
import { MorphClient } from '@morphllm/morphsdk';

const morph = new MorphClient({ apiKey: "YOUR_API_KEY" });
const openai = new OpenAI();

// Tool inherits API key from MorphClient
const tool = morph.openai.createCodebaseSearchTool({ 
  repoId: 'my-project',
  // branch: 'develop',
  // commitHash: 'abc123...'
});

const response = await openai.chat.completions.create({
  model: "gpt-4o",
  tools: [tool],
  messages: [{ 
    role: "user", 
    content: "Find the authentication code" 
  }]
});

import { generateText, stepCountIs } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';
import { MorphClient } from '@morphllm/morphsdk';

const morph = new MorphClient({ apiKey: "YOUR_API_KEY" });

// Tool inherits API key from MorphClient
const tool = morph.vercel.createCodebaseSearchTool({ 
  repoId: 'my-project',
  // branch: 'develop',
  // commitHash: 'abc123...'
});

const result = await generateText({
  model: anthropic('claude-sonnet-4-5-20250929'),
  tools: { codebaseSearch: tool },
  prompt: "Figure out how to add 2FA to the authentication code",
  stopWhen: stepCountIs(5)
});

How It Works

Two-stage retrieval (~1000ms total):

Vector search (~240ms) - Embed query, HNSW index retrieves top 50 candidates
GPU rerank (~630ms) - morph-rerank-v3 scores for precision
Returns top 10 most relevant

Why two stages? Vector search is fast but imprecise. Reranking is slow but accurate. Together = fast + accurate.

Direct Usage

const results = await morph.codebaseSearch.search({
  query: "Where is JWT validation implemented?",
  repoId: 'my-project',
  target_directories: [], // Empty = all, or ["src/auth"]
  limit: 10,
  // Optional: search specific branch or commit
  // branch: 'develop',        // Uses latest commit on 'develop'
  // commitHash: 'abc123...'   // Uses exact commit (takes precedence)
});

console.log(`Found ${results.results.length} matches in ${results.stats.searchTimeMs}ms`);
results.results.forEach(r => {
  console.log(`${r.filepath} - ${(r.rerankScore * 100).toFixed(1)}% match`);
  console.log(r.content);
});

Search Tips

Good queries:

“Where is JWT validation implemented?”
“Show database error handling”
“Find the login flow”

Avoid:

Single words (“auth”)
Too vague (“code”)
Too broad (“everything”)

Searching Specific Branches or Commits

By default, semantic search uses the latest commit on main. You can search specific branches or exact commits:

Latest Main (default)
Specific Branch
Exact Commit

// Searches latest commit on 'main' branch
const results = await morph.codebaseSearch.search({
  query: "How does auth work?",
  repoId: 'my-project'
});

// Searches latest commit on 'develop' branch
const results = await morph.codebaseSearch.search({
  query: "How does auth work?",
  repoId: 'my-project',
  branch: 'develop'
});

// Searches specific commit (e.g., for debugging)
const results = await morph.codebaseSearch.search({
  query: "How does auth work?",
  repoId: 'my-project',
  commitHash: 'abc123def456...'
});

Priority: commitHash (if provided) > branch (if provided) > main (default)

API

Input:

{
  query: string,              // Natural language question
  repoId: string,             // Repository ID
  branch?: string,            // Optional: branch name (uses latest commit)
  commitHash?: string,        // Optional: specific commit (takes precedence)
  target_directories: string[], // Filter paths, or [] for all
  limit?: number              // Max results (default: 10)
}

Returns:

{
  success: boolean,
  results: [{
    filepath: string,         // "auth.ts::login@L5-L20"
    content: string,          // Code chunk
    rerankScore: number,      // 0-1 relevance (use this!)
    language: string,
    startLine: number,
    endLine: number
  }],
  stats: { searchTimeMs: number }
}

Get Started

Models

API Reference

Integrations

Installation

Quick Start

How It Works

Direct Usage

Search Tips

Searching Specific Branches or Commits

API

​Installation

​Quick Start

​How It Works

​Direct Usage

​Search Tips

​Searching Specific Branches or Commits

​API

Installation

Quick Start

How It Works

Direct Usage

Search Tips

Searching Specific Branches or Commits

API