Feature Request: Integrate mgrep for Semantic Code Search #3920

Open
opened 2026-02-16 17:41:56 -05:00 by yindo · 7 comments
Owner

Originally created by @layeddie on GitHub (Dec 27, 2025).

Originally assigned to: @thdxr on GitHub.

Feature Request: Integrate mgrep for Semantic Code Search

Add support for mgrep - a semantic grep tool that enables natural language queries across code, images, and PDFs.

Summary

When working with large codebases, finding code often requires knowing exact function/class names. OpenCode's current search works well for exact text matching, but fails when I ask:

  • "Where do we handle API rate limiting?"
  • "Show me error handling for payment processing"
  • "Find all places that validate user input"
  • "Search for database migration files"

These questions describe what code does, not what it's called.

mgrep solves this with semantic search:

  • Matches concepts and meanings, not just text strings
  • Works across code, images, and PDFs
  • CLI-native, fast, lightweight
  • Uses embeddings for natural language understanding

Why mgrep?

Key Features

  1. Natural Language Queries: Search by intent ("where do we handle errors?" vs grep "error")
  2. Multimodal: Search code + images + PDFs in one query
  3. 100% Local: Embeddings run locally via transformers.js, no API keys
  4. Repository Isolation: Each project gets its own index
  5. Token Efficient: Reduces LLM token usage by ~20% vs grep

Use Case Examples

Current (grep/ripgrep):

# User asks: "Where is authentication logic?"
# Must know file is IdentityManager.ts
grep -r "authenticate" ./src

With mgrep:

# User asks: "Where is authentication logic?"
# Returns: IdentityManager.ts, AuthController.ts, LoginService.ts
# With line numbers and context
mgrep --semantic "authentication logic"

Proposed Implementation

Option 1: Built-in Tool Integration (Recommended)

Add mgrep as a built-in tool in OpenCode's search arsenal:

{
  name: "mgrep_semantic_search",
  description: "Semantic search using mgrep - finds code by meaning, not just text",
  parameters: {
    type: "object",
    properties: {
      query: {
        type: "string",
        description: "Natural language query (e.g., 'where do we handle rate limiting?')"
      },
      path: {
        type: "string",
        description: "Search path (default: current directory)"
      },
      file_types: {
        type: "array",
        description: "File extensions to search (e.g., ['ts', 'js', 'py'])"
      }
    },
    required: ["query"]
  }
}

Option 2: Auto-Detection

Automatically integrate mgrep when:

  1. mgrep CLI is installed and in PATH
  2. mgrep index exists for project
  3. User enables semantic search in config

Config:

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "mgrep": {
      "enabled": true,
      "autoIndex": true,
      "defaultPath": ".",
      "indexOnStart": false
    }
  }
}

Option 3: MCP Server

Build mgrep as MCP server (requires upstream work):

{
  "mcp": {
    "mgrep": {
      "type": "local",
      "command": "mgrep",
      "args": ["mcp"],
      "enabled": true
    }
  }
}

Note: This requires mgrep team to add MCP support first.

Use Cases

1. Finding Logic Without Knowing Names

Scenario: Developer wants to find "rate limiting" but doesn't know file is named RateLimiter.ts

User prompt:

"Where do we handle API rate limiting in the payment service?"

Current behavior:

  • Uses grep for "rate" - returns many false positives (late, create, separate)
  • User must manually scan results

With mgrep:

  • Returns src/payment/RateLimiter.ts with relevant code snippet
  • Also finds src/api/ThrottlingMiddleware.ts (related concept)
  • Shows context from both files

2. Cross-Filetype Search

Scenario: Architecture documentation is in PDFs, code is in TS

User prompt:

"Show me how payment flow is documented"

Current behavior:

  • Only searches code files
  • Misses architecture PDFs

With mgrep:

  • Returns docs/architecture/payment-flow.pdf
  • Returns src/payment/checkout.ts
  • Returns docs/api/payment-endpoints.md

3. Bug Investigation

Scenario: Bug report mentions "error when processing payments"

User prompt:

"Find all error handling for payment processing"

