DEV Community

Cover image for Repocks: Enable RAG from In-Repo Documentation
Boke0 / Taigen Takeshita
Boke0 / Taigen Takeshita

Posted on

Repocks: Enable RAG from In-Repo Documentation

#vibecoding #rag #mcp #ai

Background: The Rise of “Context Engineering”

Recently, Vibe Coding has been gaining traction, popularizing a development experience centered around AI assistants. In this workflow, it's common to consolidate prompt instructions and development guidelines into a CLAUDE.md or similar file, which is then read by the AI model.

As a result, feeding information effectively to AI has become increasingly important. A new concept called Context Engineering is emerging as a successor to Prompt Engineering:

Context engineering

simonwillison.net

However, this approach has its challenges. Bundling all critical project knowledge into a CLAUDE.md file can quickly exceed the model's context window and lead to degraded output quality.

To solve this, I wondered if it would be possible to build a lightweight, project-local RAG (Retrieval-Augmented Generation) system. However, most examples I found focused on searching across general documentation on a developer’s machine, rather than documents within a single project.

Introducing: Repocks, a Local MCP Server for In-Repo RAG

To address this, I built Repocks, a Local MCP (Multi-Context Provider) Server that indexes and retrieves in-repo documentation to answer questions contextually.

GitHub logo boke0 / repocks

Turn your repository into local RAG / MCPServer.

Repocks

Repocks

Transform your Markdown documentation into an intelligent knowledge base. Repocks indexes your documents and provides AI-powered search and Q&A capabilities through an MCP server.

What is Repocks?

Repocks turns your collection of Markdown files into a searchable knowledge base that AI assistants can query. Whether you have technical documentation, meeting notes, or personal knowledge management files, Repocks makes them accessible through natural language queries.

Key Benefits

  • Smart Search: Find relevant information using natural language, not just keywords
  • AI-Powered Q&A: Get comprehensive answers based on your documentation
  • Easy to Update: Run index command to sync changes in your documents
  • Works with Any MCP Client: Compatible with Claude Desktop, Cline, and other MCP-supporting AI tools
  • Local & Private: Your data stays on your machine

Quick Start

Prerequisites

  • Node.js 20.9.0 or higher
  • Ollama running locally
  • npm, yarn, pnpm, etc.

Installation

# Install Repocks
npm install -g repocks
…
Enter fullscreen mode Exit fullscreen mode
View on GitHub

Tech Stack

Architecture

Repocks is built using Mastra, a modern AI agent framework. It separates concerns by using one model for text generation and another for embedding and retrieval. Both run locally to avoid any API costs.

By default:

  • Text generation: qwen3:4b (via Ollama)
  • Embedding: mxbai-embed-large (via Ollama)

How It Works

Repocks exposes two main operations: Indexing and Agent Querying.

1. Indexing

You can trigger indexing via the CLI or from an MCP client.

Here's what happens under the hood:

  1. Load Markdown documents (defaults: docs/**/*.md and ~/.repocks/**/*.md)
  2. Generate vector embeddings using the Ollama embedding model
  3. Store both the embeddings and raw text in DuckDB

Each project maintains its own DuckDB file at .repocks/store.duckdb, ensuring clean separation between projects.

2. Agent Querying

This is done via the MCP Client. It performs semantic search on your indexed docs and generates answers based on retrieved context:

  1. The AI agent uses the Ollama chat model to transform your query into an embedding and performs cosine similarity search in DuckDB
  2. Relevant documents are retrieved and used to generate a contextual answer

You can also use only search by documentQueryTool, but it’s not recommended as a workaround for context window limitations.

Getting Started

Installation

Install with npm:

npm install -g repocks
Enter fullscreen mode Exit fullscreen mode

You’ll also need to install Ollama and pull the necessary models:

ollama pull qwen3:4b
ollama pull mxbai-embed-large
Enter fullscreen mode Exit fullscreen mode

Indexing Documents

Move to your project directory and run:

cd /path/to/project
repocks index
Enter fullscreen mode Exit fullscreen mode

This will create a DuckDB file at .repocks/store.duckdb:

$ tree .repocks
.repocks
└── store.duckdb
Enter fullscreen mode Exit fullscreen mode

Using Repocks with Claude Code

You can register Repocks as an MCP server for Claude Code:

claude mcp add repocks -- repocks start
Enter fullscreen mode Exit fullscreen mode

Then in Claude Code, run /mcp and verify that repocks is connected:

Manage MCP servers
  1. repocks     ✔ connected · Enter to view details
Enter fullscreen mode Exit fullscreen mode

Conclusion

The old model of centralizing all project knowledge in a single CLAUDE.md file no longer scales. As projects grow, this leads to bloated context and lower-quality model responses.

Repocks changes that by delivering the right context at the right time—dynamically, not statically.

In my projects, I now include an instruction like:

“Ask Repocks about project-specific details when designing or implementing anything involving .”

If you're a team looking to improve both productivity and model accuracy, Repocks might be just what you need.

Check out the GitHub repo and try it out in your own workflow:
👉 https://github.com/boke0/repocks

Top comments (0)