RAG in 5 minutes

End-to-end guide to the Easy RAG layer (ADR-005): build a queryable RAG over a codebase, documents or data without writing a single line of code. Everything works offline and without credentials.

Requirements

npm install -g karajan-rag      # or npx karajan-rag <command>
pnpm add @lancedb/lancedb       # default local store (optional peer)

1. Index

karajan-rag index ./my-project

What happens:

• Autodetection by file type: code (js/ts/py/go/…) is chunked respecting declaration boundaries, docs (md/txt/rst) by headings, data (csv/tsv/jsonl) in record batches with the header as context. Binaries and unknown extensions are excluded and listed — never silently ignored.
• The index persists in ./my-project/.karajan/ (gitignore it — init does that for you) with a manifest.json that stores the vector-space fingerprint (ADR-002) and the hash of every file.
• Incremental reindexing: run the same command again and only what changed is reprocessed; deleted files are invalidated from the store.

The default embedder is hash: deterministic and dependency-free, ideal to try the flow. For real semantic quality use --embedder transformers (requires @huggingface/transformers).

2. Query

karajan-rag query "how is billing calculated?" ./my-project

Hybrid retrieval (vector + BM25 with dedupe) with file:line (score) output plus the passage. The embedder self-configures from the manifest: querying with a vector space different from the indexed one is impossible.

With an AI CLI installed (claude/codex/gemini/ollama…), add generation:

karajan-rag query "how is billing calculated?" ./my-project --answer --adapter ollama

3. Use it from your agent

One command takes the folder to Claude Code:

karajan-rag init ./my-project --claude

It indexes, registers the MCP server (claude mcp add rag-my-project -- karajan-rag serve …) and writes into CLAUDE.md, between markers, the rule to ask rag_query before assuming. Run it again and the block is replaced, never duplicated. Without claude on the PATH it says so and leaves the command for you to paste.