Projects / Cortex

Cortex

A RAG codebase companion. Indexes repos and pull requests with AST-aware chunking, then answers questions with cited code over streaming chat.

Source on GitHubDocker Compose file

Demo

A real recording of Cortex running locally: a new chat, the question typed, the answer streaming in with file and line citations, then the Sources drawer.

Overview

Cortex lets you point at any GitHub repository and chat with it in plain English. It indexes the source code and the engineering history (merged pull requests, their descriptions and diff summaries), so it can answer what the code does and why it was written.

Open /owner/repo in the browser and Cortex resolves the repository, indexes it in the background with a progress bar, and then answers questions with citations to files and line ranges.

The demo below indexes frick, another project of mine, and asks how its double-frick feature works.

What it does

Screenshots

Cortex chat with the question about running frick twice typed in
Ask in plain English, scoped to one repository.
Cortex streaming an answer token by token
The answer streams in as it is generated (Server-Sent Events).
Finished Cortex answer with inline file and line citations
Every claim carries a file and line range, such as cmd/frick/main.go:188-192.
Cortex Sources Cited drawer showing the README chunk used
The Sources drawer shows the exact chunks the answer was built from, split into code and PR history.

How it works

Interactive diagram · 9 steps
open / ask enqueue job fetch files, PRs chunks vectors top-k chunks context tokens A Vue 3 app with a chat window, an indexing progress bar and a citations drawer. Visiting /owner/repo asks the API to resolve the repository and starts indexing it the first time.Vue 3 frontend/:owner/:repo, chat1 The gateway. It resolves repositories, creates chat sessions, queues indexing jobs and streams answers over Server-Sent Events. Users and chat history live in SQLite, or PostgreSQL in production.Flask APIREST + SSE, JWT auth2 A Redis queue holds indexing jobs and their progress, so the API stays responsive while a repository is being processed in the background.Redis queuejobs and progress3 Runs the indexing pipeline in the background: fetch the repository, chunk it, embed the chunks and store them. Progress is reported back through the job status endpoint.ƒCelery workerindexing pipeline4 Supplies the file tree and contents, plus merged pull requests with their descriptions and diff summaries, so Cortex can explain why code exists as well as what it does.GitHub APIfiles + merged PRs5 Code is split along real function and class boundaries using tree-sitter, so each chunk is a meaningful unit instead of an arbitrary slice of text.tree-sitter chunksfunctions + classes6 Each chunk is turned into a vector with gemini-embedding-001 (1536 dimensions). The same model embeds your question at query time.Gemini embeddingsgemini-embedding-0017 A persistent vector store with separate collections for code and for pull requests. Nearest-neighbour search by cosine distance finds the chunks closest to a question.ChromaDBvector index (cosine)8 When you ask a question the API passes it here. Cortex embeds it, pulls the closest code and PR chunks from ChromaDB, and builds a prompt that carries those chunks as numbered sources.RAG retrievalembed question, top-k9 The language model writes the answer using only the retrieved context, and is asked to cite files and line ranges so you can check every claim.Gemma LLMvia Gemini API10 Tokens stream to the browser as they are generated, then the response closes with the list of cited sources, which opens in the Sources drawer.Streamed answertokens + citations11
Pick a stepHover, focus or tap any shape to see what it does.
Solid arrows are the indexing path. Dashed arrows are what happens when you ask a question. Editable source (.excalidraw)
  1. You open a repository in the Vue app. The Flask API resolves it and, the first time, queues an indexing job in Redis.
  2. A Celery worker picks the job up and fetches the file tree, file contents and merged pull requests from the GitHub API.
  3. Code is chunked with tree-sitter, every chunk is embedded with Gemini, and the vectors are stored in ChromaDB.
  4. When you ask a question, the API embeds it and retrieves the closest code and PR chunks as numbered sources.
  5. A Gemma model answers using only that context and cites files and line ranges. Tokens stream back to the browser, and the sources open in the drawer.

Install and try it

Cortex needs a Google AI Studio API key, Python 3.11+, Node 18+ and Redis. It reads repositories through your gh login, or a GITHUB_TOKEN.

  1. Get the code and add your key
    git clone https://github.com/BriskAM/cortex.git
cd cortex
echo 'GOOGLE_API_KEY=your-key' > .env
  2. Start Redis
    redis-server --daemonize yes
  3. Set up the backend
    cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cd ..
  4. Start the worker and the API

    Run them in two terminals. On macOS the worker needs --pool=solo; the default process pool starts without the Flask app context and every task fails.

    PYTHONPATH=. backend/.venv/bin/celery -A backend.celery_worker.celery worker --pool=solo --loglevel=info
PORT=5001 PYTHONPATH=. backend/.venv/bin/python backend/run.py
  5. Start the frontend

    Then open http://localhost:5173/BriskAM/frick (or any owner/repo). To run everything in containers instead, use docker compose up --build.

    cd frontend
npm install
npm run dev

Notes

All projects · Home