repository·main·Indexed 26 days ago
https://github.com/mixedbread-ai/mgrepmgrep is a CLI-native tool for semantic, natural-language searching across code, text, PDFs, and images. It complements traditional grep by providing intent-based search and integrates with AI coding agents like Claude Code, OpenCode, Codex, and Factory Droid to reduce token usage. Key features include repository indexing via `mgrep watch`, AI-powered narrative answers, web search integration, and agentic search modes.
When building or configuring agents, you must override default search behaviors to ensure correct tool usage. mgrep is intended to replace the following tools:
mgrep --web --answer "query"mgrep "query"mgrep "query"mgrep uses bats (Bash Automated Testing System) for integration testing, focusing on CLI behavior and end-to-end workflows.
Use the following commands to execute tests:
pnpm testbats test/test.batsbats test/test.bats --filter "Search"bats test/test.bats --verbose-run```bash
# Run all tests (excludes long-running tests)
pnpm test
# Run all tests including long-running
bats test/test.bats
# Run specific test by name pattern
bats test/test.bats --filter "Search"
# Run with verbose output
bats test/test.bats --verbose-run
```埋You can integrate mgrep with Claude Code. Installing the plugin allows the agent to automatically index the repository and keep the store in sync without needing to run mgrep watch manually.
cd path/to/repo
mgrep install-claude-code
claudecd path/to/repo # go to the project you want to index
mgrep install-claude-code
claudeBefore using mgrep, you must authenticate. You can either sign in interactively using the login command or provide an API key via the MXBAI_API_KEY environment variable in your shell or CI environment.
mgrep loginIf tests are failing, use these methods to inspect the behavior:
--verbose-run.--timing.echo "message" >&3 inside a test block to print to stderr, which will be visible in the test output.# Show command output even on success
bats test/test.bats --verbose-run
# Show test timing
bats test/test.bats --timing```bash
@test "debug example" {
run mgrep search "query"
# Print to stderr (visible in test output)
echo "Output was: $output" >&3
echo "Status was: $status" >&3
assert_success
}
```埋To enable semantic search, you must first index your project. Use mgrep watch within your repository. This command performs an initial sync, respects .gitignore and .mgrepignore files, and then maintains a background sync as files change.
You can explicitly specify a path to watch:
mgrep watch /path/to/your/projectcd path/to/repo
mgrep watchThe mgrep skill is a mandatory replacement for all built-in search tools (WebSearch, Grep, and Glob). It provides semantic search capabilities, allowing you to search for files, code, or content using natural language queries.
To search for code or content within your local codebase, use the mgrep command followed by your natural language query. You can optionally specify a directory.
To search the web and get a summarized answer, you must use the --web and --answer flags together. Never use the built-in WebSearch tool; use mgrep --web --answer "query" instead.
To index a repository and keep the semantic store in sync with your local files, navigate to your project directory and run mgrep watch. This command scans your files (respecting .gitignore), uploads them to a Mixedbread Store, and uses a file watcher to keep the index up to date.
cd path/to/repo
mgrep watchcd path/to/repo # go to the project you want to index
mgrep watch # index and keep your store in syncYou can categorize tests using tags to control which tests run in different environments (e.g., excluding slow or network-dependent tests).
Tagging a test:
Add a comment with the tag immediately above the @test block.
# bats test_tags=long-running
@test "full index of large repo" {
...
}Running tagged tests:
bats test/test.bats --filter-tags long-runningbats test/test.bats --filter-tags '!network'```bash
# Tag a test as long-running (excluded from default run)
# bats test_tags=long-running
@test "full index of large repo" {
...
}
# Multiple tags
# bats test_tags=slow,network
@test "web search integration" {
...
}
# Run tagged tests:
# Include long-running tests
bats test/test.bats --filter-tags long-running
# Exclude specific tags
bats test/test.bats --filter-tags '!network'
```埋Install the mgrep CLI globally using npm, pnpm, or bun to start using semantic search in your local repositories.
npm install -g @mixedbread/mgrepnpm install -g @mixedbread/mgrep # or pnpm / bunInstall the mgrep CLI globally using npm, pnpm, or bun. To use the service, you must authenticate via a browser-based login or by providing an API key in a headless environment.
Browser Login:
Run mgrep login and follow the URL in your browser.
Headless/CI Authentication:
Set the MXBAI_API_KEY environment variable to bypass the browser flow.
Use mgrep to search your codebase using natural language. By default, it searches the current working directory unless a path is provided.
Basic Usage:
mgrep "<query>" [path]
Common Search Flags:
-m <max_count>: Limit the number of results returned.-c, --content: Show the content of the search results.-a, --answer: Generate a concise natural language answer based on the results.-w, --web: Include web search results alongside local files.--agentic: Enable agentic search to automatically refine queries and perform multiple searches for complex questions.-s, --sync: Sync local files to the store before searching.-d, --dry-run: Perform a dry run without actual file syncing.