Installation

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

Run the Installer

macOS / Linux
Windows (PowerShell)

npx @codealive/installer

irm https://raw.githubusercontent.com/CodeAlive-AI/codealive-installer/main/install.ps1 | iex

Or if you already have Node.js:

npx @codealive/installer

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

Authenticate

Enter your CodeAlive API key when prompted. Get one at app.codealive.ai.The key is stored securely in your OS credential store — you only need to enter it once.

Restart Your Agents

Restart your AI coding agents to pick up the new configuration. The installer will tell you which agents were configured.

Installation Methods

Interactive (Default)
CI Mode
Programmatic

The default wizard walks you through component selection and agent detection:

npx @codealive/installer

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

npx @codealive/installer --api-key YOUR_KEY

For automated environments, CI mode skips all prompts and installs the MCP server to all detected agents:

npx @codealive/installer --ci --api-key YOUR_KEY

Import the installer in your own TypeScript scripts:

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();

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

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

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

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

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

Installer not detecting my agent

The installer looks for known config file locations. If your agent uses a non-standard path:

Run npx @codealive/installer --debug to see which paths are checked
If your agent isn’t listed, use the manual setup guides instead

API key not saved

If the credential store fails:

Set the environment variable manually: export CODEALIVE_API_KEY="your_key"
On macOS, ensure Keychain Access is unlocked
On Linux, ensure secret-tool is installed (sudo apt install libsecret-tools)

Permission errors on Windows

Run PowerShell as Administrator, or use the Node.js method:

npx @codealive/installer

Node.js not installed

The installer requires Node.js 18+. Install it from nodejs.org or use the Windows PowerShell one-liner which doesn’t require Node.js.

Quickstart

Get started with CodeAlive in minutes

MCP Integration

Manual MCP setup for all agents

Agent Skills

Learn about skills and plugins

GitHub

Installer source code

Getting Started

Features

Model Context Protocol

Agent Skills & Plugins

Instructing Agents

Overview

Quick Start

Installation Methods

Supported Agents

What Gets Installed

API Key Storage

Command Reference

Troubleshooting

Quickstart

MCP Integration

Agent Skills

GitHub

​Overview

​Quick Start

​Installation Methods

​Supported Agents

​What Gets Installed

​API Key Storage

​Command Reference

​Troubleshooting

​Related Resources

Quickstart

MCP Integration

Agent Skills

GitHub

Overview

Quick Start

Installation Methods

Supported Agents

What Gets Installed

API Key Storage

Command Reference

Troubleshooting

Related Resources