RAGBuddy

A multi-project RAG (Retrieval-Augmented Generation) platform for coding agents and developers. RAGBuddy provides project-aware access to documentation and knowledge through a web dashboard with AI chat, CLI, and MCP server — all powered by the same underlying core.

What it is

RAGBuddy indexes the docs/ folder (configurable) of one or more registered Git repositories into Qdrant, a vector database, and exposes that index three ways:

• CLI — ragbuddy ingest/sync/search/hook/project/mcp/web
• Web dashboard — register projects, browse indexed files, upload extra documents, search, chat with a project's indexed docs, run ingest/sync with a live log, review sync history, toggle auto-sync, and copy per-project MCP config, all from a browser
• MCP server — a coding agent working in your repo can call get_project_context for a quick orientation, then search_project_docs to find the architecture doc, feature spec, or issue writeup relevant to what it's doing right now, instead of relying on whatever happened to fit in its context window

Features

• 🧠 Multi-project RAG with project-isolated retrieval
• 💬 Web AI chat over project knowledge
• 🔌 MCP server for coding agents
• 📚 Repository documentation indexing
• 📎 Upload PDF, Word, Excel, Markdown, CSV, and text documents
• 🔄 Incremental synchronization using content hashes
• 🪝 Git post-commit auto-sync
• 🗄️ Single Qdrant collection with project-level isolation
• 🧩 Ollama and OpenAI-compatible embedding providers
• 🖥️ Web Dashboard and CLI using the same core implementation

Architecture

Coding Agents / Web Chat
          │
          ▼
       RAGBuddy
          │
    ┌─────┴─────┐
    │           │
   MCP       Web / CLI
    │           │
    └─────┬─────┘
          ▼
     RAG Pipeline
          │
          ▼
       Qdrant

Each project is isolated using a project field in the Qdrant payload. Retrieval operations are always filtered by project.

See docs/steering/architecture.md for the detailed architecture.

Quick Start

Requirements

• Node.js 18+
• npm
• Docker
• Qdrant
• Optional: Ollama for local embeddings

Install

git clone <this-repository>
cd ragbuddy

npm install
npm run build

cp .env.example .env

Start Qdrant:

docker compose up -d

Configure Embeddings

For local Ollama:

EMBEDDING_PROVIDER=ollama
EMBEDDING_BASE_URL=http://localhost:11434
EMBEDDING_MODEL=bge-m3

Then:

ollama pull bge-m3

OpenAI-compatible embedding providers are also supported.

See docs/steering/setup.md for configuration details.

Register a Project

ragbuddy project register <id> <repository>

Example:

ragbuddy project register my-project /path/to/my-project

Projects can also be managed from the Web Dashboard.

Index & Sync

Initial indexing:

ragbuddy ingest <project-id>

Incremental synchronization:

ragbuddy sync <project-id>

Install Git auto-sync:

ragbuddy hook install <project-id>

RAGBuddy uses the Git repository as the source of truth. Qdrant acts as a rebuildable search index.

Web Dashboard

RAGBuddy includes a web dashboard for managing projects, documents, RAG search, AI chat, ingestion, synchronization, and MCP configuration.

Project Overview

Project Documents

Project Search

AI Chat

Start the dashboard:

npm run web

Open:

http://localhost:4300

For frontend development:

cd web
npm install
npm run dev

MCP

RAGBuddy exposes project knowledge through MCP.

Available tools:

Tool	Purpose
get_project_context	Get a compact overview of the current project
search_project_docs	Semantic search over project knowledge
get_project_document	Read a specific document
list_project_knowledge	List indexed project knowledge

Example:

claude mcp add ragbuddy -- node /absolute/path/to/ragbuddy/dist/cli/index.js mcp

The current project can be resolved automatically from the agent's working directory.

See docs/steering/mcp.md for MCP configuration and usage.

Teaching your agent to actually use it

The four tools above are visible to your agent automatically once the MCP server connects — no extra config needed for that. But an agent only reaches for a tool it happens to think of; it won't necessarily call get_project_context before diving into a task just because the tool exists. Add this to the registered project's AGENTS.md / CLAUDE.md so your agent knows when to use each one:

## Knowledge Retrieval Strategy (ragbuddy MCP)

Before implementing a non-trivial feature in this project:
  1. Use `get_project_context` first to understand the project (identity, Git status, tech stack/architecture summaries, doc inventory).
  2. Use `search_project_docs` for architecture, business rules, historical issues, conventions, and documented behavior.
  3. Use `get_project_document` to read a full doc found via search when a snippet isn't enough.
  4. Use `list_project_knowledge` to see everything currently indexed when orienting from scratch.
  5. Read the actual source code before making implementation decisions — treat it as the final authority for current behavior.

Don't force `get_project_context` for trivial tasks where it adds no value.

Knowledge Sources

RAGBuddy can index:

Repository
├── README.md
└── configured documentation paths
    ├── features/
    ├── steering/
    ├── issue/
    └── ...

Additional documents can be uploaded through the Web Dashboard.

All indexed knowledge is stored in a single Qdrant collection and isolated using the project identifier.

Documentation

Documentation	Description
docs/steering/	Architecture, stack, setup, routing, system flow, and conventions
docs/features/	Feature documentation
docs/issue/	Issues and root-cause analysis
docs/design-system/	Web UI design system

Development

npm run typecheck
npm test
npm run build
npm run web

Frontend:

cd web
npm run dev
npm run build
npx oxlint src

See CLAUDE.md and AGENTS.md for the coding-agent workflow.

License

See LICENSE.