Skip to content
Back to search

Mixedbread-Grep

MarketplaceWorks with Claude CodeGitHub

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mixedbread-ai--mgrep/badge.svg)](/listings/mixedbread-ai--mgrep)

HTML

<a href="/listings/mixedbread-ai--mgrep"><img src="/api/listings/mixedbread-ai--mgrep/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. **Install**

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

2. **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.

3. **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.

4. **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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 20 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "Mixedbread-Grep",
  4. "owner": {
  5. "name": "Mixedbread",
  6. "email": "support@mixedbread.ai"
  7. },
  8. "plugins": [
  9. {
  10. "name": "mgrep",
  11. "source": "./plugins/mgrep",
  12. "description": "Search your local files using Mixedbread",
  13. "version": "0.0.0",
  14. "author": {
  15. "name": "Joel Dierkes"
  16. },
  17. "skills": ["./skills/mgrep"]
  18. }
  19. ]
  20. }
README.md · README · 371 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <a href="https://github.com/mixedbread-ai/mgrep">
  3. <img src="public/logo_mb.svg" alt="mgrep" width="96" height="96" />
  4. </a>
  5. <h1>mgrep</h1>
  6. <p><em>A calm, CLI-native way to semantically grep everything, like code, images, pdfs and more.</em></p>
  7. <a href="https://www.npmjs.com/package/@mixedbread/mgrep"><img src="https://badge.fury.io/js/@mixedbread%2Fcli.svg" alt="npm version" /></a>
  8. <a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License: Apache 2.0" /></a><br>
  9. <a href="https://demo.mgrep.mixedbread.com"><img src="https://img.shields.io/badge/Playground-Try%20it%20now-brightgreen" alt="Playground: Try it now" /></a>
  10. <a href="https://join.slack.com/t/mixedbreadcommunity/shared_invite/zt-3kagj5m36-wwM_hryIFby7B2wlcOaHaQ"><img src="https://img.shields.io/badge/Slack-Join%20Community-4A154B?logo=slack" alt="Slack Community" /></a>
  11. <br>
  12. <p align="center">
  13. <video src="https://github.com/user-attachments/assets/7cb6d2ab-f96b-4092-9088-abbca85b0d52" controls="controls" style="max-width: 730px;">
  14. Your browser does not support the video tag.
  15. </video>
  16. </p>
  17. </div>
  18. ## Why mgrep?
  19. - Natural-language search that feels as immediate as `grep`.
  20. - Semantic, multilingual & multimodal (audio, video support coming soon!)
  21. - Web search built-in — query the web alongside your local files with `--web`.
  22. - Smooth background indexing via `mgrep watch`, designed to detect and keep up-to-date everything that matters inside any git repository.
  23. - Friendly device-login flow and first-class coding agent integrations.
  24. - 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.
  25. - Reduces the token usage of your agent by 2x while maintaining superior performance
  26. ```bash
  27. # index once
  28. mgrep watch
  29. # then ask your repo things in natural language
  30. mgrep "where do we set up auth?"
  31. ```
  32. ## Quick Start
  33. 1. **Install**
  34. ```bash
  35. npm install -g @mixedbread/mgrep # or pnpm / bun
  36. ```
  37. 2. **Sign in once**
  38. ```bash
  39. mgrep login
  40. ```
  41. A browser window (or verification URL) guides you through Mixedbread authentication.
  42. **Alternative: API Key Authentication**
  43. For CI/CD or headless environments, set the `MXBAI_API_KEY` environment variable:
  44. ```bash
  45. export MXBAI_API_KEY=your_api_key_here
  46. ```
  47. This bypasses the browser login flow entirely.
  48. 3. **Index a project**
  49. ```bash
  50. cd path/to/repo
  51. mgrep watch
  52. ```
  53. `watch` performs an initial sync, respects `.gitignore`, then keeps the Mixedbread store updated as files change.
  54. 4. **Search anything**
  55. ```bash
  56. mgrep "where do we set up auth?" src/lib
  57. mgrep -m 25 "store schema"
  58. ```
  59. Searches default to the current working directory unless you pass a path.
  60. **Today, `mgrep` works great on:** code, text, PDFs, images.
  61. **Coming soon:** audio & video.
  62. ## Using it with Coding Agents
  63. > [!CAUTION]
  64. > **Background Sync Enabled**: When installed with a coding agent, mgrep runs a
  65. > background process that syncs your files to enable semantic search. This
  66. > process starts automatically when you begin a session and stops when your
  67. > session ends. You can see your current usage in the [Mixedbread
  68. > platform](https://www.platform.mixedbread.com/).
  69. > [!NOTE]
  70. > **Default Limits**: mgrep enforces default limits to ensure optimal performance:
  71. > - **Maximum file size**: 1MB per file
  72. > - **Maximum file count**: 1,000 files per directory
  73. >
  74. > These limits can be customized via CLI flags (`--max-file-size`, `--max-file-count`),
  75. > environment variables, or config files. See the [Configuration](#configuration) section for details.
  76. If you prefer to manually start the file watcher instead of relying on the agent's
  77. automatic background sync, you can run:
  78. ```bash
  79. mgrep watch /path/to/your/project
  80. ```
  81. This gives you explicit control over when indexing occurs and which directories are watched.
  82. `mgrep` supports assisted installation commands for many agents:
  83. - `mgrep install-claude-code` for Claude Code
  84. - `mgrep install-opencode` for OpenCode
  85. - `mgrep install-codex` for Codex
  86. - `mgrep install-droid` for Factory Droid
  87. These commands sign you in (if needed) and add Mixedbread `mgrep` support to the
  88. agent. After that you only have to start the agent in your project folder, thats
  89. it.
  90. ### More Agents Coming Soon
  91. More agents (Cursor, Windsurf, etc.) are on the way—this section will grow as soon as each integration lands.
  92. ## Making your agent smarter
  93. We plugged `mgrep` into Claude Code and ran a benchmark of 50 QA tasks to evaluate the economics of `mgrep` against `grep`.
  94. ![mgrep benchmark](public/bench.jpg)
  95. In our 50-task benchmark, `mgrep`+Claude Code used ~2x fewer tokens than grep-based workflows at similar or better judged quality.
  96. `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](http://demo.mgrep.mixedbread.com).
  97. *Note: Win Rate (%) was calculated by using an LLM as a judge.*
  98. ## Why we built mgrep
  99. `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.
  100. 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.
  101. 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.
  102. 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.
  103. Under the hood, `mgrep` is powered by [Mixedbread Search](https://www.mixedbread.com/blog/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.
  104. ## When to use what
  105. We designed `mgrep` to complement `grep`, not replace it. The best code search combines `mgrep` with `grep`.
  106. | Use `grep` (or `ripgrep`) for... | Use `mgrep` for... |
  107. | --- | --- |
  108. | **Exact Matches** | **Intent Search** |
  109. | Symbol tracing, Refactoring, Regex | Code exploration, Feature discovery, Onboarding |
  110. ## Web Search
  111. `mgrep` can also search the web alongside your local files. This is useful when
  112. you need to find documentation, tutorials, or answers to programming questions
  113. without leaving your terminal.
  114. ```bash
  115. # Search the web and get a summarized answer
  116. mgrep --web --answer "How do I integrate a JavaScript runtime into Deno?"
  117. # Get the urls of the search
  118. mgrep --web "best practices for error handling in TypeScript"
  119. ```
  120. Web search queries the `mixedbread/web` store in addition to your local store, merging results based on relevance. Use `--answer` (or `-a`) to get a concise summary instead of raw results.
  121. ## mgrep as Subagent
  122. For complex questions that require information from multiple sources, `mgrep` can act as a subagent that automatically refines queries and performs multiple searches to find the best answer.
  123. ```bash
  124. # Enable agentic search for complex multi-part questions
  125. mgrep --agentic "What are the yearly numbers for 2020, 2021, 2022, 2023, 2024?"
  126. # Combine with --answer for a synthesized response from multiple sources
  127. mgrep --agentic -a "How does authentication work and where is it configured?"
  128. ```
  129. When `--agentic` is enabled, mgrep will:
  130. - Automatically break down complex queries into sub-queries
  131. - Perform multiple searches as needed to gather comprehensive results
  132. - Combine findings from different parts of your codebase
  133. This is particularly useful for questions that span multiple files or concepts, where a single search might miss important context.
  134. ## Commands at a Glance
  135. | Command | Purpose |
  136. | --- | --- |
  137. | `mgrep` / `mgrep search <pattern> [path]` | Natural-language search with many `grep`-style flags (`-i`, `-r`, `-m`...). |
  138. | `mgrep watch` | Index current repo and keep the Mixedbread store in sync via file watchers. |
  139. | `mgrep login` & `mgrep logout` | Manage device-based authentication with Mixedbread. |
  140. | `mgrep install-claude-code` | Authenticate, add the Mixedbread mgrep plugin to Claude Code. |
  141. | `mgrep install-opencode` | Authenticate and add the Mixedbread mgrep to OpenCode. |
  142. | `mgrep install-codex` | Authenticate and add the Mixedbread mgrep to Codex. |
  143. | `mgrep install-droid` | Authenticate and add the Mixedbread mgrep hooks/skills to Factory Droid. |
  144. ### mgrep search
  145. `mgrep search` is the default command. It can be used to search the current
  146. directory for a pattern.
  147. | Option | Description |
  148. | --- | --- |
  149. | `-m <max_count>` | The maximum number of results to return |
  150. | `-c`, `--content` | Show content of the results |
  151. | `-a`, `--answer` | Generate an answer to the question based on the results |
  152. | `-w`, `--web` | Include web search results alongside local files |
  153. | `--agentic` | Enable agentic search to automatically refine queries and perform multiple searches |
  154. | `-s`, `--sync` | Sync the local files to the store before searching |
  155. | `-d`, `--dry-run` | Dry run the search process (no actual file syncing) |
  156. | `--no-rerank` | Disable reranking of search results |
  157. | `--max-file-size <bytes>` | Maximum file size in bytes to upload (overrides config) |
  158. | `--max-file-count <count>` | Maximum number of files to upload (overrides config) |
  159. All search options can also be configured via environment variables (see
  160. [Environment Variables](#environment-variables) section below).
  161. **Examples:**
  162. ```bash
  163. mgrep "What code parsers are available?" # search in the current directory
  164. mgrep "How are chunks defined?" src/models # search in the src/models directory
  165. mgrep -m 10 "What is the maximum number of concurrent workers in the code parser?" # limit the number of results to 10
  166. mgrep -a "What code parsers are available?" # generate an answer to the question based on the results
  167. mgrep --web --answer "How do I integrate a JavaScript runtime into Deno?" # search the web and get a summarized answer
  168. ```
  169. ### mgrep watch
  170. `mgrep watch` is used to index the current repository and keep the Mixedbread
  171. store in sync via file watchers.
  172. It respects the current `.gitignore`, as well as a `.mgrepignore` file in the
  173. root of the repository. The `.mgrepignore` file follows the same syntax as the
  174. [`.gitignore`](https://git-scm.com/docs/gitignore) file.
  175. | Option | Description |
  176. | --- | --- |
  177. | `-d`, `--dry-run` | Dry run the watch process (no actual file syncing) |
  178. | `--max-file-size <bytes>` | Maximum file size in bytes to upload (overrides config) |
  179. | `--max-file-count <count>` | Maximum number of files to upload (overrides config) |
  180. **Examples:**
  181. ```bash
  182. mgrep watch # index the current repository and keep the Mixedbread store in sync via file watchers
  183. mgrep watch --max-file-size 1048576 # limit uploads to files under 1MB
  184. mgrep watch --max-file-count 5000 # limit sync to 5000 changed files or fewer
  185. ```
  186. ## Mixedbread under the hood
  187. - Every file is pushed into a Mixedbread Store using the same SDK your apps get.
  188. - Searches request top-k matches with Mixedbread reranking enabled by default
  189. for tighter relevance (can be disabled with `--no-rerank` or
  190. `MGREP_RERANK=0`).
  191. - Results include relative paths plus contextual hints (line ranges for text, page numbers for PDFs, etc.) for a skim-friendly experience.
  192. - Because stores are cloud-backed, agents and teammates can query the same corpus without re-uploading.
  193. ## Configuration
  194. mgrep can be configured via config files, environment variables, or CLI flags.
  195. ### Config File
  196. Create a `.mgreprc.yaml` (or `.mgreprc.yml`) in your project root for local configuration, or `~/.config/mgrep/config.yaml` (or `config.yml`) for global configuration.
  197. ```yaml
  198. # Maximum file size in bytes to upload (default: 1MB)
  199. maxFileSize: 5242880
  200. # Maximum number of files to sync (upload/delete) per operation (default: 1000)
  201. maxFileCount: 5000
  202. ```
  203. **Configuration precedence** (highest to lowest):
  204. 1. CLI flags (`--max-file-size`, `--max-file-count`)
  205. 2. Environment variables (`MGREP_MAX_FILE_SIZE`, `MGREP_MAX_FILE_COUNT`)
  206. 3. Local config file (`.mgreprc.yaml` in project directory)
  207. 4. Global config file (`~/.config/mgrep/config.yaml`)
  208. 5. Default values
  209. ### Configuration Tips
  210. - `--store <name>` lets you isolate workspaces (per repo, per team, per experiment). Stores are created on demand if they do not exist yet.
  211. - Ignore rules come straight from git, so temp files, build outputs, and vendored deps stay out of your embeddings.
  212. - `watch` reports progress (`processed / uploaded`) as it scans; leave it running in a terminal tab to keep your store fresh.
  213. - `search` accepts most `grep`-style switches, and politely ignores anything it cannot support, so existing muscle memory still works.
  214. ## Environment Variables
  215. All search options can be configured via environment variables, which is
  216. especially useful for CI/CD pipelines or when you want to set defaults for all
  217. searches.
  218. ### Authentication & Store
  219. - `MXBAI_API_KEY`: Set this to authenticate without browser login (ideal for CI/CD)
  220. - `MXBAI_STORE`: Override the default store name (default: `mgrep`)
  221. ### Search Options
  222. - `MGREP_MAX_COUNT`: Maximum number of results to return (default: `10`)
  223. - `MGREP_CONTENT`: Show content of the results (set to `1` or `true` to enable)
  224. - `MGREP_ANSWER`: Generate an answer based on the results (set to `1` or `true` to enable)
  225. - `MGREP_WEB`: Include web search results (set to `1` or `true` to enable)
  226. - `MGREP_AGENTIC`: Enable agentic search for complex multi-source queries (set to `1` or `true` to enable)
  227. - `MGREP_SYNC`: Sync files before searching (set to `1` or `true` to enable)
  228. - `MGREP_DRY_RUN`: Enable dry run mode (set to `1` or `true` to enable)
  229. - `MGREP_RERANK`: Enable reranking of search results (set to `0` or `false` to disable, default: enabled)
  230. ### Sync Options
  231. - `MGREP_MAX_FILE_SIZE`: Maximum file size in bytes to upload (default: `1048576` / 1MB)
  232. - `MGREP_MAX_FILE_COUNT`: Maximum number of files to sync per operation (default: `1000`)
  233. **Examples:**
  234. ```bash
  235. # Set default max results to 25
  236. export MGREP_MAX_COUNT=25
  237. mgrep "search query"
  238. # Always show content in results
  239. export MGREP_CONTENT=1
  240. mgrep "search query"
  241. # Disable reranking globally
  242. export MGREP_RERANK=0
  243. mgrep "search query"
  244. # Use multiple options together
  245. export MGREP_MAX_COUNT=20
  246. export MGREP_CONTENT=1
  247. export MGREP_ANSWER=1
  248. mgrep "search query"
  249. ```
  250. Note: Command-line options always override environment variables.
  251. ## Development
  252. ```bash
  253. pnpm install
  254. pnpm build # or pnpm dev for a quick compile + run
  255. pnpm format # biome formatting + linting
  256. ```
  257. - The executable lives at `dist/index.js` (built from TypeScript via `tsc`).
  258. - Husky is wired via `pnpx husky init` (run `npx husky init` once after cloning).
  259. - Tests are not wired up yet—`pnpm typecheck` is your best friend before
  260. publishing.
  261. - To connect to a local Mixedbread api set the `export NODE_ENV=development`.
  262. ### Testing
  263. ```bash
  264. pnpm test
  265. ```
  266. The tests are written using [bats](https://bats-core.readthedocs.io/en/stable/).
  267. ## Troubleshooting
  268. - **Login keeps reopening**: run `mgrep logout` to clear cached tokens, then try `mgrep login` again.
  269. - **Watcher feels noisy**: set `MXBAI_STORE` or pass `--store` to separate experiments, or pause the watcher and restart after large refactors.
  270. - **Need a fresh store**: delete it from the Mixedbread dashboard, then run `mgrep watch`. It will auto-create a new one.
  271. ## Support
  272. For usage questions, feedback, or other support, please reach out on the [Mixedbread Slack](https://join.slack.com/t/mixedbreadcommunity/shared_invite/zt-3kagj5m36-wwM_hryIFby7B2wlcOaHaQ).
  273. ## License
  274. Apache-2.0. See the [LICENSE](https://opensource.org/licenses/Apache-2.0) file for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.