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

> Install the CodeAlive plugin for Claude Code — includes skill, subagent, and authentication hooks

## Overview

The CodeAlive plugin is the recommended way to integrate CodeAlive with Claude Code. It bundles everything into a single install:

* **Context Engine skill** — teaches Claude Code effective query patterns, cost-aware tool selection, and multi-step exploration workflows
* **Code Explorer subagent** — a lightweight Haiku-powered agent that iteratively searches your codebase and returns structured summaries, saving your main conversation context
* **Authentication hook** — automatically checks your API key on session start

<Info>
  The plugin works standalone or alongside the [MCP server](/integrations/mcp/claude-code). When used together, the MCP server provides direct tool access and the plugin teaches Claude Code how to use those tools effectively.
</Info>

## Prerequisites

* [Claude Code](https://claude.ai/code) installed
* CodeAlive account with API key ([Get one here](https://app.codealive.ai/settings/api-keys))
* Indexed repositories in your CodeAlive dashboard

## Installation

<Steps>
  <Step title="Add the Plugin Marketplace">
    In Claude Code, run:

    ```
    /plugin marketplace add CodeAlive-AI/codealive-skills
    ```
  </Step>

  <Step title="Install the Plugin">
    ```
    /plugin install codealive@codealive-marketplace
    ```
  </Step>

  <Step title="Set Up Authentication">
    Run the interactive setup to store your API key securely:

    ```bash theme={null}
    python setup.py
    ```

    This will ask for your [API key](https://app.codealive.ai/settings/api-keys), verify it, and store it in your OS credential store.

    Alternatively, set the environment variable:

    ```bash theme={null}
    export CODEALIVE_API_KEY="your_key"
    ```
  </Step>

  <Step title="Verify Installation">
    Start a new Claude Code session and ask:

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

## What's Included

### Context Engine Skill

The skill provides six tools, each optimized for different use cases:

| Tool                       | Speed   | Cost | Best For                                                           |
| -------------------------- | ------- | ---- | ------------------------------------------------------------------ |
| **List Data Sources**      | Instant | Free | Discovering indexed repos and workspaces                           |
| **Semantic Search**        | Fast    | Low  | Finding relevant artifacts by meaning                              |
| **Grep Search**            | Fast    | Low  | Exact text and regex matches with line previews                    |
| **Fetch Artifacts**        | Fast    | Low  | Retrieving full content for search results                         |
| **Artifact Relationships** | Fast    | Low  | Expanding call graph, inheritance, and references for one artifact |
| **Chat with Codebase**     | Slow    | High | Synthesized answers, architectural explanations                    |

**Cost guidance:** Search is lightweight and should be the default starting point. Chat invokes an LLM on the server side, making it more expensive — use it when you need a synthesized answer rather than raw search results.

### Code Explorer Subagent

The plugin includes a dedicated subagent (`codealive-code-explorer`) that handles iterative code exploration autonomously. When Claude Code needs to investigate a codebase question, it delegates to this subagent, which:

* Runs multiple search queries iteratively
* Refines queries based on results
* Returns a structured summary with file paths and line references
* Uses Haiku for cost efficiency

This keeps your main conversation context clean while performing deep exploration.

### Authentication Hook

On every session start, the plugin automatically checks that your CodeAlive API key is configured and valid. If the key is missing, you'll be prompted to set it up.

## API Key Storage

The API key is resolved in this order:

1. `CODEALIVE_API_KEY` environment variable
2. OS credential store:

| Platform | Store              | Manual command                                                             |
| -------- | ------------------ | -------------------------------------------------------------------------- |
| macOS    | Keychain           | `security add-generic-password -a "$USER" -s "codealive-api-key" -w "KEY"` |
| Linux    | Secret Service     | `secret-tool store --label="CodeAlive API Key" service codealive-api-key`  |
| Windows  | Credential Manager | `cmdkey /generic:codealive-api-key /user:codealive /pass:"KEY"`            |

The key is stored once and shared across all agents on the same machine.

**Self-hosted instance:** set `CODEALIVE_BASE_URL` to your deployment origin, for example `https://codealive.yourcompany.com`. `https://host/api` is also accepted and normalized automatically.

## Plugin vs MCP vs Skill

|                       | Plugin                                        | MCP Server                           | Skill (standalone)                 |
| --------------------- | --------------------------------------------- | ------------------------------------ | ---------------------------------- |
| **Install method**    | `/plugin install`                             | `claude mcp add`                     | `npx skills add`                   |
| **Claude Code only**  | Yes                                           | No (works with 15+ agents)           | No (works with 30+ agents)         |
| **Provides tools**    | Via skill scripts                             | Via MCP protocol                     | Via skill scripts                  |
| **Teaches workflows** | Yes                                           | No                                   | Yes                                |
| **Subagent**          | Yes                                           | No                                   | No                                 |
| **Auth hooks**        | Yes                                           | No                                   | No                                 |
| **Best for**          | Claude Code users wanting the full experience | Any agent needing direct tool access | Any agent needing guided workflows |

<Tip>
  For Claude Code, we recommend the **plugin** as the primary integration. Add the **MCP server** alongside it if you want direct tool access via MCP as well.
</Tip>

## Usage Examples

Once installed, just ask naturally — no special commands needed:

```
"How is authentication implemented across services?"
"Find all API endpoints in the user service"
"What error handling patterns does this codebase use?"
"Explain the payment flow architecture"
"Search for OAuth implementation in the backend"
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Plugin not found after install">
    1. Ensure you added the marketplace first: `/plugin marketplace add CodeAlive-AI/codealive-skills`
    2. Then install: `/plugin install codealive@codealive-marketplace`
    3. Restart Claude Code
  </Accordion>

  <Accordion title="API key not configured">
    Run the setup script:

    ```bash theme={null}
    python setup.py
    ```

    Or set the environment variable:

    ```bash theme={null}
    export CODEALIVE_API_KEY="your_key"
    ```
  </Accordion>

  <Accordion title="Authentication hook errors">
    If the session start hook fails:

    * Check that Python 3.8+ is available in your PATH
    * Verify the API key is valid at [app.codealive.ai](https://app.codealive.ai/settings/api-keys)
    * Try setting `CODEALIVE_API_KEY` directly as an environment variable
  </Accordion>

  <Accordion title="Subagent not triggered">
    The code explorer subagent activates when Claude Code needs iterative codebase exploration. Try asking questions that require multi-step investigation, such as "Trace the request flow from API endpoint to database."
  </Accordion>
</AccordionGroup>

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

## Related Resources

<CardGroup cols={2}>
  <Card title="MCP Integration" icon="plug" href="/integrations/mcp/claude-code">
    Add MCP server alongside the plugin
  </Card>

  <Card title="Skills & Plugins" icon="graduation-cap" href="/integrations/skills">
    Universal skill for all agents
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/CodeAlive-AI/codealive-skills">
    Plugin source code
  </Card>

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