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

# Tips & Tricks

> Get the most out of CodeAlive with these practical tips

A collection of practical tips for getting better results from CodeAlive across all AI agents.

## Prompting Strategies

<AccordionGroup>
  <Accordion title="Be specific with domain terms">
    Use the actual names from your codebase — class names, service names, module names. The more specific you are, the more relevant the results.

    | Instead of...    | Try...                                                 |
    | ---------------- | ------------------------------------------------------ |
    | "auth code"      | "authentication middleware in the Express API gateway" |
    | "database stuff" | "Prisma schema for the User model"                     |
    | "error handling" | "how does OrderService handle payment failures?"       |
    | "the API"        | "the /api/v2/users REST endpoint"                      |
  </Accordion>

  <Accordion title="Ask about patterns, not just code">
    CodeAlive understands architectural patterns, not just individual files. Ask higher-level questions:

    ```
    "How does error handling work across the API layer?"
    "What pattern do we use for database transactions?"
    "How are background jobs structured in this project?"
    ```
  </Accordion>

  <Accordion title="Make chat questions self-contained">
    Tool API chat is stateless. Include the relevant findings and constraints again when you drill deeper:

    ```
    First: "How does the payment flow work?"
    Next: "Given the payment flow above, what happens if the payment provider returns a timeout?"
    Next: "Using the timeout path above, show me the retry logic for that case"
    ```
  </Accordion>

  <Accordion title="Combine search and chat">
    Start with `semantic_search` or `grep_search` to gather evidence, then use `chat` only if you still need a synthesized explanation:

    ```
    1. Search: "payment webhook handler"
    2. Grep: "refund"
    3. Chat: "Explain how the payment webhook handler processes refund events"
    ```

    This gives chat more focused context and produces better answers.
  </Accordion>
</AccordionGroup>

## Search Optimization

<AccordionGroup>
  <Accordion title="Choose the right search tool">
    Use the canonical pair by default:

    | Tool              | When to use                                                   | Speed  |
    | ----------------- | ------------------------------------------------------------- | ------ |
    | `semantic_search` | Meaning-based retrieval, architecture clues, related patterns | Fast   |
    | `grep_search`     | Exact strings, identifiers, log lines, regex patterns         | Fast   |
    | `codebase_search` | Legacy compatibility only                                     | Varies |
  </Accordion>

  <Accordion title="Scope searches to repositories">
    If you have multiple repositories indexed, scope your search to avoid noise:

    ```
    "Search for authentication logic in the backend repository"
    "Find React components in the frontend repo"
    ```

    Use `get_data_sources` to see available repositories and workspaces. Pass your task as its
    `query` argument to get only the relevant sources, each with a `relevanceReason` — useful when
    many repositories are indexed.
  </Accordion>

  <Accordion title="Search first, then chat">
    `semantic_search` and `grep_search` are the default tools. `chat` is slower, can take up to 30 seconds, and uses more tokens but synthesizes a complete answer.

    **Recommended flow:**

    1. Search to find where relevant code lives
    2. Fetch or read the most relevant artifacts
    3. Chat only when you need synthesis, explanation, or analysis
  </Accordion>
</AccordionGroup>

## Workspace Organization

<AccordionGroup>
  <Accordion title="Group related repos into workspaces">
    Workspaces let you organize repositories by team, project, or domain:

    * `backend` — API services, database layer, background jobs
    * `frontend` — Web app, mobile app, shared components
    * `infrastructure` — Terraform, CI/CD configs, deployment scripts

    Scoped searches within a workspace return faster, more relevant results.
  </Accordion>

  <Accordion title="Keep workspaces focused">
    Indexing too many unrelated repositories in one workspace adds noise to search results. If you're getting irrelevant hits, split your workspace or scope your queries to specific repos.
  </Accordion>
</AccordionGroup>

## Cost & Token Optimization

<AccordionGroup>
  <Accordion title="Use search before chat">
    `semantic_search` and `grep_search` are significantly cheaper and faster than `chat`. Use search for lookups and locating code. Reserve chat for synthesis and analysis.

    If your agent supports subagents and you need maximum reliability or depth, prefer a subagent-driven workflow built on `semantic_search` and `grep_search` instead of jumping straight to chat.

    | Tool                              | Best for                                    | Relative cost                                                 |
    | --------------------------------- | ------------------------------------------- | ------------------------------------------------------------- |
    | `get_data_sources`                | Listing repos, checking status              | Minimal (low with `query`, which runs an AI relevance filter) |
    | `semantic_search` / `grep_search` | Finding code, locating evidence             | Low                                                           |
    | `chat`                            | Explanations, analysis, synthesized answers | Higher                                                        |
  </Accordion>

  <Accordion title="Write focused queries">
    Shorter, more focused queries return better results and use fewer tokens. Instead of explaining your entire situation, ask a direct question:

    | Instead of...                                                                                                                                         | Try...                                   |
    | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
    | "I'm working on a feature where users can reset their password and I need to understand how the current password reset flow works so I can modify it" | "How does the password reset flow work?" |
  </Accordion>
</AccordionGroup>

## Agent-Specific Tips

<AccordionGroup>
  <Accordion title="Claude Code">
    * Use `claude mcp add` for the simplest setup — one command, done
    * Add CodeAlive to your custom instructions so Claude uses it automatically
    * Works with both remote MCP and local Docker
  </Accordion>

  <Accordion title="Cursor">
    * Composer Agent mode automatically uses MCP tools when relevant
    * Use `.cursor/mcp.json` for project-specific config (shareable with team)
    * Add CodeAlive patterns to `.cursorrules` for consistent AI behavior
  </Accordion>

  <Accordion title="Windsurf">
    * Config uses `serverUrl` — not `url` — different from other agents
    * Supports Streamable HTTP transport
    * Check Windsurf's MCP settings page for connection status
  </Accordion>

  <Accordion title="Cline">
    * Supports auto-approve for MCP tools to reduce confirmation prompts
    * Add CodeAlive rules to `.cline/rules.md` for automatic context usage:
      ```
      Always search CodeAlive before writing new code.
      Follow existing patterns found in the codebase.
      ```
  </Accordion>

  <Accordion title="VS Code + GitHub Copilot">
    * Native MCP support is GA in VS Code
    * Configure in `.vscode/mcp.json` for project-level setup
    * Agent mode in Copilot Chat automatically discovers MCP tools
  </Accordion>
</AccordionGroup>

## What's Next

<CardGroup cols={2}>
  <Card title="Example Workflows" icon="flask" href="/workflows">
    See real-world usage patterns
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/troubleshooting">
    Solutions for common issues
  </Card>
</CardGroup>