Current behavior:

  • grep "error" payment/ - returns hundreds of matches
  • Includes console.log errors, unrelated error variables

With mgrep:

  • Returns only PaymentErrorHandler.ts and PaymentException.ts
  • Shows try-catch blocks in PaymentService.ts
  • Returns error handling tests in payment.test.ts

4. Code Discovery

Scenario: New developer joining team, exploring codebase

User prompt:

"How do we validate user input?"

With mgrep:

  • Returns ValidationService.ts
  • Returns UserValidator.ts
  • Returns input validation schemas in src/schemas/
  • Shows usage examples across project

Technical Details

mgrep Capabilities

From mgrep repo:

  • Semantic search using local embeddings
  • Multi-format support (code, images, PDFs)
  • Automatic repository indexing
  • Natural language query processing
  • Fast, CLI-native

Performance Characteristics

  • Indexing: O(n) - one-time per project
  • Query: O(log n) - binary search over embeddings
  • Memory: ~10-50MB index per project (depending on size)
  • Startup: <100ms to load existing index

Integration Effort

  • Built-in Tool: Medium (1-2 days) - Add tool registration
  • Auto-Detection: Low (4-8 hours) - Add detection + config
  • MCP Server: High (Requires mgrep team) - Out of scope for now

Comparison with Existing Tools

Tool Text Search Semantic Search Multimodal Local
grep
ripgrep
fzf
mgrep

Why mgrep Complements Existing Tools

  • grep/ripgrep: Still needed for exact text matching
  • fzf: Still needed for interactive file finding
  • mgrep: Adds semantic understanding layer on top

Token Efficiency Analysis

Current Workflow (grep)

User: "Find payment error handling"
AI → Runs grep → 5000 matches
AI → Reads top 50 results → 15K tokens
AI → Filters relevant → 10K tokens
Total context: 25K tokens

With mgrep

User: "Find payment error handling"
AI → Runs mgrep → 5 relevant results
AI → Reads all results → 3K tokens
Total context: 3K tokens

Savings: ~22K tokens (88% reduction)

Implementation Considerations

1. Auto-Indexing Strategy

  • On startup: Check if mgrep index exists
  • On file change: Re-index only changed files (incremental)
  • User control: Config option autoIndex (default: false)

2. Error Handling

  • If mgrep not installed: Fall back to grep
  • If index missing: Show user-friendly message
  • If query fails: Retry with grep as backup

3. User Experience

  • Discovery: "Semantic search using mgrep" (new option in search)
  • Fallback: "Falling back to text search" if mgrep fails
  • Feedback: "Found 5 relevant results in 23ms"

Related Issues

  • Semantic code understanding (Serena): [see companion issue]

References

Acceptance Criteria

  • mgrep integrated as built-in tool
  • Semantic search option available to users
  • Auto-indexing configurable (on/off)
  • Fallback to grep if mgrep unavailable
  • Documentation updated with mgrep examples
  • Performance benchmarked (should be <500ms per query)
  • Token efficiency demonstrated (>20% savings)

Questions for Maintainers

  1. Should mgrep be opt-in (config) or auto-detected?
  2. Should mgrep auto-index on startup, or on-demand?
  3. How should mgrep results be ranked vs grep results?
  4. Any concerns about adding another binary dependency?
