RepoSense

A minimal web app that lets you paste a GitHub repository URL, ingest the repo, and ask natural-language questions about the codebase using an AI agent.

Workshop demo — no auth, no database, in-memory processing.

What it does

1. Ingest: You submit a GitHub repo URL. The app fetches the file tree, then downloads prioritized files (README, package.json, src/, app/, config files), skips large/binary files, and keeps them in memory.
2. Ask: You type questions in plain English. The RepoSense agent answers using only the ingested files as context: it explains architecture, points to files, and says when something isn’t in the provided codebase.

How the agent works

• System prompt: The agent is instructed to act as “RepoSense,” a senior-engineer style explainer that answers strictly from the provided codebase context. It must not invent files or code that aren’t in the context.
• Context injection: All ingested file contents are concatenated and sent with each question (with file path headers). The LLM sees this as the only source of truth.
• No hallucination: If the answer isn’t in the context, the agent is prompted to say so clearly (e.g. “I don’t see authentication logic in the ingested files”).

So the “agent” is: system prompt + full repo snippet context + user question → single LLM call → answer.

How to run locally

1. Clone and install

   cd RepoSense
   npm install

2. Environment

   • If .env.local is missing, create it by copying .env.example:
     cp .env.example .env.local (Unix/macOS) or copy the file manually on Windows.
   • Set LYZR_API_KEY and LYZR_AGENT_ID (required for the Ask feature). Get these from Lyzr.
   • Optionally set GITHUB_TOKEN for higher GitHub API rate limits.
   • These variables are used on the server only (no NEXT_PUBLIC_ prefix); they are never exposed to the client.
   • Restart the dev server after creating or changing .env.local; Next.js only loads env vars at startup.
   • If you see "LYZR_API_KEY or LYZR_AGENT_ID is not set", ensure both are set in .env.local and restart npm run dev.

3. Run

   npm run dev

   Open http://localhost:3000.

4. Use

   • Paste a GitHub repo URL (e.g. https://github.com/vercel/next.js) and click Ingest Repository.
   • When ingestion finishes, type a question (e.g. “What does this project do?”, “Where is the main entry point?”) and click Ask.

Tech stack

• Frontend: Next.js (App Router), React, Tailwind CSS.
• Backend: Next.js API routes (/api/ingest, /api/ask).
• LLM: OpenAI API (model configurable via OPENAI_MODEL).
• Storage: In-memory only; one repo at a time.

API

• POST /api/ingest
  Body: { "repoUrl": "https://github.com/owner/repo" }
  Returns: { "ok": true, "repoName": "owner/repo", "fileCount": N } or { "error": "..." }.

• POST /api/ask
  Body: { "question": "Your question?" }
  Returns: { "answer": "..." } or { "error": "..." }.

Project structure

src/
  app/
    api/
      ingest/route.ts   # POST ingest: fetch repo, store in memory
      ask/route.ts     # POST ask: run agent with repo context
    layout.tsx
    page.tsx           # Single-page UI (ingest + chat)
    globals.css
  lib/
    store.ts           # In-memory repo state
    github.ts          # GitHub API: parse URL, fetch tree, fetch file contents
    agent.ts           # RepoSense agent: system prompt + context + OpenAI call

Non-goals (not built)

• Authentication, persistent storage, multi-repo support, vector DBs.