Skip to main content

15-Minute Guide

From zero to semantic code search in one page. By the end, you'll have TeaRAGs running locally, your codebase indexed, and your first natural-language query answered.

Time estimate

5 minutes to install and start services. 5 minutes to connect and index. 5 minutes to query and explore.

Prerequisites​

Before you start, make sure you have:

  • Claude Code installed and authenticated
  • A git repository you want to search

Everything else — runtime, embedding model, vector DB, MCP registration — is handled by the setup plugin.

Step 1: Install​

Pick one of two paths — the plugin wizard (recommended) or a manual install.

Option A — via the setup plugin (recommended)​

Inside Claude Code, add the TeaRAGs marketplace and install the setup plugin (the installation wizard):

/plugin marketplace add artk0de/TeaRAGs-MCP
/plugin install tea-rags-setup@tea-rags

Run the wizard:

/tea-rags-setup:install

The wizard walks 9 steps: environment detection, Node.js, tea-rags binary, embedding provider (Ollama / ONNX / OpenAI / Cohere / Voyage), Qdrant (embedded by default), performance tuning, git analytics, MCP registration, verification. Progress is saved — if any step fails, re-run /tea-rags-setup:install to resume. Skip to Step 2 once the wizard finishes.

Two separate plugins

tea-rags-setup installs and configures the TeaRAGs MCP server itself. The tea-rags plugin — installed in Step 3 below — is Claude Code-specific and ships the skills (/tea-rags:explore, /tea-rags:bug-hunt, …). Don't install it yet.

Option B — manual install​

Use this for CI, non-Claude MCP clients (Cursor, Roo Code, Continue, …), air-gapped environments, or full control over the setup.

The full manual path — per-platform Node.js install, npm install -g tea-rags, all four embedding providers, and claude mcp add registration — lives in Installation → Option B.

Skim the 4 sub-steps there (B.1 Node → B.2 tea-rags → B.3 embedding provider → B.4 MCP register), then return here for Step 2.

Step 2: Restart Claude Code​

Restart so it picks up the new tea-rags tools. Verify:

/mcp

tea-rags should appear in the list with ~17 tools available.

Step 3: Install the skills plugin​

This is the final step before use — and it's Claude Code only (other MCP clients like Cursor or Roo Code don't support Claude plugins; they can still talk to the tea-rags MCP server directly from Step 1).

/plugin install tea-rags@tea-rags

If you used Option A, the marketplace is already added. If you used Option B and skipped the plugin marketplace, run /plugin marketplace add artk0de/TeaRAGs-MCP first.

Now /tea-rags:explore, /tea-rags:bug-hunt, /tea-rags:index, /tea-rags:risk-assessment, /tea-rags:data-driven-generation, and /tea-rags:force-reindex are available to your agent. See Skills for the full list.

Step 4: Index Your Codebase​

Open Claude Code in your project directory and invoke the indexing skill:

/tea-rags:index

The skill is smart — first run does a full index, subsequent runs do an incremental reindex (only changed files). No arguments needed; the skill infers the project path from the current working directory.

TeaRAGs will:

  1. Discover files (respects .gitignore and .contextignore)
  2. Parse code into semantic chunks using tree-sitter (functions, classes, methods)
  3. Attach trajectory signals (git + static) per chunk
  4. Generate vector embeddings via your chosen provider
  5. Store everything in Qdrant

First index takes 1–5 minutes depending on codebase size. Later runs take seconds.

Large rewrites or branch switches

Use /tea-rags:force-reindex — zero-downtime full re-index. Search stays available on the current collection while the new one is built.

Not using the tea-rags plugin?

If you went with Option B and skipped Step 3 (skills plugin), ask your agent directly: "Index this codebase with tea-rags" — it will call the index_codebase MCP tool.

Step 5: Your First Query​

Now search your code using natural language:

How does authentication work in this project?

Find where we handle errors in the payment flow

Show me the database connection logic

Results come back with file paths, line numbers, and the actual code — your agent can immediately read and reason about them.

Try these progressively​

QueryWhat it demonstrates
"Where is retry logic implemented?"Finding code by behavior, not by name
"Find recently modified authentication code"Filtering by recency
"Show me stable, low-churn utility functions"Reranking by code quality signals

Step 6: Git Intelligence (enabled by default)​

Standard semantic search is already powerful. TeaRAGs goes further — enriching every code chunk with 20+ quality signals: who wrote it, how often it changes, its bug-fix rate, associated tickets, structural imports, documentation weight, and more.

This is enabled by default (TRAJECTORY_GIT_ENABLED=true). No re-index needed — if your project is a git repo, every chunk already carries git signals.

To disable (non-git project or fast iteration), set:

-e TRAJECTORY_GIT_ENABLED=false

You can immediately ask questions that no regular code search can answer:

Find high-churn code that keeps getting fixed — the danger zones

Who owns the authentication module? Show me the dominant authors

Find stable, battle-tested implementations I can use as templates

This is trajectory enrichment awareness — the core differentiator of TeaRAGs. Every search result carries its own history, and your agent can reason about code quality, not just code similarity.

See Git Enrichments for the full list of signals and how to use them.

You're Up and Running​

In 15 minutes you've gone from zero to a fully functional semantic code search with optional git intelligence. Here's what to explore next:

Deepen Your Understanding​

  • Core Concepts — how vectorization, semantic search, and reranking work under the hood
  • What is TeaRAGs — the full story, comparisons, and non-goals

Level Up Your Agent​

Configure and Tune​