DevRag
Free Local RAG for Claude Code - Save Tokens & Time
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:
macOS/Linux:
tar -xzf devrag-*.tar.gz
chmod +x devrag-*
sudo mv devrag-* /usr/local/bin/
Note: macOS releases include
libonnxruntime.dylibfor CoreML GPU acceleration. Keep it in the same directory as thedevragbinary.
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:
{
"mcpServers": {
"devrag": {
"type": "stdio",
"command": "/usr/local/bin/devrag"
}
}
}
Using a custom config file:
{
"mcpServers": {
"devrag": {
"type": "stdio",
"command": "/usr/local/bin/devrag",
"args": ["--config", "/path/to/custom-config.json"]
}
}
}
3. Add Your Documents
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:
{
"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_dirfield is still supported (automatically migrated)
- Supports directory paths:
db_path: Vector database file pathchunk_size: Document chunk size in characterssearch_top_k: Number of search results to returncompute.device: Compute device (auto,cpu,gpu)compute.fallback_to_cpu: Fallback to CPU if GPU unavailablemodel.name: Embedding model namemodel.dimensions: Vector dimensions
Command-Line Options
--config <path>: Specify a custom configuration file path (default:config.json)
Example:
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
{
"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 languagetop_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.
# 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.
# 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:
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:
# 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:
- Manage docs in Git: Normal Git workflow
- Each developer runs DevRag: Local setup on each machine
- Search via Claude Code: Everyone can search all docs
- Auto-sync:
git pullautomatically updates the index
Configure for your project's docs directory:
{
"document_patterns": [
"./docs",
"./api-docs/**/*.md",
"./wiki/**/*.md"
],
"db_path": "./.devrag/vectors.db"
}
Performance
Environment: MacBook Pro M2, 100 files (1MB total)
260x faster search, 40x fewer tokens
Development
Run Tests
# 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
# 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
# Create version tag
git tag v1.0.1
# Push tag
git push origin v1.0.1
GitHub Actions automatically:
- Builds for all platforms
- Creates GitHub Release
- Uploads binaries
- 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:
- Check internet connection
- For proxy environments:
export HTTP_PROXY=http://your-proxy:port export HTTPS_PROXY=http://your-proxy:port - Manual download (see
models/DOWNLOAD.md) - Retry (incomplete files are auto-removed)
GPU / CoreML Not Working
On macOS, DevRag uses Apple CoreML for GPU/Neural Engine acceleration. Requirements:
libonnxruntime.dylibmust be in the same directory as thedevragbinary- macOS releases from GitHub include this file automatically
If CoreML is not available, DevRag falls back to CPU automatically. To tune performance:
# Adjust CPU thread count (default: 4)
DEVRAG_THREADS=4 devrag
To explicitly force CPU mode:
{
"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
- Vector Database: sqlite-vec
- MCP Protocol: Model Context Protocol
- ONNX Runtime: onnxruntime-go
Contributing
Issues and Pull Requests are welcome!
Contributors
Special thanks to all contributors who helped improve DevRag:
- @badri - Multiple document paths with glob patterns (#2),
--configCLI flag (#3) - @io41 - Project cleanup and documentation improvements (#4)
Your contributions make DevRag better for everyone!
Author
日本語版
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から環境に合ったファイルをダウンロード：
macOS/Linux:
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 に追加：
{
"mcpServers": {
"devrag": {
"type": "stdio",
"command": "/usr/local/bin/devrag"
}
}
}
カスタム設定ファイルを使用する場合:
{
"mcpServers": {
"devrag": {
"type": "stdio",
"command": "/usr/local/bin/devrag",
"args": ["--config", "/path/to/custom-config.json"]
}
}
}
3. ドキュメントを配置
mkdir documents
cp your-notes.md documents/
これで完了！起動時に自動的にインデックス化されます。
4. Claude Codeで検索
Claude Codeで：
「JWTの認証方法について検索して」
設定
config.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 <path>: カスタム設定ファイルのパスを指定（デフォルト:config.json）
使用例:
devrag --config /path/to/custom-config.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コマンドとして利用可能です。
# 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で人間が読みやすい形式になります。
# JSON（デフォルト、スクリプトやAIエージェント向け）
devrag search "認証"
# テキスト（人間向け）
devrag search "認証" --output text
MCPツール名との互換性
CLIコマンドはアンダースコア形式のMCPツール名でも動作します：
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 と同じ
フラグの構文
フラグは位置引数の前に置く必要があります：
# 正しい
devrag delete --dry-run file.md
# 誤り（--dry-runが無視される）
devrag delete file.md --dry-run
チーム開発
大量のドキュメントがあるチームに最適：
- Gitでドキュメント管理: 通常のGitワークフロー
- 各開発者がDevRagを起動: 各マシンでローカルセットアップ
- Claude Codeで検索: 全員が全ドキュメントを検索可能
- 自動同期:
git pullでインデックスを自動更新
プロジェクトのdocsディレクトリ用に設定：
{
"document_patterns": [
"./docs",
"./api-docs/**/*.md",
"./wiki/**/*.md"
],
"db_path": "./.devrag/vectors.db"
}
パフォーマンス
環境: MacBook Pro M2, 100ファイル (合計1MB)
検索は260倍速、トークンは40分の1
開発
テスト実行
# すべてのテスト
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
ビルド
# ビルドスクリプト使用
./build.sh
# 直接ビルド
go build -o devrag cmd/main.go
# クロスプラットフォームリリースビルド
./scripts/build-release.sh
リリース作成
# バージョンタグを作成
git tag v1.0.1
# タグをプッシュ
git push origin v1.0.1
GitHub Actionsが自動的に：
- 全プラットフォーム向けにビルド
- GitHub Releaseを作成
- バイナリをアップロード
- チェックサムを生成
プロジェクト構造
devrag/
├── cmd/
│ └── main.go # エントリーポイント
├── internal/
│ ├── cli/ # CLIコマンド
│ ├── config/ # 設定管理
│ ├── embedder/ # ベクトル埋め込み
│ ├── indexer/ # インデックス処理
│ ├── mcp/ # MCPサーバー
│ └── vectordb/ # ベクトルDB
├── models/ # ONNXモデル
├── build.sh # ビルドスクリプト
└── integration_test.go # 統合テスト
トラブルシューティング
モデルのダウンロードに失敗
原因: インターネット接続またはHugging Faceサーバーの問題
解決方法:
- インターネット接続を確認
- プロキシ環境の場合：
export HTTP_PROXY=http://your-proxy:port export HTTPS_PROXY=http://your-proxy:port - 手動ダウンロード（
models/DOWNLOAD.md参照） - 再試行（不完全なファイルは自動削除）
GPU / CoreMLが動作しない
macOSではApple CoreMLによるGPU/Neural Engine高速化を使用します。条件：
libonnxruntime.dylibがdevragバイナリと同じディレクトリにあること- GitHubのmacOS版リリースにはこのファイルが含まれています
CoreMLが利用できない場合は自動的にCPUにフォールバックします。パフォーマンス調整：
# CPUスレッド数の変更（デフォルト: 4）
DEVRAG_THREADS=4 devrag
明示的にCPUモードを指定する場合：
{
"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
- ベクトルデータベース: sqlite-vec
- MCPプロトコル: Model Context Protocol
- ONNX Runtime: onnxruntime-go
コントリビューション
IssuesとPull Requestsを歓迎します！
コントリビューター
DevRagの改善に貢献してくださった皆様に感謝します：
皆様の貢献がDevRagをより良くしています！
