tomohiro-owada/devrag

**Free Local RAG for Claude Code - Save Tokens & Time**
日本語版はこちら | Japanese Version
DevRag is a lightweight RAG (Retrieval-Augmented Generation) system designed specifically for developers using Claude Code. Stop wasting tokens by reading entire documents - let vector search find exactly what you need.
Why DevRag?
When using Claude Code, reading documents with the Read tool consumes massive amounts of tokens:
- ❌ **Wasting Context**: Reading entire docs every time (3,000+ tokens per file)
- ❌ **Poor Searchability**: Claude doesn't know which file contains what
- ❌ **Repetitive**: Same documents read multiple times across sessions
**With DevRag:**
- ✅ **40x Less Tokens**: Vector search retrieves only relevant chunks (~200 tokens)
- ✅ **15x Faster**: Search in 100ms vs 30 seconds of reading
- ✅ **Auto-Discovery**: Claude Code finds documents without knowing file names
Features
- 🤖 **Simple RAG** - Retrieval-Augmented Generation for Claude Code
- 📝 **Markdown Support** - Auto-indexes .md files
- 🔍 **Semantic Search** - Natural language queries like "JWT authentication method"
- 🚀 **Single Binary** - No Python, models auto-download on first run
- 💻 **CLI & MCP** - Use as MCP server or standalone CLI commands
- 🖥️ **Cross-Platform** - macOS / Linux / Windows
- ⚡ **Fast** - Auto GPU/CPU detection, incremental sync
- 🌐 **Multilingual** - Supports 100+ languages including Japanese & English
Quick Start
1. Download Binary
Get the appropriate binary from Releases:
| Platform | File |
|----------|------|
| macOS (Apple Silicon) | devrag-macos-apple-silicon.tar.gz |
| macOS (Intel) | devrag-macos-intel.tar.gz |
| Linux (x64) | devrag-linux-x64.tar.gz |
| Linux (ARM64) | devrag-linux-arm64.tar.gz |
| Windows (x64) | devrag-windows-x64.zip |
**macOS/Linux:**
> **Note**: macOS releases include libonnxruntime.dylib for CoreML GPU acceleration. Keep it in the same directory as the devrag binary.
**Windows:**
- Extract the zip file
- Place in your preferred location (e.g., C:\Program Files\devrag\)
2. Configure Claude Code
Add to ~/.claude.json or .mcp.json:
**Using a custom config file:**
3. Add Your Documents
That's it! Documents are automatically indexed on startup.
4. Search with Claude Code
In Claude Code:
Configuration
Create config.json:
Configuration Options
- document_patterns: Array of document paths and glob patterns
- Supports directory paths: "./documents"
- Supports glob patterns: "./docs/**/*.md" (recursive)
- Multiple patterns: Index files from different locations
- **Note**: Old documents_dir field is still supported (automatically migrated)
- db_path: Vector database file path
- chunk_size: Document chunk size in characters
- search_top_k: Number of search results to return
- compute.device: Compute device (auto, cpu, gpu)
- compute.fallback_to_cpu: Fallback to CPU if GPU unavailable
- model.name: Embedding model name
- model.dimensions: Vector dimensions
Command-Line Options
- --config : Specify a custom configuration file path (default: config.json)
**Example:**
This is useful for:
- Running multiple instances with different configurations
- Testing different models or chunk sizes
- Maintaining separate dev/test/prod configurations
Pattern Examples
MCP Tools
DevRag provides the following tools via Model Context Protocol:
search
Perform semantic vector search with optional filtering
**Parameters:**
- query (string, required): Search query in natural language
- top_k (number, optional): Maximum number of results (default: 5)
- directory (string, optional): Filter to specific directory (e.g., "docs/api")
- file_pattern (string, optional): Glob pattern for filename (e.g., "api-*.md", "*.md")
**Returns:**
Array of search results with filename, chunk content, and similarity score
**Examples:**
index_markdown
Index a markdown file
**Parameters:**
- filepath (string): Path to the file to index