Your coding agent copies the first code it finds โ not the right one.
TeaRAGs is a Codebase Intelligence layer your agent queries over MCP. It indexes the repository on your machine into five layers โ three that read the code and two that judge its interfaces:
- ๐ What it does โ semantic and hybrid search over AST-aware chunks
- ๐ธ๏ธ How it is connected โ callers, callees, fan-in, transitive impact
- ๐งฌ How it has lived โ churn, bug-fix rate, ownership, age
- ๐๏ธ Whether it is laid out right โ dependency direction, leaking facades, files that change together with no edge between them
- ๐ค What the project calls things โ the naming vocabulary, inferred from the call graph, and a verdict on every new name The first three layers and why an agent needs all of them at once are laid out in Codebase Intelligence ะดะปั ะฐะณะตะฝัะฐ (Habr, in Russian).
TeaRAGs also ships agent skills that know which layer a task needs. The agent stops guessing which code is safe to copy, what is critical, and what a change will break โ it reads the dossier instead.
๐ Documentation ยท ๐ 15-minute quickstart ยท ๐ง Core concepts
๐ See It
Three questions an agent asks before touching code, answered by TeaRAGs on its own repository. Every number below is a real response, trimmed.
1. "Find retry logic I can reuse"
semantic_search { query: "retry a failed request with exponential backoff", rerank: "hotspots" }
Similarity alone puts OllamaEmbeddings#retryWithBackoff first. The dossiers of
the top two candidates tell different stories:
The closest match keeps getting fixed. The agent copies the quiet helper's shape โ or learns why the first one keeps breaking before it repeats the mistake.
{
"symbolId": "OllamaEmbeddings#retryWithBackoff",
"relativePath": "src/core/adapters/embeddings/ollama.ts",
"startLine": 290,
"endLine": 378,
"preset": "hotspots",
"git": {
"file": {
"commitCount": 28,
"ageDays": { "value": 2, "label": "recent" },
"bugFixRate": { "value": 54, "label": "concerning" },
"relativeChurn": { "value": 2.55, "label": "normal" }
},
"chunk": {
"commitCount": { "value": 11, "label": "extreme" },
"relativeChurn": { "value": 9.09, "label": "high" }
}
},
"codegraph": { "symbols": { "chunk": { "fanIn": 2, "fanOut": 6 } } }
}
Labels are computed from this repository's own percentiles, so extreme means extreme for this codebase, not for some global average.
2. "What is risky to touch around vector writes?"
semantic_search { query: "write points to the vector database in batches", rerank: "dangerous" }
Similarity alone ranks PointsAccumulator#flushBatch,
QdrantPointStore#addPointsOptimized and QdrantPointStore#addPoints first.
The dangerous preset reorders by risk and says why:
3. "Who calls it before I change it?"
get_callers { symbolId: "QdrantManager#addPointsWithSparse" }
Ten exact call sites across eight files โ method fan-in 10 ยท central, file transitive impact 47 ยท regional:
ChunkPipeline#createBatchHandler ingest/pipeline/chunk-pipeline.ts
createQdrantPipeline ingest/pipeline/pipeline-manager.ts
storeIndexingMarker (2 sites) ingest/pipeline/indexing-marker.ts
DocumentOps#add api/internal/ops/document-ops.ts
SchemaManager#storeSchemaMetadata adapters/qdrant/schema-manager.ts
EmbeddingModelGuard#readOrCreateMarker adapters/qdrant/embedding-model-guard.ts
IndexStoreAdapter#storeSchemaVersion maintenance/migration/adapters/index-store-adapter.ts
SparseStoreAdapter#rebuildSparseVectors maintenance/migration/adapters/sparse-store-adapter.ts
SparseStoreAdapter#storeSparseVersion maintenance/migration/adapters/sparse-store-adapter.ts
Need the whole chain from an entry point to this call? trace_path enumerates
every AโB path and, with a rerank preset, sorts them by how dangerous each step
is.
โ What It Answers
Ask in plain language. The plugin picks the skill, tools and rerank presets
for every question automatically โ it ships a decision table that maps intent
to the right call, so nobody has to know a preset name. Other MCP clients get
the same routing guide as an MCP resource (tea-rags://schema/search-guide).
One question per layer, most distinctive first. Every number is a real response on TeaRAGs' own repository.
1. ๐๏ธ "Is this codebase laid out correctly?"
/tea-rags:architecture-diagnostics โ get_architecture_report
Four detectors judge the borders between modules, not the risk of touching them. Each violation carries the file edges or commits that prove it, grouped into root causes:
A component is a module with a facade, or a plain directory when there is none. The facade-adoption and coupling-strength cut-offs are derived from the repository itself (Otsu), so the same report reads a small library and a monolith without tuning.
2. ๐ค "Do the names in my diff speak the project's language?"
review_changes { changes: { base: "main" }, sections: ["naming"] } โ also step
D8 of /tea-rags:mr-review and the last check of
/tea-rags:data-driven-generation
The project's vocabulary is read from its call graph: how values of each type are named, which role word each directory gives its types, which word the project already uses for a concept. Only declarations on added lines are judged, and the changed files are left out of the evidence, so a diff never confirms itself:
Verdicts are CONFORMS, MISFIT with a suggestion, NEW_TERM with the
project's closest terms, and COLLISION for a name already taken elsewhere. The
rules are checked against the project's own history: every type rename a commit
message records is a case the tool must flag. get_ontology_report audits the
whole vocabulary โ synonyms, homonyms, outliers.
3. ๐งฌ "We have four payment-gateway retries. Which one should I copy?"
semantic_search with proven โ /tea-rags:data-driven-generation runs it as
its template step
Similarity finds all four; history decides. proven ranks long-lived,
low-bug-rate, multi-author code first, and every result carries its dossier โ
commits, bug-fix share, age, owners โ labelled against this repository's own
percentiles. The closest match by text is often the one fixed every sprint; see
See It โ 1 for a real pair.
4. ๐ธ๏ธ "How does a request get from the API to the card charge, and which step is riskiest?"
trace_path with dangerous โ get_callers for a single hop
Every call path between the two symbols, resolved from the call graph rather than guessed from names, with each step ranked by how risky it is to touch. An ambiguous call is reported as ambiguous, never picked at random. See See It โ 3 for the ten call sites of a real write path.
5. ๐ "Where do we charge a bill with a saved card?" โ when the code says invoice
hybrid_search โ dense vectors for the meaning, BM25 for exact names
The code is chunked on AST boundaries, so a result is a whole method with its class, not a window of N lines. Search by meaning crosses the vocabulary gap between the question and the code; BM25 still pins an exact identifier when the question names one.
The right column shows what runs under the hood.
๐บ๏ธ Understand
โป๏ธ Reuse and generate
๐ฏ Change safely
๐ Find problems
๐ฅ Review, ownership and audit
โจ Features
- ๐ Git- and codegraph-aware ranking โ 23 rerank presets blend churn,
bug-fix rate, ownership and age with fan-in, PageRank and transitive impact
(
proven,hotspots,techDebt,blastRadius,criticalPath, โฆ), plus 12 filter presets - ๐ธ๏ธ Call graph โ callers, callees, cycles and AโB paths (
get_callers,get_callees,find_cycles,trace_path) for TypeScript, JavaScript, Ruby, Swift and Python at a high tier - ๐๏ธ Architecture report โ Stable Dependencies at component level, imports
that leak past an adopted facade, files that change together with no edge
between them, and distance from the main sequence (
get_architecture_report) - ๐ Change review โ one call over a working-tree change or a branch: names
off the project vocabulary, co-change partners the change left untouched,
per-file cohesion, and new edges that break architecture boundaries
(
review_changes) - ๐ค Naming review โ the project's vocabulary inferred from the call graph:
verdicts on value and type names, the project's own word for a synonym, a
review of every name a diff declares (
review_changes), and a whole-code audit of synonyms, homonyms and outliers (get_ontology_report) - ๐ง Agent skills โ the plugin routes every question to the right tools and
presets on its own; 15 ready-made workflows (
explore,bug-hunt,risk-assessment,data-driven-generation,mr-review, โฆ) plusdinopowers, 10 wrappers that feed index signals intosuperpowers - ๐ 100% local โ embedded Qdrant and DuckDB, no Docker; embeddings through Ollama โ on the laptop or on any machine in your network, with the laptop as an automatic fallback (see Embedding providers) โ with OpenAI, Cohere and Voyage optional
- ๐ Always fresh โ incremental reindex, auto-update on a target branch, per-worktree index clones, and a drift report that names the exact command to run
- ๐ข Built for enterprise monorepos โ AST chunking for 9 languages, parallel pipelines, validated on a 3.5M-line production monolith
๐ฆ Installation
๐ป System requirements
Disk taken by real indexes (turbo quantization, dense + sparse vectors):
The call graph grows with the code; the vector index much less โ a codebase five times smaller still takes 1.2 GB.
Pull the code-embedding model:
ollama pull unclemusclez/jina-embeddings-v2-base-code:latest
Claude Code โ plugins plus a setup wizard that detects your hardware and tunes the pipeline:
/plugin marketplace add artk0de/TeaRAGs-MCP
/plugin install tea-rags-setup@tea-rags
/tea-rags-setup:install
/plugin install tea-rags@tea-rags
Any MCP client (Cursor, Roo Code, Continue, โฆ):
npm install -g tea-rags
{
"mcpServers": {
"tea-rags": {
"command": "tea-rags",
"args": ["server"]
}
}
}
Qdrant downloads and starts on first use. Cloud embeddings (OpenAI, Cohere, Voyage), an external Qdrant, and the built-in ONNX provider (beta) are covered in the installation guide.
๐ธ๏ธ The call graph
The call graph is on by default. To index a project without it, set
CODEGRAPH_ENABLED=false for that run, or pin it on an indexed project:
tea-rags projects set-env --name <alias> CODEGRAPH_ENABLED=false
The flag is recorded per project, so later runs from the CLI, the MCP server or
auto-update keep each project's choice. Projects indexed while the call graph
was opt-in keep the state they were indexed with; turn it on for one with
CODEGRAPH_ENABLED=true in the same command. Details:
Codegraph Enrichments.
๐ Quick Start
tea-rags index-codebase /path/to/repo --name myrepo # first index: register + index
tea-rags prime /path/to/repo # index state, drift, signal thresholds
In Claude Code, /tea-rags:index does the same. Then ask your agent:
- "How does auth work in this project?"
- "Find stable examples of retry logic I can copy."
- "What breaks if I change the payment module?"
๐ค Why TeaRAGs?
๐ Compared to other tools
TeaRAGs is not a coding agent. It is the context layer an agent queries, so the closest comparisons are the tools that hand a codebase to an LLM. Every competitor cell links to that product's own documentation, checked on 2026-09-23; "โ" means the capability is not in those docs.
Two names that usually come up here changed shape. Cody Free and Cody Pro shut down on 2025-07-23 (Sourcegraph); Cody Enterprise continues and uses Sourcegraph Search as its context source, which is why it shares the Sourcegraph row. GitHub ended the Copilot Workspace technical preview on 2025-05-30 (GitHub Next).
A wider table against other MCP code-search servers (claude-context, serena, grepai, โฆ) lives in the comparison guide.
โ๏ธ How It Works
%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#fdf8e7", "primaryTextColor": "#2d2d2d", "primaryBorderColor": "#d4af37", "lineColor": "#c4941f", "secondaryColor": "#f5f5dc", "tertiaryColor": "#fafafa", "mainBkg": "#fdf8e7", "secondBkg": "#f5f5dc", "nodeBorder": "#d4af37", "clusterBkg": "#fffdf6", "clusterBorder": "#d4af37", "titleColor": "#2d2d2d", "edgeLabelBackground": "#ffffff", "fontSize": "15px"}}}%%
flowchart LR
User([๐ค You])
Agent[๐ค Coding agent<br/>+ TeaRAGs skills]
subgraph pkg["๐ต tea-rags"]
MCP[๐ MCP server<br/>28 tools]
CLI[โจ๏ธ CLI<br/>index ยท prime ยท projects ยท auto-update]
Core[โ๏ธ Core<br/>chunk ยท enrich ยท search ยท rerank]
MCP --> Core
CLI --> Core
end
subgraph storage["๐ป Local storage"]
Qdrant[(๐๏ธ Qdrant<br/>embedded ยท vectors + signals)]
DuckDB[(๐ฆ DuckDB<br/>embedded ยท call graph)]
end
Embeddings[โจ Embeddings<br/>Ollama ยท OpenAI ยท Cohere ยท Voyage]
Repo[๐ Your repo<br/>code + git history]
User <--> Agent
Agent <--> MCP
User --> CLI
Core <--> Qdrant
Core <--> DuckDB
Core --> Embeddings
Core --> Repo
Your agent calls TeaRAGs over MCP; you run the CLI to index and maintain. Both
drive one core: it chunks code on AST boundaries, embeds each chunk, attaches
git and call-graph signals, and ranks results by the preset the task asks for.
Qdrant and DuckDB run embedded under ~/.tea-rags โ no Docker, no servers to
manage.
โก Indexing Speed
Measured on a production monolith โ 3.3M lines of Ruby and TypeScript, tests included, plus 162K lines of docs in ~34k files โ and on TeaRAGs itself. Search is available as soon as the embeddings are stored; git and call-graph enrichment keep filling in behind it.
ยน Ollama on a LAN mini-PC with an AMD RX 7800M eGPU (ROCm), measured 2026-09-27. Ollama 0.34.4 (auto-updated from 0.24.0 that day) embeds one chunk per GPU pass through a single llama-server slot, which keeps the GPU about 55% busy โ expect roughly a quarter to a third faster once that is fixed. Direct support for the llama.cpp server, as an alternative to Ollama, is coming soon.
For scale: in January 2026, on the smaller monolith of the time, the server TeaRAGs was forked from needed 4โ10 hours for a full index and 40+ minutes to catch up on 100 commits.
Why it is fast. Every stage runs in parallel: 50 files in flight,
tree-sitter parser and git-blame worker pools, GPU batches of up to 512 chunks,
and the call graph in its own DuckDB process under a hard 2 GB memory cap, with
SCC and PageRank computed as streams. Embeddings dominate a full rebuild, so a
change to git or call-graph signals is recomputed with --force-enrichments
without re-embedding a single chunk โ minutes instead of a full reindex. Each
run picks its embedding batch size and concurrency itself โ backing off when the
server fails on a batch, climbing toward the fastest measured size, remembering
the result per endpoint โ within bounds that tea-rags tune measures for your
hardware in about 90 seconds; details in
Performance Tuning.
๐ Measured
Call-graph quality is checked against independent oracles, not eyeballed.
ยน About two thirds of the TypeScript gap is callbacks passed through props and dependency injection โ the type checker names a function type there, not an implementation, so no static resolver can pin those edges.
The Python oracle harness ships in the repo
(scripts/py-codegraph-jedi-oracle.ts), so those numbers can be reproduced on
your own corpus.
Languages Compatibilities
Support: ๐ maximum ยท ๐ full ยท ๐ high ยท ๐ medium ยท ๐ moderate ยท ๐ partial/low ยท ๐ minimal ยท ๐ none
What tea-rags supports per language and at what level. AST chunking is how
source is split into searchable chunks; Test chunking is how faithfully test
structure is preserved; Codegraph is the call-graph resolution ceiling (the
realized per-project number lives in the tea-rags prime digest, not here).
Rows are ordered by overall capability, richest support first.
Language / toolchain versions
Descriptor policy is authoritative. Fixture-validated means syntax examples, not compiler conformance. Grammar-bounded means installed parser plus project fixtures; no certified release range. Unversioned means dialect-based documents or syntax-blind fallback. Internal revisions only route index rebuilds.
MCP clients
Every language above works the same way in every client โ the client only decides how much of the tooling on top of the MCP server you get.
Embedding providers
Set EMBEDDING_PROVIDER; EMBEDDING_MODEL overrides the default model.
Throughput per provider and how to choose: Embedding Providers.
Ollama on another machine, the laptop as the fallback. Ollama does not have to run where the agent does. Put it on any computer in your local network โ a desktop GPU, a home server, a spare Mac โ and keep the laptop's own GPU or Apple chip as the fallback. TeaRAGs switches to the fallback when the primary stops answering or fails three embed calls in a row, and switches back once the primary is healthy again. Your code and index stay on the laptop; only chunk text crosses your own network.
EMBEDDING_BASE_URL=http://gpu-box:11434 # primary: any machine on your LAN
EMBEDDING_FALLBACK_URL=http://localhost:11434 # fallback: the laptop itself
Details: Ollama provider.
Embedding model comparison
Measured on one GPU host and three code corpora (TypeScript, two Ruby); quality is dense MRR on 200 identifier-free natural-language queries per corpus.
Models of 1.5Bโ7B parameters gain mostly at R@1 and run 15โ110ร slower: every model finds the target in the top 10 on 99โ100% of the TypeScript queries, and an agent reads the whole top-10 page. Which model to pick: Embedding model choice; the method and all tables: Embedding model comparison.
โจ๏ธ CLI
๐ FAQ
How is this different from Aider or Copilot? Those are coding agents; TeaRAGs is what an agent asks before it writes. It indexes the repository once, keeps the index fresh, and answers over MCP with code plus its history and call graph. Any agent that speaks MCP can use it. See Compared to other tools.
Does it need the cloud? No. Qdrant and DuckDB run embedded under
~/.tea-rags, and the default embeddings come from a local Ollama (or the
built-in ONNX runtime), so code never leaves your machine. The network is used
to download the Qdrant binary on first run and for a cached npm version check in
tea-rags prime. OpenAI, Cohere and Voyage are opt-in.
How big a repository can it handle? The largest measured index is a production monolith of 3.3M lines of Ruby and TypeScript, tests included: ~34k files, 175k chunks, 2.0 GB of vectors and ~460 MB of call graph (see System requirements). After the first run, reindexing is incremental โ only changed files are re-embedded.
Which languages are supported? Nine languages get AST chunking and a call graph of varying depth: TypeScript, JavaScript, Ruby, Python, Swift, Go, Java, Rust and Bash. Markdown is chunked by heading; SQL and JSON fall back to plain character chunks. Per-language depth is in Languages Compatibilities.
How accurate are the git signals? They are read from your real history; the
one heuristic is bug-fix detection. A commit counts as a bug fix when its
message says so (fix:, [Bug], TICKET-123 Fix โฆ, fixes #123) or it
arrived through a merged fix/, hotfix/ or bugfix/ branch; "fix typo", "fix
lint" and similar are excluded. Chunk-level history follows each chunk's lines
through diff hunks and looks back 6 months by default (12 for file level); files
over 5,000 lines get file-level signals only. Labels such as high or
concerning are percentiles of your own repository, and signals backed by only
a few commits are dampened before they affect ranking.
๐ Documentation
๐ From the Blog
Engineering notes behind the releases, each with the corpus it was measured on โ all posts ยท RSS.
โญ Star History
๐ค Contributing
See CONTRIBUTING.md for workflow and conventions.
๐ Acknowledgments
Started as a fork of mhalder/qdrant-mcp-server โ clean architecture, solid tests, open-source spirit โ and its ancestor qdrant/mcp-server-qdrant. Code vectorization inspired by claude-context (Zilliz).
Feel free to fork this fork. It's forks all the way down. ๐ข