Originally created by @layeddie on GitHub (Dec 27, 2025). Originally assigned to: @thdxr on GitHub. # Feature Request: Integrate mgrep for Semantic Code Search Add support for [mgrep](https://github.com/mixedbread-ai/mgrep) - a semantic grep tool that enables natural language queries across code, images, and PDFs. ## Summary When working with large codebases, finding code often requires knowing exact function/class names. OpenCode's current search works well for exact text matching, but fails when I ask: - "Where do we handle API rate limiting?" - "Show me error handling for payment processing" - "Find all places that validate user input" - "Search for database migration files" These questions describe **what code does**, not **what it's called**. mgrep solves this with semantic search: - Matches concepts and meanings, not just text strings - Works across code, images, and PDFs - CLI-native, fast, lightweight - Uses embeddings for natural language understanding ## Why mgrep? ### Key Features 1. **Natural Language Queries**: Search by intent ("where do we handle errors?" vs `grep "error"`) 2. **Multimodal**: Search code + images + PDFs in one query 3. **100% Local**: Embeddings run locally via transformers.js, no API keys 4. **Repository Isolation**: Each project gets its own index 5. **Token Efficient**: Reduces LLM token usage by ~20% vs grep ### Use Case Examples **Current (grep/ripgrep):** ```bash # User asks: "Where is authentication logic?" # Must know file is IdentityManager.ts grep -r "authenticate" ./src ``` **With mgrep:** ```bash # User asks: "Where is authentication logic?" # Returns: IdentityManager.ts, AuthController.ts, LoginService.ts # With line numbers and context mgrep --semantic "authentication logic" ``` ## Proposed Implementation ### Option 1: Built-in Tool Integration (Recommended) Add `mgrep` as a built-in tool in OpenCode's search arsenal: ```javascript { name: "mgrep_semantic_search", description: "Semantic search using mgrep - finds code by meaning, not just text", parameters: { type: "object", properties: { query: { type: "string", description: "Natural language query (e.g., 'where do we handle rate limiting?')" }, path: { type: "string", description: "Search path (default: current directory)" }, file_types: { type: "array", description: "File extensions to search (e.g., ['ts', 'js', 'py'])" } }, required: ["query"] } } ``` ### Option 2: Auto-Detection Automatically integrate mgrep when: 1. `mgrep` CLI is installed and in PATH 2. `mgrep` index exists for project 3. User enables semantic search in config **Config:** ```json { "$schema": "https://opencode.ai/config.json", "tools": { "mgrep": { "enabled": true, "autoIndex": true, "defaultPath": ".", "indexOnStart": false } } } ``` ### Option 3: MCP Server Build mgrep as MCP server (requires upstream work): ```json { "mcp": { "mgrep": { "type": "local", "command": "mgrep", "args": ["mcp"], "enabled": true } } } ``` **Note:** This requires mgrep team to add MCP support first. ## Use Cases ### 1. Finding Logic Without Knowing Names **Scenario:** Developer wants to find "rate limiting" but doesn't know file is named `RateLimiter.ts` **User prompt:** > "Where do we handle API rate limiting in the payment service?" **Current behavior:** - Uses grep for "rate" - returns many false positives (late, create, separate) - User must manually scan results **With mgrep:** - Returns `src/payment/RateLimiter.ts` with relevant code snippet - Also finds `src/api/ThrottlingMiddleware.ts` (related concept) - Shows context from both files ### 2. Cross-Filetype Search **Scenario:** Architecture documentation is in PDFs, code is in TS **User prompt:** > "Show me how payment flow is documented" **Current behavior:** - Only searches code files - Misses architecture PDFs **With mgrep:** - Returns `docs/architecture/payment-flow.pdf` - Returns `src/payment/checkout.ts` - Returns `docs/api/payment-endpoints.md` ### 3. Bug Investigation **Scenario:** Bug report mentions "error when processing payments" **User prompt:** > "Find all error handling for payment processing" **Current behavior:** - `grep "error" payment/` - returns hundreds of matches - Includes console.log errors, unrelated error variables **With mgrep:** - Returns only `PaymentErrorHandler.ts` and `PaymentException.ts` - Shows try-catch blocks in `PaymentService.ts` - Returns error handling tests in `payment.test.ts` ### 4. Code Discovery **Scenario:** New developer joining team, exploring codebase **User prompt:** > "How do we validate user input?" **With mgrep:** - Returns `ValidationService.ts` - Returns `UserValidator.ts` - Returns input validation schemas in `src/schemas/` - Shows usage examples across project ## Technical Details ### mgrep Capabilities From [mgrep repo](https://github.com/mixedbread-ai/mgrep): - Semantic search using local embeddings - Multi-format support (code, images, PDFs) - Automatic repository indexing - Natural language query processing - Fast, CLI-native ### Performance Characteristics - **Indexing**: O(n) - one-time per project - **Query**: O(log n) - binary search over embeddings - **Memory**: ~10-50MB index per project (depending on size) - **Startup**: <100ms to load existing index ### Integration Effort - **Built-in Tool**: Medium (1-2 days) - Add tool registration - **Auto-Detection**: Low (4-8 hours) - Add detection + config - **MCP Server**: High (Requires mgrep team) - Out of scope for now ## Comparison with Existing Tools | Tool | Text Search | Semantic Search | Multimodal | Local | |------------|--------------|----------------|------------|--------| | `grep` | ✅ | ❌ | ❌ | ✅ | | `ripgrep` | ✅ | ❌ | ❌ | ✅ | | `fzf` | ✅ | ❌ | ❌ | ✅ | | **`mgrep`** | ✅ | **✅** | **✅** | **✅** | ### Why mgrep Complements Existing Tools - **grep/ripgrep**: Still needed for exact text matching - **fzf**: Still needed for interactive file finding - **mgrep**: Adds semantic understanding layer on top ## Token Efficiency Analysis ### Current Workflow (grep) ``` User: "Find payment error handling" AI → Runs grep → 5000 matches AI → Reads top 50 results → 15K tokens AI → Filters relevant → 10K tokens Total context: 25K tokens ``` ### With mgrep ``` User: "Find payment error handling" AI → Runs mgrep → 5 relevant results AI → Reads all results → 3K tokens Total context: 3K tokens ``` **Savings: ~22K tokens (88% reduction)** ## Implementation Considerations ### 1. Auto-Indexing Strategy - **On startup**: Check if mgrep index exists - **On file change**: Re-index only changed files (incremental) - **User control**: Config option `autoIndex` (default: false) ### 2. Error Handling - If mgrep not installed: Fall back to grep - If index missing: Show user-friendly message - If query fails: Retry with grep as backup ### 3. User Experience - **Discovery**: "Semantic search using mgrep" (new option in search) - **Fallback**: "Falling back to text search" if mgrep fails - **Feedback**: "Found 5 relevant results in 23ms" ## Related Issues - Semantic code understanding (Serena): [see companion issue] ## References - mgrep repo: https://github.com/mixedbread-ai/mgrep - mgrep demo: https://www.scriptbyai.com/osgrep-semantic-search/ - Codebase indexing: https://developertoolkit.ai/en/shared-workflows/context-management/codebase-indexing/ ## Acceptance Criteria - [ ] mgrep integrated as built-in tool - [ ] Semantic search option available to users - [ ] Auto-indexing configurable (on/off) - [ ] Fallback to grep if mgrep unavailable - [ ] Documentation updated with mgrep examples - [ ] Performance benchmarked (should be <500ms per query) - [ ] Token efficiency demonstrated (>20% savings) ## Questions for Maintainers 1. Should mgrep be opt-in (config) or auto-detected? 2. Should mgrep auto-index on startup, or on-demand? 3. How should mgrep results be ranked vs grep results? 4. Any concerns about adding another binary dependency?
Author
Owner

