# GitRead
### Chat with any GitHub repository โ instantly.
Paste a GitHub URL. Ask anything about the codebase.
No docs. No setup. No confusion.
[](https://python.org)
[](https://fastapi.tiangolo.com)
[](https://langchain-ai.github.io/langgraph)
[](LICENSE)
[](https://github.com/vidit1920/GitRead/stargazers)
---
## ๐ง What is GitRead?
**GitRead** is an AI-powered developer tool that lets you have a natural language conversation with any GitHub repository.
Instead of spending hours reading source code, digging through READMEs, or guessing how things connect โ just paste a GitHub URL and ask. GitRead clones the repo, indexes it using local vector embeddings, and lets you chat with the entire codebase in plain English.
---
## โจ Features
| Feature | Description |
|---|---|
| ๐ **Any GitHub URL** | Works with any public repository |
| โก **Instant Analysis** | Clones, indexes and understands code in seconds |
| ๐ง **AI Chat** | Ask anything โ architecture, bugs, how to run, dependencies |
| ๐บ **Code Map** | Understand how files and modules connect |
| ๐ **Bug Finder** | Spot issues without reading every line |
| ๐ฆ **Zero Docs Needed** | GitRead reads the code so you don't have to |
| ๐ **Bring Your Own Key** | Use your own Gemini, OpenAI or Claude API key |
| ๐ **Local Embeddings** | SFR-Embedding-Code-400M runs on the server via ONNX Runtime (no torch needed) |
---
## ๐ Tech Stack
```
Frontend โ HTML ยท CSS ยท Vanilla JavaScript
Backend โ Python ยท FastAPI ยท Uvicorn
AI / LLM โ Gemini / OpenAI / Claude (your key) ยท LangGraph
Vector Search โ ChromaDB ยท Local Embeddings
Architecture โ Agentic RAG Pipeline
```
---
## ๐ Getting Started
### Prerequisites
- Python 3.10+
- Git
- An API key from Google Gemini ([free](https://aistudio.google.com/app/apikey)), OpenAI or Anthropic โ pasted in the app's Settings, not in `.env`
### Installation
```bash
# 1. Clone the repository
git clone https://github.com/vidit1920/GitRead.git
cd GitRead
# 2. Create and activate virtual environment
python -m venv venv
# Windows
venv\Scripts\activate
# Mac / Linux
source venv/bin/activate
# 3. Install dependencies (for a GPU, replace onnxruntime with onnxruntime-gpu)
pip install -r requirements.txt
# 4. (Optional) environment variables
cp .env.example .env
# 5. Start the app (serves the frontend too)
uvicorn back_end.main:app --host 127.0.0.1 --port 8000
# 6. Open http://127.0.0.1:8000 and add your API key via the key icon
```
---
## ๐ฌ Example Questions
Once you paste a GitHub URL and hit **Analyse**, you can ask:
```
"How do I run this project locally?"
"Explain the overall architecture"
"What are all the dependencies and what do they do?"
"Where is the main entry point?"
"Find any potential bugs or issues"
"Generate a code map of this repo"
"What does the authentication flow look like?"
```
---
## ๐ Project Structure
```
GitRead/
โโโ back_end/
โ โโโ agent/
โ โ โโโ graph.py # LangGraph agent definition
โ โ โโโ tools.py # Agent tools
โ โโโ core/
โ โ โโโ downloader.py # GitHub repo cloner
โ โ โโโ embeddings.py # Vector embedding pipeline
โ โ โโโ loader.py # File loader
โ โ โโโ splitter.py # Code chunker
โ โโโ config.py # App + security configuration
โ โโโ llm.py # Bring-your-own-key provider factory
โ โโโ security.py # Rate limiting + security headers
โ โโโ sessions.py # Per-visitor isolated sessions
โ โโโ main.py # FastAPI entry point
โโโ front_end/
โ โโโ index.html # Main UI
โ โโโ style.css # Styles
โ โโโ app.js # Frontend logic
โ โโโ bg.js # Background animation
โโโ requirements.txt
โโโ README.md
```
---
## โ๏ธ Environment Variables
Users bring their own LLM key, so **no secret is required** to run GitRead.
All settings are optional โ see [`.env.example`](.env.example) for the full list:
| Variable | Default | Purpose |
|---|---|---|
| `ALLOW_SERVER_KEY_FALLBACK` | `false` | If `true`, visitors without a key use `GOOGLE_API_KEY` (your quota!) |
| `GOOGLE_API_KEY` | โ | Only used with the fallback above. Set it as a **Secret** on Hugging Face |
| `ALLOWED_ORIGINS` | empty | Extra origins allowed to call the API cross-origin |
| `MAX_LOADED_REPOS` | `20` | Repos held in memory at once (idle ones are evicted first) |
| `RATE_LIMIT_CHAT_PER_MIN` | `12` | Chat requests per session per minute |
| `EMBEDDING_TIME_BUDGET_SECONDS` | `600` | If embedding a repo would take longer than this on the current hardware, fall back to keyword + file search |
| `MAX_CHUNKS_TO_EMBED` | `4000` | Hard cap on chunks to embed |
| `EMBEDDING_DEVICE` | `auto` | `auto` (CUDA when `onnxruntime-gpu` is installed) or `cpu` |
> **Speed:** the 400M embedding model is heavy for a CPU. On a free 2-vCPU Space expect roughly
> 1โ3 chunks per minute, so only small repos get semantic search within the default 10-minute budget;
> larger ones automatically use keyword (BM25) + exact/file search. A GPU or larger CPU Space removes the limit.
> The embedding model `Salesforce/SFR-Embedding-Code-400M_R` is licensed **CC-BY-NC-4.0** (non-commercial use only).
---
## ๐ค Contributing
Contributions are welcome! Feel free to open an issue or submit a pull request.
1. Fork the repo
2. Create your branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
---
## ๐ License
Distributed under the MIT License. See [`LICENSE`](LICENSE) for more information.
---
Built with โค๏ธ by [vidit1920](https://github.com/vidit1920)
โญ Star this repo if you found it useful!