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

# Claude Code Integration

> Connect CodeAlive with Claude Code for enhanced AI-powered development

## Overview

<Warning>
  **Recommended: Use the [Claude Code Plugin](/integrations/plugin-claude-code) instead.** The plugin provides a better experience for Claude Code users — it includes the Context Engine skill, a code exploration subagent, and authentication hooks, all in a single install. The MCP integration described on this page is still supported and can be used alongside the plugin for direct tool access.
</Warning>

Integrate CodeAlive with Claude Code to enhance your AI coding assistant with deep contextual understanding of your entire codebase. This integration uses the Model Context Protocol (MCP) to provide Claude Code with semantic search and code intelligence capabilities.

<Tip>
  **Quick install:** Run `npx @codealive/installer` to automatically configure CodeAlive for Claude Code.
  See the [Installation Guide](/installation) for details.
</Tip>

<Info>
  **Claude Code defaults to its built-in `Grep`/`Glob` for exploration.** Connecting the MCP server alone won't change that — add routing rules to your project's `CLAUDE.md` so Claude reaches for CodeAlive first. See [Custom Instructions](#custom-instructions) below for a complete snippet.
</Info>

<Note />

## Prerequisites

* Claude Pro, Max, Team, or Enterprise subscription (required for MCP support)
* [Claude Code](https://claude.ai/code) installed
* CodeAlive account ([Sign up here](https://app.codealive.ai))
* Indexed repositories in your CodeAlive dashboard

## Installation Steps

<Info>
  Claude Code supports both local and remote MCP servers with OAuth authentication.
</Info>

<Steps>
  <Step title="Add via CLI (Recommended)">
    Run this command in your terminal:

    ```bash theme={null}
    claude mcp add --transport http codealive https://mcp.codealive.ai/api
    ```

    Start Claude Code, run `/mcp`, select `codealive`, and complete browser sign-in. Claude Code stores and refreshes the OAuth credential automatically.

    <Info>Existing API-key configurations remain supported. Add `--header "Authorization: Bearer YOUR_API_KEY_HERE"` only when you intentionally choose that fallback.</Info>
  </Step>

  <Step title="Alternative: Docker (STDIO)">
    For local development or enhanced privacy:

    ```bash theme={null}
    claude mcp add codealive-docker /usr/bin/docker run --rm -i -e CODEALIVE_API_KEY=YOUR_API_KEY_HERE ghcr.io/codealive-ai/codealive-mcp:main
    ```
  </Step>

  <Step title="Verify Integration">
    Test the integration by asking Claude Code:

    * "What CodeAlive repositories are available?"
    * "Search for authentication code in my codebase"
    * "Explain the architecture of my project"
  </Step>
</Steps>

## Available Commands

Once integrated, Claude Code can use these CodeAlive capabilities:

### Repository Management

```
"Show me all my indexed repositories"
"What codebases are connected to CodeAlive?"
"Update the repository index"
```

### Semantic Code Search

```
"Find all API endpoints in the user service"
"Show me error handling patterns across the codebase"
"Locate database connection implementations"
"Search for OAuth implementation"
```

### Contextual Analysis

```
"Explain how the payment flow works"
"Analyze this code for security vulnerabilities"
"Generate comprehensive tests for the AuthService"
"Review the authentication implementation"
```

## Usage Patterns

<Tabs>
  <Tab title="Code Understanding">
    ```
    You: "Help me understand how the user authentication works"

    Claude Code: [Searches your codebase for authentication logic]
                [Maps out the authentication flow]
                [Explains with actual code references]
    ```
  </Tab>

  <Tab title="Bug Investigation">
    ```
    You: "Debug why users can't reset their passwords"

    Claude Code: [Searches for password reset code]
                [Traces the flow from UI to backend]
                [Identifies potential issues with code references]
    ```
  </Tab>

  <Tab title="Code Generation">
    ```
    You: "Create a new API endpoint similar to our existing ones"

    Claude Code: [Analyzes existing API patterns]
                [Generates code matching your conventions]
                [Includes proper error handling and validation]
    ```
  </Tab>

  <Tab title="Refactoring">
    ```
    You: "Refactor this service to match our microservices pattern"

    Claude Code: [Finds similar service implementations]
                [Suggests refactoring based on codebase patterns]
                [Ensures consistency with existing architecture]
    ```
  </Tab>
</Tabs>

## Windows & WSL

Claude Code on Windows runs inside WSL (Windows Subsystem for Linux). The **Remote HTTP** option above works perfectly in WSL without any extra configuration — it's the recommended approach.

<Tabs>
  <Tab title="Claude Code in WSL (Recommended)">
    When Claude Code runs inside WSL, it operates as a normal Linux environment. Use the same Remote HTTP command:

    ```bash theme={null}
    claude mcp add --transport http codealive https://mcp.codealive.ai/api
    ```

    This avoids all WSL-specific issues (path translation, Docker socket, networking).
  </Tab>

  <Tab title="Docker STDIO in WSL">
    If you need Docker STDIO in WSL, ensure Docker Desktop has WSL integration enabled for your distro:

    ```bash theme={null}
    claude mcp add codealive-docker /usr/bin/docker run --rm -i -e CODEALIVE_API_KEY=YOUR_API_KEY_HERE ghcr.io/codealive-ai/codealive-mcp:main
    ```

    <Warning>
      If `docker` is not found, enable Docker Desktop WSL integration: Docker Desktop → Settings → Resources → WSL integration → enable your distro.
    </Warning>
  </Tab>

  <Tab title="Self-Hosted in WSL2">
    If you self-host the MCP server inside WSL2, note that WSL2 uses NAT networking — `localhost` in WSL2 is not the same as `localhost` on Windows.

    **Fix:** Enable mirrored networking (Windows 11 22H2+) in `%USERPROFILE%\.wslconfig`:

    ```ini theme={null}
    [wsl2]
    networkingMode=mirrored
    ```

    Then restart WSL: `wsl --shutdown`.

    Alternatively, use the WSL2 VM IP (run `hostname -I` inside WSL) instead of `localhost`.
  </Tab>
</Tabs>

## Advanced Features

### Multi-Repository Support

CodeAlive automatically provides access to all repositories indexed in your dashboard. Use the `get_data_sources` tool to discover available repositories and workspaces — pass your task as its `query` argument to get only the relevant ones — then target specific ones in your searches:

```
"Search for authentication code in the backend repository"
"Find user models across backend, frontend, and mobile repos"
"Show me API patterns in workspace:platform-team"
```

See [Multi-Repository & Workspaces](/features/multi-repo) for details on organizing repositories.

### Custom Search Scopes

Focus searches on specific parts of your codebase:

```
"Search for user models only in the backend repository"
"Find React components in the frontend folder"
"Look for migrations in the database directory"
```

### Intelligent Code Reviews

```
"Review this PR for consistency with our codebase"
"Check if this change follows our patterns"
"Find potential breaking changes"
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Keep Repos Updated" icon="rotate">
    Regularly sync repositories in CodeAlive dashboard for accurate context
  </Card>

  <Card title="Use Specific Queries" icon="magnifying-glass">
    Be precise with technical terms for better search results
  </Card>

  <Card title="Leverage Context" icon="brain">
    Reference CodeAlive when working with large codebases
  </Card>

  <Card title="Iterate Quickly" icon="forward">
    Use CodeAlive to validate ideas before implementing
  </Card>
</CardGroup>

## Productivity Tips

<AccordionGroup>
  <Accordion title="Quick Commands">
    Use slash commands for common operations:

    * `/search` - Quick code search
    * `/explain` - Get explanations with context
    * `/similar` - Find similar implementations
    * `/repos` - List available repositories
  </Accordion>

  <Accordion title="Context Management">
    * Clear context between unrelated tasks
    * Use CodeAlive to establish context for new features
    * Reference specific files when needed
  </Accordion>

  <Accordion title="Code Generation">
    * Always search for existing patterns first
    * Let Claude Code match your coding style
    * Verify generated code against your conventions
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="CodeAlive not responding">
    **Solutions:**

    1. Check MCP server status in Claude Code
    2. Verify API key is correct and active
    3. Ensure repositories are indexed
    4. Try reloading Claude Code
  </Accordion>

  <Accordion title="No repositories found">
    **Solutions:**

    1. Log into CodeAlive dashboard
    2. Verify repositories are indexed
    3. Wait for indexing to complete
    4. Check API key permissions
  </Accordion>

  <Accordion title="Slow responses">
    **Solutions:**

    1. Use more specific search queries
    2. Limit search to specific repositories
    3. Check CodeAlive service status
    4. Consider upgrading your plan
  </Accordion>

  <Accordion title="Authentication errors">
    **Solutions:**

    1. Regenerate API key in dashboard
    2. Update MCP configuration
    3. Ensure Bearer token format is correct
    4. Test API key with curl
  </Accordion>

  <Accordion title="WSL: docker or npx not found">
    **Solutions:**

    1. Use **Remote HTTP** instead — it avoids all WSL path issues
    2. Enable Docker Desktop WSL integration for your distro (Settings → Resources → WSL integration)
    3. Use absolute binary paths (e.g., `/usr/bin/docker`, `/home/user/.nvm/versions/node/v20/bin/npx`)
    4. Add missing env vars explicitly in the MCP config `env` block — non-interactive WSL shells don't source `.bashrc`
  </Accordion>

  <Accordion title="WSL2: Connection refused to self-hosted server">
    **Solutions:**

    1. WSL2 uses NAT networking — `localhost` in WSL2 differs from Windows `localhost`
    2. Enable mirrored networking in `%USERPROFILE%\.wslconfig` (see Windows & WSL section above)
    3. Or use the WSL2 VM IP: run `hostname -I` inside WSL
  </Accordion>
</AccordionGroup>

<Tip>
  For more solutions, see the [Troubleshooting Guide](/troubleshooting).
</Tip>

## Integration with Claude Code Features

### Projects

* CodeAlive automatically understands your project structure
* Provides context across multiple files and folders
* Maintains awareness of dependencies and imports

### Custom Instructions

Claude Code reads `CLAUDE.md` from the repo root (and `~/.claude/CLAUDE.md` globally) on every run; it also picks up a repo-root `AGENTS.md`. Add a CodeAlive section with explicit routing rules — naming the built-in tools you are overriding is what makes the instruction stick:

```markdown title="CLAUDE.md — CodeAlive section" theme={null}
## CodeAlive context engine

CodeAlive MCP tools search server-side indexes of all our repositories —
cross-repo, always in sync with the default branch.

- For exploration questions — "how does X work", "where is Y implemented",
  "what calls Z" — use CodeAlive `semantic_search` FIRST. Do NOT use the
  built-in Grep/Glob for these questions unless CodeAlive has returned
  nothing useful twice.
- Phrase `semantic_search` as a full English sentence, never bare keywords.
  Keep exact identifiers verbatim.
- Use CodeAlive `grep_search` for exact symbol names, literals, error
  messages, config keys, and acronyms — pass the literal text, not a question.
- Read returned artifact identifiers with `fetch_artifacts`; map callers and
  callees with `get_artifact_relationships` before claiming how code flows.
- Built-in Grep/Glob/Read remain correct for files you are actively editing
  in the working tree.
```

Two refinements once the basics work:

* **Isolate heavy exploration in a subagent.** Search-heavy CodeAlive sessions fill the main context with tool output. A dedicated subagent (`.claude/agents/`) that owns CodeAlive exploration and returns only conclusions keeps the main conversation clean — this is exactly what the [Claude Code Plugin](/integrations/plugin-claude-code) ships out of the box.
* **Keep the section short.** `CLAUDE.md` is injected into every request; 10–15 lines is the sweet spot. General patterns and rationale live in [Instructing Coding Agents](/guides/instructing-agents).

### Code Review Mode

When reviewing code:

```
"Use CodeAlive to check if this follows our patterns"
"Find similar code that might need the same fix"
"Identify all places affected by this change"
```

## Related Resources

<CardGroup cols={2}>
  <Card title="Instructing Coding Agents" icon="chalkboard-user" href="/guides/instructing-agents">
    Patterns that make agents prefer CodeAlive tools
  </Card>

  <Card title="MCP Protocol" icon="plug" href="/integrations/mcp">
    Learn about Model Context Protocol
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/toolapi/list-visible-data-sources">
    Direct API integration guide
  </Card>

  <Card title="Dashboard" icon="gauge" href="https://app.codealive.ai">
    Manage your repositories
  </Card>

  <Card title="Support" icon="life-ring" href="mailto:support@codealive.ai">
    Get help from our team
  </Card>
</CardGroup>

## Instruct Your Agent

Connecting CodeAlive makes its tools available, but the agent may still default to its built-in search. For reliable results, add a short instruction in the agent's native format telling it to prefer `semantic_search` and `grep_search` when exploring indexed code. See [Instructing Coding Agents](https://docs.codealive.ai/guides/instructing-agents).