rag: manage the optional code search index

paqad-ai rag manages Paqad's optional code search index. RAG stands for retrieval-augmented generation: before the AI answers, a few passages from your project that look relevant to the request are found and placed in front of it. To make that possible, Paqad splits your files into small pieces (chunks) and stores a numeric fingerprint of each one (an embedding) in a local index under .paqad/vectors/.

RAG is off unless you turn it on. When it is off, or no index exists yet, nothing extra is added and the AI finds code with its normal search tools. Onboarding offers to turn it on for coding projects.

Subcommands at a glance

Command	What it does
rag init	Turns RAG on and builds the index.
rag status	Shows the settings and the state of the index.
rag rebuild	Rebuilds the whole index from scratch.
rag probe <query>	Shows the best matches for a query and their scores, for troubleshooting.
rag eval	Runs Paqad's built-in retrieval test set.
rag clear	Deletes the index and turns RAG off.
rag refresh-context	Background worker that Paqad's prompt hook starts; you normally do not run it yourself.

Every subcommand accepts --project-root <path> and prints its result as JSON.

Turn RAG on

paqad-ai rag init [--provider local|openai|voyageai] [--model <model>] [--yes]

You choose where embeddings are made:

Provider	Default model	What to know
local	Xenova/all-MiniLM-L6-v2	Runs on your machine with no account. The model is downloaded once to ~/.paqad/models and shared by all projects. A larger, code-tuned option, Xenova/jina-embeddings-v2-base-code, is offered in the interactive picker.
openai	text-embedding-3-small	Needs OPENAI_API_KEY. Pieces of your files are sent to OpenAI to be embedded.
voyageai	voyage-code-3	Needs VOYAGE_API_KEY. Pieces of your files are sent to Voyage AI to be embedded.

• Without --provider, an interactive terminal asks you; a script or CI job uses the provider already configured, or local.
• For a remote provider, Paqad reads the key from the environment first, then from .paqad/secrets.env. If the key is missing in an interactive terminal, it asks for it and saves it there with owner-only file permissions.
• If a valid index already exists, init asks before rebuilding. Pass --yes to rebuild without asking. In a non-interactive run without --yes, it prints the current status and stops.
• If the build fails in an interactive terminal, you can retry, enter a new key, or switch provider.

Check the index

paqad-ai rag status

Prints JSON with enabled, configured_provider, configured_model, index_present, valid, built_at, chunk_count and size_bytes. When the index exists but cannot be used, for example because it was built with a different model, reason explains why.

paqad-ai rag rebuild

Rebuilds the full index with the current settings. It refuses to run if RAG is not turned on and configured. Day to day you rarely need it: in tools where Paqad's prompt hook runs (see the last section), the index is kept in step with your working files in the background, and paqad-ai refresh --context does the same on demand.

Troubleshoot weak results

paqad-ai rag probe "where do we validate coupons" [--top-n 10]

Shows the top matches for a query before any cut-off is applied, with each file's score, whether it clears the similarity threshold (rag_similarity_threshold, default 0.75) and the lower relief floor (rag_relief_floor, default 0.35), and the gap to the threshold. It changes nothing, and is the quickest way to see why retrieval returned little or nothing.

Run the built-in evaluation

paqad-ai rag eval [--mode lexical-vs-rag|rag-vs-candidate|feature-off-vs-on] [--baseline <file>] [--model-graded]

Runs a small fixed set of test queries against your index and scores the results with a script. The default mode is rag-vs-candidate; --baseline compares against a saved snapshot. In feature-off-vs-on mode, Paqad compares retrieval switched off against switched on and exits with 1 if turning it on lowers quality, or raises token use without improving task success, which makes it usable as a CI gate. --model-graded asks for an extra section graded by an AI model, but the command-line runner in this release has no grader connected, so that section comes back as zeros.

Turn RAG off

paqad-ai rag clear [--yes]

Deletes the index in .paqad/vectors/ and sets rag_enabled to false. It asks for confirmation; in a non-interactive run it refuses unless you pass --yes.

Where settings are stored

• Team choice: onboarding writes the RAG choice to .paqad/configs/.config.rag, which is committed and shared.
• Your machine: rag init and rag clear write to .paqad/.config, which is git-ignored and overrides the team file for you only. A PAQAD_* environment variable overrides both.
• Which files are indexed: .paqad/rag.ignore.yaml holds project-specific include and exclude lists. By default Paqad also respects your project's ignore files and skips build output, caches and version-control folders.
• Keys: .paqad/secrets.env. paqad-ai doctor checks that it is git-ignored and not readable by other users.

When retrieved context reaches the AI

The index only helps if something passes its results to the AI. In Claude Code and Codex CLI, Paqad's prompt hook starts rag refresh-context in the background on each prompt; the refreshed context is used from the next prompt on. Other tools do not run that hook. Retrieval chooses passages by similarity scores; whether they are useful to the task is the AI's judgment. For the concepts behind this, see RAG overview.