Semantic code search and relationship tracking via MCP and Unix CLI.

• How It Works
• Installation
• Quick Start
• Claude Integration
  • MCP Server (Recommended)
  • HTTP/HTTPS Server
  • Claude Sub Agent
  • Unix-Style Integration
• Configuration
• Documentation Comments for Better Search
• CLI Commands
  • Core Commands
  • Retrieval Commands
  • Testing and Utilities
  • Common Flags
• MCP Tools
  • Simple Tools (Positional Arguments)
  • Complex Tools (Key:Value Arguments)
  • Parameters Reference
• Performance
• Architecture Highlights
• Requirements
• Current Limitations
• Roadmap
  • Version Strategy
  • v0.3.0 (Released)
  • v0.4.0 (Next Release)
  • v0.4.1 (Planned)
  • v0.4.2 (Planned)
  • v0.4.3 (Planned)
  • v0.4.4 (Planned)
  • v0.4.5 (Planned)
  • v0.5.0 (Future)
  • Supported Languages
• Feature Details
  • Completed Features
  • Planned Features
• Contributing
• License

1. Parse - Tree-sitter AST parsing for Rust, Python, and PHP (more languages coming)
2. Extract - Symbols, call graphs, implementations, and type relationships
3. Embed - 384-dimensional vectors from doc comments via AllMiniLML6V2
4. Index - Tantivy for full-text search + memory-mapped symbol cache for <10ms lookups
5. Serve - MCP protocol for AI assistants, ~300ms response time

# Install latest version
cargo install codanna

# Install with HTTP server (OAuth authentication)
cargo install codanna --features http-server

# Install with HTTPS server (TLS + optional OAuth)
cargo install codanna --features https-server

# Install from local path (development)
cargo install --path . --all-features

1. Initialize:

# Initialize codanna index space and create .codanna/settings.toml
codanna init

2. Index your codebase:

# Index with progress display
codanna index src --progress

# See what would be indexed (dry run)
codanna index . --dry-run

# Index a specific file
codanna index src/main.rs

3. Search your code:

# Semantic search with new simplified syntax
codanna mcp semantic_search_docs query:"parse rust files" limit:3 --json

# Find symbols with JSON output
codanna retrieve symbol Parser --json

# Analyze function relationships
codanna mcp find_callers process_file --json | jq '.data[].name'

# Legacy format still works
codanna mcp semantic_search_with_context --args '{"query": "parse rust files and extract symbols", "limit": 3}'

Add to your .mcp.json:

{
  "mcpServers": {
    "codanna": {
      "command": "codanna",
      "args": ["serve", "--watch", "--watch-interval", "5"]
    }
  }
}

For persistent server with real-time file watching:

# HTTP server with OAuth authentication (requires http-server feature)
codanna serve --http --watch

# HTTPS server with TLS encryption (requires https-server feature)
codanna serve --https --watch

Configure in .mcp.json:

{
  "mcpServers": {
    "codanna-sse": {
      "type": "sse",
      "url": "http://127.0.0.1:8080/mcp/sse"
    }
  }
}

For HTTPS configuration, see the HTTPS Server Mode documentation.

We include a codanna-navigator sub agent at .claude/agents/codanna-navigator.md. This agent is optimized for using the codanna MCP server.

Codanna CLI is unix-friendly with positional arguments and JSON output for easy command chaining:

# New simplified syntax - positional arguments for simple tools
codanna mcp find_symbol main --json
codanna mcp get_calls process_file
codanna mcp find_callers init

# Key:value pairs for complex tools  
codanna mcp semantic_search_docs query:"error handling" limit:3 --json
codanna mcp search_symbols query:parse kind:function --json

# Unix piping with JSON output
time codanna mcp search_symbols query:parse limit:1 --json | \
    jq -r '.data[0].name' | \
    xargs -I {} codanna retrieve callers {} --json | \
    jq -r '.data[] | "\(.name) in \(.module_path)"'

# Result:
#
# main in crate::main
# serve_http in crate::mcp::http_server::serve_http
# serve_http in crate::mcp::http_server::serve_http
# serve_https in crate::mcp::https_server::serve_https
# serve_https in crate::mcp::https_server::serve_https
# parse in crate::parsing::rust::parse
# parse in crate::parsing::rust::parse
# parse in crate::parsing::python::parse
#
# codanna mcp search_symbols query:parse limit:1 --json  0.10s user 0.08s system 122% cpu 0.143 total
# jq -r '.data[0].name'  0.00s user 0.00s system 3% cpu 0.142 total
# xargs -I {} codanna retrieve callers {} --json  0.11s user 0.07s system 63% cpu 0.288 total
# jq -r '.data[] | "\(.name) in \(.module_path)"'  0.00s user 0.00s system 1% cpu 0.288 total

# Legacy format still supported for backward compatibility
codanna mcp find_symbol --args '{"name": "main"}'

All MCP tools support --json flag for structured output, making integration with other tools seamless.

Configure Codanna in .codanna/settings.toml:

[semantic_search]
enabled = true
model = "AllMiniLML6V2"
threshold = 0.6  # Similarity threshold (0-1)

[indexing]
parallel_threads = 16  # Auto-detected by default
include_tests = true   # Index test files

