devrag

Purpose

DevRag is a lightweight local RAG (Retrieval-Augmented Generation) system designed specifically for developers using Claude Code. The core problem it solves is: reading entire documents directly in Claude Code consumes a large number of tokens, and Claude does not know which file contains what content, so the same document is repeatedly read across different sessions. DevRag retrieves only document fragments relevant to the query through vector search, thereby saving tokens and time. It is officially claimed to achieve approximately 40x fewer tokens (retrieving only relevant fragments, about 200 tokens) and approximately 15x faster search (about 100ms compared with 30 seconds to read documents), and to let Claude Code automatically discover documents without needing to know file names.

Main Capabilities

• Markdown support: Automatically indexes .md files.
• Semantic search: Supports natural language queries, such as "JWT authentication method".
• Single binary: No Python required; the model is automatically downloaded on first run.
• CLI & MCP: Can be used both as an MCP server and as a standalone CLI command.
• Cross-platform: Supports macOS / Linux / Windows.
• Fast: Automatic GPU/CPU detection, supports incremental synchronization.
• Multilingual: Supports more than 100 languages, including Japanese and English.
• Filtering: Semantic vector search supports filtering by directory (directory) and file name glob pattern (file_pattern).

Usage

Installation and Configuration

1. Download the binary: Get the binary suitable for your system from Releases. Note: the macOS version includes libonnxruntime.dylibfor CoreML GPU acceleration, which needs to be placed in the same directory as the devrag binary. Unzip the zip file and place it in your preferred location (for example C:\Program Files\devrag\).
2. Configure Claude Code: Add DevRag to ~/.claude.json or .mcp.json . A custom configuration file can also be used.
3. Add documents: Put Markdown documents into the configured directory; they will be automatically indexed at startup.
4. Search in Claude Code: Use natural language queries.

Configuration File (config.json)

Configurable items include:

• document_patterns: Array of document paths and glob patterns. Supports directory paths (such as ./documents), glob patterns (such as ./docs/**/*.md recursive), and multiple patterns (indexing files in different locations). The old field documents_dir is still supported (automatically migrated).
• db_path: Path to the vector database file.
• chunk_size: Document chunk size (number of characters).
• search_top_k: Number of search results returned.
• compute.device: Compute device (auto、cpu、gpu）。
• compute.fallback_to_cpu: Falls back to CPU when GPU is unavailable.
• model.name: Embedding model name.
• model.dimensions: Vector dimension.

Command-Line Options

• --config <path>: Specify a custom configuration file path (default:config.json). Suitable for: running multiple instances with different configurations, testing different models or chunk sizes, and maintaining separate development/test/production configurations.
• All MCP tools can be used as CLI commands. All commands output JSON by default; use --output text to get human-readable output. CLI commands also accept MCP tool names with underscores. Flags must be placed before positional arguments.

MCP Tools

DevRag provides the following tools through the Model Context Protocol:

• search: Performs semantic vector search, with optional filtering. Parameters:query(string, required),top_k(number, optional, default 5),directory(string, optional, e.g. "docs/api"),file_pattern(string, optional, glob pattern, e.g. "api-.md", ".md"). Returns an array of results containing filenames, snippet contents, and similarity scores.
• index_document: Index a Markdown file. Parameters:filepath(string).
• list_documents: List all indexed documents, returning filenames and timestamps.
• delete_document: Remove a document from the index. Parameters:filepath(string).
• reindex_document: Reindex a document. Parameters:filepath(string).

Use Cases

• Team development: Suitable for teams with large documentation repositories. Documents are managed with Git, and each developer runs DevRag locally, searching all documents through Claude Code,git pull automatically updates the index.
• Reduce token consumption: Avoid reading entire files when frequently consulting large amounts of Markdown documentation in Claude Code.
• Multilingual documentation: Scenarios requiring searching documentation in over 100 languages such as Japanese and English.

Limitations and Notes

• Primarily for indexing and searching Markdown files (.md); support for other formats is not yet documented.
• The first run requires an internet connection to download the embedding model; if the download fails, it may be related to the network connection or Hugging Face servers. You can set a proxy or download manually (see models/DOWNLOAD.md); incomplete files are automatically deleted on retry.
• On macOS, Apple CoreML is used for GPU/Neural Engine acceleration, requiring libonnxruntime.dylib and devrag binaries to be in the same directory; the GitHub macOS release automatically includes this file. If CoreML is unavailable, it automatically falls back to CPU. Performance can be adjusted or CPU mode explicitly forced.
• Building from source requires Go 1.21+, CGO enabled (for sqlite-vec), and dependencies installed.
• GPU mode loads the model into VRAM, resulting in higher memory usage; switching to CPU mode reduces memory usage.
• If search results are not as expected, you can adjust chunk_size(default 500) or rebuild the index (delete vectors.db and restart).

Tech Stack

• Embedding model:intfloat/multilingual-e5-small
• Vector database:sqlite-vec
• MCP protocol: Model Context Protocol
• ONNX Runtime:onnxruntime-go