DevRag

What is DevRag?

DevRag is a lightweight RAG (Retrieval-Augmented Generation) system designed specifically for developers using Claude Code. It helps users find exactly what they need without wasting tokens by reading entire documents. Instead, DevRag uses vector search to retrieve only the relevant chunks of information.

Benefits

DevRag offers several key advantages:

• 40x Less Tokens: Vector search retrieves only relevant chunks (~200 tokens) compared to reading entire documents (3,000+ tokens per file).
• 15x Faster: Searches take about 100ms, compared to 30 seconds of reading.
• Auto-Discovery: Claude Code can find documents without knowing their file names.
• Simple RAG: Retrieval-Augmented Generation for Claude Code.
• Markdown Support: Auto-indexes .md files.
• Semantic Search: Allows natural language queries like "JWT authentication method".
• Single Binary: No Python required; models auto-download on first run.
• Cross-Platform: Works on macOS, Linux, and Windows.
• Fast: Auto GPU/CPU detection and incremental sync.
• Multilingual: Supports 100+ languages including Japanese and English.

Use Cases

DevRag is particularly useful for:

• Developers: Quickly finding relevant information in large documentation repositories.
• Teams: Managing and searching through shared documentation efficiently.
• Multilingual Support: Useful for teams working in different languages.

Quick Start

Getting started with DevRag is straightforward:

1. Download Binary: Get the appropriate binary for your platform.
2. Configure Claude Code: Add the necessary configuration to your~/.claude.jsonor.mcp.jsonfile.
3. Add Your Documents: Place your markdown files in the specified directory.
4. Search with Claude Code: Use natural language queries to search your documents.

Configuration

You can customize DevRag by creating aconfig.jsonfile. This file allows you to specify settings such as the documents directory, vector database path, chunk size, search results, compute device, and embedding model.

MCP Tools

DevRag provides several tools via Model Context Protocol (MCP):

• search: Perform semantic vector search.
• index_markdown: Index a markdown file.
• list_documents: List all indexed documents.
• delete_document: Remove a document from the index.
• reindex_document: Re-index a document.

Team Development

DevRag is perfect for teams with large documentation repositories. Here’s how it works:

1. Manage docs in Git: Use a normal Git workflow.
2. Each developer runs DevRag: Set up DevRag locally on each machine.
3. Search via Claude Code: Everyone can search all docs.
4. Auto-sync:git pullautomatically updates the index.

Performance

DevRag offers impressive performance. For example, on a MacBook Pro M2 with 100 files (1MB total):

• Startup: 2.3 seconds
• Indexing: 8.5 seconds
• Search (1 query): 95ms and ~300 tokens
• Traditional Read: 25 seconds and ~12,000 tokens

This results in260x faster search and 40x fewer tokenscompared to traditional methods.

Development

DevRag is built using Go and includes several scripts for testing, building, and creating releases. The project structure is well-organized, making it easy to navigate and contribute.

Troubleshooting

Common issues and their solutions include:

• Model Download Fails: Check internet connection, set up proxy if needed, or manually download the model.
• GPU Not Detected: Explicitly set CPU inconfig.json.
• Won't Start: Ensure Go 1.21+ is installed, CGO is enabled, and dependencies are installed.
• Unexpected Search Results: Adjustchunk_sizeor rebuild the index.
• High Memory Usage: Switch to CPU mode for lower memory usage.

Requirements

To build DevRag from source, you need:

• Go 1.21+
• CGO enabled (for sqlite-vec)
• macOS, Linux, or Windows

License

DevRag is released under the MIT License.

Credits

DevRag uses several open-source components, including embedding models, vector databases, MCP protocol, and ONNX Runtime.

Contributing

Issues and Pull Requests are welcome! The project encourages community contributions to improve and expand its capabilities.

Author

DevRag was created by Tomohiro Owada.