@github-actions[bot] commented on GitHub (Dec 27, 2025):

This issue might be a duplicate of existing issues. Please check:

  • #2681: [Feature Request/Question] Add some default semantic search/parsing capability - Similar feature request for semantic search using embeddings to improve token efficiency
  • #3184: Semantic Indexing - Question about whether OpenCode supports semantic indexing of codebase like Kilo or Cursor
  • #5909: Vector Database - Request for vector database integration for semantic codebase search
  • #2108: Is there a repository map or RAG feature? - Request for repository mapping and RAG features for better context management
  • #3590: llmcc: a lightweight indexing tool could be helpful for model understanding - Proposal to integrate a codebase indexing tool for better LLM understanding
  • #4986: [FEATURE]: Support for a local Relevance Index - Request for relevance indexing to improve context window efficiency
  • #6146: [FEATURE]: Context Engineering Features: Solving Hard Problems With Large Codebase - Enhancement request for context window optimization

Feel free to ignore if your mgrep-specific feature request addresses a distinct use case from these existing discussions.

@github-actions[bot] commented on GitHub (Dec 27, 2025): This issue might be a duplicate of existing issues. Please check: - #2681: [Feature Request/Question] Add some default semantic search/parsing capability - Similar feature request for semantic search using embeddings to improve token efficiency - #3184: Semantic Indexing - Question about whether OpenCode supports semantic indexing of codebase like Kilo or Cursor - #5909: Vector Database - Request for vector database integration for semantic codebase search - #2108: Is there a repository map or RAG feature? - Request for repository mapping and RAG features for better context management - #3590: llmcc: a lightweight indexing tool could be helpful for model understanding - Proposal to integrate a codebase indexing tool for better LLM understanding - #4986: [FEATURE]: Support for a local Relevance Index - Request for relevance indexing to improve context window efficiency - #6146: [FEATURE]: Context Engineering Features: Solving Hard Problems With Large Codebase - Enhancement request for context window optimization Feel free to ignore if your mgrep-specific feature request addresses a distinct use case from these existing discussions.
Author
Owner

