DEV Community

Keshav Ashiya
Keshav Ashiya

Posted on

CodeSage: When grep Just Isn't Enough Anymore

#rag #langchain #cli #ai

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.

codesage init
codesage index
codesage search "validate email addresses"
Enter fullscreen mode Exit fullscreen mode

But semantic search is just the beginning.

The Three Pillars of Code Understanding

Most code search tools do one thing: match text. CodeSage takes a fundamentally different approach by combining three complementary techniques:

1. Vector Search: Find Code by Meaning

"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.

2. Graph Traversal: Understand Relationships

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:

  • "What functions call this method?"
  • "What would break if I changed this class?"
  • "How does data flow from the API endpoint to the database?"

3. Developer Memory: Learn Your Patterns

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.

Interactive Chat with Specialized Modes

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:

Mode What It's For
Brainstorm Exploring ideas, asking open-ended questions
Implement Focused task execution, generating code and plans
Review Code review, security analysis, quality checks

Switch anytime with /mode implement or let CodeSage detect your intent from context.

The chat commands go deep:

/search <query>    Semantic code search
/deep <query>      Multi-agent analysis (runs parallel search strategies)
/plan <task>       Implementation plan using your existing patterns
/review [file]     Code review with security awareness
/impact <element>  Blast radius analysis—what breaks if this changes?
/similar <code>    Find similar patterns across your codebase
/patterns          Show what CodeSage has learned about your style
Enter fullscreen mode Exit fullscreen mode

Smart Query Expansion

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.

Works with Your AI IDE

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:

codesage mcp serve --global
Enter fullscreen mode Exit fullscreen mode

Or add this to your MCP client configuration:

{
  "mcpServers": {
    "codesage": {
      "command": "codesage",
      "args": ["mcp", "serve", "--global"]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Now your AI assistant has access to intelligent code search across all your indexed projects:

MCP Tool What It Does
search_code Semantic search with graph context
get_file_context File content with its dependencies and relationships
get_task_context Implementation guidance grounded in your patterns
review_code Code review using learned conventions
analyze_security Security scan with project-specific context

Your AI assistant stops giving generic answers and starts giving grounded answers based on your actual codebase.

The Technical Stack

Everything runs locally. No exceptions.

  • Ollama handles embeddings and LLM responses
  • LanceDB provides vector storage with fast similarity search
  • KuzuDB powers the code relationship graph
  • SQLite stores metadata and developer memory

You need Ollama running with a few models:

ollama pull qwen2.5-coder:7b
ollama pull mxbai-embed-large
ollama serve
Enter fullscreen mode Exit fullscreen mode

That's it. No cloud accounts, no API keys, no data leaving your machine.

Getting Started

Installation takes one command:

pipx install pycodesage
Enter fullscreen mode Exit fullscreen mode

Then index your first project:

cd your-project
codesage init
codesage index
Enter fullscreen mode Exit fullscreen mode

Start searching:

codesage search "handle user registration"
codesage chat
Enter fullscreen mode Exit fullscreen mode

Language Support

Python works out of the box. For JavaScript, TypeScript, Go, and Rust:

pipx inject pycodesage "pycodesage[multi-language]"
Enter fullscreen mode Exit fullscreen mode

What's Next

We're actively developing:

  • More language parsers — expanding beyond the current set
  • Cross-project learning — enhanced pattern sharing between codebases
  • Documentation generation — auto-generate docs that match your style

Try It 

pipx install pycodesage
Enter fullscreen mode Exit fullscreen mode

GitHub: github.com/keshavashiya/codesage

Contributions, feedback, and feature requests are all welcome.

CodeSage: Stop searching. Start asking.

Top comments (0)