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. When using Claude Code, reading documents with the Read tool consumes massive amounts of tokens: - ❌
Add this skill
npx mdskills install tomohiro-owada/devragProduction-ready RAG system with excellent docs, semantic search, and multi-platform support
1# DevRag23**Free Local RAG for Claude Code - Save Tokens & Time**45[日本語版はこちら](#日本語版) | [Japanese Version](#日本語版)67DevRag 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.89## Why DevRag?1011When using Claude Code, reading documents with the Read tool consumes massive amounts of tokens:1213- ❌ **Wasting Context**: Reading entire docs every time (3,000+ tokens per file)14- ❌ **Poor Searchability**: Claude doesn't know which file contains what15- ❌ **Repetitive**: Same documents read multiple times across sessions1617**With DevRag:**1819- ✅ **40x Less Tokens**: Vector search retrieves only relevant chunks (~200 tokens)20- ✅ **15x Faster**: Search in 100ms vs 30 seconds of reading21- ✅ **Auto-Discovery**: Claude Code finds documents without knowing file names2223## Features2425- 🤖 **Simple RAG** - Retrieval-Augmented Generation for Claude Code26- 📝 **Markdown Support** - Auto-indexes .md files27- 🔍 **Semantic Search** - Natural language queries like "JWT authentication method"28- 🚀 **Single Binary** - No Python, models auto-download on first run29- 🖥️ **Cross-Platform** - macOS / Linux / Windows30- ⚡ **Fast** - Auto GPU/CPU detection, incremental sync31- 🌐 **Multilingual** - Supports 100+ languages including Japanese & English3233## Quick Start3435### 1. Download Binary3637Get the appropriate binary from [Releases](https://github.com/tomohiro-owada/devrag/releases):3839| Platform | File |40|----------|------|41| macOS (Apple Silicon) | `devrag-macos-apple-silicon.tar.gz` |42| macOS (Intel) | `devrag-macos-intel.tar.gz` |43| Linux (x64) | `devrag-linux-x64.tar.gz` |44| Linux (ARM64) | `devrag-linux-arm64.tar.gz` |45| Windows (x64) | `devrag-windows-x64.zip` |4647**macOS/Linux:**48```bash49tar -xzf devrag-*.tar.gz50chmod +x devrag-*51sudo mv devrag-* /usr/local/bin/devrag52```5354**Windows:**55- Extract the zip file56- Place in your preferred location (e.g., `C:\Program Files\devrag\`)5758### 2. Configure Claude Code5960Add to `~/.claude.json` or `.mcp.json`:6162```json63{64 "mcpServers": {65 "devrag": {66 "type": "stdio",67 "command": "/usr/local/bin/devrag"68 }69 }70}71```7273**Using a custom config file:**74```json75{76 "mcpServers": {77 "devrag": {78 "type": "stdio",79 "command": "/usr/local/bin/devrag",80 "args": ["--config", "/path/to/custom-config.json"]81 }82 }83}84```8586### 3. Add Your Documents8788```bash89mkdir documents90cp your-notes.md documents/91```9293That's it! Documents are automatically indexed on startup.9495### 4. Search with Claude Code9697In Claude Code:98```99"Search for JWT authentication methods"100```101102## Configuration103104Create `config.json`:105106```json107{108 "document_patterns": [109 "./documents",110 "./notes/**/*.md",111 "./projects/backend/**/*.md"112 ],113 "db_path": "./vectors.db",114 "chunk_size": 500,115 "search_top_k": 5,116 "compute": {117 "device": "auto",118 "fallback_to_cpu": true119 },120 "model": {121 "name": "multilingual-e5-small",122 "dimensions": 384123 }124}125```126127### Configuration Options128129- `document_patterns`: Array of document paths and glob patterns130 - Supports directory paths: `"./documents"`131 - Supports glob patterns: `"./docs/**/*.md"` (recursive)132 - Multiple patterns: Index files from different locations133 - **Note**: Old `documents_dir` field is still supported (automatically migrated)134- `db_path`: Vector database file path135- `chunk_size`: Document chunk size in characters136- `search_top_k`: Number of search results to return137- `compute.device`: Compute device (`auto`, `cpu`, `gpu`)138- `compute.fallback_to_cpu`: Fallback to CPU if GPU unavailable139- `model.name`: Embedding model name140- `model.dimensions`: Vector dimensions141142### Command-Line Options143144- `--config <path>`: Specify a custom configuration file path (default: `config.json`)145146**Example:**147```bash148devrag --config /path/to/custom-config.json149```150151This is useful for:152- Running multiple instances with different configurations153- Testing different models or chunk sizes154- Maintaining separate dev/test/prod configurations155156### Pattern Examples157158```json159{160 "document_patterns": [161 "./documents", // All .md files in documents/162 "./notes/**/*.md", // Recursive search in notes/163 "./projects/*/docs/*.md", // docs/ in each project164 "/path/to/external/docs" // Absolute path165 ]166}167```168169## MCP Tools170171DevRag provides the following tools via Model Context Protocol:172173### search174Perform semantic vector search with optional filtering175176**Parameters:**177- `query` (string, required): Search query in natural language178- `top_k` (number, optional): Maximum number of results (default: 5)179- `directory` (string, optional): Filter to specific directory (e.g., "docs/api")180- `file_pattern` (string, optional): Glob pattern for filename (e.g., "api-*.md", "*.md")181182**Returns:**183Array of search results with filename, chunk content, and similarity score184185**Examples:**186```187// Basic search188search(query: "JWT authentication")189190// Search only in docs/api directory191search(query: "user endpoints", directory: "docs/api")192193// Search only files matching pattern194search(query: "deployment", file_pattern: "guide-*.md")195196// Combined filters197search(query: "authentication", directory: "docs/api", file_pattern: "auth*.md")198```199200### index_markdown201Index a markdown file202203**Parameters:**204- `filepath` (string): Path to the file to index205206### list_documents207List all indexed documents208209**Returns:**210Document list with filenames and timestamps211212### delete_document213Remove a document from the index214215**Parameters:**216- `filepath` (string): Path to the file to delete217218### reindex_document219Re-index a document220221**Parameters:**222- `filepath` (string): Path to the file to re-index223224## Team Development225226Perfect for teams with large documentation repositories:2272281. **Manage docs in Git**: Normal Git workflow2292. **Each developer runs DevRag**: Local setup on each machine2303. **Search via Claude Code**: Everyone can search all docs2314. **Auto-sync**: `git pull` automatically updates the index232233Configure for your project's docs directory:234235```json236{237 "document_patterns": [238 "./docs",239 "./api-docs/**/*.md",240 "./wiki/**/*.md"241 ],242 "db_path": "./.devrag/vectors.db"243}244```245246## Performance247248Environment: MacBook Pro M2, 100 files (1MB total)249250| Operation | Time | Tokens |251|-----------|------|--------|252| Startup | 2.3s | - |253| Indexing | 8.5s | - |254| Search (1 query) | 95ms | ~300 |255| Traditional Read | 25s | ~12,000 |256257**260x faster search, 40x fewer tokens**258259## Development260261### Run Tests262263```bash264# All tests265go test ./...266267# Specific packages268go test ./internal/config -v269go test ./internal/indexer -v270go test ./internal/embedder -v271go test ./internal/vectordb -v272273# Integration tests274go test . -v -run TestEndToEnd275```276277### Build278279```bash280# Using build script281./build.sh282283# Direct build284go build -o devrag cmd/main.go285286# Cross-platform release build287./scripts/build-release.sh288```289290### Creating a Release291292```bash293# Create version tag294git tag v1.0.1295296# Push tag297git push origin v1.0.1298```299300GitHub Actions automatically:3011. Builds for all platforms3022. Creates GitHub Release3033. Uploads binaries3044. Generates checksums305306## Project Structure307308```309devrag/310├── cmd/311│ └── main.go # Entry point312├── internal/313│ ├── config/ # Configuration314│ ├── embedder/ # Vector embeddings315│ ├── indexer/ # Indexing logic316│ ├── mcp/ # MCP server317│ └── vectordb/ # Vector database318├── models/ # ONNX models319├── build.sh # Build script320└── integration_test.go # Integration tests321```322323## Troubleshooting324325### Model Download Fails326327**Cause**: Internet connection or Hugging Face server issues328329**Solutions**:3301. Check internet connection3312. For proxy environments:332 ```bash333 export HTTP_PROXY=http://your-proxy:port334 export HTTPS_PROXY=http://your-proxy:port335 ```3363. Manual download (see `models/DOWNLOAD.md`)3374. Retry (incomplete files are auto-removed)338339### GPU Not Detected340341Explicitly set CPU in `config.json`:342343```json344{345 "compute": {346 "device": "cpu",347 "fallback_to_cpu": true348 }349}350```351352### Won't Start353354- Ensure Go 1.21+ is installed (for building)355- Check CGO is enabled: `go env CGO_ENABLED`356- Verify dependencies are installed357- Internet required for first run (model download)358359### Unexpected Search Results360361- Adjust `chunk_size` (default: 500)362- Rebuild index (delete vectors.db and restart)363364### High Memory Usage365366- GPU mode loads model into VRAM367- Switch to CPU mode for lower memory usage368369## Requirements370371- Go 1.21+ (for building from source)372- CGO enabled (for sqlite-vec)373- macOS, Linux, or Windows374375## License376377MIT License378379## Credits380381- Embedding Model: [intfloat/multilingual-e5-small](https://huggingface.co/intfloat/multilingual-e5-small)382- Vector Database: [sqlite-vec](https://github.com/asg017/sqlite-vec)383- MCP Protocol: [Model Context Protocol](https://modelcontextprotocol.io/)384- ONNX Runtime: [onnxruntime-go](https://github.com/yalue/onnxruntime_go)385386## Contributing387388Issues and Pull Requests are welcome!389390## Contributors391392Special thanks to all contributors who helped improve DevRag:393394- **[@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))395- **[@io41](https://github.com/io41)** - Project cleanup and documentation improvements ([#4](https://github.com/tomohiro-owada/devrag/pull/4))396397Your contributions make DevRag better for everyone!398399## Author400401[towada](https://github.com/tomohiro-owada)402403---404405# 日本語版406407**Claude Code用の無料ローカルRAG - トークン＆時間を節約**408409DevRagは、Claude Codeを使う開発者のための軽量RAG（Retrieval-Augmented Generation）システムです。ドキュメント全体を読み込んでトークンを無駄にするのをやめて、ベクトル検索で必要な情報だけを取得しましょう。410411## なぜDevRagが必要か？412413Claude Codeでドキュメントを読み込むと、大量のトークンを消費します：414415- ❌ **コンテキストの浪費**: 毎回ドキュメント全体を読み込み（1ファイル3,000トークン以上）416- ❌ **検索性の欠如**: Claudeはどのファイルに何が書いてあるか知らない417- ❌ **繰り返し**: セッションをまたいで同じドキュメントを何度も読む418419**DevRagを使えば:**420421- ✅ **トークン消費1/40**: ベクトル検索で必要な部分だけ取得（約200トークン）422- ✅ **15倍高速**: 検索100ms vs 読み込み30秒423- ✅ **自動発見**: ファイル名を知らなくてもClaude Codeが見つける424425## 特徴426427- 🤖 **簡易RAG** - Claude Code用の検索拡張生成428- 📝 **マークダウン対応** - .mdファイルを自動インデックス化429- 🔍 **意味検索** - 「JWTの認証方法」のような自然言語クエリ430- 🚀 **ワンバイナリー** - Python不要、モデルは初回起動時に自動ダウンロード431- 🖥️ **クロスプラットフォーム** - macOS / Linux / Windows432- ⚡ **高速** - GPU/CPU自動検出、差分同期433- 🌐 **多言語** - 日本語・英語を含む100以上の言語対応434435## クイックスタート436437### 1. バイナリダウンロード438439[Releases](https://github.com/tomohiro-owada/devrag/releases)から環境に合ったファイルをダウンロード：440441| プラットフォーム | ファイル |442|----------|------|443| macOS (Apple Silicon) | `devrag-macos-apple-silicon.tar.gz` |444| macOS (Intel) | `devrag-macos-intel.tar.gz` |445| Linux (x64) | `devrag-linux-x64.tar.gz` |446| Linux (ARM64) | `devrag-linux-arm64.tar.gz` |447| Windows (x64) | `devrag-windows-x64.zip` |448449**macOS/Linux:**450```bash451tar -xzf devrag-*.tar.gz452chmod +x devrag-*453sudo mv devrag-* /usr/local/bin/devrag454```455456**Windows:**457- zipファイルを解凍458- 任意の場所に配置（例: `C:\Program Files\devrag\`）459460### 2. Claude Code設定461462`~/.claude.json` または `.mcp.json` に追加：463464```json465{466 "mcpServers": {467 "devrag": {468 "type": "stdio",469 "command": "/usr/local/bin/devrag"470 }471 }472}473```474475**カスタム設定ファイルを使用する場合:**476```json477{478 "mcpServers": {479 "devrag": {480 "type": "stdio",481 "command": "/usr/local/bin/devrag",482 "args": ["--config", "/path/to/custom-config.json"]483 }484 }485}486```487488### 3. ドキュメントを配置489490```bash491mkdir documents492cp your-notes.md documents/493```494495これで完了！起動時に自動的にインデックス化されます。496497### 4. Claude Codeで検索498499Claude Codeで：500```501「JWTの認証方法について検索して」502```503504## 設定505506`config.json`を作成：507508```json509{510 "document_patterns": [511 "./documents",512 "./notes/**/*.md",513 "./projects/backend/**/*.md"514 ],515 "db_path": "./vectors.db",516 "chunk_size": 500,517 "search_top_k": 5,518 "compute": {519 "device": "auto",520 "fallback_to_cpu": true521 },522 "model": {523 "name": "multilingual-e5-small",524 "dimensions": 384525 }526}527```528529### 設定項目530531- `document_patterns`: ドキュメントのパスとglobパターンの配列532 - ディレクトリパス対応: `"./documents"`533 - globパターン対応: `"./docs/**/*.md"` (再帰的)534 - 複数パターン: 異なる場所からファイルをインデックス化535 - **注意**: 旧形式の`documents_dir`もサポート（自動的に移行）536- `db_path`: ベクトルデータベースのパス537- `chunk_size`: ドキュメントのチャンクサイズ（文字数）538- `search_top_k`: 検索結果の返却件数539- `compute.device`: 計算デバイス（`auto`, `cpu`, `gpu`）540- `compute.fallback_to_cpu`: GPU利用不可時にCPUにフォールバック541- `model.name`: 埋め込みモデル名542- `model.dimensions`: ベクトル次元数543544### コマンドラインオプション545546- `--config <path>`: カスタム設定ファイルのパスを指定（デフォルト: `config.json`）547548**使用例:**549```bash550devrag --config /path/to/custom-config.json551```552553これは以下の用途で便利です：554- 異なる設定で複数のインスタンスを実行555- 異なるモデルやチャンクサイズをテスト556- 開発/テスト/本番環境の設定を分離557558### パターン例559560```json561{562 "document_patterns": [563 "./documents", // documents/内の全.mdファイル564 "./notes/**/*.md", // notes/内を再帰的に検索565 "./projects/*/docs/*.md", // 各プロジェクトのdocs/566 "/path/to/external/docs" // 絶対パス567 ]568}569```570571## MCPツール572573Model Context Protocolを通じて以下のツールを提供：574575### search576フィルター機能付き意味ベクトル検索を実行577578**パラメータ:**579- `query` (string, 必須): 自然言語の検索クエリ580- `top_k` (number, 任意): 最大結果数（デフォルト: 5）581- `directory` (string, 任意): 特定ディレクトリに絞り込み（例: "docs/api"）582- `file_pattern` (string, 任意): ファイル名のglobパターン（例: "api-*.md", "*.md"）583584**戻り値:**585ファイル名、チャンク内容、類似度スコアを含む検索結果の配列586587**使用例:**588```589// 基本検索590search(query: "JWT認証")591592// docs/apiディレクトリ内のみ検索593search(query: "ユーザーエンドポイント", directory: "docs/api")594595// パターンに一致するファイルのみ検索596search(query: "デプロイ", file_pattern: "guide-*.md")597598// フィルターの組み合わせ599search(query: "認証", directory: "docs/api", file_pattern: "auth*.md")600```601602### index_markdown603マークダウンファイルをインデックス化604605**パラメータ:**606- `filepath` (string): インデックス化するファイルのパス607608### list_documents609インデックス化されたドキュメントの一覧を取得610611**戻り値:**612ファイル名とタイムスタンプを含むドキュメントリスト613614### delete_document615ドキュメントをインデックスから削除616617**パラメータ:**618- `filepath` (string): 削除するファイルのパス619620### reindex_document621ドキュメントを再インデックス化622623**パラメータ:**624- `filepath` (string): 再インデックス化するファイルのパス625626## チーム開発627628大量のドキュメントがあるチームに最適：6296301. **Gitでドキュメント管理**: 通常のGitワークフロー6312. **各開発者がDevRagを起動**: 各マシンでローカルセットアップ6323. **Claude Codeで検索**: 全員が全ドキュメントを検索可能6334. **自動同期**: `git pull`でインデックスを自動更新634635プロジェクトのdocsディレクトリ用に設定：636637```json638{639 "document_patterns": [640 "./docs",641 "./api-docs/**/*.md",642 "./wiki/**/*.md"643 ],644 "db_path": "./.devrag/vectors.db"645}646```647648## パフォーマンス649650環境: MacBook Pro M2, 100ファイル (合計1MB)651652| 操作 | 時間 | トークン |653|------|------|----------|654| 起動 | 2.3秒 | - |655| インデックス化 | 8.5秒 | - |656| 検索 (1クエリ) | 95ms | ~300 |657| 従来のRead | 25秒 | ~12,000 |658659**検索は260倍速、トークンは40分の1**660661## 開発662663### テスト実行664665```bash666# すべてのテスト667go test ./...668669# 特定のパッケージ670go test ./internal/config -v671go test ./internal/indexer -v672go test ./internal/embedder -v673go test ./internal/vectordb -v674675# 統合テスト676go test . -v -run TestEndToEnd677```678679### ビルド680681```bash682# ビルドスクリプト使用683./build.sh684685# 直接ビルド686go build -o devrag cmd/main.go687688# クロスプラットフォームリリースビルド689./scripts/build-release.sh690```691692### リリース作成693694```bash695# バージョンタグを作成696git tag v1.0.1697698# タグをプッシュ699git push origin v1.0.1700```701702GitHub Actionsが自動的に：7031. 全プラットフォーム向けにビルド7042. GitHub Releaseを作成7053. バイナリをアップロード7064. チェックサムを生成707708## プロジェクト構造709710```711devrag/712├── cmd/713│ └── main.go # エントリーポイント714├── internal/715│ ├── config/ # 設定管理716│ ├── embedder/ # ベクトル埋め込み717│ ├── indexer/ # インデックス処理718│ ├── mcp/ # MCPサーバー719│ └── vectordb/ # ベクトルDB720├── models/ # ONNXモデル721├── build.sh # ビルドスクリプト722└── integration_test.go # 統合テスト723```724725## トラブルシューティング726727### モデルのダウンロードに失敗728729**原因**: インターネット接続またはHugging Faceサーバーの問題730731**解決方法**:7321. インターネット接続を確認7332. プロキシ環境の場合：734 ```bash735 export HTTP_PROXY=http://your-proxy:port736 export HTTPS_PROXY=http://your-proxy:port737 ```7383. 手動ダウンロード（`models/DOWNLOAD.md`参照）7394. 再試行（不完全なファイルは自動削除）740741### GPUが検出されない742743`config.json`で明示的にCPUを指定：744745```json746{747 "compute": {748 "device": "cpu",749 "fallback_to_cpu": true750 }751}752```753754### 起動しない755756- Go 1.21+がインストールされているか確認（ソースからビルドする場合）757- CGOが有効か確認: `go env CGO_ENABLED`758- 依存関係がインストールされているか確認759- 初回起動時はインターネット接続が必要（モデルダウンロード）760761### 検索結果が期待と異なる762763- `chunk_size`を調整（デフォルト: 500）764- インデックスを再構築（vectors.dbを削除して再起動）765766### メモリ使用量が多い767768- GPUモードではモデルがVRAMにロード769- CPUモードに切り替えるとメモリ使用量が減少770771## 必要要件772773- Go 1.21+（ソースからビルドする場合）774- CGO有効（sqlite-vecのため）775- macOS, Linux, または Windows776777## ライセンス778779MIT License780781## クレジット782783- 埋め込みモデル: [intfloat/multilingual-e5-small](https://huggingface.co/intfloat/multilingual-e5-small)784- ベクトルデータベース: [sqlite-vec](https://github.com/asg017/sqlite-vec)785- MCPプロトコル: [Model Context Protocol](https://modelcontextprotocol.io/)786- ONNX Runtime: [onnxruntime-go](https://github.com/yalue/onnxruntime_go)787788## コントリビューション789790IssuesとPull Requestsを歓迎します！791792## コントリビューター793794DevRagの改善に貢献してくださった皆様に感謝します：795796- **[@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))797- **[@io41](https://github.com/io41)** - プロジェクトのクリーンアップとドキュメント改善 ([#4](https://github.com/tomohiro-owada/devrag/pull/4))798799皆様の貢献がDevRagをより良くしています！800801## 作者802803[towada](https://github.com/tomohiro-owada)804
Full transparency — inspect the skill content before installing.