[Resource]: DevRag - Local RAG for Context Engineering

[tomohiro-owada]

Display Name

DevRag

Category

Tooling

Sub-Category

General

Primary Link

https://github.com/tomohiro-owada/devrag

Secondary Link

Author Name

Tomohiro OWada

Author Link

https://abalol.com/

License

MIT

Other License

No response

Description

Lightweight local RAG system for Claude Code that uses vector search to retrieve only relevant document chunks, reducing token usage by 40x and search time by 15x compared to reading entire files.

Additional Comments

No response

Submission Checklist

• [x] I have checked that this resource hasn't already been submitted
• [x] My resource provides genuine value to Claude Code users, and any risks are clearly stated
• [x] All provided links are working and publicly accessible
• [x] I am submitting only ONE resource in this issue
• [x] I understand that low-quality or duplicate submissions may be rejected

[github-actions[bot]]

🤖 Validation Results

✅ All validation checks passed!

Your submission is ready for review by a maintainer.

Validated Data:

{
  "display_name": "DevRag",
  "category": "Tooling",
  "subcategory": "General",
  "primary_link": "https://github.com/tomohiro-owada/devrag",
  "secondary_link": "",
  "author_name": "Tomohiro OWada",
  "author_link": "https://abalol.com/",
  "license": "MIT",
  "description": "Lightweight local RAG system for Claude Code that uses vector search to retrieve only relevant document chunks,\nreducing token usage by 40x and search time by 15x compared to reading entire files.",
  "active": "TRUE",
  "last_checked": "2025-10-25:04-27-05"
}

---

_{This comment is automatically updated when you edit the issue.}

[hesreallyhim]

@tomohiro-owada thanks for your patience, I'm starting to develop a framework to improve efficiency in evaluating powerful tools like this, but in the meantime, an easy thing would be something simple like this: describe a task that i or some other CC user might be doing, and a prompt to give to CC - and what should i expect to see if i run that same scenario using this resource vs. not using it? basically i'm trying to go for a more evidence-based approach, and i'm letting you tell me what evidence I should look at it to be confident that this resource is effective. What do you think?

[hesreallyhim]

@tomohiro-owada hey this looks promising, i'd like to add it so i was just wondering if you're still actively maintaining it, I don't see any updates in a little while so just let me know if it's still an active project - thanks!

[tomohiro-owada]

@hesreallyhim

@tomohiro-owadahey this looks promising, i'd like to add it so i was just wondering if you're still actively maintaining it, I don't see any updates in a little while so just let me know if it's still an active project - thanks!

Thank you for your patience! I recently became a parent and haven't been able to update as frequently.

In the meantime, several contributors have helped add new features to DevRag (v1.2.0):

• Filtered search (directory and file pattern filters)
• Multiple document paths with glob patterns
• Custom config file support (--config flag)

Please find the effectiveness evidence below. I hope this helps with your evaluation framework.

DevRag Effectiveness Evidence

Test Environment

• Date: 2025-12-15
• DevRag Version: v1.2.0
• Embedding Model: multilingual-e5-small (384 dimensions)
• Test Documents: 4 markdown files (2,193 bytes total)

Test Scenario

User Query: "How does JWT authentication work?"

Method 1: Without DevRag (Read All Files)

To answer a question about JWT authentication, Claude Code needs to read files to find relevant information.

Files read:

documents/api/authentication.md  (524 bytes, 31 lines)
documents/api/users.md           (467 bytes, 37 lines)
documents/guides/deployment.md   (674 bytes, 37 lines)
documents/guides/setup.md        (528 bytes, 39 lines)
─────────────────────────────────────────────────────
Total:                           2,193 bytes, 144 lines

Token consumption: ~800-1,000 tokens (mixed Japanese/English content)

Method 2: With DevRag (Vector Search)

Query: "authentication login Bearer token"
Results: 1 relevant chunk returned

Search result:

{
  "document": "documents/api/authentication.md",
  "chunk": "# Authentication API\n\n## JWT認証\n\nJWTトークンを使った...",
  "similarity": 0.9048,
  "position": 0
}

Token consumption: ~200-250 tokens

Comparison Results

Metric	Without DevRag	With DevRag	Reduction
Files processed	4 files	1 chunk	75%
Data size	2,193 bytes	524 bytes	76%
Token consumption	~800-1,000	~200-250	~75%

Scalability Analysis

DevRag's efficiency increases dramatically with larger documentation:

Documentation Scale	Without DevRag	With DevRag	Reduction
4 files (2KB)	~1,000 tokens	~250 tokens	75%
10 files (10KB)	~3,000 tokens	~250 tokens	92%
50 files (50KB)	~15,000 tokens	~250 tokens	98%
100 files (100KB)	~30,000 tokens	~250 tokens	99%

Key insight: DevRag returns only top-K chunks (default: 5), so token consumption remains constant regardless of total documentation size.

Search Accuracy Test

Test queries and results:

Query	Top Result	Similarity	Correct?
"authentication login Bearer token"	authentication.md	0.905	✅
"user endpoints API"	users.md	0.912	✅
"Docker Kubernetes deploy"	deployment.md	0.887	✅
"setup install build"	setup.md	0.868	✅

Filtered Search Feature (v1.2.0)

New filtering capabilities allow more precise searches:

# Search only in docs/api directory
search(query: "endpoints", directory: "docs/api")

# Search only files matching pattern
search(query: "deploy", file_pattern: "guide-*.md")

Conclusion

DevRag provides:

1. 75-99% token reduction depending on documentation size
2. Sub-100ms search response vs seconds for file reading
3. Automatic relevance ranking - most relevant content first
4. Scalability - constant token cost regardless of doc size

Raw Test Data

Document Sizes

$ wc -c documents/**/*.md
  524 documents/api/authentication.md
  467 documents/api/users.md
  674 documents/guides/deployment.md
  528 documents/guides/setup.md
 2193 total

Search Response (Full)

{
  "results": [
    {
      "document": "documents/api/authentication.md",
      "chunk": "# Authentication API\n\n## JWT認証\n\nJWTトークンを使った認証方式について説明します。\n\n### トークンの取得\n\n```\nPOST /api/auth/login\nContent-Type: application/json\n\n{\n  \"username\": \"[email protected]\",\n  \"password\": \"password123\"\n}\n```\n\n### トークンの検証\n\nAuthorization headerにBearerトークンを含めてリクエストします。\n\n```\nGET /api/protected\nAuthorization: Bearer eyJhbGciOiJIUzI1NiIs...\n```\n\n## OAuth2.0\n\n外部サービスとの連携にはOAuth2.0を使用します。",
      "similarity": 0.9048761054873466,
      "position": 0
    }
  ]
}