> ## 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.

# Codebase Chat

> Have AI-powered conversations with deep understanding of your code

## Overview

Codebase Chat is an AI consultant that knows your entire codebase. Unlike semantic search which returns file locations and snippets, Codebase Chat provides synthesized, ready-to-use answers — architecture explanations, debugging analysis, implementation guidance, and code reviews grounded in your actual code.

This is powered by CodeAlive's GraphRAG approach: the AI has access to the full knowledge graph of your codebase, not just individual files.

## How It Works

<Steps>
  <Step title="Ask a Question">
    Ask any question about your codebase in natural language. The AI retrieves relevant context from the knowledge graph before generating a response.
  </Step>

  <Step title="Get a Synthesized Answer">
    The response combines information from across your codebase — referencing multiple files, tracing data flows, and explaining architectural patterns.
  </Step>

  <Step title="Iterate">
    Ask another self-contained question that includes the findings and constraints the next answer needs.
  </Step>
</Steps>

## Example Conversations

<Tabs>
  <Tab title="Architecture">
    ```
    You: "Explain how the authentication system works in this project"

    AI: The authentication system uses a JWT-based flow with three main components:
        1. AuthController (src/controllers/auth.ts) handles login/signup endpoints
        2. JwtService (src/services/jwt.ts) manages token generation and validation
        3. AuthMiddleware (src/middleware/auth.ts) protects routes...
        [continues with specific code references]
    ```
  </Tab>

  <Tab title="Debugging">
    ```
    You: "Why might payments be failing intermittently?"

    AI: Based on the payment processing code, there are several potential causes:
        1. Race condition in PaymentProcessor.process() (src/services/payment.ts:142)
           - The lock acquisition doesn't cover the full transaction...
        2. Timeout configuration mismatch between the gateway client and...
        [continues with specific code analysis]
    ```
  </Tab>

  <Tab title="Implementation">
    ```
    You: "How should I add rate limiting to the API?"

    AI: Based on your existing middleware pattern in src/middleware/:
        1. Create a new RateLimitMiddleware following the pattern in AuthMiddleware
        2. The existing Redis connection in src/config/redis.ts can be reused...
        3. Your API routes in src/routes/index.ts use the middleware chain pattern...
        [continues with implementation guidance matching your codebase patterns]
    ```
  </Tab>

  <Tab title="Code Review">
    ```
    You: "Review the error handling in the user service"

    AI: The UserService has inconsistent error handling:
        1. createUser() (line 45) catches all errors but only logs generic messages
        2. updateUser() (line 89) correctly throws typed errors
        3. deleteUser() (line 112) has no error handling at all...
        [continues with specific recommendations]
    ```
  </Tab>
</Tabs>

## Access Methods

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

    | Parameter                                                                                                                                                        | Required | Description                      |
    | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------- |
    | `question`                                                                                                                                                       | Yes      | Your question about the codebase |
    | `data_sources`                                                                                                                                                   | Yes      | Repository or workspace names    |
    | Your AI agent may call this tool for synthesized analysis after search. For the highest reliability and depth, prefer `semantic_search` and `grep_search` first. |          |                                  |
  </Tab>

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

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

    See the [API reference](/api-reference/toolapi/stateless-chat) 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/chat.py "Explain the authentication flow" my-backend
    ```
  </Tab>
</Tabs>

## Stateless requests

Tool API chat does not retain conversation state. Include prior findings, artifact identifiers, assumptions, scope, and constraints in every `question`. This keeps each request reproducible across agents and integrations.

## Best Practices

<CardGroup cols={2}>
  <Card title="Search First" icon="magnifying-glass">
    Use `semantic_search` and `grep_search` for locating code. Use `chat` when you need explanations or analysis — it's more expensive per call and can take up to 30 seconds.
  </Card>

  <Card title="Include context" icon="comments">
    Make every question self-contained by including the relevant findings and constraints
  </Card>

  <Card title="Be Specific" icon="target">
    "Explain the payment retry logic" gets better results than "tell me about payments"
  </Card>

  <Card title="Scope by Repo" icon="folder">
    Target specific repositories for more focused, accurate answers
  </Card>
</CardGroup>

## Related Resources

<CardGroup cols={2}>
  <Card title="Semantic Search" icon="magnifying-glass" href="/features/semantic-search">
    Fast code search for finding file locations and snippets
  </Card>

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

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

  <Card title="API Reference" icon="code" href="/api-reference/toolapi/stateless-chat">
    Tool API chat endpoint documentation
  </Card>
</CardGroup>