> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codealive.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Semantic Code Search

> Find code by meaning and intent across your entire codebase

## Overview

CodeAlive's semantic code search goes beyond keyword matching — it understands the meaning and intent behind your queries. Ask for "authentication flow" and find JWT validation, OAuth callbacks, and session management code, even if none of those files contain the word "authentication."

This is powered by CodeAlive's GraphRAG indexing, which maps relationships between code components, dependencies, and architectural patterns across your entire codebase.

## How It Works

<Steps>
  <Step title="Index">
    CodeAlive indexes your repositories, building a knowledge graph of code relationships, function signatures, data flows, and architectural patterns.
  </Step>

  <Step title="Query">
    You ask a natural-language question. CodeAlive translates it into a semantic search across the knowledge graph, finding code that matches by meaning — not just text.
  </Step>

  <Step title="Results">
    You get file paths, line numbers, and code snippets ranked by relevance. Your AI agent can then read the actual files for full context.
  </Step>
</Steps>

## Choose a search tool

<Tabs>
  <Tab title="Semantic search">
    Use `semantic_search` when you know the behavior or concept but not the exact identifier.

    ```
    "Find authentication-related code"
    "Show me error handling patterns in the payment service"
    ```
  </Tab>

  <Tab title="Grep search">
    Use `grep_search` when you know the exact function name, class, string, or regular expression.

    ```
    "Find JwtTokenValidator class"
    "Locate handlePaymentWebhook function"
    ```
  </Tab>
</Tabs>

## Example Queries

<AccordionGroup>
  <Accordion title="Authentication & Security">
    * "How is JWT token validation implemented?"
    * "Find OAuth callback handlers"
    * "Show me all authorization middleware"
    * "Where are API keys validated?"
  </Accordion>

  <Accordion title="Error Handling">
    * "How does the system handle database connection failures?"
    * "Find retry logic across services"
    * "Show me error boundary implementations"
    * "Where are 500 errors caught and reported?"
  </Accordion>

  <Accordion title="Architecture Patterns">
    * "Find all event-driven communication between services"
    * "Show me the repository pattern implementations"
    * "How is dependency injection configured?"
    * "Find all middleware in the request pipeline"
  </Accordion>

  <Accordion title="API & Data">
    * "List all REST API endpoints"
    * "Find database migration files"
    * "Show me GraphQL resolver implementations"
    * "Where is caching implemented?"
  </Accordion>
</AccordionGroup>

## Access Methods

<Tabs>
  <Tab title="MCP Tool">
    The `semantic_search` tool is available through any CodeAlive-connected agent:

    | Parameter      | Required | Description                                     |
    | -------------- | -------- | ----------------------------------------------- |
    | `question`     | Yes      | Natural-language search question                |
    | `data_sources` | Yes      | Repository or workspace names to search         |
    | `paths`        | No       | Optional repo-relative path scopes              |
    | `extensions`   | No       | Optional file extensions such as `.py` or `.ts` |
    | `max_results`  | No       | Optional result cap                             |

    Your AI agent calls this tool automatically when you ask questions about your codebase.
  </Tab>

  <Tab title="REST API">
    Search directly via the CodeAlive API:

    ```bash theme={null}
    curl -X POST https://app.codealive.ai/api/tools/semantic_search \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "question": "authentication flow",
        "data_sources": ["my-backend"]
      }'
    ```

    See the [API reference](/api-reference/toolapi/semantic-search) for the request and response schemas.
  </Tab>

  <Tab title="Skill CLI">
    If you have the [CodeAlive skill](/integrations/skills) installed:

    ```bash theme={null}
    python scripts/search.py "JWT token validation" my-backend
    python scripts/search.py "error handling patterns" workspace:platform-team
    ```
  </Tab>
</Tabs>

## Best Practices

<CardGroup cols={2}>
  <Card title="Be Specific" icon="target">
    Use domain-specific terms: "JWT validation" is better than "security check"
  </Card>

  <Card title="Pick the right tool" icon="wand-magic-sparkles">
    Use semantic search for concepts and grep search for exact text or regular expressions
  </Card>

  <Card title="Scope Your Search" icon="folder">
    Target specific repositories or workspaces to get more relevant results
  </Card>

  <Card title="Iterate" icon="repeat">
    Refine your query based on initial results — each search is fast and cheap
  </Card>
</CardGroup>

## Related Resources

<CardGroup cols={2}>
  <Card title="Codebase Chat" icon="comments" href="/features/codebase-chat">
    Get synthesized answers instead of raw search results
  </Card>

  <Card title="Multi-Repository" icon="folder-tree" href="/features/multi-repo">
    Search across multiple repositories and workspaces
  </Card>

  <Card title="MCP Integration" icon="plug" href="/integrations/mcp">
    Connect search to your AI assistant
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/toolapi/semantic-search">
    Semantic search endpoint documentation
  </Card>
</CardGroup>