microsoft/monodex

microsoft/monodex

Description: Empower your agent to navigate large codebases

Language: Rust

License: NOASSERTION

Stars: 17

Forks: 5

Open issues: 15

Created: 2026-03-25T05:20:30Z

Pushed: 2026-07-30T10:42:19Z

Default branch: main

Fork: no

Archived: no

README:

Rush Monodex

Empower your agent to navigate large codebases.

Monodex is a standalone developer tool that provides smart, up-to-date codesearch for large monorepos. The CLI is directly usable by humans, but crafted to minimize LLM token cost.

Key features

• Simple to install: Run cargo install monodex, create a ~/.monodex/monodex-config.json (see [Configuration](#configuration) below), then monodex init-db to create the database, and you're ready to start crawling.
• Designed for scale: Incremental indexing means changes are picked up without re-crawling the whole repo. Ranked search surfaces the most relevant results, instead of dumping every match into your agent's context.
• Optimized for searching code: AST-guided chunking and a hybrid of full-text and semantic search, battle-tested on large scale frontend monorepos. (TypeScript today; more languages to come.)
• Self-contained: Runs entirely on your own hardware, with no LLM service, no Docker container, and no separate database process. The database can be moved between machines.
• Agent-agnostic: CLI output crafted for agent consumption, designed to plug into a variety of coding agents and workflows.
• Open source: the core developer tooling everyone relies on should be free, open to inspect, and not gated behind someone else's roadmap.

See [CHANGELOG.md](./CHANGELOG.md) for what's new.

Vocabulary

Monodex uses a few terms to describe the containment hierarchy:

• A database is the on-disk store: by default ~/.monodex/default-db. Everything lives here.
• A catalog is a named monorepo registered in your config. You might have one catalog per codebase.
• A label is a named fileset within a catalog: typically a branch or commit. Searches are scoped to a label.
• A chunk is a unit of indexed content (function, class, section).

Hierarchy: database › catalog › label › chunk

Monodex supports two retrieval methods, normally used together, individually selectable via --retrieval:

• fts: full-text search over the literal text of each chunk. Use when you know an exact name, identifier, or string and want to find every place it appears.
• vector: semantic similarity over learned chunk embeddings (Jina v2 code model). Use when you can describe what the code does but don't know what it's called. Catches matches fts would miss for lack of vocabulary overlap.

The default monodex search queries both and fuses the results by reciprocal rank. Each result line is tagged [f], [v], or [f+v] to show which method(s) ranked it.

Usage Guide

The indexed database is a complete, internally consistent snapshot of the codebase as it existed at crawl time. Searches and views work independent of any local file changes, branches, or whether the repo is even cloned, which makes Monodex more than a replacement for grep: it can be the primary way an agent learns about a codebase.

The intended integration today is via the CLI; agents shell out to monodex search and monodex view and parse the output. An MCP server is on the backlog.

Typical workflow:

1. Set default context (optional but recommended):

monodex use --catalog rushstack --label main

2. Start with search to find relevant code:

monodex search --text "how does rush handle pnpm shrinkwrap files"

3. View full chunks using the file_id:chunk_ordinal from search results:

monodex view --id 700a4ba232fe9ddc:3

4. Get surrounding context by viewing adjacent chunks:

monodex view --id 700a4ba232fe9ddc:2-4

5. Reconstruct entire files by viewing all chunks:

monodex view --id 700a4ba232fe9ddc

Output format: Code lines are >-prefixed to frame chunk content distinctly from result headers and other CLI output.

Prerequisites

• Rust: 1.93+ (for edition 2024). If you do not already have a Rust toolchain installed, the standard installer is rustup. On Linux and macOS, rustup adds ~/.cargo/bin to your shell's PATH via your shell rc file; restart your shell or run source ~/.cargo/env after installing. On Windows, the installer handles PATH automatically. Verify with rustc --version and cargo --version.

• Git: 2.35.0+ (required for working-directory crawls; the git ls-files --format flag was introduced in 2.35.0)

• Protocol Buffers compiler (`protoc`): Required at build time by LanceDB's transitive dependencies. Install via your platform package manager:

| Platform | Command | | ------------- | ---------------------------------------- | | Windows | winget install protobuf | | macOS | brew install protobuf | | Debian/Ubuntu | sudo apt-get install protobuf-compiler | | Fedora/RHEL | sudo dnf install protobuf-compiler | | Arch | sudo pacman -S protobuf |

Verify with protoc --version (any recent 3.x or 4.x/20+ release works). If protoc is installed in a non-standard location, set the PROTOC environment variable to its full path before building.

• Model: jina-embeddings-v2-base-code (auto-downloaded from Hugging Face on first use; cached locally by the hf_hub library, typically under ~/.cache/huggingface/)

Installation

From crates.io

cargo install monodex

Build from Source

git clone https://github.com/microsoft/monodex.git
cd monodex
cargo build --release

# Binary will be at ./target/release/monodex

Configuration

Create ~/.monodex/monodex-config.json:

{
// Database configuration (optional, defaults shown)
"database": {
"path": "./default-db"
},

// Catalog definitions (required)
"catalogs": {
"sparo": {
"type": "monorepo",
"path": "/path/to/sparo"
},
"rushstack": {
"type": "monorepo",
"path": "/path/to/rushstack"
}
},

// Embedding model configuration (optional, defaults shown)
"embeddingModel": {
"modelInstances": "auto",
"threadsPerInstance": "auto"
}
}

> Note: We use the Sparo monorepo for development testing, since it's a small open-source Rush monorepo.

Fields:

| Field | Required | Description | |...