Repocks: Enable RAG from In-Repo Documentation

Boke0 / Taigen Takeshita — Sat, 02 Aug 2025 18:28:22 +0000

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.

boke0 / repocks

Turn your repository into local RAG / MCPServer.

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

…

View on GitHub

Tech Stack

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:

Load Markdown documents (defaults: docs/**/*.md and ~/.repocks/**/*.md)
Generate vector embeddings using the Ollama embedding model
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:

The AI agent uses the Ollama chat model to transform your query into an embedding and performs cosine similarity search in DuckDB
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

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

Ollama: Download here

ollama pull qwen3:4b
ollama pull mxbai-embed-large

Indexing Documents

Move to your project directory and run:

cd /path/to/project
repocks index

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

$ tree .repocks
.repocks
└── store.duckdb

Using Repocks with Claude Code

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

claude mcp add repocks -- repocks start

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

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

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

Forem: Boke0 / Taigen Takeshita

Repocks: Enable RAG from In-Repo Documentation

Background: The Rise of “Context Engineering”

Context engineering

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

boke0 / repocks

Turn your repository into local RAG / MCPServer.

Repocks

What is Repocks?

Key Benefits

Quick Start

Prerequisites

Installation

Tech Stack

How It Works

1. Indexing

2. Agent Querying

Getting Started

Installation

Indexing Documents

Using Repocks with Claude Code

Conclusion