Codanna respects .gitignore and adds its own .codannaignore:

# Created automatically by codanna init
.codanna/       # Don't index own data
target/         # Skip build artifacts
node_modules/   # Skip dependencies
*_test.rs       # Optionally skip tests

Semantic search works by understanding your documentation comments:

/// Parse configuration from a TOML file and validate required fields
/// This handles missing files gracefully and provides helpful error messages
fn load_config(path: &Path) -> Result<Config, Error> {
    // implementation...
}

With good comments, semantic search can find this function when prompted for:

• "configuration validation"
• "handle missing config files"
• "TOML parsing with error handling"

This encourages better documentation → better AI understanding → more motivation to document.

All retrieve commands support --json flag for structured output (exit code 3 when not found).

• --config, -c: Path to custom settings.toml file
• --force, -f: Force operation (overwrite, re-index, etc.)
• --progress, -p: Show progress during operations
• --threads, -t: Number of threads to use
• --dry-run: Show what would happen without executing

Available tools when using the MCP server. All tools support --json flag for structured output.

Parser benchmarks on a 750-symbol test file:

Key achievements:

• Zero-cost abstractions: All parsers use borrowed string slices with no allocations in hot paths
• Parallel processing: Multi-threaded indexing that scales with CPU cores
• Memory efficiency: Approximately 100 bytes per symbol including all metadata
• Real-time capability: Fast enough for incremental parsing during editing
• Optimized CLI startup: ~300ms for all operations (53x improvement from v0.2)
• JSON output: Zero overhead - structured output adds <1ms to response time

Run performance benchmarks:

codanna benchmark all          # Test all parsers
codanna benchmark python       # Test specific language

Memory-mapped storage: Two caches for different access patterns:

• symbol_cache.bin - FNV-1a hashed symbol lookups, <10ms response time
• segment_0.vec - 384-dimensional vectors, <1μs access after OS page cache warm-up

Embedding lifecycle management: Old embeddings deleted when files are re-indexed to prevent accumulation.

Lock-free concurrency: DashMap for concurrent symbol reads, write coordination via single writer lock.

Single-pass indexing: Symbols, relationships, and embeddings extracted in one AST traversal.

Hot reload: File watcher with 500ms debounce triggers re-indexing of changed files only.

• Rust 1.75+ (for development)
• ~150MB for model storage (downloaded on first use)
• A few MB for index storage (varies by codebase size)

• Supports Rust, Python, and PHP (JavaScript/TypeScript coming in v0.4.1)
• Semantic search requires English documentation/comments
• Windows support is experimental

• 0.3.x - CLI improvements and API stability
• 0.4.x - Language expansion via modular architecture
• 0.5.x - Enterprise features and advanced analysis

Legend: ✅ Complete | 🔧 In Progress | 📋 Planned

• Rust - Full support with trait implementations and generics
• Python - Functions, classes, and imports
• PHP - Classes, functions, and namespaces

Based on developer demand and tree-sitter support:

1. JavaScript/TypeScript (v0.4.1) - Most requested for web development
2. Go (v0.4.2) - Growing popularity in cloud/backend
3. C# (v0.4.3) - Enterprise and game development
4. Java (v0.4.4) - Enterprise applications
5. C/C++ (v0.4.5) - Systems programming

All retrieve commands and MCP tools support --json flag for structured output with consistent format and proper exit codes (v0.3.0).

Semantic exit codes for scripting: 0 (success), 1 (general error), 3 (not found). Enables reliable automation (v0.3.0).

Simplified syntax with positional arguments for simple tools and key:value pairs for complex tools. No JSON escaping needed (v0.3.0).

Watch mode with automatic re-indexing of changed files. Broadcast channels coordinate updates with 500ms debouncing (v0.3.0).

Modular parser system where languages self-register via a registry. Enables easy addition of new languages without core code changes (v0.4.0).

Full PHP parser with classes, functions, namespaces, and traits. Supports PHP 5 through PHP 8 syntax (v0.4.0).

Direct retrieve semantic command for natural language code search without going through MCP interface.

Process multiple symbols in a single command to reduce overhead and improve CI/CD performance.

Choose between compact (script-friendly), full (human-readable), and json output formats.

Full JavaScript/ES6+ parser with modules, classes, async/await, and JSX support.

TypeScript parser with full type annotation support, interfaces, and decorators.

Go language parser with interfaces, goroutines, channels, and struct methods.

C# parser with .NET ecosystem support, LINQ, async/await, and attributes.

Java parser with class hierarchies, interfaces, generics, and annotations.

C and C++ parsers with headers, templates, macros, and cross-compilation units.

Advanced search syntax with wildcards, boolean operators, and complex filters.

Environment-specific settings (dev, test, production) with profile inheritance.

JSON-formatted progress output for better CI/CD integration and monitoring.

Track and analyze references across different programming languages in polyglot codebases.

LSP implementation for IDE integration with real-time code intelligence.

This is an early release focused on core functionality. Contributions welcome! See CONTRIBUTING for guidelines.

Licensed under the Apache License, Version 2.0 - See LICENSE file for details.

Attribution required when using Codanna in your project. See NOTICE file.

Built with 🦀 by developers who wanted their AI assistants to actually understand their code.