README.md

metadata

title: GitRead
emoji: 🔍
colorFrom: red
colorTo: red
sdk: docker
pinned: false

GitRead

Chat with any GitHub repository — instantly.

Paste a GitHub URL. Ask anything about the codebase. No docs. No setup. No confusion.

---

🧠 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), OpenAI or Anthropic — pasted in the app's Settings, not in .env

Installation

# 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 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 for more information.

---

Built with ❤️ by vidit1920

⭐ Star this repo if you found it useful!