/code-search - Semantic Code Search

Search your codebase using natural language queries via codanna's semantic search engine.

Prerequisites

Codanna must be configured as an MCP server. See: ADR-065

Quick Setup:

# Ensure codanna is installed
which codanna || cargo install codanna

# Index your project (first time)
/code-index

Usage

# Basic semantic search
/code-search "authentication handlers"

# Search with context
/code-search "error handling in API routes" --context

# Search specific file types
/code-search "database connection" --lang rust

# Limit results
/code-search "logging implementation" --limit 5

# Show symbol relationships
/code-search "UserService" --with-calls

System Prompt

⚠️ EXECUTION DIRECTIVE: When the user invokes /code-search with a query, you MUST:

1. IMMEDIATELY execute the semantic search via MCP tool
2. Display results with file paths, line numbers, and context
3. Offer navigation to relevant files if user wants to explore

---

You are executing semantic code search using codanna's MCP integration.

MCP Tool: semantic_search or semantic_search_with_context

Execution Flow:

1. Parse the user's natural language query
2. Call the appropriate MCP tool
3. Format and display results
4. Offer to read/navigate to top results

Example MCP Call:

{
  "tool": "semantic_search",
  "arguments": {
    "query": "authentication handlers",
    "limit": 10
  }
}

With Context:

{
  "tool": "semantic_search_with_context",
  "arguments": {
    "query": "authentication handlers",
    "limit": 10,
    "include_relationships": true
  }
}

Options

Option	Description
<query>	Natural language search query (required)
--context	Include surrounding code context
--lang LANG	Filter by language (rust, python, typescript, etc.)
--limit N	Maximum results (default: 10)
--with-calls	Include call relationships
--kind KIND	Filter by symbol kind (function, class, struct, etc.)

Examples

Find Authentication Code

/code-search "user authentication and login"

Result: Files containing authentication logic, ranked by semantic relevance

Find Error Handling Patterns

/code-search "how errors are handled in the API" --context

Result: Error handling code with surrounding context

Find Database Operations

/code-search "database queries and connections" --lang python

Result: Python files with database operations

Find a Specific Symbol with Calls

/code-search "UserService" --with-calls

Result: UserService definition plus what it calls and what calls it

Output Format

Results are displayed with:

📁 src/auth/handlers.rs:42
   ├─ Symbol: authenticate_user (function)
   ├─ Score: 0.89
   └─ Context:
      │ pub async fn authenticate_user(credentials: &Credentials) -> Result<User> {
      │     let user = db.find_user(&credentials.email).await?;
      │     verify_password(&credentials.password, &user.password_hash)?;
      │     Ok(user)
      │ }

📁 src/middleware/auth.rs:15
   ├─ Symbol: AuthMiddleware (struct)
   ├─ Score: 0.82
   └─ Context:
      │ pub struct AuthMiddleware {
      │     jwt_secret: String,
      │     session_store: SessionStore,
      │ }

Integration

Works with:

• /code-index - Index project before searching
• /impact - Analyze change impact on found symbols
• /callers - Find what calls a discovered function
• /calls - Find what a discovered function calls

MCP Server: codanna (stdio mode)

Troubleshooting

Issue	Solution
"No index found"	Run /code-index first
"MCP server not running"	Check ~/.claude/mcp.json configuration
Low relevance scores	Try more specific query terms
Missing files	Check .codannaignore exclusions

When NOT to Use

Do NOT use when:

• Looking for exact string match (use Grep instead)
• Searching file names (use Glob instead)
• Project not yet indexed

Principles

This command embodies:

• #1 Recycle, Extend, Re-Use - Leverages existing codanna tool
• #3 Complete Execution - Returns actionable results
• #5 Graceful Degradation - Falls back to grep if MCP unavailable

Full Standard: CODITECT-STANDARD-AUTOMATION.md

---

MCP Tool: semantic_search, semantic_search_with_context Requires: codanna MCP server ADR: ADR-065 Version: 1.0.0 Last Updated: 2026-01-11