TeaRAGs 🦖🍵

Trajectory Enrichment-Aware RAG for Coding Agents

Your coding agent copies the first code it finds — not the right one.

TeaRAGs is an MCP server for code search that enriches every retrieved chunk
with git history: authorship, churn, bug-fix rate, ownership. Your agent stops
learning from hotspots and starts learning from stable, owned, battle-tested
code.

📖 Full documentation · 🏁
15-minute quickstart
· 🧠
Core concepts

The Problem

1. Understanding a monorepo is expensive — for humans AND agents

Every new developer pays in hours. Every fresh agent session pays in tokens.
Naming conventions, domain logic, local idioms — all of it has to be rebuilt
from scratch, every time.

2. Bad code hygiene is a tax on your agent

Confusing names mean the agent reads more files. More files mean more tokens,
slower responses, and a higher chance of picking the wrong example. Your
codebase's technical debt is now your AI bill.

3. Agents can't tell stable code from a hotspot

Standard code search ranks by embedding similarity alone. It doesn't know which
function gets bug-fixed every sprint, which module hasn't been touched in two
years, or whose name is on the commits. So the agent copies whatever looks
similar — including the broken examples.

The Solution

TeaRAGs gives your agent two things it can't get from vanilla code search.

1. Every chunk carries its own history

Retrieved code comes with signals about who wrote it, how stable it is, how
often it gets bug-fixed, and how impactful a change would be. Semantic
similarity stops being the whole answer — it becomes the floor.

2. Pre-built skills, not just raw tools

TeaRAGs ships agent skills — ready-made playbooks that tell your agent when
and how to use the signals. No prompt engineering required:

• explore — orient in an unfamiliar codebase
• data-driven-generation — write code backed by stable, owned templates
• risk-assessment — know what you'd break before you break it
• refactoring-scan · bug-hunt · pattern-search — and more

Install the plugin, your agent learns the workflow.
See all skills →

Bonus: dinopowers — a companion plugin with 10 wrappers over
superpowers:* skills (Jesse Vincent's
skills library for Claude Code) that inject tea-rags signals into brainstorming,
planning, debugging, TDD, review, and completion flows. Mean eval delta +71pp
across 136 cases.
Learn more →

Use Cases

🛡️ Safe code generation

Your agent writes new code backed by stable, canonical templates — modules
with a low bug-fix rate, long stability, and a clear owner. No more copying from
last sprint's hotspot. Skill: data-driven-generation ·
Why stable code is safer →

🔧 Refactoring planning & problem-pattern discovery

Find the 5% of code responsible for 80% of incidents. High churn + high
bug-fix rate + concentrated ownership = your next production issue — and your
next refactoring candidate. Skills: refactoring-scan, bug-hunt

🎯 Risk assessment before changes

Before modifying a function, the agent checks who depends on it, how often it
breaks, and what its ticket history says. Know the blast radius before you
blast. Skill: risk-assessment ·
Coupling & blast radius theory →

🗺️ Learning an unfamiliar codebase

Ask questions instead of reading directory trees. "How does auth work?"
returns the stable, canonical implementation with its history attached — not
a random similar-looking snippet. Skill: explore

How It Works

flowchart LR
    User([👤 You])

    subgraph mcp["TeaRAGs MCP Server"]
        Agent[🤖 Agent<br/>runs skills]
        TeaRAGs[🍵 TeaRAGs<br/>search · enrich · rerank]
        Agent <--> TeaRAGs
    end

    Qdrant[(🗄️ Qdrant<br/>vector DB)]
    Embeddings[✨ Embeddings<br/>Ollama/OpenAI]
    Codebase[📁 Your Codebase<br/>+ Git History]

    User <--> Agent
    TeaRAGs <--> Qdrant
    TeaRAGs <--> Embeddings
    TeaRAGs <--> Codebase

You talk to your agent. The agent runs a TeaRAGs skill. TeaRAGs searches your
code, enriches each result with git history, and ranks by what the skill needs —
stability, ownership, risk, or pure relevance.

What You Get

