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
• 🖥️ 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:

tar -xzf devrag-*.tar.gz
chmod +x devrag-*
sudo mv devrag-* /usr/local/bin/devrag

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_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 <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 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

# 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:

{
  "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

#  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:

1. Builds for all platforms
2. Creates GitHub Release
3. Uploads binaries
4. Generates checksums

# Project Structure

devrag/
├── cmd/
│   └── main.go              #  Entry point
├── internal/
│   ├── 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:

   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 Not Detected

Explicitly set CPU in config.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
• 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), - -config CLI flag (# 3)
• @io41 - Project cleanup and documentation improvements (# 4)

Your contributions make DevRag better for everyone!

# Author

towada

---

日本語版

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不要、モデルは初回起動時に自動ダウンロード
• 🖥️ クロスプラットフォーム - macOS / Linux / Windows
• ⚡ 高速 - GPU/CPU自動検出、差分同期
• 🌐 多言語 - 日本語・英語を含む100以上の言語対応

# クイックスタート

# # 1. バイナリダウンロード

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:

tar -xzf devrag-*.tar.gz
chmod +x devrag-*
sudo mv devrag-* /usr/local/bin/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): 再インデックス化するファイルのパス

# チーム開発

大量のドキュメントがあるチームに最適：

1. Gitでドキュメント管理: 通常のGitワークフロー
2. 各開発者がDevRagを起動: 各マシンでローカルセットアップ
3. Claude Codeで検索: 全員が全ドキュメントを検索可能
4. 自動同期: git pullでインデックスを自動更新

プロジェクトのdocsディレクトリ用に設定：

{
  "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

# 開発

# # テスト実行

#  すべてのテスト
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が自動的に：

1. 全プラットフォーム向けにビルド
2. GitHub Releaseを作成
3. バイナリをアップロード
4. チェックサムを生成

# プロジェクト構造

devrag/
├── cmd/
│   └── main.go              #  エントリーポイント
├── internal/
│   ├── config/              #  設定管理
│   ├── embedder/            #  ベクトル埋め込み
│   ├── indexer/             #  インデックス処理
│   ├── mcp/                 #  MCPサーバー
│   └── vectordb/            #  ベクトルDB
├── models/                  #  ONNXモデル
├── build.sh                 #  ビルドスクリプト
└── integration_test.go      #  統合テスト

# トラブルシューティング

# # モデルのダウンロードに失敗

原因: インターネット接続またはHugging Faceサーバーの問題

解決方法:

1. インターネット接続を確認
2. プロキシ環境の場合：

   export HTTP_PROXY=http://your-proxy:port
   export HTTPS_PROXY=http://your-proxy:port
   

3. 手動ダウンロード（models/DOWNLOAD.md参照）
4. 再試行（不完全なファイルは自動削除）

# # GPUが検出されない

config.jsonで明示的に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の改善に貢献してくださった皆様に感謝します：

• @badri - 複数ドキュメントパスとglobパターン対応 (# 2)、- -config CLIフラグ (# 3)
• @io41 - プロジェクトのクリーンアップとドキュメント改善 (# 4)

皆様の貢献がDevRagをより良くしています！

# 作者

towada