Codebase Compass

A local-first AI assistant that lets you ask questions about any GitHub repository using Ollama, ChromaDB, Streamlit, and RAG.

Local-first | No paid APIs | Python 3.10+

Demo

Screenshot placeholder:

Features

• Paste a public GitHub repo URL
• Clone repo locally
• Filter useful code/docs files
• Chunk files with line numbers
• Create local embeddings with Ollama
• Store vectors in ChromaDB
• Ask questions about the repo
• Display source files and line ranges
• Runs locally with no paid APIs

Architecture

flowchart TD
    User[User] --> UI[Streamlit UI]
    UI --> Loader[Repo Loader]
    Loader --> Filter[File Filter]
    Filter --> Chunker[Chunker]
    Chunker --> Chroma[ChromaDB]

    User --> UI
    UI --> Retriever[Retriever]
    Retriever --> Chroma
    Retriever --> Ollama[Ollama]
    Ollama --> Answer[Answer with Sources]
    Answer --> UI

Loading

Tech Stack

• Python
• Streamlit
• Ollama
• ChromaDB
• GitPython

Prerequisites

• Python 3.10+
• Git
• Ollama

Install Ollama from https://ollama.com and make sure it is running locally.

Setup: macOS/Linux

git clone https://github.com/YOUR_USERNAME/codebase-compass.git
cd codebase-compass
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
ollama pull llama3.2:3b
ollama pull nomic-embed-text
./run_ui.sh

Setup: Windows PowerShell

git clone https://github.com/YOUR_USERNAME/codebase-compass.git
cd codebase-compass
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
ollama pull llama3.2:3b
ollama pull nomic-embed-text
.\run_ui.ps1

Configuration

Defaults work for a local Ollama install. To customize models or the Ollama URL, copy .env.example to .env or export the variables in your shell before running the app.

export OLLAMA_URL=http://localhost:11434
export CHAT_MODEL=llama3.2:3b
export EMBED_MODEL=nomic-embed-text

Usage

1. Paste a public GitHub repository URL.
2. Click Index Repository.
3. Ask questions about the indexed repository.

Example questions:

• What does this project do?
• How do I run this project locally?
• Explain the folder structure.
• Where are tests located?
• What are the main dependencies?

Limitations

• Public repos only for MVP
• Large repos may take time to index
• Generated/minified files are skipped
• Answers depend on retrieved context

Roadmap

• MCP tools for repo inspection
• GitHub API integration
• Private repo support
• Hybrid keyword + vector search
• Docker support
• Better code-aware chunking
• Branch selector

Security and Privacy

• Repositories are cloned locally into data/repos/
• Embeddings are generated locally through Ollama
• Vectors are stored locally in data/chroma/
• No paid cloud LLM API is used

Do not commit cloned repositories, vector databases, secrets, or .env files.

License

MIT License. See LICENSE.