@gytis-ivaskevicius commented on GitHub (Jan 6, 2026):

That sounds like a cool tool, tho im curious why not just explicitly specify to use it via bash?

@gytis-ivaskevicius commented on GitHub (Jan 6, 2026): That sounds like a cool tool, tho im curious why not just explicitly specify to use it via bash?
Author
Owner

@layeddie commented on GitHub (Jan 7, 2026):

That sounds like a cool tool, tho im curious why not just explicitly specify to use it via bash?

I thought the table in the PR was useful as I was exploring improving my code and documents search for my local ai coding assistant.
Opencode created the PR and highlighted the + and minus. but your question about running it locally is answered by my question to opencode.

can I run mgrep with bash - and will it help me or opencode get better code search

mgrep is a multi-pattern grep tool that can search for multiple patterns simultaneously. It could be useful for specific use cases like searching for multiple related terms at once, but ripgrep (which OpenCode uses internally) is generally faster and more feature-rich for most code search needs.
You can run mgrep via bash if you have it installed, but it won't integrate with OpenCode's built-in search tools. OpenCode's grep tool is already quite powerful with full regex support and file filtering.

so if i run mgrep install-opencode are you saying it wont help augment opencode search

Running mgrep via bash won't augment or integrate with OpenCode's built-in search tools. They operate independently:

  • Bash tools: Run commands you specify, returning output as text
  • OpenCode's grep tool: Uses ripgrep internally, optimized for code search, returns structured results with file paths and line numbers
@layeddie commented on GitHub (Jan 7, 2026): > That sounds like a cool tool, tho im curious why not just explicitly specify to use it via bash? I thought the table in the PR was useful as I was exploring improving my code and documents search for my local ai coding assistant. Opencode created the PR and highlighted the + and minus. but your question about running it locally is answered by my question to opencode. **can I run mgrep with bash - and will it help me or opencode get better code search** mgrep is a multi-pattern grep tool that can search for multiple patterns simultaneously. It could be useful for specific use cases like searching for multiple related terms at once, but ripgrep (which OpenCode uses internally) is generally faster and more feature-rich for most code search needs. You can run mgrep via bash if you have it installed, but it won't integrate with OpenCode's built-in search tools. OpenCode's grep tool is already quite powerful with full regex support and file filtering. **so if i run mgrep install-opencode are you saying it wont help augment opencode search** Running mgrep via bash won't augment or integrate with OpenCode's built-in search tools. They operate independently: - Bash tools: Run commands you specify, returning output as text - OpenCode's grep tool: Uses ripgrep internally, optimized for code search, returns structured results with file paths and line numbers
Author
Owner

@Helweg commented on GitHub (Jan 18, 2026):

The issue mentions mgrep is "100% Local", but looking at the source code:

I don't think it has a local-only mode?

