When Your Codebase Becomes a Queryable Graph

You know that feeling when you're deep in a massive codebase, grepping for some function or import, and you realize you've spent more time searching than actually writing code? That's the problem codegraph tries to solve in a pretty clever way.

Instead of running grep over files every time you ask something, it pre-indexes your codebase into a graph structure. Then your agent—or you—can query relationships between files, functions, classes, and dependencies without touching the filesystem. It's like having a mental map of your code, but faster and more accurate.

What It Does

Codegraph is a tool that builds a graph of your source code. It parses your project's files, extracts symbols (functions, classes, imports, exports), and links them together. The result is a queryable graph where you can ask questions like:

• "What files import this module?"
• "Where is this function defined?"
• "What dependencies does this file have?"

It's designed to work with agents, but you can also use it directly from the command line.

Under the hood, it uses tree-sitter for parsing (so it's fast and language-aware) and stores the graph in a simple SQLite database. The query interface is a basic CLI or a Python library.

Why It's Cool

The real magic is the pre-indexing. Once you've scanned your codebase once, every subsequent query is a database lookup, not a filesystem traversal. That makes it:

• Fast — especially for large projects where grep starts to hurt.
• Structured — you get relationships, not just string matches. You can trace a function call through multiple files.
• Agent-friendly — if you're building an AI coding assistant, this is way more efficient than making it grep every time.

The implementation is refreshingly simple. It's not trying to be a full code analysis platform. It's a focused tool that does one thing well: give you a queryable graph of your code.

How to Try It

Getting started is straightforward. Clone the repo and install with pip:

git clone https://github.com/colbymchenry/codegraph.git
cd codegraph
pip install .

Then index your project:

codegraph scan /path/to/your/project

After that, you can query:

codegraph query "find imports in src/main.py"

Or use it from Python if you're building an agent:

from codegraph import CodeGraph
cg = CodeGraph("path/to/db")
cg.query("functions defined in utils.py")

Check the repo's README for detailed usage—it's well documented.

Final Thoughts

This is one of those tools that solves a real pain point without overcomplicating it. If you work with large codebases or build AI tools that need to navigate code, codegraph feels like a sensible building block. It's not flashy, but it's the kind of utility that quietly saves you time every day.

Give it a spin on a project you know well. You might be surprised how much faster your queries get.

Found this on @githubprojects