# 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](https://github.com/tomohiro-owada/devrag/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:** ```bash tar -xzf devrag-*.tar.gz chmod +x devrag-* sudo mv devrag-* /usr/local/bin/ ``` > **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`: ```json { "mcpServers": { "devrag": { "type": "stdio", "command": "/usr/local/bin/devrag" } } } ``` **Using a custom config file:** ```json { "mcpServers": { "devrag": { "type": "stdio", "command": "/usr/local/bin/devrag", "args": ["--config", "/path/to/custom-config.json"] } } } ``` ### 3. Add Your Documents ```bash mkdir documents cp your-notes.md documents/ ``` That's it! Documents are automatically indexed on startup. ### 4. Search with Claude Code In Claude Code: ``` "Search for JWT authentication methods" ``` ## Configuration Create `config.json`: ```json { "document_patterns": [ "./documents", "./notes/**/*.md", "./projects/backend/**/*.md" ], "db_path": "./vectors.db", "chunk_size": 500, "search_top_k": 5, "compute": { "device": "auto", "fallback_to_cpu": true }, "model": { "name": "multilingual-e5-small", "dimensions": 384 } } ``` ### 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:** ```bash devrag --config /path/to/custom-config.json ``` This is useful for: - Running multiple instances with different configurations - Testing different models or chunk sizes - Maintaining separate dev/test/prod configurations ### Pattern Examples ```json { "document_patterns": [ "./documents", // All .md files in documents/ "./notes/**/*.md", // Recursive search in notes/ "./projects/*/docs/*.md", // docs/ in each project "/path/to/external/docs" // Absolute path ] } ``` ## 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:** ``` // Basic search search(query: "JWT authentication") // Search only in docs/api directory search(query: "user endpoints", directory: "docs/api") // Search only files matching pattern search(query: "deployment", file_pattern: "guide-*.md") // Combined filters search(query: "authentication", directory: "docs/api", file_pattern: "auth*.md") ``` ### index_markdown Index a markdown file **Parameters:** - `filepath` (string): Path to the file to index ### list_documents List all indexed documents **Returns:** Document list with filenames and timestamps ### delete_document Remove a document from the index **Parameters:** - `filepath` (string): Path to the file to delete ### reindex_document Re-index a document **Parameters:** - `filepath` (string): Path to the file to re-index ## CLI Usage DevRag can also be used as a standalone CLI tool. All MCP tools are available as CLI commands. ```bash # Start MCP server (default) devrag devrag serve # Search documents devrag search "JWT authentication" devrag search "deployment" --top-k 10 --directory docs/api # Index files devrag index ./docs/api-spec.md devrag index-code --directory ./src # List indexed documents devrag list devrag list --fields filename # Delete / Reindex devrag delete ./docs/old-spec.md --dry-run devrag reindex ./docs/updated-spec.md # Code symbol relations devrag search-relations handleAuth --type calls # Build dictionary (Japanese-English mapping) devrag build-dictionary # Show CLI schema (machine-readable) devrag schema ``` ### Output Format All commands output JSON by default. Use `--output text` for human-readable output. ```bash # JSON (default, suitable for scripts and AI agents) devrag search "authentication" # Text (human-readable) devrag search "authentication" --output text ``` ### MCP Tool Name Compatibility CLI commands also accept MCP tool names with underscores: ```bash devrag index_markdown ./docs/api.md # same as: devrag index devrag list_documents # same as: devrag list devrag delete_document ./docs/old.md # same as: devrag delete devrag reindex_document ./docs/api.md # same as: devrag reindex ``` ### Flag Syntax Flags must be placed **before** positional arguments: ```bash # Correct devrag delete --dry-run file.md # Incorrect (--dry-run is ignored) devrag delete file.md --dry-run ``` ## Team Development Perfect for teams with large documentation repositories: 1. **Manage docs in Git**: Normal Git workflow 2. **Each developer runs DevRag**: Local setup on each machine 3. **Search via Claude Code**: Everyone can search all docs 4. **Auto-sync**: `git pull` automatically updates the index Configure for your project's docs directory: ```json { "document_patterns": [ "./docs", "./api-docs/**/*.md", "./wiki/**/*.md" ], "db_path": "./.devrag/vectors.db" } ``` ## Performance Environment: MacBook Pro M2, 100 files (1MB total) | Operation | Time | Tokens | |-----------|------|--------| | Startup | 2.3s | - | | Indexing | 8.5s | - | | Search (1 query) | 95ms | ~300 | | Traditional Read | 25s | ~12,000 | **260x faster search, 40x fewer tokens** ## Development ### Run Tests ```bash # All tests go test ./... # Specific packages go test ./internal/config -v go test ./internal/indexer -v go test ./internal/embedder -v go test ./internal/vectordb -v # Integration tests go test . -v -run TestEndToEnd ``` ### Build ```bash # Using build script ./build.sh # Direct build go build -o devrag cmd/main.go # Cross-platform release build ./scripts/build-release.sh ``` ### Creating a Release ```bash # Create version tag git tag v1.0.1 # Push tag git push origin v1.0.1 ``` GitHub Actions automatically: 1. Builds for all platforms 2. Creates GitHub Release 3. Uploads binaries 4. Generates checksums ## Project Structure ``` devrag/ ├── cmd/ │ └── main.go # Entry point ├── internal/ │ ├── cli/ # CLI commands │ ├── config/ # Configuration │ ├── embedder/ # Vector embeddings │ ├── indexer/ # Indexing logic │ ├── mcp/ # MCP server │ └── vectordb/ # Vector database ├── models/ # ONNX models ├── build.sh # Build script └── integration_test.go # Integration tests ``` ## Troubleshooting ### Model Download Fails **Cause**: Internet connection or Hugging Face server issues **Solutions**: 1. Check internet connection 2. For proxy environments: ```bash export HTTP_PROXY=http://your-proxy:port export HTTPS_PROXY=http://your-proxy:port ``` 3. Manual download (see `models/DOWNLOAD.md`) 4. Retry (incomplete files are auto-removed) ### GPU / CoreML Not Working On macOS, DevRag uses Apple CoreML for GPU/Neural Engine acceleration. Requirements: - `libonnxruntime.dylib` must be in the same directory as the `devrag` binary - macOS releases from GitHub include this file automatically If CoreML is not available, DevRag falls back to CPU automatically. To tune performance: ```bash # Adjust CPU thread count (default: 4) DEVRAG_THREADS=4 devrag ``` To explicitly force CPU mode: ```json { "compute": { "device": "cpu", "fallback_to_cpu": true } } ``` ### Won't Start - Ensure Go 1.21+ is installed (for building) - Check CGO is enabled: `go env CGO_ENABLED` - Verify dependencies are installed - Internet required for first run (model download) ### Unexpected Search Results - Adjust `chunk_size` (default: 500) - Rebuild index (delete vectors.db and restart) ### High Memory Usage - GPU mode loads model into VRAM - Switch to CPU mode for lower memory usage ## Requirements - Go 1.21+ (for building from source) - CGO enabled (for sqlite-vec) - macOS, Linux, or Windows ## License MIT License ## Credits - Embedding Model: [intfloat/multilingual-e5-small](https://huggingface.co/intfloat/multilingual-e5-small) - Vector Database: [sqlite-vec](https://github.com/asg017/sqlite-vec) - MCP Protocol: [Model Context Protocol](https://modelcontextprotocol.io/) - ONNX Runtime: [onnxruntime-go](https://github.com/yalue/onnxruntime_go) ## Contributing Issues and Pull Requests are welcome! ## Contributors Special thanks to all contributors who helped improve DevRag: - **[@badri](https://github.com/badri)** - Multiple document paths with glob patterns ([#2](https://github.com/tomohiro-owada/devrag/pull/2)), `--config` CLI flag ([#3](https://github.com/tomohiro-owada/devrag/pull/3)) - **[@io41](https://github.com/io41)** - Project cleanup and documentation improvements ([#4](https://github.com/tomohiro-owada/devrag/pull/4)) Your contributions make DevRag better for everyone! ## Author [towada](https://github.com/tomohiro-owada) --- # 日本語版 **Claude Code用の無料ローカルRAG - トークン＆時間を節約** DevRagは、Claude Codeを使う開発者のための軽量RAG（Retrieval-Augmented Generation）システムです。ドキュメント全体を読み込んでトークンを無駄にするのをやめて、ベクトル検索で必要な情報だけを取得しましょう。 ## なぜDevRagが必要か？ Claude Codeでドキュメントを読み込むと、大量のトークンを消費します： - ❌ **コンテキストの浪費**: 毎回ドキュメント全体を読み込み（1ファイル3,000トークン以上） - ❌ **検索性の欠如**: Claudeはどのファイルに何が書いてあるか知らない - ❌ **繰り返し**: セッションをまたいで同じドキュメントを何度も読む **DevRagを使えば:** - ✅ **トークン消費1/40**: ベクトル検索で必要な部分だけ取得（約200トークン） - ✅ **15倍高速**: 検索100ms vs 読み込み30秒 - ✅ **自動発見**: ファイル名を知らなくてもClaude Codeが見つける ## 特徴 - 🤖 **簡易RAG** - Claude Code用の検索拡張生成 - 📝 **マークダウン対応** - .mdファイルを自動インデックス化 - 🔍 **意味検索** - 「JWTの認証方法」のような自然言語クエリ - 🚀 **ワンバイナリー** - Python不要、モデルは初回起動時に自動ダウンロード - 💻 **CLI & MCP** - MCPサーバーとしても、CLIコマンドとしても使える - 🖥️ **クロスプラットフォーム** - macOS / Linux / Windows - ⚡ **高速** - GPU/CPU自動検出、差分同期 - 🌐 **多言語** - 日本語・英語を含む100以上の言語対応 ## クイックスタート ### 1. バイナリダウンロード [Releases](https://github.com/tomohiro-owada/devrag/releases)から環境に合ったファイルをダウンロード： | プラットフォーム | ファイル | |----------|------| | 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:** ```bash tar -xzf devrag-*.tar.gz chmod +x devrag-* sudo mv devrag-* /usr/local/bin/ ``` > **注意**: macOS版リリースにはCoreML GPU高速化用の`libonnxruntime.dylib`が含まれています。`devrag`バイナリと同じディレクトリに配置してください。 **Windows:** - zipファイルを解凍 - 任意の場所に配置（例: `C:\Program Files\devrag\`） ### 2. Claude Code設定 `~/.claude.json` または `.mcp.json` に追加： ```json { "mcpServers": { "devrag": { "type": "stdio", "command": "/usr/local/bin/devrag" } } } ``` **カスタム設定ファイルを使用する場合:** ```json { "mcpServers": { "devrag": { "type": "stdio", "command": "/usr/local/bin/devrag", "args": ["--config", "/path/to/custom-config.json"] } } } ``` ### 3. ドキュメントを配置 ```bash mkdir documents cp your-notes.md documents/ ``` これで完了！起動時に自動的にインデックス化されます。 ### 4. Claude Codeで検索 Claude Codeで： ``` 「JWTの認証方法について検索して」 ``` ## 設定 `config.json`を作成： ```json { "document_patterns": [ "./documents", "./notes/**/*.md", "./projects/backend/**/*.md" ], "db_path": "./vectors.db", "chunk_size": 500, "search_top_k": 5, "compute": { "device": "auto", "fallback_to_cpu": true }, "model": { "name": "multilingual-e5-small", "dimensions": 384 } } ``` ### 設定項目 - `document_patterns`: ドキュメントのパスとglobパターンの配列 - ディレクトリパス対応: `"./documents"` - globパターン対応: `"./docs/**/*.md"` (再帰的) - 複数パターン: 異なる場所からファイルをインデックス化 - **注意**: 旧形式の`documents_dir`もサポート（自動的に移行） - `db_path`: ベクトルデータベースのパス - `chunk_size`: ドキュメントのチャンクサイズ（文字数） - `search_top_k`: 検索結果の返却件数 - `compute.device`: 計算デバイス（`auto`, `cpu`, `gpu`） - `compute.fallback_to_cpu`: GPU利用不可時にCPUにフォールバック - `model.name`: 埋め込みモデル名 - `model.dimensions`: ベクトル次元数 ### コマンドラインオプション - `--config `: カスタム設定ファイルのパスを指定（デフォルト: `config.json`） **使用例:** ```bash devrag --config /path/to/custom-config.json ``` これは以下の用途で便利です： - 異なる設定で複数のインスタンスを実行 - 異なるモデルやチャンクサイズをテスト - 開発/テスト/本番環境の設定を分離 ### パターン例 ```json { "document_patterns": [ "./documents", // documents/内の全.mdファイル "./notes/**/*.md", // notes/内を再帰的に検索 "./projects/*/docs/*.md", // 各プロジェクトのdocs/ "/path/to/external/docs" // 絶対パス ] } ``` ## MCPツール Model Context Protocolを通じて以下のツールを提供： ### search フィルター機能付き意味ベクトル検索を実行 **パラメータ:** - `query` (string, 必須): 自然言語の検索クエリ - `top_k` (number, 任意): 最大結果数（デフォルト: 5） - `directory` (string, 任意): 特定ディレクトリに絞り込み（例: "docs/api"） - `file_pattern` (string, 任意): ファイル名のglobパターン（例: "api-*.md", "*.md"） **戻り値:** ファイル名、チャンク内容、類似度スコアを含む検索結果の配列 **使用例:** ``` // 基本検索 search(query: "JWT認証") // docs/apiディレクトリ内のみ検索 search(query: "ユーザーエンドポイント", directory: "docs/api") // パターンに一致するファイルのみ検索 search(query: "デプロイ", file_pattern: "guide-*.md") // フィルターの組み合わせ search(query: "認証", directory: "docs/api", file_pattern: "auth*.md") ``` ### index_markdown マークダウンファイルをインデックス化 **パラメータ:** - `filepath` (string): インデックス化するファイルのパス ### list_documents インデックス化されたドキュメントの一覧を取得 **戻り値:** ファイル名とタイムスタンプを含むドキュメントリスト ### delete_document ドキュメントをインデックスから削除 **パラメータ:** - `filepath` (string): 削除するファイルのパス ### reindex_document ドキュメントを再インデックス化 **パラメータ:** - `filepath` (string): 再インデックス化するファイルのパス ## CLI使用方法 DevRagはスタンドアロンのCLIツールとしても使用できます。すべてのMCPツールがCLIコマンドとして利用可能です。 ```bash # MCPサーバーを起動（デフォルト） devrag devrag serve # ドキュメントを検索 devrag search "JWT認証" devrag search "デプロイ" --top-k 10 --directory docs/api # ファイルをインデックス化 devrag index ./docs/api-spec.md devrag index-code --directory ./src # インデックス済みドキュメント一覧 devrag list devrag list --fields filename # 削除 / 再インデックス devrag delete ./docs/old-spec.md --dry-run devrag reindex ./docs/updated-spec.md # コードシンボル関係検索 devrag search-relations handleAuth --type calls # 辞書ビルド（日本語→英語マッピング） devrag build-dictionary # CLIスキーマ表示（機械可読） devrag schema ``` ### 出力形式全コマンドはデフォルトでJSONを出力します。`--output text`で人間が読みやすい形式になります。 ```bash # JSON（デフォルト、スクリプトやAIエージェント向け） devrag search "認証" # テキスト（人間向け） devrag search "認証" --output text ``` ### MCPツール名との互換性 CLIコマンドはアンダースコア形式のMCPツール名でも動作します： ```bash devrag index_markdown ./docs/api.md # devrag index と同じ devrag list_documents # devrag list と同じ devrag delete_document ./docs/old.md # devrag delete と同じ devrag reindex_document ./docs/api.md # devrag reindex と同じ ``` ### フラグの構文フラグは位置引数の**前**に置く必要があります： ```bash # 正しい devrag delete --dry-run file.md # 誤り（--dry-runが無視される） devrag delete file.md --dry-run ``` ## チーム開発大量のドキュメントがあるチームに最適： 1. **Gitでドキュメント管理**: 通常のGitワークフロー 2. **各開発者がDevRagを起動**: 各マシンでローカルセットアップ 3. **Claude Codeで検索**: 全員が全ドキュメントを検索可能 4. **自動同期**: `git pull`でインデックスを自動更新プロジェクトのdocsディレクトリ用に設定： ```json { "document_patterns": [ "./docs", "./api-docs/**/*.md", "./wiki/**/*.md" ], "db_path": "./.devrag/vectors.db" } ``` ## パフォーマンス環境: MacBook Pro M2, 100ファイル (合計1MB) | 操作 | 時間 | トークン | |------|------|----------| | 起動 | 2.3秒 | - | | インデックス化 | 8.5秒 | - | | 検索 (1クエリ) | 95ms | ~300 | | 従来のRead | 25秒 | ~12,000 | **検索は260倍速、トークンは40分の1** ## 開発 ### テスト実行 ```bash # すべてのテスト go test ./... # 特定のパッケージ go test ./internal/config -v go test ./internal/indexer -v go test ./internal/embedder -v go test ./internal/vectordb -v # 統合テスト go test . -v -run TestEndToEnd ``` ### ビルド ```bash # ビルドスクリプト使用 ./build.sh # 直接ビルド go build -o devrag cmd/main.go # クロスプラットフォームリリースビルド ./scripts/build-release.sh ``` ### リリース作成 ```bash # バージョンタグを作成 git tag v1.0.1 # タグをプッシュ git push origin v1.0.1 ``` GitHub Actionsが自動的に： 1. 全プラットフォーム向けにビルド 2. GitHub Releaseを作成 3. バイナリをアップロード 4. チェックサムを生成 ## プロジェクト構造 ``` devrag/ ├── cmd/ │ └── main.go # エントリーポイント ├── internal/ │ ├── cli/ # CLIコマンド │ ├── config/ # 設定管理 │ ├── embedder/ # ベクトル埋め込み │ ├── indexer/ # インデックス処理 │ ├── mcp/ # MCPサーバー │ └── vectordb/ # ベクトルDB ├── models/ # ONNXモデル ├── build.sh # ビルドスクリプト └── integration_test.go # 統合テスト ``` ## トラブルシューティング ### モデルのダウンロードに失敗 **原因**: インターネット接続またはHugging Faceサーバーの問題 **解決方法**: 1. インターネット接続を確認 2. プロキシ環境の場合： ```bash export HTTP_PROXY=http://your-proxy:port export HTTPS_PROXY=http://your-proxy:port ``` 3. 手動ダウンロード（`models/DOWNLOAD.md`参照） 4. 再試行（不完全なファイルは自動削除） ### GPU / CoreMLが動作しない macOSではApple CoreMLによるGPU/Neural Engine高速化を使用します。条件： - `libonnxruntime.dylib`が`devrag`バイナリと同じディレクトリにあること - GitHubのmacOS版リリースにはこのファイルが含まれています CoreMLが利用できない場合は自動的にCPUにフォールバックします。パフォーマンス調整： ```bash # CPUスレッド数の変更（デフォルト: 4） DEVRAG_THREADS=4 devrag ``` 明示的にCPUモードを指定する場合： ```json { "compute": { "device": "cpu", "fallback_to_cpu": true } } ``` ### 起動しない - Go 1.21+がインストールされているか確認（ソースからビルドする場合） - CGOが有効か確認: `go env CGO_ENABLED` - 依存関係がインストールされているか確認 - 初回起動時はインターネット接続が必要（モデルダウンロード） ### 検索結果が期待と異なる - `chunk_size`を調整（デフォルト: 500） - インデックスを再構築（vectors.dbを削除して再起動） ### メモリ使用量が多い - GPUモードではモデルがVRAMにロード - CPUモードに切り替えるとメモリ使用量が減少 ## 必要要件 - Go 1.21+（ソースからビルドする場合） - CGO有効（sqlite-vecのため） - macOS, Linux, または Windows ## ライセンス MIT License ## クレジット - 埋め込みモデル: [intfloat/multilingual-e5-small](https://huggingface.co/intfloat/multilingual-e5-small) - ベクトルデータベース: [sqlite-vec](https://github.com/asg017/sqlite-vec) - MCPプロトコル: [Model Context Protocol](https://modelcontextprotocol.io/) - ONNX Runtime: [onnxruntime-go](https://github.com/yalue/onnxruntime_go) ## コントリビューション IssuesとPull Requestsを歓迎します！ ## コントリビューター DevRagの改善に貢献してくださった皆様に感謝します： - **[@badri](https://github.com/badri)** - 複数ドキュメントパスとglobパターン対応 ([#2](https://github.com/tomohiro-owada/devrag/pull/2))、`--config` CLIフラグ ([#3](https://github.com/tomohiro-owada/devrag/pull/3)) - **[@io41](https://github.com/io41)** - プロジェクトのクリーンアップとドキュメント改善 ([#4](https://github.com/tomohiro-owada/devrag/pull/4)) 皆様の貢献がDevRagをより良くしています！ ## 作者 [towada](https://github.com/tomohiro-owada)