codanna

Codanna

Documentation · Report Bug · Discussions

Local code intelligence MCP server and CLI for AI coding agents.

X-ray vision for your agent.

Codanna is a local code intelligence and semantic code search MCP server for AI coding agents. One MCP call returns symbol context, call graph, and impact analysis, pre-correlated — the grep-and-read loop your agent runs today, collapsed into a single response it can act on.

It indexes your repository on disk and serves symbol search, semantic search, call graphs, dependency tracking, document RAG, and impact analysis to Claude Code, Cursor, Windsurf, Codex, Gemini, and any MCP-compatible client — as a persistent MCP server for session-long work, or a one-shot CLI for instant answers when LSP is too slow. Written in Rust. 15 languages. No source code leaves your machine.

Two operational modes

Codanna's MCP toolset is reachable two ways. Same tools, same surface — pick the mode that fits the workflow.

Persistent MCP server — for session-long agent workflows.

codanna serve                # stdio
codanna serve --http         # HTTP
codanna serve --https        # HTTPS

One-shot CLI — for slash-commands, bash hooks, scripts, CI. No daemon required.

codanna mcp find_symbol name:"my_function"
codanna mcp analyze_impact symbol_name:"my_function"
codanna mcp semantic_search_with_context query:"recursively extract function calls"

codanna mcp semantic_search_with_context is the headline command: it returns N semantic matches, and for each match the symbol identity, signature, docstring, callees, callers, and recursive impact analysis — five MCP tools fused into one query.

The one-shot CLI is also what makes codanna skill-friendly: an Agent Skill can wrap codanna mcp commands directly in Claude Code, Cursor, Windsurf, Codex, Gemini, or any harness that runs shell commands — no MCP plumbing required.

What one call returns

The headline command, run against codanna's own source tree. One call, and the agent has the symbol, its documentation, signature, callees with exact call sites, callers, and blast radius:

$ codanna mcp semantic_search_with_context query:"recursively extract function calls" limit:1

Found 1 results for query: 'recursively extract function calls'

1. extract_calls_recursive - Method at src/parsing/cpp/parser.rs:1002-1047 [symbol_id:1477]
   Similarity Score: 0.833
   Documentation:
     Recursively extract function calls with context tracking
   Signature: fn extract_calls_recursive<'a>(
        node: Node,
        code: &'a str,
        current_function: Option<&'a str>,
        calls: &mut Vec<(&'a str, &'a str, Range)>,
    )

   extract_calls_recursive calls 3 function(s):
     -> Method extract_calls_recursive at src/parsing/cpp/parser.rs:1002 [symbol_id:1477] (called at src/parsing/cpp/parser.rs:1045)
     -> Method function_name_at_def at src/parsing/cpp/parser.rs:377 [symbol_id:1451] (called at src/parsing/cpp/parser.rs:1008)
     -> Method new at src/types/mod.rs:112 [symbol_id:7388] (called at src/parsing/cpp/parser.rs:1028)

   2 function(s) call extract_calls_recursive:
     <- Method extract_calls_recursive at src/parsing/cpp/parser.rs:1045 [symbol_id:1477]
     <- Method find_calls at src/parsing/cpp/parser.rs:885 [symbol_id:1467]

   Changing extract_calls_recursive would impact 1 symbol(s) (max depth: 2):

     methods (1):
       - find_calls [symbol_id:1467]

Guidance: Found one match with full context. Review the relationships to understand how this fits into the codebase.

Every result carries file:line coordinates the agent can open directly, symbol_ids it can reuse to disambiguate name collisions, and a guidance hint it can chain on. Add --json for the structured envelope.

Local-first

Codanna runs on your machine. The repository index lives on disk under .codanna/. The embedding model downloads once on first use, then runs locally. No source code, symbols, or queries are sent to a remote API by default. Remote OpenAI-compatible embeddings are opt-in: remote_url under [semantic_search] in settings.toml, or CODANNA_EMBED_* environment variables; the API key is environment-only.

Quick Start

Install (macOS, Linux, WSL)

curl -fsSL --proto '=https' --tlsv1.2 https://install.codanna.sh | sh

Or via Homebrew

brew install codanna

Or via Nix

nix run github:bartolli/codanna

Windows (PowerShell)

irm https://raw.githubusercontent.com/bartolli/codanna/main/scripts/install.ps1 | iex

See Installation Guide for Cargo and other options.

Initialize and index

codanna init
codanna index src

Search code

codanna mcp semantic_search_with_context query:"where do we handle errors" limit:3

Search documentation (RAG)

codanna documents add-collection docs ./docs
codanna documents index
codanna mcp search_documents query:"authentication flow"

What It Does

Your AI assistant gains structured knowledge of your code:

• "Where's this function called?" - Instant call graph, not grep results
• "Find authentication logic" - Semantic search matches intent, not just keywords
• "What breaks if I change this?" - Full dependency analysis across files

The difference: Codanna understands code structure. It knows parseConfig is a function that calls validateSchema, not just a string match.

Features

Feature	Description
Semantic Search	Natural language queries against code and documentation. Finds functions by what they do, not just their names.
Relationship Tracking	Call graphs, implementations, and dependencies. Trace how code connects across files.
**[Document Search](https://docs.codanna.sh/features/docu