Retrieval-Augmented Generation over an entire codebase — chat with your repository, get answers grounded in real AST-parsed code with file/line citations, not just embedding-similarity guesses.
Most "chat with your codebase" projects chunk files by character count and call it a day. CodeRAG parses code with tree-sitter first, so retrieval units are actual functions, classes, and methods — not arbitrary 500-character windows that split a function in half.
┌─────────────┐
GitHub / ZIP ──▶ │ Indexer │
/ local folder │ Pipeline │
└──────┬──────┘
│
┌─────────────┼─────────────┐
▼ ▼ ▼
tree-sitter AST-based Embeddings
parser chunker (Gemini/OAI/
local ST)
│ │ │
└─────────────┴──────┬──────┘
▼
Postgres (metadata)
Qdrant (vectors)
│
┌──────────────┼──────────────┐
▼ ▼ ▼
Dense search BM25 sparse Reciprocal
(Qdrant) search Rank Fusion + MMR
└──────────────┬───────────────┘
▼
LLM (Gemini/OpenAI/
Anthropic) + citations
▼
/chat response
Every item below was written, executed, and checked against real output before being committed — not generated from a template and left untested.
| Area | Status |
|---|---|
| FastAPI backend | Full app boots, /health, /docs, /redoc, all routes register and return real responses (tested with a running uvicorn instance) |
| Tree-sitter parsing | Python and TypeScript/JavaScript/TSX — extracts functions, classes, methods, decorators, docstrings, params, inheritance, function calls, imports. 8 unit tests, all passing |
| AST-based chunking | One chunk per function/method/class using real parser-reported line ranges; sliding-window fallback for unstructured content |
| Embeddings | Gemini (default), OpenAI, and local Sentence-Transformers/BGE (no API key needed) — real provider factory |
| Vector store | Qdrant, one collection per repository, using the current query_points API |
| Hybrid retrieval | Dense (Qdrant) + sparse (BM25 with camelCase/snake_case-aware tokenization) fused via Reciprocal Rank Fusion, with an MMR diversification pass |
| Chat with citations | /chat retrieves context, calls the LLM, and returns file path + line range + similarity + confidence score for every claim; SSE streaming supported |
| Auth | JWT issuance/verification, GitHub OAuth flow |
| Repository ingestion | GitHub clone, ZIP upload (with zip-slip protection), local folder registration |
| Background indexing | Inline via FastAPI BackgroundTasks for small/medium repos; a real Celery task (app/workers/tasks/indexing_tasks.py) for large ones |
| Frontend | A working static chat UI (frontend/index.html) — add a repo, watch it index, ask questions, see citations. No build step |
| Tests | 15 tests covering parsers, chunking, and API — pytest tests/ -v |
| Docker | docker compose up starts Postgres, Redis, Qdrant, the API, a Celery worker, and the frontend |
| CI | GitHub Actions: ruff, black, mypy, pytest on every push/PR |
The full spec this project is based on includes 13 languages, 5 embedding providers, 5 LLM providers, Cohere/cross-encoder/FlashRank reranking, GraphRAG, a multi-agent LangGraph pipeline, a full Next.js dashboard, a security scanner, a documentation generator, and more. Building all of that as genuine, tested, non-placeholder code in one pass isn't realistic — most of it would end up as hollow stubs, which help no one.
This pass ships a real, working core: index a Python or TypeScript repo, ask it questions, get cited answers. Everything else is designed to slot in without changing the architecture:
- More languages: add
<lang>_parser.pyfollowingpython_parser.py's pattern, register it inapp/parsers/registry.py. Unregistered languages already chunk and index today via the sliding-window fallback — they just don't get structural (function/class) extraction yet. - Reranking:
app/rerankers/is scaffolded; wire a cross-encoder or Cohere call intoHybridRetriever.retrieve()after fusion. - GraphRAG / dependency graphs:
app/graph/is scaffolded; theimportsandcallsdata is already extracted per-symbol by the parsers, so building the graph is an aggregation step, not new extraction work. - Multi-agent workflow:
app/graph/is also where a LangGraph planner/retriever/reviewer pipeline would live, replacing the current single-shotChatServicefor complex queries. - Full dashboard: the static
frontend/index.htmlproves the API contract works end-to-end; a Next.js app can replace it without touching the backend.
cp .env.example .env
# fill in GEMINI_API_KEY (default provider) or switch EMBEDDING_PROVIDER /
# LLM_PROVIDER in config.yaml to sentence-transformers (no key needed)
docker compose up --build- API: http://localhost:8000/docs
- Frontend: http://localhost:3000
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
# start postgres/redis/qdrant however you like, then:
python scripts/init_db.py
uvicorn app.main:app --reloadpytest tests/ -v # 15 tests
ruff check app/ # lint
black app/ # format
mypy app/ # typesFull interactive docs at /docs (Swagger) and /redoc. Core endpoints:
POST /api/v1/repositories Register a repo (github | zip | local)
POST /api/v1/repositories/{id}/index Trigger indexing
GET /api/v1/repositories/{id} Poll indexing status
POST /api/v1/chat Ask a question, get an answer + citations
POST /api/v1/search Raw hybrid search, no LLM
GET /api/v1/health Liveness probe
Example:
curl -X POST localhost:8000/api/v1/repositories \
-H "Content-Type: application/json" \
-d '{"name": "my-repo", "source_type": "github", "source_url": "https://github.com/org/repo"}'
curl -X POST localhost:8000/api/v1/repositories/{id}/index
curl -X POST localhost:8000/api/v1/chat \
-H "Content-Type: application/json" \
-d '{"repository_id": "{id}", "question": "Where is JWT implemented?"}'Non-secret defaults live in config.yaml (chunking strategy, embedding/LLM provider and model, retrieval params). Secrets go in .env. See .env.example for the full list.
app/
api/routes/ FastAPI route handlers
authentication/ JWT + GitHub OAuth
core/ Settings, logging
database/ Async SQLAlchemy engine/session
embeddings/ Provider implementations + factory
indexer/ Chunking strategies, indexing pipeline
llm/ Provider implementations + factory
models/ ORM models
parsers/ Tree-sitter parsers + language registry
prompts/ Prompt templates
retrievers/ Vector store, BM25 sparse index, hybrid fusion
schemas/ Pydantic request/response models
services/ Business logic (chat, repository ingestion)
workers/ Celery app + background tasks
frontend/ Static chat UI
docker/ Dockerfiles + docker-compose
tests/ pytest suite
scripts/ DB bootstrap
- Fork and branch off
main pip install -r requirements.txt- Add tests for anything new —
pytest tests/must stay green ruff check app/ && black app/ && mypy app/before opening a PR- Structural parsers for a new language are the highest-value contribution right now — see "What's deliberately scoped out" above for the pattern to follow
MIT