Spaces:

toasted1920
/

GitRead

Sleeping

App Files Files Community

GitRead / README.md

toasted1920

Claude Opus 5.5

Add bring-your-own-key LLMs, ONNX code embeddings and security hardening

5e9ddc1 5 days ago

preview code

Raw History Blame Contribute Delete

6.93 kB

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

<div align="center">

<br />

<img src="https://img.shields.io/badge/GitRead-FF6A00?style=for-the-badge&logoColor=white" alt="GitRead" height="40"/>

<br /><br />

# GitRead

### Chat with any GitHub repository — instantly.

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

<br />

[![Python](https://img.shields.io/badge/Python-3.10+-3776AB?style=flat-square&logo=python&logoColor=white)](https://python.org)
[![FastAPI](https://img.shields.io/badge/FastAPI-009688?style=flat-square&logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com)
[![LangGraph](https://img.shields.io/badge/LangGraph-FF6A00?style=flat-square&logoColor=white)](https://langchain-ai.github.io/langgraph)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)](LICENSE)
[![Stars](https://img.shields.io/github/stars/vidit1920/GitRead?style=flat-square&color=orange)](https://github.com/vidit1920/GitRead/stargazers)

<br />

![GitRead Preview](https://raw.githubusercontent.com/vidit1920/GitRead/main/preview.png)

</div>

---

## 🧠 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.
---
<div align="center">
Built with ❤️ by [vidit1920](https://github.com/vidit1920)
⭐ Star this repo if you found it useful!
</div>

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


	<div align="center">

	<br />

	<img src="https://img.shields.io/badge/GitRead-FF6A00?style=for-the-badge&logoColor=white" alt="GitRead" height="40"/>

	<br /><br />

	# GitRead

	### Chat with any GitHub repository — instantly.

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

	<br />

	[![Python](https://img.shields.io/badge/Python-3.10+-3776AB?style=flat-square&logo=python&logoColor=white)](https://python.org)
	[![FastAPI](https://img.shields.io/badge/FastAPI-009688?style=flat-square&logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com)
	[![LangGraph](https://img.shields.io/badge/LangGraph-FF6A00?style=flat-square&logoColor=white)](https://langchain-ai.github.io/langgraph)
	[![License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)](LICENSE)
	[![Stars](https://img.shields.io/github/stars/vidit1920/GitRead?style=flat-square&color=orange)](https://github.com/vidit1920/GitRead/stargazers)

	<br />

	![GitRead Preview](https://raw.githubusercontent.com/vidit1920/GitRead/main/preview.png)

	</div>

	---

	## 🧠 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.

	---

	<div align="center">

	Built with ❤️ by [vidit1920](https://github.com/vidit1920)

	⭐ Star this repo if you found it useful!

	</div>