I built a CLI to visually map and chat with any codebase (using Tree-sitter & Graphology)

We’ve all been there. You clone a massive, undocumented repository, run npm install or pip install, open your editor, and stare blankly at a folder tree containing hundreds of files. You spend the next three hours reverse-engineering imports just to figure out where the core logic lives.

I got tired of bloated enterprise tools and wanted a fast, terminal-native utility that could just show me how a project fits together.

So, I built codebase-vis: a language-agnostic CLI tool that parses your code, clusters related modules, renders an interactive dependency graph, and lets you ask an LLM to explain the architecture.

Here is how I built it and how you can use it.

Quickstart

It is designed to be as frictionless as possible. You can run it on your current project right now:

bash
npm install -g codebase-vis
cd my-messy-project
codebase-vis init
codebase-vis generate

How it works under the hood
I wanted to build something that prioritized raw utility over complex setup. The architecture is broken down into three main pipelines:

1. The Parsing Engine (Tree-sitter + Worker Threads) Relying on simple Regex to find imports is a nightmare. Instead, I used Tree-sitter to generate actual Abstract Syntax Trees (ASTs).

Because parsing hundreds of files synchronously would block the Node.js event loop and make the CLI sluggish, I implemented a custom WorkerPool. The CLI spins up child processes to parse TypeScript, Python, Rust, C++, and Go files concurrently. It extracts module-level dependencies and entities (functions, classes) and pipes them back to the main thread.

1. Structuring the Graph (Graphology + Louvain) Once I had the raw dependencies, I needed to turn them into a readable map. I used Graphology to construct the directed graph.

But massive codebases just look like a giant spiderweb. To solve this, I implemented the Louvain community detection algorithm. The tool automatically detects clusters of highly coupled files and groups them into "communities" (like grouping your API routes separately from your database models), naming them based on their common root directories.

1. AI Explanations (Throttled LLM Integration) Seeing the graph is great, but understanding why it's built that way is better. The explain command extracts a payload from a specific cluster of the graph and sends it to a Large Language Model. To prevent hitting API rate limits when processing massive repositories, I wrote a custom TokenBucket rate-limiter to manage concurrency.

I need your feedback (and PRs!)
I build tools because I'm usually unhappy with the existing solutions out there. codebase-vis is fully open-source, and I would love for you to try it on your own projects and break it.

I am actively looking for contributors! If you want to jump into open-source, the architecture is highly modular. Here are a few easy wins if you want to contribute:

Add a new language parser: Our Tree-sitter pipeline makes it incredibly easy to add support for PHP, Ruby, or C#.

Enhance the UI: The frontend currently uses a simple HTML template with vis-network. If you know your way around frontend visualization, I'd love your help polishing the interactive graph.

Check out the repo here: [https://www.github.com/Arham-Qureshi/codebase-vis]