CodeSage is a local-first code intelligence CLI. You index your codebase once, and then you can search it using natural language. No cloud. No API keys. Everything runs on your machine.
<pre><code class="language-bash">codesage init
codesage index
codesage chat 
</code></pre>
But semantic search is just the beginning.
<hr>
<h2>The Three Pillars of Code Understanding</h2>
Most code search tools do one thing: match text. CodeSage takes a fundamentally different approach by combining three complementary techniques:
<h3>1. Vector Search: Find Code by Meaning</h3>
“Authentication middleware” and “JWT token validator” mean similar things, even though they share no words. Vector embeddings capture this semantic relationship, letting you find code by what it does, not just what it’s called.
<h3>2. Graph Traversal: Understand Relationships</h3>
Code doesn’t exist in isolation. Functions call other functions. Classes inherit from base classes. Modules import dependencies. CodeSage builds a knowledge graph of these relationships using KuzuDB, so you can ask questions like:
<ul>
<li>“What functions call this method?”</li>
<li>“What would break if I changed this class?”</li>
<li>“How does data flow from the API endpoint to the database?”</li>
</ul>
<h3>3. Developer Memory: Learn Your Patterns</h3>
Here’s where it gets interesting. CodeSage doesn’t just index what your code does—it learns how you write it.
It tracks your naming conventions, your preferred patterns, your common approaches to recurring problems. This memory persists globally across all your projects, so insights from one codebase help with others.
The result? Suggestions that feel idiomatic to your style, not generic best practices from Stack Overflow.
<hr>
<h2>Interactive Chat with Specialized Modes</h2>
Not all work is the same, and neither is how you interact with your code.
CodeSage offers three chat modes, each optimized for a different workflow:
<ul>
<li>Brainstorm — Exploring ideas, asking open-ended questions</li>
<li>Implement — Focused task execution, generating code and plans</li>
<li>Review — Code review, security analysis, quality checks</li>
</ul>
Switch anytime with <code>/mode implement</code> or let CodeSage detect your intent from context.
The chat commands go deep:
<pre><code>/search &lt;query&gt; Semantic code search
/deep &lt;query&gt; Multi-agent analysis (runs parallel search strategies)
/plan &lt;task&gt; Implementation plan using your existing patterns
/review [file] Code review with security awareness
/impact &lt;element&gt; Blast radius analysis—what breaks if this changes?
/similar &lt;code&gt; Find similar patterns across your codebase
/patterns Show what CodeSage has learned about your style
</code></pre>
<hr>
<h2>Smart Query Expansion</h2>
Intent Detection: It understands if you’re explaining, debugging, implementing, or reviewing—and adjusts its response accordingly.
Synonym Expansion: Search for “auth” and it automatically includes authentication, authorization, JWT, OAuth, and related terms.
Context Memory: It remembers what you discussed earlier in the session. “What about the other handler?” just works.
<hr>
<h2>Works with Your AI IDE</h2>
CodeSage isn’t just a standalone tool. It integrates with Claude Desktop, Cursor, and Windsurf via the Model Context Protocol (MCP).
To start the MCP server manually:
<pre><code class="language-bash">codesage mcp serve --global
</code></pre>
Or add this to your MCP client configuration:
<pre><code class="language-json">{
 &quot;mcpServers&quot;: {
 &quot;codesage&quot;: {
 &quot;command&quot;: &quot;codesage&quot;,
 &quot;args&quot;: [&quot;mcp&quot;, &quot;serve&quot;, &quot;--global&quot;]
 }
 }
}
</code></pre>
Now your AI assistant has access to intelligent code search across all your indexed projects:
<ul>
<li><code>search_code</code> — Semantic search with graph context</li>
<li><code>get_file_context</code> — File content with its dependencies and relationships</li>
<li><code>get_task_context</code> — Implementation guidance grounded in your patterns</li>
<li><code>review_code</code> — Code review using learned conventions</li>
<li><code>analyze_security</code> — Security scan with project-specific context</li>
</ul>
Your AI assistant stops giving generic answers and starts giving grounded answers based on your actual codebase.
<hr>
<h2>The Technical Stack</h2>
Everything runs locally. No exceptions.
<ul>
<li>Ollama handles embeddings and LLM responses</li>
<li>LanceDB provides vector storage with fast similarity search</li>
<li>KuzuDB powers the code relationship graph</li>
<li>SQLite stores metadata and developer memory</li>
</ul>
You need Ollama running with a few models:
<pre><code class="language-bash">ollama pull qwen2.5-coder:7b
ollama pull mxbai-embed-large
ollama serve
</code></pre>
That’s it. No cloud accounts, no API keys, no data leaving your machine.
<hr>
<h2>Getting Started</h2>
Installation takes one command:
<pre><code class="language-bash">pipx install pycodesage
</code></pre>
Then index your first project:
<pre><code class="language-bash">cd your-project
codesage init
codesage index
</code></pre>
Start searching:
<pre><code class="language-bash">codesage chat
</code></pre>
<h3>Language Support</h3>
Python works out of the box. For JavaScript, TypeScript, Go, and Rust:
<pre><code class="language-bash">pipx inject pycodesage &quot;pycodesage[multi-language]&quot;
</code></pre>
<hr>
<h2>What’s Next</h2>
We’re actively developing:
<ul>
<li>More language parsers — expanding beyond the current set</li>
<li>Cross-project learning — enhanced pattern sharing between codebases</li>
<li>Documentation generation — auto-generate docs that match your style</li>
</ul>
<hr>
<h2>Try It</h2>
<pre><code class="language-bash">pipx install pycodesage
</code></pre>
GitHub: <a href="https://github.com/keshavashiya/codesage" target="_blank" rel="noopener nofollow">github.com/keshavashiya/codesage</a>
Contributions, feedback, and feature requests are all welcome.
<hr>
CodeSage: Stop searching. Start asking.

Keshav Ashiya

CodeSage is a local-first code intelligence CLI that combines vector search, graph traversal, and developer pattern learning to enable natural language code search. It indexes codebases locally using Ollama for embeddings, LanceDB for vector storage, and KuzuDB for relationship graphs. The tool offers three chat modes (Brainstorm, Implement, Review) with specialized commands for semantic search, impact analysis, and code review. It integrates with AI IDEs through the Model Context Protocol, allowing assistants like Claude and Cursor to access intelligent code search. Everything runs on your machine without cloud services or API keys, supporting Python natively and JavaScript, TypeScript, Go, and Rust with additional setup.

CodeSage: When grep Just Isn't Enough Anymore