CodeLens 🔍

AI-powered code intelligence agent — ask questions about any codebase in plain English. Built with LangGraph, ChromaDB, and Groq's ultra-fast LLM inference.

---

What it does

Point CodeLens at any codebase and ask:

• "How is authentication handled?"
• "Where is the database connection initialised?"
• "Find all usages of the process_payment function"
• "What does the UserService class do?"

CodeLens indexes your code into a vector database, then uses a LangGraph agent with 8 specialised tools to answer questions with source-backed evidence.

---

Features

• Semantic search — ChromaDB + HuggingFace embeddings find conceptually relevant code
• Exact search — grep-backed string/regex search for identifiers and imports
• File operations — read, write, outline, directory tree
• Three interfaces — CLI, interactive chat agent, REST API
• Multi-language — Python, JavaScript, TypeScript, HTML, CSS, Markdown, JSON, YAML
• Fast inference — Groq serving Llama 3.3 70B at ~300 tokens/second

---

Quick Start

# 1. Clone and install
git clone https://github.com/lohith-1204/CodeLens.git
cd CodeLens
bash install.sh

# 2. Add your Groq API key to .env
# Get a free key at https://console.groq.com
echo "GROQ_API_KEY=your_key_here" >> .env

# 3. Index your codebase
python3 cli.py init --path /path/to/your/project

# 4. Ask a question
python3 cli.py ask "How does authentication work?"

# 5. Start interactive chat
python3 cli.py chat

---

CLI Commands

Command	Description	Example
python3 cli.py init	Index a codebase into the vector DB	python3 cli.py init --path ./my-app
python3 cli.py ask	Semantic question about the codebase	python3 cli.py ask "How is routing handled?"
python3 cli.py search	Exact string/regex search	python3 cli.py search "def authenticate"
python3 cli.py tree	Directory structure	python3 cli.py tree --max-depth 3
python3 cli.py outline	Classes/functions in a file	python3 cli.py outline ./src/main.py
python3 cli.py review	File preview + outline	python3 cli.py review ./src/app.py
python3 cli.py chat	Interactive AI agent session	python3 cli.py chat
python3 cli.py info	Configuration + status	python3 cli.py info

---

Agent Tools

The LangGraph agent has 8 tools it can call autonomously:

Tool	When the agent uses it
get_directory_tree	First step — understand project layout
codebase_search	Conceptual questions about how things work
grep_search	Finding specific strings, function names, imports
get_file_outline	Quick scan of a file's classes and functions
read_file	Full file content
write_file	Applying code edits
list_files	Directory listing
run_terminal_command	Running tests, linters, build commands

The agent follows a structured strategy: Explore → Search → Understand → Plan → Execute.

---

REST API

Start the server:

uvicorn api:app --port 8000 --reload

Method	Endpoint	Description
GET	/health	DB status + API key check
POST	/api/ask	Semantic search
POST	/api/search	Grep search
POST	/api/tree	Directory tree
POST	/api/outline	File outline
POST	/api/read	Read file
POST	/api/init	Index a repo (background task)
POST	/api/upload	Upload a zip and index it
GET	/docs	Swagger UI

Example:

curl -X POST http://localhost:8000/api/ask \
  -H "Content-Type: application/json" \
  -d '{"query": "How is the database initialised?"}'

---

Project Structure

CodeLens/
├── config.py          # All paths, model names, settings
├── agent.py           # LangGraph agent (conversational)
├── cli.py             # Click CLI interface
├── api.py             # FastAPI REST service
├── tools.py           # 8 agent tools (search, read, write, etc.)
├── create_db.py       # Codebase indexer (ChromaDB builder)
├── test.py            # pytest smoke tests
├── setup.py           # Package setup
├── install.sh         # One-command setup script
├── requirements.txt   # Pinned dependencies
├── .env.example       # Environment variable template
└── .gitignore

---

Configuration

All settings in config.py, overridable via environment variables:

Variable	Default	Description
GROQ_API_KEY	—	Required. Get free at console.groq.com
CODELENS_REPO_PATH	.	Default path to index
CODELENS_DB_PATH	./chroma_db	ChromaDB storage location
CODELENS_ALLOWED_ORIGINS	localhost:3000,8000	CORS origins for API

---

Running Tests

pip3 install pytest
pytest test.py -v

All 9 tests should pass. ✅

---

Built with ❤️ by Lohith