Get started with Sonar

Sonar finds places to start reading a codebase. It searches Rust, Python, TypeScript, TSX, and Markdown and returns JSON with file paths, symbols, and suggested line ranges.

Install the published sonar-code package from crates.io with Cargo, then index the repository you want to explore.

Prepare your tools

You need Rust 1.88 or newer, Cargo, and native build tools: a C/C++ compiler and linker. Linux is the validated platform. Cargo builds the executable from source and downloads dependencies during installation.

Basic indexing and search run locally without a model or API key. Optional compiler relationships and embedding search require additional preparation.

Install Sonar

Run this from any directory:

cargo install sonar-code --locked
sonar --help

The package name is sonar-code; the executable is sonar. Add $CARGO_HOME/bin, usually ~/.cargo/bin, to your PATH if your shell cannot find the installed command.

Index a repository

cd /path/to/your/repo
sonar index .
sonar investigate "Where are incoming requests authenticated?"

Replace the path and question with ones relevant to your project. Sonar writes .sonar/index.sqlite in your current directory. Each index belongs to one repository, and queries still need access to its source tree. Run the following commands from the same directory, or use --db /absolute/path/to/index.sqlite to select an index explicitly.

Indexing respects repository .gitignore and .ignore rules and skips hidden files, dependency directories, and build output. Add .sonar/ to the repository’s .gitignore if needed; the index contains source text and derived data.

Find a place to start reading

sonar brief "How are failed requests retried?" --limit 3
sonar investigate "How are requests routed?" --scope src --exclude src/generated
sonar outline src/main.rs

Adapt the questions and paths to your repository. brief returns a short list of starting points. investigate groups relevant locations with suggested line ranges. outline lists declarations in an indexed file.

Follow the returned paths and ranges with your editor or your agent’s file-reading tools. Search rankings help choose where to look; an empty result does not establish that a feature is absent.

Prepare richer navigation

Basic search needs only index. You can also prepare supported document links and module navigation:

sonar index-navigation

For Rust caller and reference navigation, install rust-analyzer and prepare the target project’s toolchain and dependencies, then run:

sonar resolve

Rust analysis runs with locked, locally available dependencies. For TypeScript relationships, you need Node.js, the project’s dependencies, and a local TypeScript 5.x or 6.x compiler:

sonar resolve --typescript /path/to/node_modules/typescript

Use the actual path to your TypeScript installation. Run both resolution commands for a mixed Rust and TypeScript repository. Python supports search and declarations; resolved calls and field uses are unavailable. Relationship coverage can be incomplete.

Connect a coding agent

After indexing and any optional preparation, configure an MCP client to launch:

sonar --db /absolute/path/to/your/repo/.sonar/index.sqlite mcp

Use absolute database and executable paths in the client configuration so its working directory does not change which index is opened. The client communicates over stdin and stdout.

Ask the agent to check sonar_status, then use sonar_brief or sonar_investigate. These tools read a prepared index; the agent needs its own tools to read the source files.

Refresh after changes

From the repository directory:

sonar index .

There is no automatic watcher. Repeat whichever optional preparation commands you used, including index-navigation, resolve, or embed, with the same options. Reindex and repeat preparation after upgrading Sonar too.

Running MCP processes see a refreshed index on their next call. Obtain fresh navigation handles after reindexing, and restart the client after changing the executable or configured database.