@mixedbread/mgrep

mgrep

A calm, CLI-native way to semantically grep everything, like code, images, pdfs and more.

Try it out in our playground!

Why mgrep?

• Natural-language search that feels as immediate as grep.
• Semantic, multilingual & multimodal (audio, video support coming soon!)
• Smooth background indexing via mgrep watch, designed to detect and keep up-to-date everything that matters inside any git repository.
• Friendly device-login flow and first-class coding agent integrations.
• Built for agents and humans alike, and designed to be a helpful tool, not a restrictive harness: quiet output, thoughtful defaults, and escape hatches everywhere.
• Reduces the token usage of your agent by 2x while maintaining superior performance

# index once
mgrep watch

# then ask your repo things in natural language
mgrep "where do we set up auth?"

Quick Start

• Install

  npm install -g @mixedbread/mgrep    # or pnpm / bun
  

• Sign in once

  mgrep login
  

  A browser window (or verification URL) guides you through Mixedbread authentication.

  Alternative: API Key Authentication For CI/CD or headless environments, set the MXBAI_API_KEY environment variable:

  export MXBAI_API_KEY=your_api_key_here
  

  This bypasses the browser login flow entirely.

• Index a project

  cd path/to/repo
  mgrep watch
  

  watch performs an initial sync, respects .gitignore, then keeps the Mixedbread store updated as files change.

• Search anything

  mgrep "where do we set up auth?" src/lib
  mgrep -m 25 "store schema"
  

  Searches default to the current working directory unless you pass a path.

Today, mgrep works great on: code, text, PDFs, images.
Coming soon: audio & video.

Using it with Coding Agents

• Claude Code (today)
  • Run mgrep install-claude-code. The command signs you in (if needed), adds the Mixedbread mgrep plugin to the marketplace, and installs it.
  • Open Claude Code, enable the plugin, and point your agent at the repo you are indexing with mgrep watch.
  • Ask Claude something just like you do locally; results stream straight into the chat with file paths and line hints.
• More agents (Codex, Cursor, Windsurf, etc.) are on the way—this section will grow as soon as each integration lands.

Making your agent smarter

We plugged mgrep into Claude Code and ran a benchmark of 50 QA tasks to evaluate the economics of mgrep against grep.

In our 50-task benchmark, mgrep+Claude Code used ~2x fewer tokens than grep-based workflows at similar or better judged quality.

mgrep finds the relevant snippets in a few semantic queries first, and the model spends its capacity on reasoning instead of scanning through irrelevant code from endless grep attempts. You can Try it yourself.

Note: Win Rate (%) was calculated by using an LLM as a judge.

Why we built mgrep

grep is an amazing tool. It's lightweight, compatible with just about every machine on the planet, and will reliably surface any potential match within any target folder.

But grep is from 1973, and it carries the limitations of its era: you need exact patterns and it slows down considerably in the cases where you need it most, on large codebases.

Worst of all, if you're looking for deeply-buried critical business logic, you cannot describe it: you have to be able to accurately guess what kind of naming patterns would have been used by the previous generations of engineers at your workplace for grep to find it. This will often result in watching a coding agent desperately try hundreds of patterns, filling its token window, and your upcoming invoice, with thousands of tokens.

But it doesn't have to be this way. Everything else in our toolkit is increasingly tailored to understand us, and so should our search tools. mgrep is our way to bring grep to 2025, integrating all of the advances in semantic understanding and code-search, without sacrificing anything that has made grep such a useful tool.

Under the hood, mgrep is powered by Mixedbread Search, our full-featured search solution. It combines state-of-the-art semantic retrieval models with context-aware parsing and optimized inference methods to provide you with a natural language companion to grep. We believe both tools belong in your toolkit: use grep for exact matches, mgrep for semantic understanding and intent.

When to use what

We designed mgrep to complement grep, not replace it. The best code search combines mgrep with grep.

Use grep (or ripgrep) for...	Use mgrep for...
Exact Matches	Intent Search
Symbol tracing, Refactoring, Regex	Code exploration, Feature discovery, Onboarding

Commands at a Glance

Command	Purpose
mgrep / mgrep search <pattern> [path]	Natural-language search with many grep-style flags (-i, -r, -m...).
mgrep watch	Index current repo and keep the Mixedbread store in sync via file watchers.
mgrep login & mgrep logout	Manage device-based authentication with Mixedbread.
mgrep install-claude-code	Log in, add the Mixedbread mgrep plugin to Claude Code, and install it for you.

