◎OmniRepo
A full-stack AI concierge for unfamiliar codebases: paste a GitHub repo and chat with an agent that reads the real code, streams its reasoning live, and cites every claim with a clickable file:line.
Timeline
2026
Team
Solo build
Role
Design & Full-Stack Engineering
Skills
AI Agents, Full-Stack, TypeScript
Built with
LONG STORY SHORT
I built an AI concierge that reads a codebase live and backs every claim with a clickable file:line.
Onboarding to a repository you've never seen is slow: you grep blindly, chase imports, and guess where things live. OmniRepo turns that into a conversation. You paste a GitHub URL, the server shallow-clones the repo, and an agent explores the actual checkout — no pre-indexing, no embeddings, no vector database. Because it reads the real code every time, its answers are grounded in what's actually there, and every file it references opens a syntax-highlighted viewer scrolled to the exact line.
How it works
Creating a session validates the URL against a strict github.com/{owner}/{repo} regex and kicks off a depth-1 git clone (passed to execFile verbatim, never shell-interpolated). The moment the clone lands, the server computes a briefing — a language breakdown, a detected stack, a clickable file tree, and starter questions tailored to what it found. A "how are the tests organized?" prompt only appears if it actually detects a test setup.
From there the client connects over a WebSocket (REST and WS share one port) and asks a question at a chosen effort level. Turns on hard questions can run for minutes, so the whole experience is built around live streaming: you watch the agent think, call tools, and write its answer in real time, with the running token cost shown in the header.
The request lifecycle
Every question follows the same path — validate and clone the repo, compute a briefing, then run a single streamed agentic turn whose every event (thinking, tool calls, answer) lands in the browser live.
- 1
Paste a repo
validated GitHub URL
- 2
Shallow clone
depth-1, per session
- 3
Briefing
stack · tree · prompts
- 4
Connect & ask
over one WebSocket
- 5
Agentic loop
think · tools · repeat
- 6
Stream & cite
live, to file:line
Architecture
Three tiers, one deployable. The API and the built frontend ship as a single container, so there's one thing to run. The browser talks to an Express + ws server that owns the agentic loop and a per-session git workspace; the server, in turn, streams to Anthropic's Messages API and executes the model's tool calls against the cloned repo — every event flowing back to the browser over a single WebSocket.
Client
React UI
- Vite
- Hand-built chat & file viewer
- WebSocket stream
Server
Express + ws
- Agentic tool loop
- Sandboxed git workspace
- Path-safety guards
Model
Anthropic
- Claude, agentic tool use
- Adaptive thinking
- Prompt caching
Under the hood
The agentic loop calls Claude's streaming Messages API in a bounded for loop (max 30 iterations): the model thinks, emits tool_use blocks, the server runs those tools against the sandboxed repo and feeds the results back in one message, and repeats until there's a final answer. It leans on the patterns a real deployment needs — adaptive summarized thinking, per-message effort control, prompt caching against a byte-stable system prompt, and clean handling of refusals and model fallback.
The sandboxed tools
The model gets four read-only tools, each scoped strictly to the cloned repo with sane caps. The security-critical piece is path safety: every path a tool touches is resolved against the repo root and rejected if it escapes, then realpath'd and re-checked so a symlink inside the repo can't point outside it. Directory walks never follow symlinks.
file_tree
An indented map of the whole repo.
skips .git / node_modules · ~400-entry cap · never follows symlinks
list_directory
One directory's entries with type + size.
non-recursive
read_file
File contents with line numbers.
400 lines / 100KB per call · refuses >10MB & binaries · windowed reads
search
Regex across the repo's text files.
skips binaries / huge files · 50-match cap · optional path prefix
Verifiable by construction
Answers cite path/to/file.ts:42. Clicking a citation fetches the file through that same path-safety guard and opens a slide-in viewer with the cited line highlighted — so a reader can verify the agent's claims rather than take them on trust. Because the agent reads the real checkout on every turn, those citations always point at code that's actually there.
Why I built it this way
- Read the code live, don't index it. No embeddings or vector store — the agent explores the real checkout, so answers stay grounded and citations are exact.
- Streaming-first, not request/response. A typed WebSocket event stream makes minutes-long turns feel alive instead of hanging on a spinner.
- Security at the tool boundary. Path-traversal and symlink-escape guards keep an autonomous model contained to one repo's sandbox.
- Type-safe across the wire. A single shared package defines every REST + WS message, so the client and server can't drift.
- Production-shaped AI usage. Prompt caching, effort control, refusal/fallback handling, and live per-turn cost accounting.
- Demoable for free. A
$0mock mode runs the whole pipeline — clone, real tools, live streaming — against a canned response, so it works end to end with no API key and no spend.
NEXT UP …