mgrep - Moses Yebei

The Problem

grep matches literal strings, not meaning. Searching a codebase for "where do we set up auth?" requires knowing the exact terms — passport, session, middleware — and even then you get a token match, not an answer. For multimodal content (PDFs, images), grep does not work at all. mgrep replaces that with semantic, natural-language search over your local files, indexed in the background.

What This Does

mgrep is a CLI that indexes a git repository and answers natural-language queries against it. The core loop is mgrep watch to index, then mgrep "your question" to search. It handles code, text, PDFs, and images, with a --web flag for web search. It is built for both humans and coding agents, with a background sync mode that starts and stops with an agent session.

The implementation is TypeScript, organized under src/. The CLI entry point is src/index.ts, which dispatches to subcommands in src/commands/ (search.ts, watch.ts, login.ts, etc.). Core logic lives in src/lib/, including auth.ts for device login, config.ts for settings, and store.ts for the local index.

How It Is Wired

Execution starts at src/index.ts, which parses arguments and dispatches to a command. src/commands/search.ts handles the query path: it reads the local store, sends the query to the Mixedbread API, and prints results. src/commands/watch.ts is the indexing path: it walks the filesystem, respects .gitignore, and syncs changes to the remote store. src/commands/login.ts handles the device-auth flow, writing credentials to a local config.

The central hub is src/lib/store.ts — both search and watch route through it for local state. src/lib/auth.ts is the second most impactful: every network call depends on its token management. The watch command also has a Python hook (plugins/mgrep/hooks/mgrep_watch.py) that manages the background process lifecycle for coding agents.

The wiring is straightforward: CLI command → lib function → network call or filesystem operation. No complex module graph or cycles. The only external dependency is the Mixedbread API, which the CLI calls for both indexing and search. The background sync for agents is the one piece that touches the process lifecycle, via the Python hook scripts.

How To Use It

Setup — install globally:

npm install -g @mixedbread/mgrep

Configuration — sign in once with mgrep login, or set the MXBAI_API_KEY environment variable for headless use.

Running it — index and search:

cd path/to/repo
mgrep watch
mgrep "where do we set up auth?" src/lib

The commands are documented in the README and implemented in src/commands/.

Real-World Use

A developer joins a new codebase. Instead of reading through src/lib/auth.ts to find where sessions are created, they run mgrep watch once, then ask mgrep "how do we validate JWT tokens?". The CLI returns the relevant file and line, cutting the exploration time from minutes to seconds. A CI pipeline can use the same flow with an API key, searching a codebase for security patterns before a release.

Code Health & Issues

No measured static analysis has run for this repo yet. The structure shows: 26 TypeScript files, 4 test files (test/test.bats), CI in .github/workflows/ci.yml, and a license. The dependency on the @mixedbread/mgrep npm package and the remote API means a network call is required for every search — there is no fully local mode in the code. The Python hooks in plugins/ are a separate runtime from the main TypeScript code, which adds a second language to maintain.

The Bottom Line

mgrep solves a real problem — semantic search over local files — with a clean CLI and a simple architecture. The trade-off is the mandatory remote API dependency; if the service goes down, so does search. It is a solid tool for developers and agents working in large codebases, but teams needing fully offline search would need to look elsewhere.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

59 files

TypeScript26
Markdown13
JSON7
YAML3
Python3

ReactTransformers

Module dependencies

The 10 most depended-upon modules of 29, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_src_lib_utils["utils"] n1_src_lib_token["token"] n2_src_lib_auth["auth"] n3_src_lib_file["file"] n4_src_lib_config["config"] n5_src_lib_warning["warning"] n6_src_lib_store["store"] n7_src_lib_sync_helpers["sync-helpers"] n8_src_commands_watch["watch"] n9_src_lib_context["context"] n8_src_commands_watch --> n4_src_lib_config n8_src_commands_watch --> n9_src_lib_context n8_src_commands_watch --> n3_src_lib_file n8_src_commands_watch --> n7_src_lib_sync_helpers n8_src_commands_watch --> n0_src_lib_utils n2_src_lib_auth --> n1_src_lib_token n2_src_lib_auth --> n0_src_lib_utils n9_src_lib_context --> n2_src_lib_auth n9_src_lib_context --> n3_src_lib_file n9_src_lib_context --> n6_src_lib_store n9_src_lib_context --> n0_src_lib_utils n1_src_lib_token --> n2_src_lib_auth n0_src_lib_utils --> n4_src_lib_config n0_src_lib_utils --> n3_src_lib_file n0_src_lib_utils --> n6_src_lib_store n0_src_lib_utils --> n7_src_lib_sync_helpers n0_src_lib_utils --> n1_src_lib_token classDef cyc stroke:#ef4444,stroke-width:2px; class n0_src_lib_utils,n1_src_lib_token,n2_src_lib_auth cyc;

Dependencies

9 of 26 declared dependencies are a major version behind. Resolved 26 of 26 against the registry.

Package	Declared	Latest	Behind
`ora`	^5.4.1	9.4.1	4 major
`p-limit`	^3.1.0	7.3.1	4 major
`@types/node`	^24.10.0	26.2.0	2 major
`typescript`	^5.9.3	7.0.2	2 major
`@clack/prompts`	^0.11.0	1.7.0	1 major
`chalk`	^5.6.2	6.0.0	1 major
`commander`	^14.0.2	15.0.0	1 major
`comment-json`	^4.5.0	5.0.0	1 major

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high2

medium4

low1

Pin third-party GitHub Actions to a commit SHAhigh

.github/workflows

pnpm/action-setup@v4

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Add a test suite; this repository has nonehigh29 occurrences

29 source files, no test files

Any change ships with no signal that existing behaviour still holds, so a regression reaches production undetected.

Fix: Add one test per public entry point, then a CI step that runs them.

Declare least-privilege permissions for GITHUB_TOKENmedium

.github/workflows/ci.yml

1 workflow(s) declare no permissions

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

1 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/ci.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow2 occurrences

.github/workflows/ci.yml

2 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.