mgrep search

mgrep search is the default command. It can be used to search the current directory for a pattern.

Option	Description
-m <max_count>	The maximum number of results to return
-c, --content	Show content of the results
-a, --answer	Generate an answer to the question based on the results
-s, --sync	Sync the local files to the store before searching
-d, --dry-run	Dry run the search process (no actual file syncing)
--no-rerank	Disable reranking of search results

All search options can also be configured via environment variables (see Environment Variables section below).

Examples:

mgrep "What code parsers are available?"  # search in the current directory
mgrep "How are chunks defined?" src/models  # search in the src/models directory
mgrep -m 10 "What is the maximum number of concurrent workers in the code parser?"  # limit the number of results to 10
mgrep -a "What code parsers are available?"  # generate an answer to the question based on the results

mgrep watch

mgrep watch is used to index the current repository and keep the Mixedbread store in sync via file watchers.

It respects the current .gitignore, as well as a .mgrepignore file in the root of the repository. The .mgrepignore file follows the same syntax as the .gitignore file.

Examples:

mgrep watch  # index the current repository and keep the Mixedbread store in sync via file watchers

Mixedbread under the hood

• Every file is pushed into a Mixedbread Store using the same SDK your apps get.
• Searches request top-k matches with Mixedbread reranking enabled by default for tighter relevance (can be disabled with --no-rerank or MGREP_RERANK=0).
• Results include relative paths plus contextual hints (line ranges for text, page numbers for PDFs, etc.) for a skim-friendly experience.
• Because stores are cloud-backed, agents and teammates can query the same corpus without re-uploading.

Configuration Tips

• --store <name> lets you isolate workspaces (per repo, per team, per experiment). Stores are created on demand if they do not exist yet.
• Ignore rules come straight from git, so temp files, build outputs, and vendored deps stay out of your embeddings.
• watch reports progress (processed / uploaded) as it scans; leave it running in a terminal tab to keep your store fresh.
• search accepts most grep-style switches, and politely ignores anything it cannot support, so existing muscle memory still works.

Environment Variables

All search options can be configured via environment variables, which is especially useful for CI/CD pipelines or when you want to set defaults for all searches.

Authentication & Store

• MXBAI_API_KEY: Set this to authenticate without browser login (ideal for CI/CD)
• MXBAI_STORE: Override the default store name (default: mgrep)

Search Options

• MGREP_MAX_COUNT: Maximum number of results to return (default: 10)
• MGREP_CONTENT: Show content of the results (set to 1 or true to enable)
• MGREP_ANSWER: Generate an answer based on the results (set to 1 or true to enable)
• MGREP_SYNC: Sync files before searching (set to 1 or true to enable)
• MGREP_DRY_RUN: Enable dry run mode (set to 1 or true to enable)
• MGREP_RERANK: Enable reranking of search results (set to 0 or false to disable, default: enabled)

Examples:

# Set default max results to 25
export MGREP_MAX_COUNT=25
mgrep "search query"

# Always show content in results
export MGREP_CONTENT=1
mgrep "search query"

# Disable reranking globally
export MGREP_RERANK=0
mgrep "search query"

# Use multiple options together
export MGREP_MAX_COUNT=20
export MGREP_CONTENT=1
export MGREP_ANSWER=1
mgrep "search query"

Note: Command-line options always override environment variables.

Development

pnpm install
pnpm build        # or pnpm dev for a quick compile + run
pnpm format       # biome formatting + linting

• The executable lives at dist/index.js (built from TypeScript via tsc).
• Husky is wired via pnpx husky init (run npx husky init once after cloning).
• Tests are not wired up yet—pnpm typecheck is your best friend before publishing.
• To connect to a local Mixedbread api set the export NODE_ENV=development.

Testing

pnpm test

The tests are written using bats.

Troubleshooting

• Login keeps reopening: run mgrep logout to clear cached tokens, then try mgrep login again.
• Watcher feels noisy: set MXBAI_STORE or pass --store to separate experiments, or pause the watcher and restart after large refactors.
• Need a fresh store: delete it from the Mixedbread dashboard, then run mgrep watch. It will auto-create a new one.

License

Apache-2.0. See the LICENSE file for details.