bartolli/codanna

Codanna – Local Code‑Intelligence Server for AI Coding Agents

What it is – Codanna is a Rust‑based tool that builds a searchable, semantic index of a codebase on your own machine. It then exposes that knowledge through the MCP (Model‑Client‑Protocol), a lightweight protocol used by AI coding assistants such as Claude Code, Google Gemini, OpenAI Codex, Cursor, and Windsurf. In a single MCP call you can get a symbol’s definition, its documentation, its callers and callees, and an impact‑analysis (the “blast radius” if the symbol changes). The whole process runs locally; no source code or queries are sent to external services unless you explicitly enable a remote embedding model.

How it works

• Indexing – codanna init creates a .codanna/ directory, then codanna index <path> parses the files (15 languages supported) and stores symbols, call‑graph edges, and embeddings for semantic search.
• MCP interface – Two ways to talk to Codanna:
  1. Persistent server (codanna serve / codanna serve --http) that stays up for a whole development session.
  2. One‑shot CLI (codanna mcp …) that can be invoked from shell scripts, CI pipelines, or directly by an AI‑assistant skill.
• Main command – codanna mcp semantic_search_with_context returns, for each match, the symbol ID, signature, docstring, list of callers, list of callees (with exact call sites), and a recursive impact analysis. The output can be plain text or JSON (--json).

Key features

Feature	What you get
Semantic search	Natural‑language queries over code and markdown docs; finds functions by intent, not just name.
Relationship tracking	Call graphs, implementations, and cross‑module dependencies, enabling “where is this function called?” and “what breaks if I change it?” queries.
Document RAG	Indexes project documentation (markdown, text) so AI agents can retrieve relevant docs alongside code.
MCP protocol	Drop‑in compatibility with Claude, Gemini, Codex, Cursor, Windsurf, or any client that can invoke an external command.
Profiles / Skills	Pre‑packaged command sets for different project types; can be added to Claude Code via the plugin marketplace.
Local‑first	All indexing and embedding happen on‑device; optional remote OpenAI‑compatible embeddings are opt‑in only.
Performance	Parses up to ~250 k symbols/second; warm lookups under 10 ms; semantic queries a few milliseconds after the index is built.

Typical workflow

# Install (macOS/Linux/WSL) – one‑liner or Homebrew/Nix/PowerShell
curl -fsSL https://install.codanna.sh | sh

# Initialise the workspace
codanna init
codanna index src            # build the index for your source tree

# Ask an AI assistant (or the CLI) for context
codanna mcp semantic_search_with_context query:"extract function calls" limit:1

# Add project docs for RAG
codanna documents add-collection docs ./docs
codanna documents index
codanna mcp search_documents query:"authentication flow"

The CLI output includes file:line locations, symbol IDs, and a short guidance hint that an agent can chain into further queries.

Integration – Add a .mcp.json file to the project root so Claude Code, Cursor, or other MCP‑compatible tools launch Codanna automatically:

{ "mcpServers": { "codanna": { "command": "codanna", "args": ["--config", ".codanna/settings.toml", "serve", "--watch"] } } }

Transport can be stdio, HTTP, or HTTPS.

Installation options

• One‑line script (curl … | sh)
• Homebrew (brew install codanna)
• Nix (nix run github:bartolli/codanna)
• PowerShell script for Windows (experimental support)
• Build from source with Rust 1.85+ and cargo install codanna

System requirements

• ~150 MiB download for the default ONNX embedding model.
• macOS: Apple‑Silicon only (Intel not supported by current ONNX Runtime builds).
• Linux: glibc 2.38+ and GCC 13+ runtime libraries (pre‑built binaries target Ubuntu 24.04).
• Windows: experimental.

License – Apache 2.0 (with required attribution). Contributions are welcomed via the usual GitHub workflow.

---

Bottom line – Codanna gives AI coding assistants a fast, local, and richly structured view of a codebase, turning the usual “grep‑then‑read” loop into a single, context‑aware MCP request. It’s especially useful for agents that need to answer questions like “where is this function used?”, “what would break if I modify X?”, or “find the authentication logic” without sending any proprietary code to the cloud.