About the Project

Inspiration

Code reviews are powerful, but they’re also slow and mentally taxing. Most of the time isn’t spent on the new code itself, but on reconstructing context:

Where does this function live?
What other files does it touch?
How do I know this change won’t break something downstream?

We wanted a tool that could reduce that cognitive overhead. Inspired by Arc’s link previews and modern AI copilots, we asked: what if GitHub reviews had inline AI explanations—just by selecting the code you care about?

What We Built

Oracle is a browser extension + backend that augments GitHub pull requests. With Oracle, you can:

Select any block of code in a PR.
Get an AI-generated summary of what it does, how it works, and why it matters.
Pull in repo-wide context (definitions, callers, related files) to ground the explanation.

Architecture:

Extension: Content script detects code selection in GitHub diffs and triggers a floating tooltip.
Backend: FastAPI service with two main endpoints:
- /ingest: loads the entire repo into memory, chunks it (functions/blocks), computes embeddings, and stores them in a vector DB.
- /select: takes the selected code, finds related chunks via semantic search, and asks the LLM for a concise explanation.
Storage: ChromaDB for vectors, lightweight caching, and OpenAI/Cerebras for summaries.

How We Built It

Repo ingestion
- Fetched repositories directly via the GitHub Trees + Raw API.
- Implemented naive chunking around functions, classes, and defs.
- Generated vector embeddings (text-embedding-3-small) and upserted into Chroma.
Selection to summary
- Extension packages the selection (file, sha, range, selected_text).
- Backend performs k-NN search over embeddings to find semantically related chunks.
- Prompt constructed with both the selection and nearest neighbors.
- LLM outputs structured bullets and a concise explanation.
Streaming UX
- Implemented StreamingResponse in FastAPI so summaries stream progressively.
- Tooltip updates in real time, creating an Arc-like feel.

What We Learned

Streaming is tricky — browsers buffer unless you use ReadableStream + TextDecoder carefully.
Vector embeddings matter — improving how we chunked files and generated embeddings had a direct impact on context quality. Better embeddings = higher precision in selecting relevant functions, tests, or callers.
Context-sensitive analysis — explanations became far more accurate once we included related code blocks via semantic search. Pure “selected text” summaries often hallucinated; context-aware prompts grounded the LLM in reality.
Developer experience counts — even small UI touches (tooltip delay, smooth streaming) make the tool feel like a natural part of GitHub reviews.

Challenges We Faced

GitHub App vs. simplicity: private repo auth was too complex for the MVP, so we stuck with public repos.
Large repos: had to filter by file type/size and truncate to keep embeddings tractable.
Prompt balance: too much context = token explosion, too little = shallow explanations.
Vector relevance: ensuring embeddings captured semantics (not just syntax) was non-trivial; we experimented with different models and chunk strategies.
Error handling: the tooltip needed to fail gracefully without breaking GitHub’s DOM.

Next Steps

Integrate Tree-sitter for smarter symbol parsing and chunk boundaries.
Reduce the latency of the ingest functionality (Ollama embedding is a bit slow)
Experiment with higher-quality embedding models and hybrid retrieval (vector + keyword).
Add impact analysis: highlight downstream callers, related tests, and potentially affected modules.
Support private repos through GitHub Apps.
Polish the UX: inline definition modals, reviewer notes, and richer side panels.

Takeaway

Oracle taught us that the key to useful AI code review isn’t just summarization—it’s context-sensitive analysis powered by embeddings. By improving the quality of our vector index and grounding the LLM in relevant repo context, explanations became more reliable, concise, and reviewer-friendly.