• 🧬 Trajectory-aware retrieval — the only open-source code RAG that scores
  results by git history, not just embedding similarity
• 📚 Ships with agent skills — 6 ready-made playbooks for exploration,
  generation, risk assessment, and index management (plus 2 internal strategies)
• 🔒 Local-first, privacy-first — works fully offline with Ollama; your code
  never leaves your machine (cloud providers optional)
• 🚀 Built for monorepos — AST-aware chunking across 10+ languages,
  incremental reindexing, parallel pipelines, millions of LOC tested

🕸️ Codegraph Enrichments (beta)

⚠️ Beta. Structural graph signals are still being calibrated across
languages and may change between releases.

Beyond git history, tea-rags can enrich chunks with structural graph signals
— call graph and import graph (fan-in, fan-out, instability, PageRank,
transitive impact) — and expose graph-query MCP tools (get_callers,
get_callees, find_cycles, trace_path). This powers blast-radius and
architectural-hub ranking.

Codegraph is disabled by default (beta). Opt in with the CODEGRAPH_ENABLED
environment variable, then re-index:

CODEGRAPH_ENABLED=true   # enable graph signals + tools
CODEGRAPH_ENABLED=false  # default — graph extraction off

See the
Codegraph Enrichments docs
for signals, presets, supported languages, and configuration.

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.

Who It's For

• Developers in large monorepos — where "find similar code" returns a dozen
  near-duplicates and you need the canonical one
• Solo devs doing agentic development — agent-driven workflows produce
  bursts of micro-commits that wreck churn metrics. TeaRAGs ships a
  GIT SESSIONS
  mode (TRAJECTORY_GIT_SQUASH_AWARE_SESSIONS=true) that groups commits by
  (author, time gap) so a 20-commit refactor session counts as one. Churn,
  bug-fix rate, and ownership stay meaningful even with a single human + an
  agent as the only contributors.
• Tech leads worried about AI code quality — who want their team's agents to
  learn from stable modules, not from last sprint's hotspot
• Privacy-sensitive teams — finance, healthcare, defense, or anyone who
  can't send source code to a cloud API

Not for: repos without git history (no signal to enrich) or teams that only
need autocomplete (use Copilot).

🚀 Quick Start

Inside Claude Code, install the TeaRAGs plugins and run the setup wizard:

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

Then install the skills plugin (Claude-only, final step):

/plugin install tea-rags@tea-rags

Optionally install dinopowers for wrappers over superpowers:* skills:

/plugin install dinopowers@tea-rags

Index your codebase:

/tea-rags:index

Ask your agent anything: "How does auth work in this project?", "Find stable
examples of retry logic", "What should I know before touching the payment
module?".

For other MCP clients, CI, or air-gapped setups, see the
manual install
(Node + npm install -g tea-rags + Ollama/ONNX/OpenAI/Cohere/Voyage).

🗂️ Project Registry

TeaRAGs maintains a per-machine registry at ~/.tea-rags/registry.json (or
$TEA_RAGS_DATA_DIR/registry.json) that records collection metadata and lets
you address indexed projects by a short name instead of an absolute path or
opaque collection id.

CLI:

tea-rags register-project --path ./my-repo --name myrepo
tea-rags list-projects
tea-rags list-projects --json
tea-rags tune --project myrepo
tea-rags unregister-project --name myrepo

MCP tools: register_project, list_projects, unregister_project.

Every project-aware tool and command also accepts an optional project
parameter alongside path and collection. Resolution priority is
collection > project > path. The registry is auto-populated at the end of each
indexing / reindexing run with the embedding model, embedding dimensions, Qdrant
URL, indexedAt timestamp, tea-rags version, and chunk count — no manual
register-project call is required for collections you index through tea-rags.

📚 Documentation

artk0de.github.io/TeaRAGs-MCP

🤝 Contributing

See CONTRIBUTING.md for workflow and conventions.

🙏 Acknowledgments

Built on 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. 🐢

⚖️ License

MIT — see LICENSE. Brand policy in BRAND.md.