cd ~/projects/reposense/backend python3 -m venv venv source venv/bin/activate pip install "mcp[cli]>=1.25 # pin below is more important, see note pip install httpx python-dotenv
PRD — RepoSense (working name): AI Codebase Intelligence Agent
Problem: Understanding an unfamiliar codebase (onboarding, OSS contribution, code review) requires manually digging through files, issues, and history. No single tool reasons across code + docs + issue history together with verified, cited answers.
Goal: An agent that takes a GitHub repo URL, ingests it, and answers questions about architecture, bugs, and history — grounded in actual retrieved source, not hallucinated, with measured accuracy.
Users: Developers onboarding to a new repo, OSS maintainers triaging issues, recruiters evaluating your project (be honest with yourself — this is also for them).
Core features (MVP → full):
- Ingest a public GitHub repo (code, README, issues) — MVP
- Answer questions with cited source (file/line or issue #) — MVP
- Multi-agent verification (fact-checker re-confirms claims against retrieval) — v2
- Tool-augmented actions: lint-check a suggested fix, run backtest-style code search — v2
- Eval harness reporting accuracy/recall on a fixed question set — v2, non-negotiable
Non-goals: private repos, write access to repos, multi-repo cross-referencing, fine-tuning.
Success metric: ≥80% correct/cited answers on a 15-20 question golden set you define, published in the README.
Plan (3 weeks, same cadence as before, HFT stripped out)
Week 1 — vertical slice
- Day 1-2: MCP server #1 — GitHub API wrapper (fetch files, issues, commits). Test with a raw MCP client call before touching the agent.
- Day 2-3: Single LangGraph node calling that MCP server, returning raw output. Prove tool-calling works.
- Day 4-5: Qdrant in Docker. Ingest 2-3 of your own repos (LOBE, Baskit — used as test data, not the project's identity) — code comments, README, docstrings. Embed with Gemini text-embedding-004. Manually sanity-check retrieval before wiring in.
- Day 6-7: Second MCP server — code/text search over the repo. Wire retrieval into the graph. End of week 1: single-agent RAG+tools pipeline giving real answers.
Week 2 — multi-agent + evals
- Day 8-9: Split into Researcher → Explainer → Fact-checker graph. Fact-checker re-queries the vector DB against the Explainer's claims and flags unsupported ones.
- Day 10-11: MCP server #3 — linter wrapper (ESLint/Ruff) so the agent can validate a suggested code fix, not just describe it.
- Day 12-13: Build the 15-20 question golden set, write a scoring script (LangSmith or your own), log accuracy/citation-correctness. This is the artifact that separates you from the pile.
- Day 14: Buffer.
Week 3 — ship
- Day 15-16: FastAPI backend, SSE streaming of the agent's reasoning trace (not just final answer).
- Day 17-18: Next.js frontend — repo URL input, live trace panel, cited final answer.
- Day 19: Docker Compose everything, deploy free (Render backend, Vercel frontend), test the cold public URL.
- Day 20-21: README with architecture diagram, eval results table, 60-sec demo GIF. Resume bullet leads with the eval number and MCP server count.
If week 2 slips, cut the linter MCP server before you cut evals — the eval harness is the actual differentiator, not tool count.
cd ~/RepoSense/backend source .venv/bin/activate uv run mcp dev server.py