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

# Installation

> Install CodeAlive to your AI coding agents with one command

## Overview

The CodeAlive installer automatically detects your AI coding agents and configures CodeAlive for each one. It supports three installation methods: MCP server (direct tool access), agent skill (workflow guidance), and Claude Code plugin (Claude-specific enhancements).

## Quick Start

<Steps>
  <Step title="Run the Installer">
    <Tabs>
      <Tab title="macOS / Linux">
        ```bash theme={null}
        npx @codealive/installer
        ```
      </Tab>

      <Tab title="Windows (PowerShell)">
        ```powershell theme={null}
        irm https://raw.githubusercontent.com/CodeAlive-AI/codealive-installer/main/install.ps1 | iex
        ```

        Or if you already have Node.js:

        ```powershell theme={null}
        npx @codealive/installer
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Select Components">
    The interactive wizard will ask what to install:

    | Component              | Best for                                                 | Description                                                                                                                                      |
    | ---------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
    | **MCP Server**         | Any MCP-compatible client                                | Configures the v3 Tool API set: data sources, ontology, semantic/grep search, tree/read, fetch, relationships, ArtifactQuery, and stateless chat |
    | **CodeAlive Skill**    | Cursor, Copilot, Windsurf, Gemini CLI, Codex, 30+ agents | Teaches your agent effective query patterns and workflows                                                                                        |
    | **Claude Code Plugin** | Claude Code users                                        | Includes the skill plus authentication hooks and a code exploration subagent                                                                     |
  </Step>

  <Step title="Authenticate">
    Enter your CodeAlive API key when prompted. Get one at [app.codealive.ai](https://app.codealive.ai/settings/api-keys).

    The key is stored securely in your OS credential store — you only need to enter it once.
  </Step>

  <Step title="Restart Your Agents">
    Restart your AI coding agents to pick up the new configuration. The installer will tell you which agents were configured.
  </Step>
</Steps>

## Installation Methods

<Tabs>
  <Tab title="Interactive (Default)">
    The default wizard walks you through component selection and agent detection:

    ```bash theme={null}
    npx @codealive/installer
    ```

    If you already have an API key, pass it to skip the key prompt:

    ```bash theme={null}
    npx @codealive/installer --api-key YOUR_KEY
    ```
  </Tab>

  <Tab title="CI Mode">
    For automated environments, CI mode skips all prompts and installs the MCP server to all detected agents:

    ```bash theme={null}
    npx @codealive/installer --ci --api-key YOUR_KEY
    ```
  </Tab>

  <Tab title="Programmatic">
    Import the installer in your own TypeScript scripts:

    ```typescript theme={null}
    import { runWizard, installMcp, installSkill, installPlugin } from '@codealive/installer';

    // Run the full wizard
    await runWizard({ apiKey: 'your-key' });

    // Or install individual components
    const mcpClients = await installMcp('your-key');
    const skillResult = installSkill();
    const pluginOk = await installPlugin();
    ```
  </Tab>
</Tabs>

## Supported Agents

The installer auto-detects and configures these agents:

| Agent                    | MCP Server | Skill | Plugin |
| ------------------------ | ---------- | ----- | ------ |
| Claude Code              | Yes        | Yes   | Yes    |
| Cursor                   | Yes        | Yes   | —      |
| VS Code (GitHub Copilot) | Yes        | Yes   | —      |
| Windsurf                 | Yes        | Yes   | —      |
| Cline                    | Yes        | Yes   | —      |
| Roo Code                 | Yes        | Yes   | —      |
| Zed                      | Yes        | Yes   | —      |
| OpenCode                 | Yes        | Yes   | —      |
| Codex                    | Yes        | Yes   | —      |
| Antigravity              | Yes        | Yes   | —      |

## What Gets Installed

<AccordionGroup>
  <Accordion title="MCP Server">
    Configures the CodeAlive MCP server (`https://mcp.codealive.ai/api/`) in each detected agent's config file. This gives your agent access to the v3 Tool API set:

    * **`get_data_sources`** — List indexed repositories and workspaces, optionally filtered to the current task with `query`
    * **`semantic_search`** — Default semantic search across your codebase
    * **`grep_search`** — Default exact text and regex search with line previews
    * **`get_repository_ontology`** — Orient around one repository
    * **`get_file_tree`** — Inspect repository files
    * **`read_file`** — Read one repository-relative file
    * **`fetch_artifacts`** — Fetch full source for identifiers
    * **`get_artifact_relationships`** — Expand graph relationships for one artifact
    * **`get_artifact_query_schema`** — Inspect metadata query schema
    * **`query_artifact_metadata`** — Run read-only metadata analytics
    * **`chat`** — Stateless slower synthesized codebase Q\&A, only when explicitly requested

    The installer writes the appropriate config format for each agent (JSON, TOML, YAML, or CLI command).
  </Accordion>

  <Accordion title="Agent Skill">
    Installs the CodeAlive Context Engine skill via `npx skills add`. The skill teaches your agent:

    * Effective query patterns for search and chat
    * Cost-aware tool selection (search vs. chat)
    * Multi-step exploration workflows
    * Data source management (repos and workspaces)

    Works with 30+ agents that support the [skills.sh](https://skills.sh/) standard.
  </Accordion>

  <Accordion title="Claude Code Plugin">
    Installs the Claude Code marketplace plugin, which includes:

    * The CodeAlive skill (same as above)
    * Authentication hooks for automatic API key injection
    * A code exploration subagent for guided multi-step analysis

    Install commands:

    ```
    /plugin marketplace add CodeAlive-AI/codealive-skills
    /plugin install codealive@codealive-marketplace
    ```
  </Accordion>
</AccordionGroup>

## API Key Storage

Your API key is stored securely in the 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.

## Command Reference

```
npx @codealive/installer [options]

Options:
  --api-key, -k   CodeAlive API key
  --ci            CI mode — skip prompts, install MCP to detected agents
  --debug         Enable debug logging
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Installer not detecting my agent">
    The installer looks for known config file locations. If your agent uses a non-standard path:

    1. Run `npx @codealive/installer --debug` to see which paths are checked
    2. If your agent isn't listed, use the [manual setup guides](/integrations/mcp) instead
  </Accordion>

  <Accordion title="API key not saved">
    If the credential store fails:

    1. Set the environment variable manually: `export CODEALIVE_API_KEY="your_key"`
    2. On macOS, ensure Keychain Access is unlocked
    3. On Linux, ensure `secret-tool` is installed (`sudo apt install libsecret-tools`)
  </Accordion>

  <Accordion title="Permission errors on Windows">
    Run PowerShell as Administrator, or use the Node.js method:

    ```powershell theme={null}
    npx @codealive/installer
    ```
  </Accordion>

  <Accordion title="Node.js not installed">
    The installer requires Node.js 18+. Install it from [nodejs.org](https://nodejs.org) or use the Windows PowerShell one-liner which doesn't require Node.js.
  </Accordion>
</AccordionGroup>

## Related Resources

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Get started with CodeAlive in minutes
  </Card>

  <Card title="MCP Integration" icon="plug" href="/integrations/mcp">
    Manual MCP setup for all agents
  </Card>

  <Card title="Agent Skills" icon="graduation-cap" href="/integrations/skills">
    Learn about skills and plugins
  </Card>

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