CodeSage was born from a simple philosophy: True intelligence should live where your code lives—on your metal.
It is a local-first, semantic search engine and AI assistant that runs entirely on your machine. By combining LangChain’s orchestration with the power of Ollama, CodeSage turns your codebase into an interactive knowledge base without a single byte leaving your computer.
The Philosophy: Your Code, Your Sage
Most "AI coding tools" treat your project as a generic string of text. They predict the next token based on the average of the internet's code. CodeSage takes a different approach. It respects the specific "culture" of your repository.
When you ask, "How do we handle error logging?", a generic model might give you a standard Python logging tutorial. CodeSage, however, looks at your existing implementation—your custom wrappers, your specific error classes—and acts as a sage that knows the history of your project. It doesn't just generate code; it recalls your team's best practices.
Under the Hood: A Technical Deep Dive
CodeSage is built on a precise RAG (Retrieval-Augmented Generation) pipeline designed for local performance.
1. Semantic Indexing
Instead of simple regex matching, CodeSage parses your Python code into an Abstract Syntax Tree (AST). It understands functions, classes, and methods as distinct logical units. It then uses mxbai-embed-large, an open-source embedding model, to convert these units into high-dimensional vectors. These vectors capture the intent of the code, not just the keywords.
2. Fast Vector Storage
These embeddings are stored locally in ChromaDB. This allows for lightning-fast retrieval. When you index your project, we only re-process files that have changed, keeping the loop tight and efficient.
3. The "Suggester" Engine
When you run a query like codesage suggest "database connection logic", the engine performs a cosine similarity search in the vector space. But it goes a step further. It passes the retrieved context to qwen2.5-coder, a powerful 7B parameter local LLM.
The application uses a custom logic that doesn't just dump code at you—it explains why this piece of code matches your query. It synthesizes the retrieved context to provide an answer that is both accurate and educational.
Why Local Matters
Building offline-first isn't just a privacy feature; it's a performance feature.
- Zero Latency: No network round-trips.
- Privacy First: Your IP never leaves your machine.
- Flow State: Works perfectly on an airplane or in a cabin without WiFi.
CodeSage represents a future where AI tools are modular, private, and highly specialized agents that sit alongside us, not above us. It is a return to the Unix philosophy: do one thing well, and own your tools.
Try It Out
CodeSage is open source and ready for you to try. Check it out on GitHub: https://github.com/keshavashiya/codesage
# Install from PyPI
pip install pycodesage
# Initialize in your project
codesage init
# Index your codebase
codesage index
# Start asking questions
codesage suggest "how do we authenticate users?"
Top comments (0)