Video Demo
Gallery
RepoScribe interface gallery
From Clerk sign-in and live ingestion to the agent's tool-use trace, grounded answers, and clickable code citations.
01 / 09
Initial loading screen
Project Overview
RepoScribe is a “chat with your codebase” application. Instead of answering from generic training knowledge like a normal chatbot, it answers from one specific repository's actual code — and it proves every claim by citing the exact files and line ranges it used. Paste a public GitHub URL, watch it ingest and index the codebase, then start asking questions.
The buzzword is “Agentic RAG,” and both halves are load-bearing. RAG means that before the LLM answers, the app retrieves relevant code chunks by meaning and grounds the answer in them. Agentic means it doesn't run one fixed “search → answer” step: a router classifies intent, a sufficiency check decides whether retrieval was actually enough, and the agent can self-correct by reading a whole file or searching the web before it answers — picking from seven tools dynamically.
Unlike a single-service demo, RepoScribe is a genuine multi-service system: a decoupled frontend and backend, an asynchronous ingestion worker, a vector database, an object queue, a sandboxed code executor, and pluggable AI providers — each independently deployable. It was built solo as a deep-dive to learn how to architect, secure, and scale a real multi-service AI application, not just call an LLM.
System Architecture
Two fully-decoupled projects — a Next.js client on Vercel and a Node/Express server on a Google Cloud VM — talk only over REST and SSE. The server fronts an asynchronous ingestion worker, a Docker sandbox, and a job queue, while embeddings, vectors, LLMs, and auth are pluggable managed services.
Frontend
- Next.js
- React
- TypeScript
- Tailwind CSS
- Clerk
- SSE client
Backend
- Node.js
- Express
- LangChain / LangGraph
- BullMQ
- Docker sandbox
- 129 tests
AI & Data
- Qdrant
- Hugging Face
- OpenRouter
- Redis
How Retrieval Works: The Agentic RAG Loop
This is the heart of RepoScribe. A plain RAG app does retrieve → answer and stops. RepoScribe instead runs a LangGraph loop: a router classifies the question, a sufficiency check asks whether the retrieved context is genuinely enough, and if it isn't, the agent self-corrects with another tool and re-checks — only answering once it can back the claim with real code.
The loop back from a tool to the sufficiency check is what makes it agentic — the agent decides how much work a question needs, rather than following one hard-coded path.
The Agent's Tool Belt
The router picks dynamically from seven strictly-typed tools — each with a Zod schema — spanning five capabilities. It chooses which tool to use for a given question instead of always doing the same thing.
Semantic Search
Retrieves the most relevant code chunks by meaning, not keywords — asking "how does it limit concurrency?" finds activeCount < concurrency even though the code never says "limit".
Read File
When retrieved snippets aren't enough, the agent pulls a whole file into context to self-correct before it commits to an answer.
Sandboxed Code Execution
Runs untrusted repository code to verify behaviour — but only ever inside a hardened Docker sandbox that never touches the host.
GitHub Actions
Reaches back to the live repository for structure, metadata, and files beyond what was indexed at ingestion time.
Web Search
Steps outside the repo for library documentation or general knowledge when the answer isn't in the codebase at all.
Ingestion Pipeline
Ingestion never blocks the API. Pasting a URL enqueues a job on BullMQ; a separate worker clones the repo, splits it into code-aware chunks, embeds them with Hugging Face, and stores the vectors in Qdrant — streaming progress back to the UI the whole time.
The worker is a separate process — without it, jobs simply queue up and wait, which keeps the API fast and the heavy lifting off the request path.
Live Trace & Clickable Citations
A single question opens an SSE stream. As the agent retrieves, checks sufficiency, and calls tools, each step is emitted as a trace event and rendered live — then the answer tokens stream in, every claim tagged with a citation you can click to open the exact file and highlighted lines.
Every answer ships with clickable code citations like path/to/file.ts:10-30 — retrieval you can verify, not just trust.
Engineering Principles
The non-negotiables that shaped the build — the same rules that keep a multi-service AI app safe, responsive, and testable.
Async by default
Ingestion always goes through the BullMQ queue — the API never clones or embeds inline, so it stays responsive.
Strictly-typed tools
Every agent tool has a Zod schema and retrieval is validated, so the model can't call a tool with a malformed payload.
Safety is non-negotiable
Untrusted code only ever runs inside the hardened sandbox — code execution is a capability, never a liability.
Decoupled services
Client and server talk only over REST + SSE with no shared code, so each is independently deployable.
Fail loudly
Backend errors — bad URL, private or oversized repo, LLM timeout — surface directly in the UI instead of hanging.
Network-free tests
Everything is mocked, so the 129-test suite is deterministic and runs in CI without touching a single live service.
Key Features
Challenges & Solutions
Challenge: Answering from a repo's real code, not the model's memory
Solution: Before the LLM answers, the app embeds the codebase with Hugging Face, stores the vectors in Qdrant, and retrieves the most relevant chunks by meaning. Every answer is grounded in those chunks and proves it with file-and-line citations.
Challenge: Knowing when retrieval isn't actually enough
Solution: A LangGraph sufficiency-check node decides whether the retrieved context can really answer the question. If it can't, the agent self-corrects — reading a whole file, running code, or searching the web — and loops back to re-check before answering.
Challenge: Running untrusted repository code without risk
Solution: Code execution is a genuine agent tool, but it is confined to a hardened Docker sandbox. The agent can run code to verify behaviour while the host stays completely isolated from anything the repo contains.
Challenge: Not blocking the API on slow ingestion
Solution: Cloning and embedding always run asynchronously through a BullMQ queue and a separate worker process. The API returns immediately and streams live indexing progress to the UI over SSE.
Challenge: Proving it's an agent, not a wrapped prompt
Solution: Every routing decision and tool call emits an SSE event that renders live in the UI as a tool-use trace, alongside citations you can click to jump straight to the cited file and highlighted lines.
Challenge: Shipping a multi-service system across hosts
Solution: A fully decoupled client and server communicate only over REST + SSE, deployed across Vercel and a Google Cloud VM, with AI providers kept pluggable behind a single OpenRouter gateway.
Project Stats
Technologies Used
Architecture Highlights
License
Released under the MIT License — a portfolio project demonstrating agentic RAG, tool orchestration, streaming, safe code execution, and multi-service deployment. Free to study, fork, and build on.