CodeGent — Agentic Codebase Q&A System

CodeGent is an intelligent AI-powered system designed to help developers explore, understand, and query large GitHub repositories using natural language. It leverages a multi-agent architecture (LangGraph), semantic search (ChromaDB), and advanced code parsing to provide grounded answers with precise source code references.

Features

• Intelligent Parsing: Uses AST-based parsing to chunk Python code by logical definitions (classes/functions), ensuring context is never split mid-block.
• Multi-Agent Reasoning: Employs a Planner Agent to strategize retrieval and an Executor Agent to interact with tools.
• Semantic Search: Powered by ChromaDB and high-quality local embeddings (bge-small-en-v1.5).
• Interactive Web UI: Modern Next.js interface with real-time streaming and agent reasoning visibility.
• Grounded Answers: Every response includes file paths and line ranges to the relevant code.
• Local or Cloud LLMs: Seamlessly switch between local Ollama models or cloud providers like Google Gemini and Groq.

---

Screenshots

Dashboard & Repository Explorer

Efficient Indexing

Agent Reasoning & Thought Process

Grounded Answers with References

---

Setup & Installation

Prerequisites

• Docker & Docker Compose (Recommended)
• Ollama (Optional, for local LLM support)

1. Clone the project

git clone https://github.com/nafeu-khan/codegent.git
cd codegent

2. Configure Environment

Create a .env file in the backend/ directory (you can copy .env.example):

cp backend/.env.example backend/.env

set provider of llm. Fill in your API keys if using cloud providers:

• GOOGLE_API_KEY: For Gemini
• GROQ_API_KEY: For Groq
• OPENROUTER_API_KEY: For OpenRouter

3. Start with Docker Compose

docker compose -f docker-compose.dev.yml up --build

This will start:

• Frontend: http://localhost:3000
• Backend: http://localhost:8000
• Ollama: http://localhost:11437

4. API Documentation

Once the backend is running, you can access the interactive API documentation at:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

---

Usage

1. Index a Repository: On the dashboard, enter a GitHub URL (e.g., pallets/flask) and click Index.
2. Wait for Processing: The system will clone, parse, and embed the repository.
3. Chat & Query: Select the indexed repository and ask questions like:
   • "How does the routing system work in this project?"
   • "Explain the authentication flow."
   • "Where is the main entry point defined?"
4. Explore Reasoning: Click on the "Thinking" steps to see how the agent planned its search and which tools it used.

---

Architecture

• Backend: FastAPI (Python 3.11)
• Frontend: Next.js 15+ (TailwindCSS, Lucide)
• Agent Framework: LangGraph
• Vector Database: ChromaDB
• Embeddings: BAAI/bge-small-en-v1.5 (via Sentence-Transformers)
• Parsing: Python AST (Abstract Syntax Trees)

---

Chosen Repository for Testing

pallets/flask was chosen due to its architectural richness and clear modular structure, making it ideal for testing semantic retrieval and complex reasoning.

---

Rules & Integrity

• AI Tool Use: Use the assistance of Antigravity for code generation, debugging, and UI design.
• Citations: AST parsing logic and LangGraph state management patterns were adapted from official documentation and community best practices.

---