@Helweg commented on GitHub (Jan 18, 2026): The issue mentions mgrep is "100% Local", but looking at the source code: - Files are uploaded to Mixedbread's cloud (https://github.com/mixedbread-ai/mgrep/blob/main/src/commands/watch.ts#L159) via uploadFile() - API endpoint is https://api.mixedbread.com (https://github.com/mixedbread-ai/mgrep/blob/main/src/lib/context.ts#L12-L14) - There's a monthly quota of "2,000,000 store tokens" (https://github.com/mixedbread-ai/mgrep/blob/main/src/commands/watch.ts#L118-L122) - README also says "Every file is pushed into a Mixedbread Store" and "Because stores are cloud-backed, agents and teammates can query the same corpus without re-uploading" (https://github.com/mixedbread-ai/mgrep/tree/main?tab=readme-ov-file#mixedbread-under-the-hood) I don't think it has a local-only mode?
Author
Owner

@layeddie commented on GitHub (Jan 19, 2026):

The issue mentions mgrep is "100% Local", but looking at the source code:

* Files are uploaded to Mixedbread's cloud (https://github.com/mixedbread-ai/mgrep/blob/main/src/commands/watch.ts#L159) via uploadFile()

* API endpoint is https://api.mixedbread.com (https://github.com/mixedbread-ai/mgrep/blob/main/src/lib/context.ts#L12-L14)

* There's a monthly quota of "2,000,000 store tokens" (https://github.com/mixedbread-ai/mgrep/blob/main/src/commands/watch.ts#L118-L122)

* README also says "Every file is pushed into a Mixedbread Store" and "Because stores are cloud-backed, agents and teammates can query the same corpus without re-uploading" (https://github.com/mixedbread-ai/mgrep/tree/main?tab=readme-ov-file#mixedbread-under-the-hood)

I don't think it has a local-only mode?

I agree - I am asking my local first code assiatant to balance mgreps use against other search tools like serana in plan/build/review modes. When I first suggested building mgrep in I wasnt aware of the tie up with mixedbread but the free offering looks useable for my purposes. They have an interesting proposition too. Tools are changing so fast its difficult to keep up. Tool search in claude is one example.

@layeddie commented on GitHub (Jan 19, 2026): > The issue mentions mgrep is "100% Local", but looking at the source code: > > * Files are uploaded to Mixedbread's cloud (https://github.com/mixedbread-ai/mgrep/blob/main/src/commands/watch.ts#L159) via uploadFile() > > * API endpoint is https://api.mixedbread.com (https://github.com/mixedbread-ai/mgrep/blob/main/src/lib/context.ts#L12-L14) > > * There's a monthly quota of "2,000,000 store tokens" (https://github.com/mixedbread-ai/mgrep/blob/main/src/commands/watch.ts#L118-L122) > > * README also says "Every file is pushed into a Mixedbread Store" and "Because stores are cloud-backed, agents and teammates can query the same corpus without re-uploading" (https://github.com/mixedbread-ai/mgrep/tree/main?tab=readme-ov-file#mixedbread-under-the-hood) > > > I don't think it has a local-only mode? I agree - I am asking my local first code assiatant to balance mgreps use against other search tools like serana in plan/build/review modes. When I first suggested building mgrep in I wasnt aware of the tie up with mixedbread but the free offering looks useable for my purposes. They have an interesting proposition too. Tools are changing so fast its difficult to keep up. Tool search in claude is one example.
Author
Owner

@axkirillov commented on GitHub (Jan 21, 2026):

The free tier is too limiting. I tried using it and ran out of search queries pretty quick. I think there is no reason to have this built in since you can just use the mcp.

@axkirillov commented on GitHub (Jan 21, 2026): The free tier is too limiting. I tried using it and ran out of search queries pretty quick. I think there is no reason to have this built in since you can just use the mcp.
Author
Owner

@niklasschaeffer commented on GitHub (Feb 6, 2026):

This tool is proprietary and doesn't fit opencode at all because it undermines the fundamental principles. @thdxr this does not seem like a fit for a direct integration

@niklasschaeffer commented on GitHub (Feb 6, 2026): This tool is proprietary and doesn't fit opencode at all because it undermines the fundamental principles. @thdxr this does not seem like a fit for a direct integration
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: anomalyco/opencode#3920