# Fetch artifacts
Source: https://docs.codealive.ai/api-reference/toolapi/fetch-artifacts
/openapi-tool-api-v3.json post /api/tools/fetch_artifacts
Fetches full content for up to 50 known artifact identifiers (`repository::path` or `repository::path::symbol`) returned by `semantic_search`, `grep_search`, `read_file`, or `get_artifact_relationships`. This is the preferred way to read code once an identifier is known — do not split the identifier back into a repository and path for `read_file`. Responses include relationship previews (caller/callee counts) that suggest the next traversal step.
# Get artifact relationships
Source: https://docs.codealive.ai/api-reference/toolapi/get-artifact-relationships
/openapi-tool-api-v3.json post /api/tools/get_artifact_relationships
Traverses the code graph around one known artifact: callers, callees, inheritance, and references. Choose `profile` by the question: `calls_only` (default) for call edges of functions and methods, `inheritance_only` for base types and implementations, `references_only` for where-used checks on types, fields, events, and other non-call usage, `all_relevant` for calls plus inheritance. Use it to find upstream entry points and downstream consumers before reading more files.
# Get ArtifactQuery schema
Source: https://docs.codealive.ai/api-reference/toolapi/get-artifactquery-schema
/openapi-tool-api-v3.json post /api/tools/get_artifact_query_schema
Returns the ArtifactQuery v1 catalog: queryable entities, fields, operators, relationships, limits, and example statements. Call it before composing a non-trivial `query_artifact_metadata` statement, or after a validation error, to get exact field names and supported operators.
# Get repository file tree
Source: https://docs.codealive.ai/api-reference/toolapi/get-repository-file-tree
/openapi-tool-api-v3.json post /api/tools/get_file_tree
Returns a bounded directory tree for one repository, with short generated summaries for files and folders. Use it for structural orientation when you need to see how a repository (or one directory) is laid out; bound the response with `max_depth` and `max_nodes`. For concept questions prefer `semantic_search` — a folder whose name matches a concept is one candidate, not the whole story.
# Get repository ontology
Source: https://docs.codealive.ai/api-reference/toolapi/get-repository-ontology
/openapi-tool-api-v3.json post /api/tools/get_repository_ontology
Returns the generated high-level map (ontology) of one repository: its purpose, subsystems, key concepts, and how they relate. Use it to orient before focused searching when the repository is unfamiliar, or to decide which part of a large codebase a question lands in. Accepts exactly one repository — workspace names are rejected; pick a specific repository from `get_data_sources`.
# Grep search
Source: https://docs.codealive.ai/api-reference/toolapi/grep-search
/openapi-tool-api-v3.json post /api/tools/grep_search
Searches indexed code for exact literal text or a regular expression (set `regex` to `true`). First choice when you already know an exact symbol name, string literal, error message, route, or configuration key, and for exhaustive "find every usage" sweeps. It complements `semantic_search`: embeddings underrepresent rare short tokens such as acronyms (`JWT`, `OIDC`), so run `grep_search` on the exact token alongside a semantic query rather than instead of it.
# List visible data sources
Source: https://docs.codealive.ai/api-reference/toolapi/list-visible-data-sources
/openapi-tool-api-v3.json post /api/tools/get_data_sources
Lists the repositories and workspaces visible to the calling API key, including readiness state. Call this first: every other tool accepts the returned `name` values in its `data_sources`/`data_source` argument (use `id` only for automation or to disambiguate duplicate names). Pass an optional `query` to rank sources by relevance to a question; the call is billed only when relevance ranking actually runs.
# Query artifact metadata
Source: https://docs.codealive.ai/api-reference/toolapi/query-artifact-metadata
/openapi-tool-api-v3.json post /api/tools/query_artifact_metadata
Executes one bounded, read-only ArtifactQuery statement over indexed artifact metadata for repository-level analytics: language and file-type mix, lines, cognitive complexity, largest files, public API surface, relationship counts. Statements must end with LIMIT. Invalid statements are not executed and return repairable diagnostics — fix the statement per the hint (see `get_artifact_query_schema`) and retry.
# Read a repository file
Source: https://docs.codealive.ai/api-reference/toolapi/read-a-repository-file
/openapi-tool-api-v3.json post /api/tools/read_file
Reads one file by its exact repository-relative path, returning line-numbered content. This is the fallback reader: when a previous search already returned an artifact `identifier` for the file, prefer `fetch_artifacts`. Bound large files with `start_line`/`end_line`. When the path does not resolve, the response includes candidate paths with the same file name so the call can be repaired.
# Semantic search
Source: https://docs.codealive.ai/api-reference/toolapi/semantic-search
/openapi-tool-api-v3.json post /api/tools/semantic_search
Searches indexed code by meaning rather than by exact text. This is the default first tool for behaviour, intent, mechanism, and architecture questions. Phrase `question` as a full natural-language English sentence — "How does task execution work?", "Where is retry handling implemented?" — not as bare keywords; keyword strings sharply degrade recall. Keep identifiers and codebase-specific terms verbatim inside the sentence. For acronyms, exact names, error text, routes, or config keys, run `grep_search` alongside. Results carry stable artifact `identifier` values — pass them to `fetch_artifacts` to read the code, or to `get_artifact_relationships` to map callers and callees, before drawing conclusions from snippets.
# Stateless chat
Source: https://docs.codealive.ai/api-reference/toolapi/stateless-chat
/openapi-tool-api-v3.json post /api/tools/chat
Asks CodeAlive's built-in research agent a question and returns a synthesized, evidence-grounded answer. Each call is stateless: no conversation is stored, so include all relevant prior findings, artifact identifiers, constraints, and scope in `question`. This is the highest-latency, highest-cost tool — when orchestrating your own agent loop, prefer the direct search and read tools and reserve `chat` for when a delegated end-to-end answer is explicitly wanted.
# Prepare your repository
Source: https://docs.codealive.ai/code-preparation
Learn which files CodeAlive indexes and how to exclude content from repository processing.
CodeAlive works with source code, configuration, documentation, and other text-based files. Most supported file types come from [GitHub Linguist's language definitions](https://github.com/github-linguist/linguist/blob/main/lib/linguist/languages.yml), with additional support for common text and data formats such as Markdown, plain text, JSON, and CSV.
CodeAlive automatically respects your existing `.gitignore`, so you do not need to copy those rules into another file. During repository preparation, it also removes common low-value content such as vendored dependencies, minified or bundled frontend assets, source maps, and other generated static assets.
CodeAlive does not index:
* Files excluded by `.gitignore` or `.codealiveignore`
* Unsupported or binary formats, such as images, archives, PDFs, and compiled artifacts
* The `.git` directory and symbolic links
## Exclude content with `.codealiveignore`
Add a `.codealiveignore` file when tracked content is useful to your application or development workflow but would add noise to CodeAlive search. It uses the same pattern syntax as `.gitignore`.
```gitignore theme={null}
# Generated API client; keep the source OpenAPI specification indexed
src/generated/api-client/
# Recorded HTTP responses and large test fixtures
tests/fixtures/http-recordings/
tests/fixtures/datasets/
# Generated snapshots that duplicate source-level behavior
**/__snapshots__/
# Exported sample data that is not part of the implementation
examples/data/*.json
```
You can place `.codealiveignore` in the repository root or in a subdirectory. A file in a subdirectory applies to that directory and its descendants.
Use `.codealiveignore` for project-specific exclusions. Leave dependencies, build output, and other files that should not be committed at all in `.gitignore`. Commit `.codealiveignore` so the same indexing scope applies to everyone; changes take effect during the next repository processing run.
# AI Code Review
Source: https://docs.codealive.ai/features/ai-code-review
Automated intelligent code reviews for every pull request
## Overview
CodeAlive AI Code Review automatically analyzes your pull requests, providing comprehensive feedback on code quality, security, performance, and best practices. Get instant, consistent reviews that help your team ship better code faster.
## Key Features
Reviews trigger automatically on PR creation and updates
Support for 19+ programming languages
Configure review agents for specific concerns
Maintain coding standards across your organization
## Getting Started
Choose your version control platform:
Navigate to **Providers → GitHub** in your CodeAlive dashboard
Navigate to **Providers → GitLab** in your CodeAlive dashboard
Set up your review preferences in the PR Reviews section
CodeAlive will automatically review new PRs and updates
## GitHub Integration
### Installing the GitHub App
Navigate to **Providers → GitHub** in your CodeAlive dashboard
![GitHub Integration Settings]()
1. Click **"Install GitHub App"**
2. You'll be redirected to GitHub
3. Select your organization or personal account
4. Choose repository access:
* **All repositories** - Recommended for organization-wide coverage
* **Selected repositories** - Choose specific repositories
1. Review the requested permissions
2. Click **"Install & Authorize"**
3. You'll be redirected back to CodeAlive
4. The status will show **"GitHub App Successfully Installed"**
Once connected:
* Click **"Import Repositories"** to add repos for indexing
* Select the repositories you want to review
* Wait for initial indexing to complete
## GitLab Integration
### Setting Up GitLab Access
In GitLab:
1. Go to **User Settings → Access Tokens**
2. Create a new token:
* **Name**: CodeAlive
* **Expiration**: Set as needed
* **Scopes**: Select `api` and `read_repository`
3. Copy the generated token
1. Navigate to **Providers → GitLab** in CodeAlive
2. Paste your Personal Access Token
3. Click **"Token Set"**
![GitLab Integration Settings]()
Configure GitLab webhooks for automatic reviews:
1. Copy the webhook URL from CodeAlive
2. In your GitLab project:
* Go to **Settings → Webhooks**
* Add the CodeAlive webhook URL
* Select triggers:
* Merge request events
* Comments
3. Click **"Secret Configured"** in CodeAlive
* Click **"Import Repositories"**
* Select GitLab projects to analyze
* Complete the setup
## Review Configuration
### Customizing Review Behavior
Access review settings by clicking **"Repository Review Configuration"** in the PR Reviews section.
![Review Configuration Settings]()
### Quick Settings
Control the detail level of reviews:
* **Minimal (1)**: Critical issues only
* **Basic (2)**: Important problems
* **Balanced (3)**: Comprehensive review (recommended)
* **Detailed (4)**: Include minor issues
* **Thorough (5)**: Every possible improvement
Choose the language for review comments:
* English (default)
* Spanish
* French
* German
* Japanese
* Chinese
* And many more...
This setting controls the language of the review feedback, not the programming languages supported.
Choose the tone of feedback:
* **Professional**: Formal, technical feedback
* **Friendly**: Approachable and encouraging
* **Constructive**: Balanced with suggestions
* **Direct**: Straight to the point
### Focus Areas
Enable or disable specific review agents:
Reviews code for potential security vulnerabilities, authentication issues, and data exposure risks
Analyzes code efficiency, identifies bottlenecks, and suggests optimizations
Evaluates code structure, design patterns, and architectural decisions
Checks for coding standards, naming conventions, and style consistency
Reviews overall code quality, maintainability, and best practices
Validates pull requests against linked Jira tasks to ensure requirements are met
### General Instructions
Add custom guidelines that apply to all review agents. This is useful for:
* Team-specific conventions
* Project requirements
* Domain-specific rules
* Compliance standards
Example:
```
- Follow our team's error handling patterns
- Ensure all API endpoints have proper authentication
- Use TypeScript strict mode conventions
- Include unit tests for new functions
```
## Managing Reviews
### PR Reviews Dashboard
The PR Reviews page shows all pull requests across your repositories:
![PR Reviews Dashboard]()
Features:
* **Repository selector**: Filter by repository
* **Import PRs**: Manually import pull requests
* **Auto-refresh**: Keep the list updated
* **Automatic Review**: Toggle automatic reviews on/off
### Review States
Pull requests can have the following states:
* **Review Scheduled**: Queued for review
* **Review Completed**: Review finished successfully
* **Re-analyze**: Request a fresh review
### Triggering Reviews
Reviews can be triggered in multiple ways:
Reviews trigger automatically when:
* A new PR is created
* Commits are pushed to an open PR
* PR is updated or edited
1. Go to PR Reviews page
2. Find your pull request
3. Click **"Re-analyze"**
Add a comment to your PR:
```
/codealive review
```
## Best Practices
Begin with balanced settings (level 3) and adjust based on team feedback
Enable focus areas one at a time to understand their impact
Descriptive PR titles help AI understand context better
Review and refine settings based on team needs
Use general instructions for team-specific rules
Track which suggestions are most valuable
## Troubleshooting
**Check:**
* Automatic Review toggle is enabled
* Repository is properly indexed
* Webhooks are configured (GitLab)
* GitHub App has proper permissions
**Normal duration**: 2-5 minutes depending on PR size
**If longer:**
* Check repository indexing status
* Verify API limits aren't exceeded
* Contact support if persistent
**Verify:**
* All files in PR are in supported languages
* PR isn't too large (>1000 files)
* Repository is fully indexed
* Review configuration is saved
**Steps:**
1. Verify webhook URL is correct
2. Check webhook test in GitLab settings
3. Ensure merge request events are selected
4. Confirm secret token matches
## Related Resources
* [Semantic Code Search](/features/semantic-search)
* [Codebase Chat](/features/codebase-chat)
* [Multi-Repository & Workspaces](/features/multi-repo)
* [API Reference](/api-reference/toolapi/list-visible-data-sources)
* [Getting Started](/quickstart)
* [MCP Integrations](/integrations/mcp)
# Codebase Chat
Source: https://docs.codealive.ai/features/codebase-chat
Have AI-powered conversations with deep understanding of your code
## Overview
Codebase Chat is an AI consultant that knows your entire codebase. Unlike semantic search which returns file locations and snippets, Codebase Chat provides synthesized, ready-to-use answers — architecture explanations, debugging analysis, implementation guidance, and code reviews grounded in your actual code.
This is powered by CodeAlive's GraphRAG approach: the AI has access to the full knowledge graph of your codebase, not just individual files.
## How It Works
Ask any question about your codebase in natural language. The AI retrieves relevant context from the knowledge graph before generating a response.
The response combines information from across your codebase — referencing multiple files, tracing data flows, and explaining architectural patterns.
Ask another self-contained question that includes the findings and constraints the next answer needs.
## Example Conversations
```
You: "Explain how the authentication system works in this project"
AI: The authentication system uses a JWT-based flow with three main components:
1. AuthController (src/controllers/auth.ts) handles login/signup endpoints
2. JwtService (src/services/jwt.ts) manages token generation and validation
3. AuthMiddleware (src/middleware/auth.ts) protects routes...
[continues with specific code references]
```
```
You: "Why might payments be failing intermittently?"
AI: Based on the payment processing code, there are several potential causes:
1. Race condition in PaymentProcessor.process() (src/services/payment.ts:142)
- The lock acquisition doesn't cover the full transaction...
2. Timeout configuration mismatch between the gateway client and...
[continues with specific code analysis]
```
```
You: "How should I add rate limiting to the API?"
AI: Based on your existing middleware pattern in src/middleware/:
1. Create a new RateLimitMiddleware following the pattern in AuthMiddleware
2. The existing Redis connection in src/config/redis.ts can be reused...
3. Your API routes in src/routes/index.ts use the middleware chain pattern...
[continues with implementation guidance matching your codebase patterns]
```
```
You: "Review the error handling in the user service"
AI: The UserService has inconsistent error handling:
1. createUser() (line 45) catches all errors but only logs generic messages
2. updateUser() (line 89) correctly throws typed errors
3. deleteUser() (line 112) has no error handling at all...
[continues with specific recommendations]
```
## Access Methods
The `chat` tool is available through any CodeAlive-connected agent:
| Parameter | Required | Description |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------- |
| `question` | Yes | Your question about the codebase |
| `data_sources` | Yes | Repository or workspace names |
| Your AI agent may call this tool for synthesized analysis after search. For the highest reliability and depth, prefer `semantic_search` and `grep_search` first. | | |
Chat directly via the CodeAlive API:
```bash theme={null}
curl -X POST https://app.codealive.ai/api/tools/chat \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"question": "Explain the authentication flow",
"data_sources": ["my-backend"]
}'
```
See the [API reference](/api-reference/toolapi/stateless-chat) for the request and response schemas.
If you have the [CodeAlive skill](/integrations/skills) installed:
```bash theme={null}
python scripts/chat.py "Explain the authentication flow" my-backend
```
## Stateless requests
Tool API chat does not retain conversation state. Include prior findings, artifact identifiers, assumptions, scope, and constraints in every `question`. This keeps each request reproducible across agents and integrations.
## Best Practices
Use `semantic_search` and `grep_search` for locating code. Use `chat` when you need explanations or analysis — it's more expensive per call and can take up to 30 seconds.
Make every question self-contained by including the relevant findings and constraints
"Explain the payment retry logic" gets better results than "tell me about payments"
Target specific repositories for more focused, accurate answers
## Related Resources
Fast code search for finding file locations and snippets
Chat across multiple repositories and workspaces
Connect chat to your AI assistant
Tool API chat endpoint documentation
# Multi-Repository & Workspaces
Source: https://docs.codealive.ai/features/multi-repo
Search and analyze across multiple repositories and workspaces
## Overview
CodeAlive lets you search and analyze code across multiple repositories simultaneously. Group related repos into workspaces — for example, all backend services, or your entire platform — and query them as a single unit.
This is essential for microservices architectures, monorepo setups, and organizations with code spread across many repositories.
## Setting Up
In the [CodeAlive dashboard](https://app.codealive.ai):
1. Navigate to **Providers**
2. Connect your GitHub, GitLab, or Bitbucket account
3. Authorize CodeAlive to access your repositories
1. Go to **Data Sources**
2. Click **Import Repositories**
3. Select the repositories you want to index
4. Wait for initial indexing (5-15 minutes per repository)
Group related repositories into workspaces:
1. Go to **Workspaces** in the dashboard
2. Click **Create Workspace**
3. Give it a name (e.g., "backend-services", "platform-team")
4. Add repositories to the workspace
## Workspaces
Workspaces let you group repositories and query them together. This is useful when:
* Your backend is split across multiple services
* You want to search across a team's repositories
* You need to trace data flows between services
### Querying Workspaces
Use the `workspace:` prefix to search across all repos in a workspace:
```bash theme={null}
# Search across all backend services
python scripts/search.py "error handling patterns" workspace:backend-team
# Chat about the whole platform
python scripts/chat.py "How do services communicate?" workspace:platform
```
### Querying Individual Repositories
Target specific repositories by name:
```bash theme={null}
# Search one repo
python scripts/search.py "JWT validation" auth-service
# Search multiple repos
python scripts/search.py "user model" auth-service user-service billing-service
```
## Cross-Repository Search
When searching across repositories, CodeAlive understands relationships between services:
```
"How does the auth service communicate with the user service?"
"Find all API contracts between frontend and backend"
"Show me shared database models across services"
"Trace the order flow from API to payment to notification"
```
## Data Sources
The `get_data_sources` tool lists all available repositories and workspaces:
| Type | Description | Example |
| -------------- | --------------------- | ------------------------ |
| **Repository** | Single codebase | `my-backend-api` |
| **Workspace** | Group of repositories | `workspace:backend-team` |
Use `get_data_sources` to discover what's available before searching:
```bash theme={null}
python scripts/datasources.py # Ready-to-use sources
python scripts/datasources.py --all # All (including processing)
python scripts/datasources.py --query "add OAuth to checkout" # Only sources relevant to a task
```
With many repositories indexed, pass your task as `query` (MCP) or `--query` (skill scripts). An AI
relevance filter returns only the matching sources, each with a `relevanceReason`, so the agent
starts from a focused shortlist instead of the full inventory.
## Best Practices
Create workspaces per team or domain (backend, frontend, infrastructure)
Regularly sync repositories in the dashboard for accurate cross-repo analysis
Use specific repos for targeted queries, workspaces for cross-cutting concerns
Use descriptive workspace names that match your team's vocabulary
## Related Resources
Search across repos by meaning and intent
Ask questions across your entire codebase
Connect multi-repo to your AI assistant
Manage repositories and workspaces
# Semantic Code Search
Source: https://docs.codealive.ai/features/semantic-search
Find code by meaning and intent across your entire codebase
## Overview
CodeAlive's semantic code search goes beyond keyword matching — it understands the meaning and intent behind your queries. Ask for "authentication flow" and find JWT validation, OAuth callbacks, and session management code, even if none of those files contain the word "authentication."
This is powered by CodeAlive's GraphRAG indexing, which maps relationships between code components, dependencies, and architectural patterns across your entire codebase.
## How It Works
CodeAlive indexes your repositories, building a knowledge graph of code relationships, function signatures, data flows, and architectural patterns.
You ask a natural-language question. CodeAlive translates it into a semantic search across the knowledge graph, finding code that matches by meaning — not just text.
You get file paths, line numbers, and code snippets ranked by relevance. Your AI agent can then read the actual files for full context.
## Choose a search tool
Use `semantic_search` when you know the behavior or concept but not the exact identifier.
```
"Find authentication-related code"
"Show me error handling patterns in the payment service"
```
Use `grep_search` when you know the exact function name, class, string, or regular expression.
```
"Find JwtTokenValidator class"
"Locate handlePaymentWebhook function"
```
## Example Queries
* "How is JWT token validation implemented?"
* "Find OAuth callback handlers"
* "Show me all authorization middleware"
* "Where are API keys validated?"
* "How does the system handle database connection failures?"
* "Find retry logic across services"
* "Show me error boundary implementations"
* "Where are 500 errors caught and reported?"
* "Find all event-driven communication between services"
* "Show me the repository pattern implementations"
* "How is dependency injection configured?"
* "Find all middleware in the request pipeline"
* "List all REST API endpoints"
* "Find database migration files"
* "Show me GraphQL resolver implementations"
* "Where is caching implemented?"
## Access Methods
The `semantic_search` tool is available through any CodeAlive-connected agent:
| Parameter | Required | Description |
| -------------- | -------- | ----------------------------------------------- |
| `question` | Yes | Natural-language search question |
| `data_sources` | Yes | Repository or workspace names to search |
| `paths` | No | Optional repo-relative path scopes |
| `extensions` | No | Optional file extensions such as `.py` or `.ts` |
| `max_results` | No | Optional result cap |
Your AI agent calls this tool automatically when you ask questions about your codebase.
Search directly via the CodeAlive API:
```bash theme={null}
curl -X POST https://app.codealive.ai/api/tools/semantic_search \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"question": "authentication flow",
"data_sources": ["my-backend"]
}'
```
See the [API reference](/api-reference/toolapi/semantic-search) for the request and response schemas.
If you have the [CodeAlive skill](/integrations/skills) installed:
```bash theme={null}
python scripts/search.py "JWT token validation" my-backend
python scripts/search.py "error handling patterns" workspace:platform-team
```
## Best Practices
Use domain-specific terms: "JWT validation" is better than "security check"
Use semantic search for concepts and grep search for exact text or regular expressions
Target specific repositories or workspaces to get more relevant results
Refine your query based on initial results — each search is fast and cheap
## Related Resources
Get synthesized answers instead of raw search results
Search across multiple repositories and workspaces
Connect search to your AI assistant
Semantic search endpoint documentation
# CodeAlive & 1С
Source: https://docs.codealive.ai/guides/1c-agents
Особенности инструктирования кодовых агентов для проектов 1С:Предприятие (BSL): дихотомия «метаданных», формулировка запросов, готовое правило
Эта страница написана по-русски: аудитория разработки на 1С:Предприятие русскоязычная, а ключевая проблема страницы — терминологическая — существует именно в русских формулировках. Остальная документация CodeAlive — на английском.
Функция специализированной индексации метаданных 1С сейчас находится в работе. Чтобы записаться в лист ожидания, напишите на [support@codealive.ai](mailto:support@codealive.ai). До запуска этой функции XML-описания объектов можно исследовать как обычные файлы с помощью `grep_search` и `read_file`.
## Для кого эта страница
Вы разрабатываете на 1С:Предприятие 8 (язык BSL), храните выгрузку конфигурации или расширения в git-репозитории (1C:EDT-проект либо выгрузка из Конфигуратора) и подключили этот репозиторий к CodeAlive. Настройка агентов (Claude Code, Cursor, Codex) — та же, что описана на [страницах интеграций](/integrations/mcp); здесь — только 1С-специфика, которую нужно добавить поверх.
## Главное: два разных значения слова «метаданные»
В 1С и в CodeAlive термин «метаданные» (metadata) означает **разные вещи**, и агент, работающий с 1С-проектом, обязан это различать — иначе он будет вызывать не тот инструмент.
| | «Метаданные» в 1С | Artifact metadata в CodeAlive |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Что это | Объекты конфигурации: справочники, документы, регистры (сведений, накопления, бухгалтерии, расчёта), планы видов характеристик, перечисления, общие модули, формы, роли | Технические характеристики проиндексированного кода: язык, размер, число строк, когнитивная сложность функций, связи вызовов |
| Где живёт | Структура конфигурации; в репозитории — XML-описания объектов | Индекс CodeAlive, построенный по файлам репозитория |
| Каким инструментом исследовать | `semantic_search` / `grep_search` / `read_file` по XML- и BSL-файлам выгрузки | `query_artifact_metadata` (+ `get_artifact_query_schema`) |
Инструмент CodeAlive `query_artifact_metadata` **не возвращает метаданные конфигурации 1С**. Запрос агента «покажи метаданные документа РеализацияТоваровУслуг» должен превращаться в поиск по XML-описанию объекта (`grep_search` / `read_file`), а не в вызов `query_artifact_metadata`. Обратное тоже верно: вопрос «какие самые сложные функции в проекте?» — это как раз `query_artifact_metadata`.
## Как формулировать запросы для 1С-кода
Правила те же, что и для любого языка, плюс одна особенность: идентификаторы в 1С русские.
* **`semantic_search`** — вопрос формулируется полным предложением **на английском** (так работает векторный поиск CodeAlive), но имена процедур, справочников, документов и регистров остаются **по-русски вербатим**:
```text theme={null}
How is document posting implemented in ДокументыСервер common module?
Where are записи в регистр накопления ТоварыНаСкладах created?
```
* **`grep_search`** — точные русские литералы и имена как есть: имена процедур (`ПровестиДокумент`), тексты сообщений об ошибках, имена событий, куски запросов на языке запросов 1С (`ВЫБРАТЬ`, `ИЗ РегистрНакопления`).
* **XML-описания объектов** — тоже проиндексированы: `grep_search` по имени объекта (`РеализацияТоваровУслуг`) находит и его XML-описание (реквизиты, табличные части), и все использования в BSL-модулях.
## Готовое правило для агента
Блок ниже добавляется к универсальному правилу CodeAlive из [Instructing Coding Agents](/guides/instructing-agents) — в `CLAUDE.md`, `AGENTS.md` или `.cursor/rules/codealive.mdc`. Он написан по-английски, потому что системные инструкции агентов работают надёжнее на английском; русские термины оставлены вербатим.
```markdown title="AGENTS.md / CLAUDE.md — секция для 1С-проекта" theme={null}
## 1C:Enterprise (BSL) specifics
This repository is a 1C:Enterprise configuration dump (BSL modules + XML
object descriptions).
- The word "метаданные"/"metadata" is ambiguous here. In 1C it means
configuration objects: справочники (catalogs), документы (documents),
регистры (registers), перечисления (enums), общие модули (common modules),
forms, roles. CodeAlive's `query_artifact_metadata` tool does NOT return
those — it returns code metrics (lines, complexity, languages).
- "Show metadata of документ X" → search the object's XML description with
CodeAlive `grep_search` / `read_file`, NOT `query_artifact_metadata`.
- "Which functions are the most complex?" → that IS `query_artifact_metadata`.
- `semantic_search` questions are full English sentences, but keep Russian
identifiers verbatim: procedure names (ПровестиДокумент), catalog and
register names (ТоварыНаСкладах), module names (ДокументыСервер).
- Use `grep_search` for exact Russian literals: procedure names, error
message texts, 1C query language fragments (ВЫБРАТЬ, ИЗ РегистрНакопления).
- Object XML descriptions are indexed too: to understand an object's
structure (реквизиты, табличные части, измерения, ресурсы), grep its name
and read the XML before reading module code.
```
## Совместимость с ai\_rules\_1c
Если вы используете [comol/ai\_rules\_1c](https://github.com/comol/ai_rules_1c) — переносимый набор правил и субагентов для vibecoding в 1С (Cursor, Claude Code, Codex, OpenCode, Kilo Code) — CodeAlive дополняет его, а не конкурирует с ним:
* `ai_rules_1c` задаёт дисциплину разработки (стандарты кода, формы, СКД, регистры, расширения) и MCP-first-поиск через специализированные 1С-инструменты; CodeAlive добавляет кросс-репозиторный семантический поиск и граф вызовов по проиндексированной выгрузке.
* Правило CodeAlive из этой страницы кладите в `USER-RULES.md` (файл пользовательских правил, который установщик `ai_rules_1c` не перезаписывает), а не в генерируемый им `AGENTS.md`.
* В их правиле `mcp-first-search.md` описана цепочка приоритетов поиска с fallback на `Grep` — при совместном использовании включите CodeAlive `semantic_search`/`grep_search` в эту цепочку до fallback-шага.
## Связанные страницы
Универсальное правило CodeAlive, к которому добавляется 1С-секция
Подключение CodeAlive к агентам и список инструментов
Настройка Cursor и обход встроенного codebase\_search
Настройка Claude Code и CLAUDE.md
# Build a Code Research Agent
Source: https://docs.codealive.ai/guides/build-code-research-agent
Reference architecture and an example system prompt for building your own agent on top of the CodeAlive Tool API
## Overview
CodeAlive's own chat is powered by an internal research agent that runs an LLM loop over the same tools exposed publicly as the [Tool API](/api-reference/toolapi/list-visible-data-sources) and the [MCP server](/integrations/mcp). This guide shows how to build a similar agent yourself: which tools to give it, how to instruct it, and what a complete research loop looks like.
The system prompt below is an adapted, self-contained version of the strategy CodeAlive uses in production. Copy it as a starting point and tune it for your stack.
Looking for more patterns and practical ideas for building AI agents? Explore
the [CodeAlive blog](https://codealive.ai/en/blog).
## Architecture
A code research agent is a loop:
1. The user asks a question about a codebase.
2. The LLM decides which tool to call and with what arguments.
3. Your runtime executes the call against the CodeAlive Tool API (or through MCP) and appends the result to the conversation.
4. Steps 2–3 repeat until the LLM has enough evidence, then it writes the final answer.
Every Tool API operation is read-only and returns the same envelope: `obj` (structured JSON) and `rendered` (agent-friendly text). For an agent loop, request `output_format: "agentic"` and feed `rendered` straight into the model — it is compact and already carries follow-up hints.
```bash theme={null}
curl -X POST https://app.codealive.ai/api/tools/semantic_search \
-H "Authorization: Bearer YOUR_API_KEY_HERE" \
-H "Content-Type: application/json" \
-d '{
"question": "How does task execution work?",
"data_sources": ["agent-framework"],
"output_format": "agentic"
}'
```
## Which tools to give the agent
Expose all eleven tools; each covers a distinct move in the research loop:
| Tool | Role in the loop |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_data_sources` | Discover repository and workspace names. Call once at session start. |
| `get_repository_ontology` | Orient: high-level map of one repository before focused search. |
| `get_file_tree` | Orient: bounded directory structure with summaries. |
| `semantic_search` | Locate by meaning: default first tool for behaviour and architecture questions. |
| `grep_search` | Locate by text: exact names, literals, error strings, acronyms, exhaustive sweeps. |
| `fetch_artifacts` | Read: preferred reader for known artifact identifiers. |
| `get_artifact_relationships` | Traverse: callers, callees, inheritance, references of a known artifact. |
| `read_file` | Read: fallback for exact paths without an artifact identifier; bound with `start_line`/`end_line`. |
| `get_artifact_query_schema` | Analytics: the ArtifactQuery DSL catalog. |
| `query_artifact_metadata` | Analytics: repository-level metrics (languages, lines, complexity, public API surface). |
| `chat` | Delegate: a full end-to-end answer from CodeAlive's own agent. Use sparingly — it is the most expensive tool, and you are already running your own loop. |
The generated [API Reference](/api-reference/toolapi/list-visible-data-sources) documents parameters, request examples, and response shapes for each tool.
## Example system prompt
This prompt distills the search strategy CodeAlive's production agent uses. It assumes the eleven tools above are bound with their canonical names.
```markdown title="system-prompt.md" theme={null}
You are a code research assistant. You answer questions about the user's
codebases by calling CodeAlive tools to gather evidence, then answering the way
a senior developer would.
## Tool strategy
Iterate: orient → locate → traverse → read. Combine tools; do not try to solve
everything in one call.
1. Call `get_data_sources` once to learn which repositories are available. Use
the returned `name` values in every `data_sources` / `data_source` argument.
2. For an unfamiliar repository, orient first: `get_repository_ontology` (one
repository per call) or a bounded `get_file_tree`.
3. Locate code with the search tool that matches the query shape:
- Concept, behaviour, mechanism, or architecture question → `semantic_search`.
- Exact symbol name, string literal, error text, route, config key, or an
"all usages" sweep → `grep_search`.
4. Traverse from a found artifact with `get_artifact_relationships`: callers and
callees (`calls_only`), base types and implementations (`inheritance_only`),
or where-used (`references_only`).
5. Read code with `fetch_artifacts` for every identifier you rely on. Use
`read_file` only for exact paths that no tool has returned an identifier
for, and bound it with `start_line`/`end_line`.
## Query phrasing rules
- Phrase `semantic_search` questions as full natural-language English sentences:
"How does request deduplication work?", "Where is retry handling implemented?"
Never pass bare keywords ("auth", "payment processing") — keyword strings
sharply degrade recall. Keep user-named identifiers and codebase terms
verbatim inside the sentence.
- Acronyms and rare short tokens (JWT, OIDC, OTel) are underrepresented in
embeddings: when the user names one, run `grep_search` on the exact token in
addition to `semantic_search`, not instead of it.
- For multi-faceted questions, issue several `semantic_search` calls with
distinct angles (entry point, transport, storage, consumers) rather than one
bundled query.
## Evidence rules
- Code is the source of truth. Treat READMEs and docs as orientation, not proof
of current behaviour; verify doc claims in implementation, config, or tests
before stating them as fact.
- Never make factual claims from search-result snippets alone — fetch and read
the artifact first.
- For "how does X work?" questions, verify the full flow before answering:
the upstream entry point (HTTP route, job, event handler), the mechanism
core, and the storage or side effect. An internal helper is the mechanism
core, not the whole flow — find who calls it.
- Empty or weak results mean the query was too narrow, not that the answer
does not exist. Try at least two distinct strategies (synonyms, a different
abstraction level, the other search tool) before saying "not found".
- Stop searching when the evidence is sufficient. Do not run speculative
extra searches once the entry point and mechanism core are verified.
## Answering
- Support key conclusions with short exact code snippets, plus file path and
symbol name.
- State assumptions explicitly. If two interpretations of the question lead to
materially different answers and no tool call can discriminate, ask one
focused clarifying question with concrete options instead of guessing.
- If evidence is incomplete after several attempts, say what you searched for
and what remains unverified.
```
The production prompt additionally handles multi-turn conversation state, workspace-scale scoping (up to \~1,000 repositories per workspace), and structured research-completion checkpoints. Those concerns are specific to CodeAlive's harness — start with the version above and add orchestration rules as your agent grows.
## Worked example
A typical run for *"How does task execution work in agent-framework?"*:
```json theme={null}
POST /api/tools/get_data_sources
{ "query": "task execution framework" }
```
The response lists `agent-framework` as a ready repository — its `name` goes into every following call.
```json theme={null}
POST /api/tools/semantic_search
{
"question": "How does task execution work, from scheduling to completion?",
"data_sources": ["agent-framework"]
}
```
Top hit: `CodeAlive-AI/agent-framework::src/executor.py::TaskExecutor.run` — a method artifact with a relevance score and a one-line description.
```json theme={null}
POST /api/tools/fetch_artifacts
{ "identifiers": ["CodeAlive-AI/agent-framework::src/executor.py::TaskExecutor.run"] }
```
The artifact content shows retry and telemetry wrappers — this is the mechanism core, but not the entry point.
```json theme={null}
POST /api/tools/get_artifact_relationships
{
"identifier": "CodeAlive-AI/agent-framework::src/executor.py::TaskExecutor.run",
"profile": "calls_only"
}
```
Incoming calls reveal `Scheduler.tick` in `src/scheduler.py` — the upstream trigger that drains the queue.
The agent now has the full flow — entry point (`Scheduler.tick`), mechanism core (`TaskExecutor.run`), and side effects — and answers with file paths and short snippets.
## Practical notes
* **Rate of tool calls.** Search tools are billed per call (see `x-codealive-billing` in the OpenAPI spec); read and traversal tools (`fetch_artifacts`, `get_artifact_relationships`, `read_file`, `get_file_tree`) are not. Structure the loop to search once and read many.
* **Repairable errors.** Invalid arguments come back as HTTP 200 with `obj.error = { code, message, retry, try }` and a rendered `` block. Feed the error to the model — the `try` hint is written so an LLM can repair the call and retry.
* **Stateless `chat`.** If you do expose `chat`, remember every call is independent: prior findings and identifiers must be repeated inside `question`.
## Related resources
Parameters and response examples for every tool
Make off-the-shelf agents prefer CodeAlive tools
Use the same tools through MCP instead of raw HTTP
How CodeAlive's search works under the hood
# Instructing Coding Agents
Source: https://docs.codealive.ai/guides/instructing-agents
How to make Claude Code, Cursor, and Codex actually use CodeAlive tools instead of their built-in search
## Why instructions matter
Connecting the [CodeAlive MCP server](/integrations/mcp) gives an agent new tools — it does not change the agent's habits. Coding agents ship with built-in exploration tools (Cursor's `codebase_search`, Claude Code's `Grep`/`Glob`, Codex's shell search), and their planners reach for those first. Without an explicit instruction, an agent will happily run local grep over one checkout while a fully indexed, cross-repository semantic engine sits unused.
The fix is a short instruction file in the agent's native format. This page covers the patterns that reliably work and where to put them for each agent.
Working with BSL codebases? Read the dedicated page — [CodeAlive for BSL](/guides/1c-agents) — first: the word "metadata" has a language-specific meaning, and agent instructions need to account for it.
## Know what the instruction controls
Reliable code retrieval has two separate parts: CodeAlive keeps a server-side index of the default branch, while the coding agent must retrieve the right evidence for the task at hand. An instruction file improves the second part. It cannot compensate for a repository that is missing, still processing, or unavailable to the current connection.
Start a research task with `get_data_sources`, passing the task as its `query`. This confirms the available source boundary and indexing status while narrowing multi-repository work to the most relevant sources. If an expected repository is absent or not ready, the agent should say so instead of searching an unrelated checkout and presenting the result as complete.
## Where instructions live
| Agent | Instruction file | Notes |
| ----------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Claude Code | `CLAUDE.md` (repo root or `~/.claude/CLAUDE.md`) | Also reads `AGENTS.md`. See [Claude Code setup](/integrations/mcp/claude-code) |
| Codex (CLI / App / IDE) | `AGENTS.md` (repo root) + `~/.codex/AGENTS.md` (global) | See [Codex setup](/integrations/mcp/codex) |
| Cursor | `.cursor/rules/*.mdc` | Legacy `.cursorrules` is deprecated. See [Cursor setup](/integrations/mcp/cursor) |
| Cline | `.cline/rules.md` | See [Cline setup](/integrations/mcp/cline) |
| Most other agents | `AGENTS.md` (repo root) | `AGENTS.md` has become a de-facto cross-agent standard |
Because Claude Code, Codex, Cursor's CLI, and many others all read a repo-root `AGENTS.md`, one well-written file covers most of your team regardless of which agent each person uses.
## Patterns that work
Observations from CodeAlive's own production prompt and from how other MCP vendors instruct agents converge on a few rules:
### 1. Imperative plus a trigger condition
State *when* to use the tool, not just that it exists.
```markdown theme={null}
Always use CodeAlive `semantic_search` when exploring how the codebase works,
where something is implemented, or how components relate.
```
A passive mention ("CodeAlive provides semantic search") does not change behaviour; a conditional imperative does.
### 2. Name the built-in tool you are overriding
Agents fall back to their native tools unless the instruction names them explicitly. This is the single most important pattern — and the most commonly missed one:
```markdown theme={null}
Do NOT use the built-in codebase_search or plain grep for exploration questions
before trying CodeAlive `semantic_search` / `grep_search`.
```
Generic phrasing ("prefer CodeAlive for search") loses to the planner's habit; naming the competing tool wins.
### 3. Sequence the tools
Tell the agent what a good exploration looks like as an ordered path, so it doesn't stop at the first tool:
```markdown theme={null}
For codebase questions: `semantic_search` (concepts) or `grep_search` (exact
names) → `fetch_artifacts` on the returned identifiers → answer from the
fetched code, not from snippets.
```
### 4. Teach the query grammar in one line each
The two most common failure modes are keyword-style semantic queries and question-style grep queries. One line each prevents both:
```markdown theme={null}
- `semantic_search`: full English sentences ("Where is retry handling
implemented?"), never bare keywords. Keep identifiers verbatim.
- `grep_search`: the exact literal or regex, never a question.
```
### 5. Keep always-on context small
Instruction files are injected into every request. Keep the always-on CodeAlive section compact; move detailed examples and troubleshooting into on-demand mechanisms (Cursor's Agent Requested rules, Claude Code skills). A bloated always-on rule gets skimmed by the model and taxes every prompt.
### 6. Define the local–indexed boundary
The server-side index and the local working tree answer different questions. Use CodeAlive for architecture, cross-repository discovery, default-branch code, and repositories that are not checked out. Use local file tools for uncommitted changes and files the agent is actively editing.
Say this explicitly. Otherwise agents tend to overcorrect in one direction: they either ignore CodeAlive and search only the checkout, or use indexed results to make claims about changes that exist only in the working tree.
### 7. Bound the work and require evidence
Efficient retrieval is a short, scoped path rather than a loop of broad searches:
```markdown theme={null}
Call `get_data_sources` once with the current task as `query`. Search only the
relevant sources, reuse returned artifact identifiers, and fetch the code needed
to support the answer. If a source or identifier is unavailable, report the
boundary instead of guessing.
```
This reduces noisy results and unnecessary requests while making failures visible. It also gives you something concrete to evaluate: which sources the agent selected, which artifacts it read, and whether its answer is grounded in those artifacts.
## Universal snippet
This block works verbatim in `AGENTS.md`, `CLAUDE.md`, and `.cline/rules.md`, and as the body of a Cursor `.mdc` rule:
```markdown title="AGENTS.md / CLAUDE.md — CodeAlive section" theme={null}
## CodeAlive context engine
CodeAlive MCP provides semantic search, grep, and code-graph tools over indexed
copies of our repositories (cross-repo, always up to date with the default branch).
- For any codebase exploration — "how does X work", "where is Y implemented",
"what calls Z" — start with CodeAlive `semantic_search`. Do NOT use built-in
file search (grep/glob/codebase_search) for these questions before CodeAlive
has returned nothing useful twice.
- Phrase `semantic_search` as a full English sentence, never bare keywords.
Keep exact identifiers and domain terms verbatim.
- Use CodeAlive `grep_search` for exact symbol names, string literals, error
messages, config keys, and acronyms — pass the literal text, not a question.
- When a result returns an artifact identifier (`repo::path::symbol`), read it
with `fetch_artifacts`; map callers/callees with `get_artifact_relationships`
before claiming how code flows.
- Call `get_data_sources` once with the current task as `query`; use the returned
names in `data_sources` to scope searches. If an expected source is missing or
not ready, report that boundary instead of guessing.
- Built-in file tools remain correct for files you are actively editing in the
working tree; CodeAlive covers the indexed history and the repos you don't
have checked out.
```
The last bullet matters: an instruction that bans local tools outright degrades editing tasks. Scope the preference to *exploration of indexed code*, and leave the working tree to the agent's native tools.
## Per-agent specifics
CLAUDE.md routing rules and the search subagent pattern
Rule types, and beating the built-in codebase\_search
AGENTS.md placement and a complete example
Two agent-specific facts worth knowing even before opening those pages:
* **Cursor's built-in `codebase_search` cannot be disabled** in the default Agent mode. The working approach is a precedence rule that names it — see the [Cursor page](/integrations/mcp/cursor#codealive-vs-cursors-built-in-codebase-search).
* **Codex reads the MCP server's own `instructions` field** at initialization, and the CodeAlive server ships tool-choice guidance there. `AGENTS.md` still helps: server instructions describe the tools, while `AGENTS.md` sets project-level precedence over built-ins.
## Verify it works
After adding instructions, test with a question that used to trigger built-in search:
```text theme={null}
"How does authentication work in this project?"
```
Watch the agent's tool calls: the first exploration call should be CodeAlive `semantic_search` (visible in the agent's tool log), not a local grep. If the agent still reaches for built-ins, strengthen pattern #2 — name the specific tool it used and forbid it for exploration questions.
Do not stop at one successful demo. Keep a small set of representative questions — architecture, exact-symbol lookup, cross-repository flow, and a working-tree change — and rerun them when you change the model, agent, or instruction. Check the tool trace for four quality signals:
* the agent selected CodeAlive before built-in search for indexed-code exploration;
* `get_data_sources` selected the intended repository or workspace;
* the answer was based on fetched code rather than search snippets alone;
* local tools were used when the claim depended on uncommitted changes.
This lightweight evaluation set turns instruction quality into a repeatable gate instead of a subjective impression. It also exposes wasted calls: repeated broad searches, unscoped multi-repository queries, or expensive synthesis before direct retrieval.
## Related resources
Full example prompt for your own agent on the Tool API
BSL specifics — the "metadata" dichotomy
Tool list and connection options
More agent-specific tips
# Welcome to CodeAlive
Source: https://docs.codealive.ai/index
Context Engine for AI-powered Code Review & Codebase Deep Research
## Breathe Life Into Your Codebase
**CodeAlive** is a powerful context engine that transforms how AI understands and interacts with your code. By building a comprehensive knowledge graph of your entire codebase, CodeAlive enables AI assistants to provide deeper, more accurate insights and code reviews.
## Get Started in Seconds
```bash theme={null}
npx @codealive/installer
```
Auto-detects and configures CodeAlive for Claude Code, Cursor, VS Code, Windsurf, Cline, and 15+ more agents. [Learn more →](/installation)
Set up CodeAlive in minutes and start using AI-powered code intelligence
Connect CodeAlive with 20+ AI assistants including Claude, Cursor, Windsurf, Codex, and more
Find code by meaning and intent across your entire codebase
Integrate CodeAlive's API into your development workflow
## Key Features
CodeAlive supports all programming languages, enabling comprehensive code analysis across any technology stack.
Analyze and understand relationships across multiple repositories simultaneously, perfect for microservices and monorepo architectures.
Accelerate AI agent performance by up to 83% with deep contextual understanding and semantic code search capabilities.
Automatically builds a comprehensive knowledge graph that maps relationships between code components, dependencies, and architectural patterns.
## Learn More
Real-world patterns for using CodeAlive with AI agents
Get better results with practical tips
Solutions for common issues
## Quick Links
Create your CodeAlive account
Explore our open-source projects
Get help from our team
# Installation
Source: https://docs.codealive.ai/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
```bash theme={null}
npx @codealive/installer
```
```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
```
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 |
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.
Restart your AI coding agents to pick up the new configuration. The installer will tell you which agents were configured.
## Installation Methods
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
```
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
```
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();
```
## 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
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).
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.
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
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
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`)
Run PowerShell as Administrator, or use the Node.js method:
```powershell theme={null}
npx @codealive/installer
```
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.
## Related Resources
Get started with CodeAlive in minutes
Manual MCP setup for all agents
Learn about skills and plugins
Installer source code
# Model Context Protocol (MCP)
Source: https://docs.codealive.ai/integrations/mcp
Connect CodeAlive to AI assistants via Model Context Protocol for deep codebase understanding
## Overview
Model Context Protocol (MCP) is an open standard developed by Anthropic that enables AI assistants to connect with external tools and data sources. MCP is now generally available across major development platforms including VS Code, JetBrains IDEs, and more. CodeAlive's MCP server provides your AI assistant with deep, contextual understanding of your entire codebase through semantic search and intelligent code analysis.
Already using an older CodeAlive MCP integration? Follow the
[MCP v1/v2 → v3 migration guide](/integrations/mcp/migrate-to-v3) to update
tool names, arguments, prompts, and deployment configuration.
## Why Use CodeAlive MCP?
AI understands relationships across your entire codebase, not just individual files
Find code by meaning and intent, not just keywords
Work seamlessly across multiple repositories in one session
Always work with the latest indexed version of your code
## Deployment Options
CodeAlive MCP can be deployed in three ways, depending on your needs:
### 1. Remote Service (Recommended)
* **URL**: `https://mcp.codealive.ai/api/`
* **Best for**: Quick setup, no infrastructure management
* **Requirements**: CodeAlive API key
* **Supported Clients**: All MCP-compatible AI assistants
### 2. Docker Container
* **Image**: `ghcr.io/codealive-ai/codealive-mcp:main`
* **Best for**: Enterprise environments, local development
* **Requirements**: Docker, CodeAlive API key
* **Benefits**: Network isolation, custom configuration
### 3. Self-Hosted Instance
* **Repository**: [CodeAlive MCP Server](https://github.com/CodeAlive-AI/codealive-mcp)
* **Best for**: Complete control, custom modifications
* **Requirements**: Python 3.11+, infrastructure management
* **Benefits**: Full customization, on-premise deployment
## Getting Started
Add at least one repository to CodeAlive before creating an API key. You do not need to wait for indexing to finish to create the key, but MCP queries become useful only after the repository is indexed.
1. Sign up or log in at [app.codealive.ai](https://app.codealive.ai)
2. Go to **Repositories** in your dashboard
3. Click **Add Repository**
4. Connect your GitHub/GitLab/Bitbucket account
5. Select at least one repository to add
1. Navigate to **MCP & API**
2. Click **"+ Create API Key"**
3. Copy your key immediately (it won't be displayed again)
4. Store your API key securely
CodeAlive starts indexing after the repository is added. Wait for initial indexing to complete before expecting useful chat or search results. Initial indexing typically takes 5-15 minutes.
**Quick setup:** Run `npx @codealive/installer` to auto-configure CodeAlive for your agents. See the [Installation Guide](/installation) for details.
Or select your AI assistant to see manual setup instructions:
Remote MCP with OAuth support
Native MCP support (GA)
MCP with elicitation & resources
Streamable HTTP with serverUrl
Full MCP feature support
Auto-tool creation capabilities
Desktop app with MCP
OpenAI Codex CLI with TOML config
One-command setup
CLI and IDE integration
Terminal AI with remote transport
Code Assistant and CLI setup
Native remote MCP support
Custom GPTs with Actions
Roo Code, KodaCode, GigaCode, and more
## Available MCP Tools
CodeAlive exposes eleven MCP v3 tools. The default discovery pair is `semantic_search` and `grep_search`; `chat` is a slower stateless synthesis fallback that should be called only when explicitly requested.
Agent-repairable failures, such as an invalid path or ambiguous data source,
return actionable `` text and set the MCP result's native
`isError` flag. Authentication, quota, network, and server failures are also
surfaced as tool errors rather than empty results.
### `get_data_sources`
Lists all indexed repositories and workspaces available for querying. Pass the optional `query` argument — a natural-language description of the task, such as "add OAuth to checkout" — to get only the data sources relevant to it, each with a `relevanceReason` explaining the match. Recommended whenever the agent knows what the user is trying to accomplish; omit `query` to list everything.
**Use cases:**
* Scope the source list to the current task with `query`
* Verify repository access
* Check indexing status
* List available codebases
### `semantic_search`
Canonical semantic search across indexed artifacts. Find code by meaning and intent, not just keywords.
**Use cases:**
* Find implementation patterns
* Locate specific functionality
* Discover related code
* Trace data flows
### `grep_search`
Canonical exact text or regex search with line-level previews.
**Use cases:**
* Find exact strings, identifiers, or log messages
* Run regex lookups across indexed repositories
* Confirm literal matches before fetching full source
### `chat`
Canonical synthesized codebase Q\&A tool.
Use `chat` only when explicitly requested and when you need a synthesized answer instead of direct evidence gathering. It can take substantially longer than retrieval. Tool API v3 chat is stateless: include prior findings, artifact identifiers, assumptions, scope, and constraints in every `question`. If your agent supports subagents and you need the highest reliability or depth, prefer a multi-step agent workflow that combines ontology, `semantic_search`, `grep_search`, `fetch_artifacts`, `read_file`, relationship inspection, metadata queries, and local file reads.
**Use cases:**
* Architecture explanations after search
* Synthesized flow walkthroughs
* One-shot answers with all required context included in the question
### `get_repository_ontology`
Get repository-level orientation for exactly one selected repository.
### `get_file_tree`
Inspect a bounded file tree for exactly one selected repository.
### `read_file`
Read a repository-relative file path, optionally bounded by line range.
### `fetch_artifacts`
Retrieve full source code content for specific artifacts found via search. Use this to get the actual code after reviewing search descriptions.
**Use cases:**
* Get full content for external repo search results
* Inspect specific functions or classes in detail
* Follow the search → review → fetch workflow
**Workflow:** Call `semantic_search` or `grep_search` first, review the descriptions or line previews and identifiers in the results, then call `fetch_artifacts` with the identifiers you want to inspect (max 50 per request). For repositories in your working directory, use local file reads instead.
**Optional `data_source` (disambiguation):** Each search result carries a `dataSource` `id` and `name`. When an identifier exists in more than one data source, pass that `name` or `id` as the optional `data_source` argument to scope the fetch to one source.
**Missing identifiers:** If some requested identifiers cannot be resolved (or are outside your access scope), the response is not silently truncated — they are listed in a `` block naming each concrete identifier, followed by a hint to re-check those ids and retry the problematic ones. Surface them to the user rather than omitting the requested artifact.
### `get_artifact_relationships`
Expand one artifact's call graph, inheritance hierarchy, or reference relationships after you already have its identifier.
**Use cases:**
* Trace outgoing and incoming calls for one function
* Explore class inheritance chains
* Inspect reference-heavy symbols without fetching whole files
**Optional `data_source` (disambiguation):** Same as `fetch_artifacts` — pass a data source `name` or `id` (from a search result's `dataSource`) to resolve an identifier that exists in more than one data source.
**Handling the ambiguous-identifier 409.** If you call `fetch_artifacts` or `get_artifact_relationships` with an identifier that exists in more than one data source and you do **not** pass `data_source`, the backend returns a `409` and the tool surfaces the list of candidate data sources (by name and id). Each candidate **will** resolve, so the sequence is: call without `data_source` → read the 409 candidates → retry with one candidate's `name`/`id` → if that data source isn't the one you want, retry with the next. Do not invent a result.
**Scoped request found nothing.** If you *did* pass `data_source` but the call comes back empty (`fetch_artifacts` returns no content, `get_artifact_relationships` returns `found: false`), the tool emits a hint: the identifier likely belongs to a **different** data source, or the `data_source` value is wrong. Retry with a different candidate's `name`/`id`, or omit `data_source` to get the `409` candidate list — don't conclude the artifact doesn't exist.
### `get_artifact_query_schema`
Inspect supported ArtifactQuery entities, fields, operators, and examples before writing metadata queries.
### `query_artifact_metadata`
Run read-only metadata analytics across selected repositories. Use this for aggregate questions such as file counts, languages, complexity, relationship counts, and metadata filtering.
## Common Use Cases
```
You: "Explain how user authentication works in our system"
AI: [Searches for authentication code across repositories]
[Maps out the complete auth flow]
[Explains with actual code references]
```
```
You: "Debug why payments are failing intermittently"
AI: [Searches for payment processing code]
[Analyzes error handling and retry logic]
[Identifies potential race conditions]
```
```
You: "Create a new API endpoint following our patterns"
AI: [Analyzes existing API endpoints]
[Identifies conventions and patterns]
[Generates code matching your style]
```
```
You: "What would be impacted if we change this database schema?"
AI: [Searches for all references to the schema]
[Maps dependencies across services]
[Lists required migrations and updates]
```
## Security & Privacy
CodeAlive MCP follows security best practices:
* All connections are encrypted with TLS
* API keys are never logged or stored in plain text
* Repository access is controlled at the API key level
* Self-hosted options available for sensitive codebases
## Best Practices
Regularly sync repositories in your dashboard for accurate context
Be precise with technical terms for better search results
Use separate API keys for different projects or environments
Track API usage in your dashboard to optimize queries
## Troubleshooting
**Common causes:**
* Invalid or expired API key
* Network connectivity problems
* Incorrect MCP server URL
**Solutions:**
1. Regenerate API key in dashboard
2. Check network/firewall settings
3. Verify URL is `https://mcp.codealive.ai/api/`
**Common causes:**
* Repositories not indexed
* API key lacks permissions
* Indexing still in progress
**Solutions:**
1. Check indexing status in dashboard
2. Wait 5-15 minutes for initial indexing
3. Verify API key has repository access
**Common causes:**
* Large codebase searches
* Broad/vague queries
* Network latency
**Solutions:**
1. Use more specific search queries
2. Limit search to specific repositories
3. Consider Docker or self-hosted deployment
For more solutions, see the [Troubleshooting Guide](/troubleshooting).
## Next Steps
Set up CodeAlive with your preferred AI assistant
Deploy CodeAlive MCP on your infrastructure
Explore the full CodeAlive API
View source code and contribute
# Amazon Q Developer
Source: https://docs.codealive.ai/integrations/mcp/amazon-q
Connect CodeAlive with Amazon Q Developer CLI and IDE
## Overview
Connect CodeAlive with Amazon Q Developer for AI-powered development with deep codebase understanding. Amazon Q has two integration points: the CLI and the IDE plugin (VS Code / JetBrains).
**Quick install:** Run `npx @codealive/installer` to automatically configure CodeAlive for your agents.
See the [Installation Guide](/installation) for details.
## Prerequisites
* Amazon Q Developer CLI or IDE plugin
* CodeAlive account with API key ([Sign up here](https://app.codealive.ai))
* Indexed repositories in your CodeAlive dashboard
## Setup
Amazon Q CLI reads MCP configuration from:
* **Global:** `~/.aws/amazonq/mcp.json`
* **Workspace:** `.amazonq/mcp.json`
```json theme={null}
{
"mcpServers": {
"codealive": {
"type": "http",
"url": "https://mcp.codealive.ai/api",
"headers": {
"Authorization": "Bearer YOUR_API_KEY_HERE"
}
}
}
}
```
```json theme={null}
{
"mcpServers": {
"codealive": {
"type": "stdio",
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "CODEALIVE_API_KEY=YOUR_API_KEY_HERE",
"ghcr.io/codealive-ai/codealive-mcp:main"
]
}
}
}
```
Replace `YOUR_API_KEY_HERE` with your actual CodeAlive API key.
Restart the CLI to pick up the new configuration.
Amazon Q IDE plugin reads from:
* **Global:** `~/.aws/amazonq/agents/default.json`
* **Workspace:** `.aws/amazonq/agents/default.json`
```json theme={null}
{
"mcpServers": {
"codealive": {
"type": "http",
"url": "https://mcp.codealive.ai/api",
"headers": {
"Authorization": "Bearer YOUR_API_KEY_HERE"
},
"timeout": 310000
}
}
}
```
Replace `YOUR_API_KEY_HERE` with your actual CodeAlive API key.
Or use the IDE UI: **Q panel → Chat → tools icon → Add MCP Server** → choose HTTP or STDIO.
Restart VS Code or your JetBrains IDE to load the configuration.
## Usage
Once connected, Amazon Q Developer can:
* **Search your codebase** semantically across all indexed repositories
* **Answer architecture questions** with full project context
* **Find patterns and implementations** across multiple services
```
"Find all API endpoints in the user service"
"Explain how the payment flow works"
"Show me error handling patterns"
```
## Troubleshooting
1. Verify the config file location matches your setup (CLI vs IDE)
2. Check JSON syntax
3. Restart the CLI or IDE
1. Verify your API key is correct
2. Ensure `Bearer ` prefix is included in the Authorization header
3. Try regenerating your API key in the [dashboard](https://app.codealive.ai)
Use the config file method instead of the UI for reliable persistence.
For more solutions, see the [Troubleshooting Guide](/troubleshooting).
## Related Resources
* [MCP Overview](/integrations/mcp)
* [Installation Guide](/installation)
* [Self-Hosting Guide](/integrations/mcp/self-hosting)
* [Agent Skills](/integrations/skills)
## 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).
# ChatGPT
Source: https://docs.codealive.ai/integrations/mcp/chatgpt
Connect CodeAlive with ChatGPT using a custom MCP app
## Overview
Connect ChatGPT to CodeAlive's remote MCP server with browser OAuth. The older Custom GPT Actions integration remains available as an API-key fallback.
## Prerequisites
* ChatGPT Business, Enterprise, or Edu workspace with custom MCP apps enabled
* CodeAlive account ([Sign up here](https://app.codealive.ai))
* Indexed repositories in your CodeAlive dashboard
## Integration Methods
## Create a CodeAlive app in ChatGPT
A workspace admin enables **Developer mode / Create custom MCP connectors** under **Workspace Settings → Permissions & Roles → Connected Data**. Enterprise and Edu workspaces can grant this through RBAC.
In **Settings → Apps → Create**, enter the CodeAlive MCP endpoint:
```text theme={null}
https://mcp.codealive.ai/api
```
Choose OAuth when ChatGPT asks for the authentication mechanism.
Click **Scan Tools**, complete the CodeAlive browser sign-in and consent screen, then wait for ChatGPT to finish scanning. The app exposes read-only CodeAlive tools such as `get_data_sources`, `semantic_search`, `grep_search`, and `read_file`.
Select the draft app in a new chat and ask, “What CodeAlive repositories are available?” Workspace admins can publish the tested app and control access through ChatGPT's app settings.
Each user authorizes their own CodeAlive access. Do not configure a shared API key for the MCP app.
## Create a Custom GPT with CodeAlive
Custom GPTs allow you to create a specialized version of ChatGPT that connects to CodeAlive.
1. Go to [chat.openai.com](https://chat.openai.com)
2. Click on "Explore GPTs" in the sidebar
3. Click "Create" to build a new GPT
Set up your GPT with these instructions:
```
You are a code assistant with access to CodeAlive, which provides
semantic search and analysis of entire codebases. You can:
1. Search for code implementations across repositories
2. Understand project architecture and patterns
3. Find related code and dependencies
4. Generate code following existing patterns
Always use CodeAlive to:
- Search for existing implementations before writing new code
- Understand the codebase context
- Follow established patterns and conventions
```
1. Click on "Configure" → "Add Actions"
2. Import the CodeAlive OpenAPI schema:
```json theme={null}
{
"openapi": "3.1.1",
"info": {
"title": "CodeAlive Tool API",
"version": "3.0.0"
},
"servers": [
{
"url": "https://app.codealive.ai"
}
],
"paths": {
"/api/tools/get_data_sources": {
"post": {
"operationId": "ToolApiGetDataSources",
"summary": "List available repositories",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"query": {"type": "string"},
"ready_only": {"type": "boolean"},
"output_format": {"type": "string", "enum": ["json", "agentic"]}
}
}
}
}
},
"security": [{"bearerAuth": []}]
}
},
"/api/tools/semantic_search": {
"post": {
"operationId": "ToolApiSemanticSearch",
"summary": "Search code semantically",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": ["question"],
"properties": {
"question": {"type": "string"},
"data_sources": {
"type": "array",
"items": {"type": "string"}
},
"paths": {"type": "array", "items": {"type": "string"}},
"extensions": {"type": "array", "items": {"type": "string"}},
"max_results": {"type": "integer"},
"output_format": {"type": "string", "enum": ["json", "agentic"]}
}
}
}
}
},
"security": [{"bearerAuth": []}]
}
},
"/api/tools/chat": {
"post": {
"operationId": "ToolApiChat",
"summary": "Ask a stateless question about code",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": ["question"],
"properties": {
"question": {"type": "string"},
"data_sources": {
"type": "array",
"items": {"type": "string"}
},
"output_format": {"type": "string", "enum": ["json", "agentic"]}
}
}
}
}
},
"security": [{"bearerAuth": []}]
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer"
}
}
}
}
```
1. In the Actions configuration, click "Authentication"
2. Select "API Key"
3. Auth Type: "Bearer"
4. Add your CodeAlive API key
Test with queries like:
* "What repositories are available in CodeAlive?"
* "Search for authentication implementations"
* "Explain the user service architecture"
## Use CodeAlive API Directly in ChatGPT
You can also manually provide API responses to ChatGPT for analysis.
Use curl or any HTTP client to query CodeAlive:
```bash theme={null}
curl -X POST https://app.codealive.ai/api/tools/semantic_search \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"question": "Where is authentication implemented?", "data_sources": ["your-repo-name"], "output_format": "agentic"}'
```
Copy the API response and paste it into ChatGPT with context:
```
Here's the code search result from my codebase.
Please analyze this authentication implementation:
[Paste API response]
```
## Usage Examples
### Code Search
```
User: "Search my codebase for payment processing logic"
ChatGPT: [Uses CodeAlive action to search]
Found payment processing in:
- /services/payment/processor.js
- /api/routes/checkout.js
- /lib/payment-gateway.js
```
### Architecture Analysis
```
User: "Explain how the authentication flow works"
ChatGPT: [Searches for auth code via CodeAlive]
[Analyzes the flow across multiple files]
[Provides detailed explanation with code references]
```
### Code Generation
```
User: "Create a new API endpoint following our patterns"
ChatGPT: [Searches for existing endpoints]
[Identifies patterns and conventions]
[Generates code matching your style]
```
## Advanced Configuration
### Custom GPT Capabilities
Configure your GPT with specific capabilities:
```json theme={null}
{
"capabilities": {
"web_browsing": false,
"dall_e_image_generation": false,
"code_interpreter": true
},
"actions": ["codealive"],
"conversation_starters": [
"Search for implementations of...",
"Explain the architecture of...",
"Find all references to...",
"Generate code similar to..."
]
}
```
### Rate Limiting
Be aware of rate limits:
* ChatGPT has limits on Actions calls per conversation
* CodeAlive API has rate limits based on your plan
* Use specific queries to minimize API calls
### Privacy Settings
For team/enterprise accounts:
1. Control data sharing in GPT settings
2. Set action permissions (private, team, public)
3. Configure audit logging if required
## Sharing Your GPT
### Make it Public
1. Go to GPT settings
2. Click "Publish" → "Public"
3. Share the GPT link with others
4. Users will need their own CodeAlive API key
### Team Sharing
For ChatGPT Team/Enterprise:
1. Set visibility to "Anyone at \[Your Organization]"
2. Team members can use shared authentication
3. Centrally manage API keys
## Best Practices
Use precise search terms to get relevant results
Be mindful of token limits when searching large codebases
Reuse search results within the same conversation
Never share API keys in conversation
## Troubleshooting
**Solutions:**
1. Verify API key is correct
2. Check key hasn't expired
3. Ensure Bearer prefix is included
4. Regenerate key if needed
**Solutions:**
1. Verify repositories are indexed
2. Check search query syntax
3. Test API directly with curl
4. Check rate limits
**Solutions:**
1. Explicitly ask to "use CodeAlive"
2. Check action is enabled
3. Verify OpenAPI schema is valid
4. Review GPT instructions
**Solutions:**
1. Reduce frequency of searches
2. Use more specific queries
3. Upgrade CodeAlive plan
4. Cache results when possible
For more solutions, see the [Troubleshooting Guide](/troubleshooting).
## Limitations
**Current Limitations:**
* ChatGPT can't maintain persistent connections
* Actions have timeout limits (30 seconds)
* Token limits may truncate large responses
* No real-time code updates
## Alternatives
If ChatGPT doesn't meet your needs, consider:
Native MCP support with real-time updates
IDE-integrated AI with MCP
Open-source alternative with MCP
Build custom integration
## Related Resources
* [OpenAI GPTs Documentation](https://help.openai.com/en/articles/8554397-gpts)
* [ChatGPT Actions Guide](https://platform.openai.com/docs/actions)
* [CodeAlive API Reference](/api-reference/toolapi/list-visible-data-sources)
* [MCP Overview](/integrations/mcp)
## 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).
# Claude Code Integration
Source: https://docs.codealive.ai/integrations/mcp/claude-code
Connect CodeAlive with Claude Code for enhanced AI-powered development
## Overview
**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.
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.
**Quick install:** Run `npx @codealive/installer` to automatically configure CodeAlive for Claude Code.
See the [Installation Guide](/installation) for details.
**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.
## 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
Claude Code supports both local and remote MCP servers with OAuth authentication.
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.
Existing API-key configurations remain supported. Add `--header "Authorization: Bearer YOUR_API_KEY_HERE"` only when you intentionally choose that fallback.
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
```
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"
## 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
```
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]
```
```
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]
```
```
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]
```
```
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]
```
## 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.
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).
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
```
If `docker` is not found, enable Docker Desktop WSL integration: Docker Desktop → Settings → Resources → WSL integration → enable your distro.
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`.
## 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
Regularly sync repositories in CodeAlive dashboard for accurate context
Be precise with technical terms for better search results
Reference CodeAlive when working with large codebases
Use CodeAlive to validate ideas before implementing
## Productivity Tips
Use slash commands for common operations:
* `/search` - Quick code search
* `/explain` - Get explanations with context
* `/similar` - Find similar implementations
* `/repos` - List available repositories
* Clear context between unrelated tasks
* Use CodeAlive to establish context for new features
* Reference specific files when needed
* Always search for existing patterns first
* Let Claude Code match your coding style
* Verify generated code against your conventions
## Troubleshooting
**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
**Solutions:**
1. Log into CodeAlive dashboard
2. Verify repositories are indexed
3. Wait for indexing to complete
4. Check API key permissions
**Solutions:**
1. Use more specific search queries
2. Limit search to specific repositories
3. Check CodeAlive service status
4. Consider upgrading your plan
**Solutions:**
1. Regenerate API key in dashboard
2. Update MCP configuration
3. Ensure Bearer token format is correct
4. Test API key with curl
**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`
**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
For more solutions, see the [Troubleshooting Guide](/troubleshooting).
## 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
Patterns that make agents prefer CodeAlive tools
Learn about Model Context Protocol
Direct API integration guide
Manage your repositories
Get help from our team
## 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).
# Claude Desktop
Source: https://docs.codealive.ai/integrations/mcp/claude-desktop
Connect CodeAlive with Claude Desktop application
## Overview
Integrate CodeAlive with Claude Desktop to enhance your AI assistant with deep understanding of your entire codebase. This integration uses the Model Context Protocol (MCP) to provide Claude Desktop with semantic search and code intelligence capabilities.
**Quick install:** Run `npx @codealive/installer` to automatically configure CodeAlive for this agent.
See the [Installation Guide](/installation) for details.
## Prerequisites
* [Claude Desktop](https://claude.ai/download) installed
* CodeAlive account with API key ([Sign up here](https://app.codealive.ai))
* Indexed repositories in your CodeAlive dashboard
## Installation Methods
This is the best fit for Claude Desktop when you authenticate with a bearer token. It uses Claude Desktop's native extension installer, stores the API key securely, and supports self-hosted CodeAlive via a configurable base URL.
From the `codealive-mcp` repository:
```bash theme={null}
npm install -g @anthropic-ai/mcpb
mcpb pack
```
This produces a `.mcpb` bundle you can install into Claude Desktop.
Open **Settings → Extensions → Install Extension...** and select the generated `.mcpb` file.
Fill in these settings in Claude Desktop:
* **CodeAlive API Key** — your bearer token
* **CodeAlive Base URL** — your deployment origin, for example `https://codealive.yourcompany.com`
* **Ignore TLS Errors** — only for development or self-signed test environments
`https://host` is preferred. `https://host/api` is also accepted and normalized automatically.
This setup adds CodeAlive as a local MCP server in `claude_desktop_config.json` using Docker (STDIO). If you want to use Claude Desktop remote connectors instead, add them through Claude Desktop settings.
Find your Claude Desktop configuration file:
**macOS**:
```bash theme={null}
~/Library/Application Support/Claude/claude_desktop_config.json
```
**Windows**:
```bash theme={null}
%APPDATA%\Claude\claude_desktop_config.json
```
Create the file if it doesn't exist.
Add this Docker (STDIO) configuration:
```json theme={null}
{
"mcpServers": {
"codealive": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "CODEALIVE_API_KEY=YOUR_API_KEY_HERE",
"ghcr.io/codealive-ai/codealive-mcp:main"
]
}
}
}
```
Replace `YOUR_API_KEY_HERE` with your actual CodeAlive API key.
Completely quit and restart Claude Desktop:
* **macOS**: Cmd+Q then reopen
* **Windows**: Alt+F4 then reopen
## Verification
Test the integration by asking Claude:
```
"What CodeAlive repositories are available?"
"Search for authentication code in my codebase"
"Explain the main architecture of my project"
```
## Usage Examples
```
You: "Review the recent changes in the user service for security issues"
Claude: [Searches for user service code]
[Analyzes security patterns]
[Provides specific recommendations]
```
```
You: "Help me debug why the API is returning 500 errors"
Claude: [Searches for error handling code]
[Traces through stack traces]
[Identifies potential causes]
```
```
You: "Generate API documentation for the payment endpoints"
Claude: [Analyzes payment API code]
[Extracts request/response schemas]
[Creates comprehensive documentation]
```
## Advanced Configuration
### Multiple API Keys
Use separate servers for different teams or environments:
```json theme={null}
{
"mcpServers": {
"codealive-production": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "CODEALIVE_API_KEY=PROD_API_KEY",
"ghcr.io/codealive-ai/codealive-mcp:main"
]
},
"codealive-development": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "CODEALIVE_API_KEY=DEV_API_KEY",
"ghcr.io/codealive-ai/codealive-mcp:main"
]
}
}
}
```
## Windows & WSL
Claude Desktop on Windows **cannot** connect to MCP servers running inside WSL directly. Use one of these approaches instead.
If Docker Desktop is installed on Windows, the Docker STDIO configuration above works as-is — `docker` is in the Windows PATH.
If Docker is only available inside WSL, use `wsl.exe` as a bridge in `claude_desktop_config.json`:
```json theme={null}
{
"mcpServers": {
"codealive": {
"command": "wsl.exe",
"args": [
"--", "docker", "run", "--rm", "-i",
"-e", "CODEALIVE_API_KEY=YOUR_API_KEY_HERE",
"ghcr.io/codealive-ai/codealive-mcp:main"
]
}
}
}
```
The `.mcpb` extension bundle (see Native Extension tab above) works on Windows without any WSL workarounds — it connects to the CodeAlive cloud API directly over HTTP.
## Troubleshooting
**Solutions:**
1. Verify JSON syntax in configuration file
2. Ensure Claude Desktop was fully restarted (Cmd+Q/Alt+F4)
3. Check API key is valid and active
4. Look for errors in Claude Desktop logs
**Solutions:**
1. Verify repositories are indexed in dashboard
2. Wait for indexing to complete (5-15 minutes)
3. Check API key has repository access
4. Test API key with curl command
**Solutions:**
1. Check network connectivity
2. Verify firewall allows outbound HTTPS
3. Try Docker deployment for local access
4. Check CodeAlive service status
**Solutions:**
1. Ensure Docker is running
2. Check port 8000 is not in use
3. Verify environment variables are set
4. Review container logs for errors
For more solutions, see the [Troubleshooting Guide](/troubleshooting).
## Best Practices
Store API keys securely, use environment variables
Use Docker for faster local responses
Use separate configs for different projects
Keep repositories indexed regularly
## Related Resources
* [MCP Overview](/integrations/mcp)
* [Self-Hosting Guide](/integrations/mcp/self-hosting)
* [API Reference](/api-reference/toolapi/list-visible-data-sources)
* [GitHub Repository](https://github.com/CodeAlive-AI/codealive-mcp)
## 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).
# Cline
Source: https://docs.codealive.ai/integrations/mcp/cline
Connect CodeAlive with Cline autonomous coding agent
## Overview
Integrate CodeAlive with Cline - the open-source AI coding agent used by millions of developers. Cline can autonomously create and extend its capabilities through MCP tools. With 30k+ GitHub stars, Cline offers complete transparency and zero vendor lock-in.
**Quick install:** Run `npx @codealive/installer` to automatically configure CodeAlive for Cline.
See the [Installation Guide](/installation) for details.
## Prerequisites
* [Cline](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev) extension installed in VS Code
* CodeAlive account with API key ([Sign up here](https://app.codealive.ai))
* Indexed repositories in your CodeAlive dashboard
## Connecting to CodeAlive
Access Cline's MCP configuration:
1. Click on the Cline icon in the VS Code sidebar
2. Click the settings gear icon
3. Navigate to "MCP Servers" section
Or use Command Palette:
* Cmd/Ctrl+Shift+P → "Cline: Configure MCP Servers"
Configure CodeAlive as an MCP server:
```json theme={null}
{
"mcpServers": {
"codealive": {
"url": "https://mcp.codealive.ai/api",
"headers": {
"Authorization": "Bearer YOUR_API_KEY_HERE"
}
}
}
}
```
**Cline's Unique Feature:** Ask Cline to "add a tool" and it will create and install custom MCP servers tailored to your workflow - no manual configuration needed!
Replace `YOUR_API_KEY_HERE` with your actual CodeAlive API key
Ensure MCP is enabled in Cline settings:
```json theme={null}
{
"cline.enableMCP": true,
"cline.mcpAutoConnect": true
}
```
Restart VS Code to ensure all changes take effect
Test by asking Cline:
* "Use CodeAlive to show me all available repositories"
* "Search the codebase for authentication logic"
* "Analyze the project architecture using CodeAlive"
## Configuration Options
### Advanced Settings
```json theme={null}
{
"mcpServers": {
"codealive": {
"url": "https://mcp.codealive.ai/api",
"headers": {
"Authorization": "Bearer YOUR_API_KEY_HERE"
}
}
}
}
```
### Docker Deployment
Run CodeAlive locally for better performance:
```json theme={null}
{
"mcpServers": {
"codealive": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "CODEALIVE_API_KEY=YOUR_API_KEY_HERE",
"ghcr.io/codealive-ai/codealive-mcp:main"
]
}
}
}
```
## Usage Patterns
Let Cline use CodeAlive automatically:
```
"Refactor the user service to match our microservices pattern"
Cline will:
1. Use CodeAlive to find existing patterns
2. Analyze the current implementation
3. Generate refactored code
4. Update related files
```
Direct Cline to use CodeAlive:
```
"Use CodeAlive to find all payment processing code,
then add retry logic following our existing patterns"
```
Have Cline review code with context:
```
"Use CodeAlive to review this PR for consistency
with our codebase conventions"
```
## Cline Rules Configuration
Create `.cline/rules.md` in your project root:
```markdown theme={null}
# CodeAlive Integration Rules
## Always Use CodeAlive For:
- Finding existing implementations before writing new code
- Understanding project architecture and patterns
- Locating all files that might be affected by changes
- Searching for similar code patterns
## Code Generation Guidelines:
- Match the style found via CodeAlive search
- Follow conventions discovered in the codebase
- Reuse existing utilities and helpers
- Maintain consistency with existing patterns
## Before Making Changes:
1. Search with CodeAlive for related code
2. Analyze existing patterns
3. Consider impact on other parts of the system
4. Follow established conventions
```
## Advanced Features
### Task Planning
Configure Cline to use CodeAlive for planning:
```json theme={null}
{
"cline.planning": {
"enabled": true,
"useCodeAlive": true,
"steps": [
"Search for similar implementations",
"Analyze existing patterns",
"Plan changes based on findings",
"Execute implementation"
]
}
}
```
### Custom Commands
Create Cline commands that leverage CodeAlive:
```json theme={null}
{
"cline.customCommands": [
{
"name": "Analyze Architecture",
"command": "Use CodeAlive to analyze and explain the project architecture"
},
{
"name": "Find Security Issues",
"command": "Use CodeAlive to search for potential security vulnerabilities"
},
{
"name": "Generate Tests",
"command": "Use CodeAlive to find the code, then generate comprehensive tests"
}
]
}
```
### Model Configuration
Optimize Cline's model usage with CodeAlive:
```json theme={null}
{
"cline.apiProvider": "anthropic",
"cline.apiModel": "claude-3-opus-20240229",
"cline.contextStrategy": "codealive-first",
"cline.maxContextTokens": 100000
}
```
## Workspace Settings
### Project-Specific Configuration
`.vscode/settings.json`:
```json theme={null}
{
"mcpServers": {
"codealive": {
"type": "http",
"url": "https://mcp.codealive.ai/api",
"headers": {
"Authorization": "Bearer ${env:CODEALIVE_API_KEY}"
},
"repositories": ["backend", "frontend", "shared"]
}
},
"cline.autoDetectTasks": true
}
```
### Team Collaboration
Share configuration without exposing API keys:
1. Add to `.vscode/settings.json`:
```json theme={null}
{
"cline.mcpServers.codealive.headers.Authorization": "Bearer ${env:CODEALIVE_API_KEY}"
}
```
2. Team members set environment variable:
```bash theme={null}
export CODEALIVE_API_KEY="their_api_key"
```
## Performance Optimization
Enable caching for repeated queries:
```json theme={null}
{
"cline.cache": {
"enabled": true,
"codealiveQueries": true,
"ttl": 3600
}
}
```
Optimize context window usage:
```json theme={null}
{
"cline.contextOptimization": {
"useCodeAliveFirst": true,
"summarizeContext": true,
"maxFilesPerRequest": 10
}
}
```
Enable parallel CodeAlive queries:
```json theme={null}
{
"cline.parallel": {
"enabled": true,
"maxConcurrent": 3
}
}
```
## Troubleshooting
**Solutions:**
1. Check MCP is enabled in Cline settings
2. Verify MCP server configuration
3. Restart VS Code completely
4. Check Cline output panel for errors
**Solutions:**
1. Use Docker for local deployment
2. Limit repository scope in searches
3. Enable caching
4. Optimize context window usage
**Solutions:**
1. Regenerate API key
2. Check Bearer token format
3. Verify environment variables
4. Test connection manually
**Solutions:**
1. Enable context optimization
2. Use CodeAlive for large file searches
3. Limit files per request
4. Use summarization features
For more solutions, see the [Troubleshooting Guide](/troubleshooting).
## Best Practices
Allow Cline to use CodeAlive for task planning
Always review Cline's changes in context
Use CodeAlive to verify changes match patterns
Test Cline's changes in development first
## Tips for Effective Use
### Prompting Strategies
**Good Prompts:**
```
"Use CodeAlive to find our API endpoint patterns,
then create a new user profile endpoint"
"Search for our error handling patterns with CodeAlive,
then improve error handling in the payment service"
```
**Avoid:**
```
"Create a new endpoint" (too vague, won't use context)
"Fix the bug" (doesn't leverage CodeAlive)
```
### Task Delegation
Let Cline handle complex multi-file operations:
```
"Use CodeAlive to find all references to the old User model,
then update them to use the new UserProfile model"
```
## Related Resources
* [MCP Overview](/integrations/mcp)
* [Cline Documentation](https://github.com/saoudrizwan/claude-dev)
* [Self-Hosting Guide](/integrations/mcp/self-hosting)
* [VS Code Integration](/integrations/mcp/vscode)
## 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).
# Codex
Source: https://docs.codealive.ai/integrations/mcp/codex
Connect CodeAlive with OpenAI Codex CLI, Desktop App, and IDE Extension
## Overview
OpenAI's Codex ships in three form-factors that share the same configuration file:
* **Codex CLI** — terminal agent (`npm install -g @openai/codex` or `brew install --cask codex`)
* **Codex App** — native macOS / Windows desktop app ([openai.com/codex](https://openai.com/codex/get-started/))
* **Codex IDE Extension** — VS Code (`openai.chatgpt`) and JetBrains (IntelliJ, PyCharm, WebStorm, Rider; 2025.3+)
All three read `~/.codex/config.toml`, so one snippet wires CodeAlive into every Codex surface.
**Quick install:** Run `npx @codealive/installer` to automatically configure CodeAlive for Codex.
See the [Installation Guide](/installation) for details.
**Codex defaults to shell-based search (grep/rg) for exploration.** Connecting the MCP server alone won't change that — add routing rules to your project's `AGENTS.md`. See [Instructing Codex via AGENTS.md](#instructing-codex-via-agents-md) below.
## Prerequisites
* Any of: [Codex CLI](https://github.com/openai/codex), [Codex App](https://openai.com/codex/get-started/), or [Codex IDE Extension](https://developers.openai.com/codex/ide)
* CodeAlive account ([Sign up here](https://app.codealive.ai))
* Indexed repositories in your CodeAlive dashboard
## Setup
Run this in your terminal:
```bash theme={null}
codex mcp add codealive --url https://mcp.codealive.ai/api
```
Authenticate once in your browser:
```bash theme={null}
codex mcp login codealive
```
Codex uses OAuth 2.1 with PKCE, stores the resulting credential, and refreshes it automatically. No CodeAlive API key belongs in `config.toml`.
API-key authentication remains supported for existing setups:
```toml theme={null}
[mcp_servers.codealive]
url = "https://mcp.codealive.ai/api"
bearer_token_env_var = "CODEALIVE_API_KEY"
```
Export the key in the shell that launches Codex:
```bash theme={null}
export CODEALIVE_API_KEY="YOUR_API_KEY_HERE"
```
Add to `~/.codex/config.toml`:
```toml theme={null}
[mcp_servers.codealive]
command = "docker"
args = ["run", "--rm", "-i", "ghcr.io/codealive-ai/codealive-mcp:main"]
env_vars = ["CODEALIVE_API_KEY"]
```
Then export the key in the shell that launches Codex:
```bash theme={null}
export CODEALIVE_API_KEY="YOUR_API_KEY_HERE"
```
`env_vars` forwards values from the parent shell — safer than embedding the key in `args`.
If you can't use OAuth or an environment variable, use a static header:
```toml theme={null}
[mcp_servers.codealive]
url = "https://mcp.codealive.ai/api"
headers = { Authorization = "Bearer YOUR_API_KEY_HERE" }
```
Verify the entry was registered:
```bash theme={null}
codex mcp list
```
Then restart Codex (CLI, App, or reload the IDE extension) and try in chat:
* "What CodeAlive repositories are available?"
* "Find authentication code in my codebase"
## Codex App: Setup via UI
Codex App (macOS / Windows) lets you manage MCP servers from **Settings → MCP Servers → Add Server**. Fill in:
* **Name**: `codealive`
* **URL**: `https://mcp.codealive.ai/api`
* **Authentication**: Choose browser OAuth when prompted; use an Authorization header only for the API-key fallback
The UI writes the entry into `~/.codex/config.toml`; the CLI and IDE extension pick it up automatically.
## Codex IDE Extension
The Codex extension for VS Code (`openai.chatgpt`) and JetBrains (2025.3+) shares `~/.codex/config.toml` with the CLI and App — there is no separate config surface. In VS Code, open the Codex panel → settings (⚙) → **MCP settings → Open config.toml**.
## Project-level Config
Codex now supports a per-project `.codex/config.toml` at the repository root (for trusted projects). Useful when:
* The whole team should share the same MCP server set
* Different projects need different CodeAlive workspaces
```toml theme={null}
# .codex/config.toml (committed to the repo)
[mcp_servers.codealive]
url = "https://mcp.codealive.ai/api"
```
Each teammate runs `codex mcp login codealive` and receives their own CodeAlive authorization; no shared credential is committed.
## Optional Fields
The `[mcp_servers.codealive]` table accepts several extras:
| Key | Purpose |
| --------------------- | -------------------------------------------------------------------- |
| `enabled` | Set to `false` to keep the entry but disable the server |
| `startup_timeout_sec` | Override the default 10s startup timeout |
| `tool_timeout_sec` | Override the default 60s per-tool timeout |
| `tool_allowlist` | Restrict which tools Codex is allowed to call |
| `startup_required` | If `true`, Codex refuses to start if the server can't initialize |
| `cwd` | Working directory (stdio only) |
| `env_vars` | List of env-var names to forward into the child process (stdio only) |
Example with a larger tool timeout (useful when relying on the slower `chat` tool):
```toml theme={null}
[mcp_servers.codealive]
url = "https://mcp.codealive.ai/api"
bearer_token_env_var = "CODEALIVE_API_KEY"
tool_timeout_sec = 120
```
## Instructing Codex via AGENTS.md
Codex reads `AGENTS.md` from the repository root on every run, plus a global `~/.codex/AGENTS.md` that applies to all projects. Repo-root instructions win on conflict; keep org-wide defaults global and project specifics in the repo.
Without instructions, Codex explores with shell search (grep/rg) over the local checkout. Add a CodeAlive section that names that habit explicitly:
```markdown title="AGENTS.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 reach for
shell grep/rg or directory listings 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.
- Shell tools remain correct for files you are actively editing in the
working tree.
```
Two Codex-specific notes:
* **The MCP server's own instructions help too.** At initialization Codex reads the server-provided `instructions` field, and the CodeAlive server ships tool-usage guidance there. That covers *how* to call the tools; `AGENTS.md` is still needed to set *precedence* over Codex's built-in shell search.
* **`AGENTS.md` is cross-agent.** Claude Code, Cursor's CLI, and most modern agents read the same repo-root file, so this one section covers teammates on other tools. See [Instructing Coding Agents](/guides/instructing-agents) for the general patterns.
## Usage
Once connected, Codex can:
* **Search your codebase** semantically across all indexed repositories
* **Answer architecture questions** with full project context
* **Find patterns and implementations** across multiple services
```text theme={null}
"Find all error handling patterns in the payment service"
"Explain how the user registration flow works"
"Search for database migration code"
```
## Troubleshooting
1. Run `codex mcp list` to confirm Codex sees the entry
2. Verify the config file is at `~/.codex/config.toml` (or project-level `.codex/config.toml`)
3. Check TOML syntax (use a TOML validator)
4. Restart Codex (CLI, App, or reload the IDE extension)
1. Confirm the URL is exactly `https://mcp.codealive.ai/api`
2. Run `codex mcp login codealive` and complete the browser redirect
3. Run `codex mcp get codealive` to inspect the stored configuration
1. Run `codex mcp logout codealive`, then `codex mcp login codealive`
2. Confirm the browser shows the expected CodeAlive consent screen and callback host
3. If you intentionally use the API-key fallback, verify `CODEALIVE_API_KEY` is exported in the shell that launched Codex
For more solutions, see the [Troubleshooting Guide](/troubleshooting).
## Related Resources
* [Instructing Coding Agents](/guides/instructing-agents)
* [CodeAlive & 1С (1C:Enterprise specifics)](/guides/1c-agents)
* [MCP Overview](/integrations/mcp)
* [Installation Guide](/installation)
* [Self-Hosting Guide](/integrations/mcp/self-hosting)
* [Agent Skills](/integrations/skills)
* [Codex MCP Documentation (OpenAI)](https://developers.openai.com/codex/mcp)
* [Codex Config Reference (OpenAI)](https://developers.openai.com/codex/config-reference)
## 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).
# Continue
Source: https://docs.codealive.ai/integrations/mcp/continue
Connect CodeAlive with Continue open-source AI code assistant
## Overview
Integrate CodeAlive with Continue - the first client to offer full support for all MCP features (Resources, Prompts, Tools, and Sampling). Continue is an open-source platform that lets you build custom AI code agents with any model, without vendor lock-in.
**Quick install:** Run `npx @codealive/installer` to automatically configure CodeAlive for Continue.
See the [Installation Guide](/installation) for details.
## Prerequisites
* [Continue](https://continue.dev) extension installed in VS Code or JetBrains IDE
* CodeAlive account with API key ([Sign up here](https://app.codealive.ai))
* Indexed repositories in your CodeAlive dashboard
## Configuring Continue with CodeAlive
Follow the installation steps above for your IDE
Access Continue configuration:
**VS Code:**
* Click Continue icon in sidebar
* Click gear icon → "Open config.json"
**JetBrains:**
* Open Continue panel
* Settings → Configuration
Continue has full MCP support. Create or edit `~/.continue/config.yaml`:
```yaml theme={null}
mcpServers:
- name: CodeAlive
type: streamable-http
url: https://mcp.codealive.ai/api
requestOptions:
headers:
Authorization: "Bearer YOUR_API_KEY_HERE"
```
Replace `YOUR_API_KEY_HERE` with your actual CodeAlive API key.
Continue maps MCP features to its existing capabilities:
* Resources → Context sources
* Prompts → Slash commands
* Tools → Tool integrations
* Sampling → Model configurations
Restart your IDE to load the new configuration
Type `@codealive` in Continue chat to test:
* "@codealive what repositories are available?"
* "@codealive find authentication code"
## Configuration Options
### Docker Setup (STDIO)
For local deployment or enhanced privacy:
```yaml theme={null}
mcpServers:
- name: CodeAlive
type: stdio
command: docker
args:
- run
- --rm
- -i
- -e
- CODEALIVE_API_KEY=YOUR_API_KEY_HERE
- ghcr.io/codealive-ai/codealive-mcp:main
```
## Usage Patterns
Use `@codealive` to add context to your prompts:
```
@codealive find the user authentication flow
Then explain how to add OAuth support
```
Create custom slash commands:
```json theme={null}
{
"slashCommands": [
{
"name": "search",
"description": "Search codebase with CodeAlive",
"run": "@codealive search for {{{input}}}"
},
{
"name": "explain",
"description": "Explain code with context",
"run": "@codealive explain {{{input}}}"
}
]
}
```
Automatically include CodeAlive context:
```json theme={null}
{
"contextProviders": [
{
"name": "codealive",
"provider": "mcp",
"autoInclude": true,
"config": {
"serverUrl": "https://mcp.codealive.ai/api",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
]
}
```
## Advanced Features
### Custom Models with CodeAlive
Configure Continue to use CodeAlive with different models:
```json theme={null}
{
"models": [
{
"title": "GPT-4 with CodeAlive",
"model": "gpt-4",
"provider": "openai",
"contextProviders": ["codealive"]
},
{
"title": "Claude with CodeAlive",
"model": "claude-3-opus",
"provider": "anthropic",
"contextProviders": ["codealive"]
},
{
"title": "Local Ollama with CodeAlive",
"model": "codellama",
"provider": "ollama",
"contextProviders": ["codealive"]
}
]
}
```
### Repository Filtering
Limit CodeAlive searches to specific repositories:
```json theme={null}
{
"contextProviders": [
{
"name": "codealive-backend",
"provider": "mcp",
"config": {
"serverUrl": "https://mcp.codealive.ai/api",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
},
"filters": {
"repositories": ["backend", "api"]
}
}
}
]
}
```
### Custom Prompts
Create templates that leverage CodeAlive:
```json theme={null}
{
"customPrompts": [
{
"name": "Code Review",
"prompt": "@codealive find similar code to:\n\n{{{input}}}\n\nReview for best practices and suggest improvements"
},
{
"name": "Test Generation",
"prompt": "@codealive analyze:\n\n{{{input}}}\n\nGenerate comprehensive unit tests"
}
]
}
```
## IDE-Specific Setup
Additional VS Code settings:
```json theme={null}
{
"continue.telemetry": false,
"continue.enableTabAutocomplete": true,
"continue.contextProviders.codealive.enabled": true
}
```
JetBrains-specific configuration:
```json theme={null}
{
"jetbrains": {
"enabled": true,
"port": 65432
},
"mcpServers": {
"codealive": {
"type": "http",
"url": "https://mcp.codealive.ai/api",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
```
For Neovim with Continue:
```lua theme={null}
-- In your Neovim config
require('continue').setup({
mcp_servers = {
codealive = {
type = 'http',
url = 'https://mcp.codealive.ai/api',
headers = {
Authorization = 'Bearer YOUR_API_KEY'
}
}
}
})
```
## Troubleshooting
**Solutions:**
1. Check config.json syntax is valid
2. Restart IDE completely
3. Verify contextProviders section exists
4. Check Continue logs for errors
**Solutions:**
1. Verify API key is valid
2. Check repositories are indexed
3. Test MCP server URL directly
4. Review Continue debug output
**Solutions:**
1. Use more specific queries
2. Limit repository scope
3. Consider Docker deployment
4. Check network latency
For more solutions, see the [Troubleshooting Guide](/troubleshooting).
## Best Practices
Use @codealive for large context needs, reducing token usage
Pair faster models with CodeAlive for better performance
Enable Continue's cache for repeated queries
Use Docker or self-hosted for sensitive code
## Related Resources
* [MCP Overview](/integrations/mcp)
* [Continue Documentation](https://continue.dev/docs)
* [Self-Hosting Guide](/integrations/mcp/self-hosting)
* [API Reference](/api-reference/toolapi/list-visible-data-sources)
## 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).
# Cursor
Source: https://docs.codealive.ai/integrations/mcp/cursor
Integrate CodeAlive with Cursor IDE for AI-powered development
## Overview
Connect CodeAlive with Cursor IDE to enhance your AI-powered development experience. CodeAlive provides Cursor with deep contextual understanding of your entire codebase through the Model Context Protocol (MCP).
**Quick install:** Run `npx @codealive/installer` to automatically configure CodeAlive for Cursor.
See the [Installation Guide](/installation) for details.
**Cursor ships its own `codebase_search` and will prefer it by default.** Connecting the MCP server is not enough — add a project rule so Cursor's agent reaches for CodeAlive first. See [CodeAlive vs Cursor's built-in codebase search](#codealive-vs-cursors-built-in-codebase-search) and the ready-made rule in [Project Rules](#project-rules-for-codealive).
Working with 1C:Enterprise (BSL)? Also read [CodeAlive & 1С](/guides/1c-agents) — the term "metadata" needs explicit disambiguation in 1C projects.
## Prerequisites
* [Cursor](https://cursor.com) installed (latest version recommended)
* CodeAlive account ([Sign up here](https://app.codealive.ai))
* Indexed repositories in your CodeAlive dashboard
## Connecting to CodeAlive
Open Cursor Settings:
* **macOS**: `Cmd+,` or menu **Cursor → Settings**
* **Windows/Linux**: `Ctrl+,` or **File → Preferences → Settings**
Then go to **Tools & MCP** in the left panel and click **New MCP Server**.
In older Cursor builds this panel was named **Tools & Integrations**.
Cursor opens `.cursor/mcp.json` (project-level) or `~/.cursor/mcp.json` (global) for editing. Paste this configuration:
```json theme={null}
{
"mcpServers": {
"codealive": {
"url": "https://mcp.codealive.ai/api"
}
}
}
```
Save the file.
Cursor detects the transport from the `url` field — Streamable HTTP first, with automatic SSE fallback.
Cursor supports OAuth for remote Streamable HTTP servers. Follow the browser sign-in prompt; in Cursor Agent you can start it explicitly with `cursor-agent mcp login codealive`.
Back on **Tools & MCP**, authenticate when prompted. The `codealive` server should then show a green status dot.
Open Cursor's chat panel and try:
* "What repositories are available in CodeAlive?"
* "Search for authentication logic in my codebase"
* "Explain the architecture of my project"
### One-Click Install Link
Cursor supports a deeplink that installs an MCP server in one click. Encode the CodeAlive config as base64 JSON and open this URL:
```text theme={null}
cursor://anysphere.cursor-deeplink/mcp/install?name=codealive&config=BASE64_CONFIG
```
Generate `BASE64_CONFIG` from this JSON:
```json theme={null}
{
"url": "https://mcp.codealive.ai/api"
}
```
For example, on macOS / Linux:
```bash theme={null}
echo -n '{"url":"https://mcp.codealive.ai/api"}' | base64
```
Only follow MCP deeplinks from trusted sources — clicking installs and configures a server without further confirmation.
## CodeAlive vs Cursor's built-in codebase search
Cursor's agent has a native `codebase_search` tool backed by a local index of the open workspace. It cannot be disabled in the default Agent mode (tool selection is only available in Custom Modes, and the built-in search has known quirks there), and without instructions the planner will use it for every exploration question — your connected CodeAlive server never gets called.
The two tools are not equivalent:
| | Cursor `codebase_search` | CodeAlive `semantic_search` |
| -------------------- | --------------------------- | ---------------------------------------------------------------------- |
| Scope | The workspace you have open | Every indexed repository and workspace, including ones not checked out |
| Index | Local, per-machine | Server-side, kept in sync with the default branch |
| Cross-repo questions | No | Yes — one query across services |
| Code graph follow-up | No | `get_artifact_relationships`, `fetch_artifacts` |
Since you cannot remove the built-in tool, the working approach is a **precedence rule that names it explicitly**. Vague phrasing ("prefer CodeAlive for search") reliably loses to the planner's default; naming `codebase_search` as the thing to avoid wins. That is what the rule below does.
## Project Rules for CodeAlive
Project rules teach Cursor's agent how to use CodeAlive. The legacy `.cursorrules` file is deprecated — use `.cursor/rules/*.mdc` (MDC format) instead.
Cursor rules have four activation modes, controlled by the `.mdc` frontmatter:
| Mode | Frontmatter | When the rule loads |
| --------------- | --------------------------------------- | ------------------------------------------- |
| Always | `alwaysApply: true` | Every chat and agent run |
| Auto Attached | `globs` set | When matching files are in context |
| Agent Requested | `description` set, `alwaysApply: false` | The agent decides, based on the description |
| Manual | none of the above | Only when you `@`-mention the rule |
For a tool-precedence rule use **Always** — it must be active before the planner picks its first search tool, so an on-demand mode is too late. Keep it short for that same reason: always-on rules are injected into every request.
Create `.cursor/rules/codealive.mdc` in your project:
```markdown theme={null}
---
description: CodeAlive is the primary code search and context engine
alwaysApply: true
---
# CodeAlive context engine
CodeAlive MCP tools search server-side indexes of all our repositories —
cross-repo, always in sync with the default branch.
## Search precedence (important)
- For exploration questions — "how does X work", "where is Y implemented",
"what calls Z" — use CodeAlive `semantic_search` FIRST. Do NOT call the
built-in `codebase_search` or plain grep 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.
- For exact symbol names, string literals, error messages, config keys, and
acronyms use CodeAlive `grep_search` with the literal text (not a question).
- When a result returns an artifact identifier (`repo::path::symbol`), read it
with `fetch_artifacts`; map callers/callees with `get_artifact_relationships`.
- Built-in tools remain fine for files currently being edited in this
workspace; CodeAlive covers indexed history and repos not checked out here.
## Working with results
- Search for existing implementations before writing new code; match the
patterns CodeAlive surfaces.
- When reviewing or refactoring, use `get_artifact_relationships`
(`references_only`) to find all affected call sites across repositories.
```
See [Instructing Coding Agents](/guides/instructing-agents) for the general patterns behind this rule (imperative + trigger, naming the built-in tool, sequencing) and a universal `AGENTS.md` variant that also covers teammates on other agents — Cursor's CLI reads repo-root `AGENTS.md` too. Cursor rules reference: [cursor.com/docs/context/rules](https://cursor.com/docs/context/rules).
## Usage Patterns
```text theme={null}
Cursor AI: "Complete this function based on our codebase patterns"
// Cursor analyzes existing patterns via CodeAlive
// and suggests completions matching your style
```
```text theme={null}
You: "Refactor this service to match our other microservices"
Cursor: [Searches for microservice patterns]
[Suggests refactoring based on architecture]
```
```text theme={null}
You: "Why is this API endpoint failing?"
Cursor: [Traces through related code using CodeAlive]
[Identifies potential issues across files]
```
## Advanced Features
### Multi-File Operations
Cursor can use CodeAlive to work across multiple files:
```text theme={null}
"Show me all files that import UserService"
"Find all API endpoints that call this function"
"List database migrations related to users"
```
```text theme={null}
"What will break if I change this interface?"
"Find all tests affected by this change"
"Show usage of this deprecated method"
```
```text theme={null}
"Find similar error handling patterns"
"Show all authentication middleware"
"Locate all database transactions"
```
## Project vs Global Configuration
Cursor reads MCP servers from two locations:
* **Project-level**: `.cursor/mcp.json` at the workspace root — commit this so the whole team gets the server.
* **Global**: `~/.cursor/mcp.json` — applies to every project on your machine.
If both files define a server with the same name, the project-level entry wins.
### Team Collaboration
Share the project-level config without exposing API keys:
1. Commit `.cursor/mcp.json` referencing an environment variable:
```json theme={null}
{
"mcpServers": {
"codealive": {
"url": "https://mcp.codealive.ai/api",
"headers": {
"Authorization": "Bearer ${CODEALIVE_API_KEY}"
}
}
}
}
```
2. Each teammate exports their own key before launching Cursor:
```bash theme={null}
export CODEALIVE_API_KEY="their_api_key"
```
## Docker Alternative
Run the CodeAlive MCP server locally with Docker (stdio transport):
```json theme={null}
{
"mcpServers": {
"codealive": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "CODEALIVE_API_KEY=YOUR_API_KEY_HERE",
"ghcr.io/codealive-ai/codealive-mcp:main"
]
}
}
}
```
## Productivity Tips
Save recurring CodeAlive prompts as slash commands in `.cursor/commands` for one-tap reuse.
Use CodeAlive for codebases that exceed the model's context limit — semantic search retrieves only the relevant slice.
Use `globs` in `.cursor/rules/*.mdc` to apply CodeAlive guidance only where it matters.
Share `.cursor/rules/codealive.mdc` via git to keep the whole team on the same workflow.
## Troubleshooting
**Solutions:**
1. Check the server status indicator in **Settings → Tools & MCP** (green = healthy, red = failed)
2. Verify your API key is correct and active
3. Reload Cursor: `Cmd/Ctrl+Shift+P → "Developer: Reload Window"`
4. Check network connectivity to `https://mcp.codealive.ai/api`
**Solutions:**
1. Ensure your repositories are fully indexed in the CodeAlive dashboard
2. Wait for indexing to complete
3. Verify the API key has access to the relevant repositories
4. Check repository filters
**Solutions:**
1. Use more specific queries
2. Limit search to specific repositories
3. Check indexing status in dashboard
4. Consider the Docker option for lower-latency local-network deployments
For more solutions, see the [Troubleshooting Guide](/troubleshooting).
## Related Resources
* [Instructing Coding Agents](/guides/instructing-agents)
* [CodeAlive & 1С (1C:Enterprise specifics)](/guides/1c-agents)
* [MCP Overview](/integrations/mcp)
* [Self-Hosting Guide](/integrations/mcp/self-hosting)
* [API Reference](/api-reference/toolapi/list-visible-data-sources)
* [Cursor MCP Documentation](https://cursor.com/docs/context/mcp)
* [Cursor Rules Documentation](https://cursor.com/docs/context/rules)
## 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).
# Gemini CLI
Source: https://docs.codealive.ai/integrations/mcp/gemini-cli
Connect CodeAlive with Google Gemini CLI
## Overview
Connect CodeAlive with Google's Gemini CLI for AI-powered development with deep codebase understanding. Gemini CLI supports a one-command setup — no config files needed.
**Quick install:** Run `npx @codealive/installer` to automatically configure CodeAlive for Gemini CLI.
See the [Installation Guide](/installation) for details.
## Prerequisites
* Gemini CLI installed ([github.com/google-gemini/gemini-cli](https://github.com/google-gemini/gemini-cli))
* CodeAlive account with API key ([Sign up here](https://app.codealive.ai))
* Indexed repositories in your CodeAlive dashboard
## Setup
Run this single command:
```bash theme={null}
gemini mcp add --transport http secure-http https://mcp.codealive.ai/api --header "Authorization: Bearer YOUR_API_KEY_HERE"
```
Replace `YOUR_API_KEY_HERE` with your actual CodeAlive API key. That's it — no config files needed.
Start Gemini CLI and try:
* "Show me all available repositories"
* "Find authentication code in my codebase"
## Community Extension
For an enhanced experience, install the community-built Gemini CLI extension that adds slash commands and workflow guidance:
```bash theme={null}
gemini extensions install https://github.com/akolotov/gemini-cli-codealive-extension
```
This adds:
* `/codealive:chat` — Chat with your codebase
* `/codealive:find` — Search for code
* `/codealive:search` — Semantic search
* `GEMINI.md` guidance for effective CodeAlive usage
### Extension Configuration
Set your API key for the extension:
```bash theme={null}
# Option 1: .env file next to where you run gemini
CODEALIVE_API_KEY="your_codealive_api_key_here"
# Option 2: Environment variable
export CODEALIVE_API_KEY="your_codealive_api_key_here"
```
## Usage
Once connected, Gemini CLI can:
* **Search your codebase** semantically across all indexed repositories
* **Answer architecture questions** with full project context
* **Find patterns and implementations** across multiple services
```
"Find all API endpoints in the user service"
"Explain how the payment flow works"
"Show me error handling patterns across services"
```
## Troubleshooting
1. Verify the server was added: `gemini mcp list`
2. Check your API key is correct
3. Remove and re-add: `gemini mcp remove secure-http` then re-run the add command
1. Verify the extension is installed: `gemini extensions list`
2. Check the `CODEALIVE_API_KEY` is set
3. Restart Gemini CLI
For more solutions, see the [Troubleshooting Guide](/troubleshooting).
## Related Resources
* [MCP Overview](/integrations/mcp)
* [Installation Guide](/installation)
* [Self-Hosting Guide](/integrations/mcp/self-hosting)
* [Agent Skills](/integrations/skills)
## 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).
# Migrate to MCP v3
Source: https://docs.codealive.ai/integrations/mcp/migrate-to-v3
Upgrade a CodeAlive MCP v1 or v2 integration to the eleven-tool MCP v3 contract
MCP v3 moves CodeAlive integrations onto the public Tool API v3 contract. It
adds repository orientation, bounded file reading, relationship traversal, and
metadata analytics while making tool names and arguments consistent across MCP
and the HTTP API.
This guide uses **v1** for the original CodeAlive MCP generation built around
`get_data_sources`, `codebase_search`, and `codebase_consultant`, and **v2** for
the later generation that also exposed canonical search, fetch, and
relationship tools.
The hosted MCP endpoint and existing CodeAlive API keys do not change. For most
remote users, the upgrade is: refresh the MCP configuration, restart the
client, and update any prompts or automation that call old tool names or
arguments.
## What changed
| Area | v1 / v2 | v3 |
| --------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| Tool set | Three core tools in v1; search, fetch, and relationship tools added through v2 | Eleven canonical tools covering orientation, search, traversal, reading, analytics, and synthesis |
| Legacy aliases | `codebase_search`, `codebase_consultant` | Removed from the MCP tool list |
| Semantic-search input | `query` | `question` |
| Data-source readiness | `alive_only` | `ready_only` |
| Relationship profiles | camelCase values such as `callsOnly` | snake\_case values such as `calls_only` |
| Chat state | Optional `conversation_id` | Stateless; include all required context in each `question` |
| Errors | Tool-specific text and transport errors | Repairable failures return actionable `` content and set the MCP result's `isError` flag |
## Migrate with your agent
Paste this prompt into the coding agent you want to migrate. It inventories
every CodeAlive integration available to the agent, upgrades each installed
method, preserves self-hosted addresses, and tests the migrated tools. Mintlify
code blocks include a copy button in the upper-right corner.
```text title="Agent migration prompt" theme={null}
Migrate every CodeAlive integration installed for this user or the current
project to the v3 Tool API. Do the work yourself with the shell, filesystem,
package manager, Docker, and UI tools available to you. Do not stop after
giving me instructions when you can perform the next step safely.
- Never print, copy, or replace API keys, tokens, passwords, private
certificates, or other secrets. Refer to existing credentials without
exposing their values.
- Preserve unrelated agent configuration and create a backup before editing a
configuration file.
- Never replace a self-hosted address with a CodeAlive cloud address.
- Do not install an integration method that was not already present. More than
one method may be installed; update and verify every method you find.
- Do not claim success based only on files, versions, or tool discovery. Run
the verification calls in through every updated integration.
Before changing anything, inspect both user-level and project-level locations
and identify all of the following:
1. CodeAlive MCP configurations used by this agent and any other detected
agents. Determine whether each one uses the hosted remote endpoint, a
self-hosted remote endpoint, Docker, or a source checkout.
2. Every installed copy or symlink of the `codealive-context-engine` Agent
Skill, including copies installed manually or through a skill/plugin
manager.
3. The CodeAlive native Claude Desktop Extension (`codealive-mcp.mcpb`), if it
is installed.
For each installation, record its owning client, scope, installed version or
source, installation path, and whether it uses CodeAlive cloud or self-hosted
CodeAlive. For self-hosted installations, record all non-secret addresses
before updating anything: the MCP endpoint, the CodeAlive deployment origin
used by skills or extensions, and any `CODEALIVE_BASE_URL` value. Redact query
strings, credentials, and authorization headers.
Show me the inventory, then continue with the migration without waiting for
confirmation unless a destructive production operation, elevated permission,
or maintenance-window approval is required.
Update every installation found in :
1. MCP configurations and servers
- For CodeAlive cloud, use `https://mcp.codealive.ai/api/` and keep the
existing credential reference.
- For a standalone Docker or source-based MCP server, update it to the
current v3 release using the existing deployment method. Preserve its
self-hosted `CODEALIVE_BASE_URL`, MCP listen URL, CA trust settings,
network settings, and credential references.
- For the self-hosted CodeAlive deployment described by
`selfhosted/UPGRADE-FROM-EARLY-APRIL-2026.md`, follow that runbook instead
of applying the generic standalone-server procedure. Respect all of its
preflight, backup, maintenance-window, migration, and rollback gates. Its
embedded MCP endpoint after the application upgrade is
`https:///mcp/api`.
- Remove or disable stale v1/v2 duplicates only after the replacement has
the same intended cloud or self-hosted destination.
2. Agent Skills
- Update every installed `codealive-context-engine` copy with its existing
skill/plugin manager. If it has no managed update path, reinstall it from
`CodeAlive-AI/codealive-skills@codealive-context-engine` in the same scope.
- An update may overwrite local URL changes. After every skill update,
restore the recorded self-hosted deployment origin. Prefer setting
`CODEALIVE_BASE_URL=https://` in the same non-secret agent or
process configuration that launches the skill. The skill appends the Tool
API path itself; do not set this value to the MCP endpoint
`https:///mcp/api`.
- If that agent cannot pass `CODEALIVE_BASE_URL`, patch the updated skill's
default cloud origin to the recorded self-hosted deployment origin,
report every patched file, and do not change any credential handling.
3. Claude Desktop Extension
- If the native CodeAlive extension is installed, download and install this
v3 bundle as its replacement:
https://github.com/CodeAlive-AI/codealive-mcp/releases/download/v3.0.2/codealive-mcp.mcpb
- Preserve the existing API-key reference and the recorded CodeAlive Base
URL. For self-hosted CodeAlive, the extension's base URL is the deployment
origin `https://`, not the embedded MCP endpoint.
- Use Claude Desktop UI automation if available. If the extension installer
requires the user to confirm a native dialog, prepare the downloaded file
and ask for only that confirmation.
4. Search project instructions, prompts, automation, and programmatic MCP
calls in scope for v1/v2 names and arguments. Apply the migration mappings
on this page, including `codebase_search` to `semantic_search`,
`codebase_consultant` to `chat`, semantic `query` to `question`,
`alive_only` to `ready_only`, removal of `conversation_id`, and snake_case
relationship profiles. Do not modify historical examples or vendored files
unless they are active inputs.
Verify each updated MCP, Agent Skill, and Claude Desktop Extension path
independently. Do not use a working MCP installation as proof that a separate
skill or extension works.
For each path:
1. Call `get_data_sources` (or run the skill's equivalent data-source script)
and select one ready data source from the actual response.
2. Run `semantic_search` against that data source with the v3 `question`
argument and confirm it returns a successful, non-error response.
3. Take a concrete identifier or text fragment from the response and run
`grep_search` against the same data source. Confirm it returns a successful,
non-error response.
4. For MCP-based paths, confirm the client discovers the eleven canonical v3
tools and does not expose `codebase_search` or `codebase_consultant`.
If there is no ready data source, report that verification is blocked and the
exact action needed; do not substitute a configuration check for these calls.
Determine whether each updated client, extension, MCP process, container, or
agent must restart to reload its configuration or tool list. Restart it when
that is safe and does not terminate this migration session. Otherwise tell me
explicitly:
- exactly which application or process I must restart;
- why the restart is required;
- which verification steps remain pending afterward.
Never silently restart the agent that is running this conversation. Never
declare the migration complete until the required restart has happened and
the post-restart verification calls have passed. If this conversation cannot
survive the restart, give me a short continuation prompt that performs only
the remaining verification.
Report:
- every installation found and whether it was updated;
- the final non-secret cloud or self-hosted URL used by each installation;
- the result of `get_data_sources`, `semantic_search`, and `grep_search` for
each path;
- files or settings changed;
- any required restart or remaining blocker.
```
## Before you upgrade
1. Locate the CodeAlive entry in your agent's MCP configuration.
2. Record whether it uses the hosted endpoint, Docker, or a source checkout.
3. Search project instructions and automation for the removed aliases and old
argument names shown below.
4. Keep your existing API key. Do not paste it into source-controlled config.
Do not keep an old and a new CodeAlive server entry enabled at the same time.
Clients may discover duplicate tools and route calls to the stale server.
## Step 1: upgrade the server connection
Run the installer again and let it update every detected agent:
```bash theme={null}
npx @codealive/installer
```
Review the detected clients, keep **MCP Server** selected, and restart each
client after the installer finishes.
Keep the existing API key and make sure the server URL is exactly:
```text theme={null}
https://mcp.codealive.ai/api/
```
Compare your client configuration with its current setup page under
[MCP integrations](/integrations/mcp). Save the configuration and fully
restart the client so it discards the cached v1/v2 tool list.
Pull and recreate the container from the current image:
```bash theme={null}
docker pull ghcr.io/codealive-ai/codealive-mcp:main
```
If you use Compose, update the image to
`ghcr.io/codealive-ai/codealive-mcp:main`, then run:
```bash theme={null}
docker compose pull
docker compose up -d
```
Preserve `CODEALIVE_API_KEY`, `CODEALIVE_BASE_URL` for self-hosted CodeAlive,
and any network allowlists. See [Self-hosting](/integrations/mcp/self-hosting)
for the current container and HTTP configuration.
Update the checkout, recreate the locked environment, and restart the process:
```bash theme={null}
git pull --ff-only
uv sync --locked
```
Follow the runtime and `uv` versions documented in the current
[MCP repository](https://github.com/CodeAlive-AI/codealive-mcp). If your
deployment pins a release tag, move the pin to the latest `v3.x` release
instead of tracking `main`.
## Step 2: replace removed tool names
Update project rules, system prompts, saved workflows, and programmatic MCP
calls:
| Old tool | v3 replacement | Required adjustment |
| ---------------------------- | ---------------------------- | ------------------------------------------------------------------------ |
| `codebase_search` | `semantic_search` | Rename `query` to `question`; remove `mode` and `description_detail` |
| `codebase_consultant` | `chat` | Remove `conversation_id`; include prior findings and scope in `question` |
| `semantic_search` | `semantic_search` | Rename `query` to `question` |
| `grep_search` | `grep_search` | No required rename; `query` remains the exact text or regex |
| `get_data_sources` | `get_data_sources` | Rename `alive_only` to `ready_only` |
| `fetch_artifacts` | `fetch_artifacts` | No required argument changes |
| `get_artifact_relationships` | `get_artifact_relationships` | Convert `profile` values to snake\_case |
### Search call
```json title="Before (v1 / v2)" theme={null}
{
"tool": "codebase_search",
"arguments": {
"query": "How does request authentication work?",
"data_sources": ["backend"],
"mode": "auto",
"description_detail": "short"
}
}
```
```json title="After (v3)" theme={null}
{
"tool": "semantic_search",
"arguments": {
"question": "How does request authentication work?",
"data_sources": ["backend"]
}
}
```
### Chat call
```json title="Before (v1 / v2)" theme={null}
{
"tool": "codebase_consultant",
"arguments": {
"question": "How does authentication work?",
"data_sources": ["backend"],
"conversation_id": "previous-session-id"
}
}
```
```json title="After (v3)" theme={null}
{
"tool": "chat",
"arguments": {
"question": "Explain authentication in backend. Prior findings: the request enters through AuthController and token validation is performed by AccessTokenValidator. Verify the complete flow and cite relevant artifacts.",
"data_sources": ["backend"]
}
}
```
`chat` is the slowest and most expensive MCP tool. For an agent that can run
several tool calls, prefer `semantic_search` and `grep_search`, then read the
returned identifiers with `fetch_artifacts` and inspect their relationships.
### Relationship profile values
| v2 value | v3 value |
| ----------------- | ------------------ |
| `callsOnly` | `calls_only` |
| `inheritanceOnly` | `inheritance_only` |
| `allRelevant` | `all_relevant` |
| `referencesOnly` | `references_only` |
## Step 3: adopt the new tools
The existing calls can be migrated without using every new capability at once.
Add these tools to agent allowlists and orchestration code when ready:
| New v3 tool | Use it for |
| --------------------------- | --------------------------------------------------- |
| `get_repository_ontology` | High-level orientation for one repository |
| `get_file_tree` | A bounded repository or directory tree |
| `read_file` | Exact-path reading with optional line bounds |
| `get_artifact_query_schema` | Discovering the ArtifactQuery v1 schema |
| `query_artifact_metadata` | Read-only repository metrics and metadata analytics |
The complete v3 set is documented on the [MCP overview](/integrations/mcp) and
in the [Tool API Reference](/api-reference/toolapi/list-visible-data-sources).
## Step 4: update agent instructions
Old prompts often tell the agent to call one broad consultant tool. A v3 prompt
should make direct evidence gathering the default:
```markdown theme={null}
When researching indexed code, use CodeAlive tools in this order:
1. Call `get_data_sources` to resolve repository or workspace names.
2. Use `semantic_search` for behaviour and architecture questions.
3. Use `grep_search` for exact identifiers, strings, errors, and regexes.
4. Read relevant identifiers with `fetch_artifacts` and traverse callers,
callees, inheritance, or references with `get_artifact_relationships`.
5. Use `chat` only when explicitly requested. Every chat call is stateless, so
include all prior findings and scope in its `question`.
```
For production-ready routing rules, see
[Instructing Coding Agents](/guides/instructing-agents).
## Step 5: verify the migration
After restarting the client:
1. Open its MCP tools panel and confirm that CodeAlive exposes **eleven** tools.
2. Confirm `codebase_search` and `codebase_consultant` are absent.
3. Call `get_data_sources` with `{ "ready_only": false }`.
4. Call `semantic_search` with a full English `question` and one returned data
source name.
5. If you automate relationship traversal, exercise at least one snake\_case
profile such as `calls_only`.
6. Trigger one intentionally invalid development call and confirm the client
surfaces a repairable `` instead of treating it as an empty
successful result.
The migration is complete when the client discovers only the canonical v3
tools and no prompt, rule, test fixture, or integration code references the
removed aliases, `conversation_id`, `alive_only`, or camelCase relationship
profiles.
## Troubleshooting
Fully quit and restart the client; many MCP clients cache tool discovery for
the process lifetime. Also check for a second CodeAlive entry that still points
to an old local process or container.
MCP v3 renamed the semantic input to `question`. Keep `query` only for
`grep_search` and for the optional relevance filter on `get_data_sources`.
Replace the v2 camelCase value with its v3 snake\_case equivalent from the table
above.
This is expected in v3: `chat` is stateless. Put the relevant prior findings,
identifiers, scope, and constraints into every new `question`, or keep the
research loop in your own agent and use the direct tools instead.
# OpenClaw
Source: https://docs.codealive.ai/integrations/mcp/openclaw
Connect CodeAlive with OpenClaw for semantic code search and codebase intelligence
## Overview
Integrate CodeAlive with [OpenClaw](https://openclaw.ai/) to give your personal AI agent deep contextual understanding of your entire codebase. OpenClaw supports MCP natively, so CodeAlive tools are available out of the box.
**Quick install:** Run `npx @codealive/installer` to automatically configure CodeAlive for OpenClaw.
See the [Installation Guide](/installation) for details.
## Prerequisites
* [OpenClaw](https://openclaw.ai/) installed and running
* CodeAlive account
* At least one repository added in your CodeAlive dashboard
* CodeAlive API key ([Sign up here](https://app.codealive.ai))
* Indexed repositories in your CodeAlive dashboard
## Installation
Add at least one repository in your CodeAlive dashboard, then get your API key from [app.codealive.ai/settings/api-keys](https://app.codealive.ai/settings/api-keys).
Edit your OpenClaw configuration file at `~/.openclaw/openclaw.json` and add the CodeAlive MCP server under `agents.main.mcpServers`:
**Remote HTTP (recommended):**
```json theme={null}
{
"agents": {
"main": {
"mcpServers": {
"codealive": {
"transport": "streamable-http",
"url": "https://mcp.codealive.ai/api",
"headers": {
"Authorization": "Bearer YOUR_API_KEY_HERE"
}
}
}
}
}
}
```
**Docker (STDIO):**
```json theme={null}
{
"agents": {
"main": {
"mcpServers": {
"codealive": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "CODEALIVE_API_KEY=YOUR_API_KEY_HERE",
"ghcr.io/codealive-ai/codealive-mcp:main"
]
}
}
}
}
}
```
Replace `YOUR_API_KEY_HERE` with your actual API key.
OpenClaw uses JSON5 format — comments and trailing commas are allowed in the config file.
OpenClaw watches `openclaw.json` for changes and applies them automatically. If the server doesn't pick up the new config, restart it.
Ask OpenClaw:
* "What CodeAlive repositories are available?"
* "Search for authentication code in my codebase"
## Available Tools
Once connected, OpenClaw can use these CodeAlive tools:
| Tool | Description |
| ---------------------------- | ------------------------------------------------------------------------------------------- |
| `semantic_search` | Canonical semantic search across indexed repositories |
| `grep_search` | Exact text or regex search with line-level previews |
| `get_repository_ontology` | Repository-level orientation for one selected repository |
| `get_file_tree` | Bounded file tree for one repository |
| `read_file` | Read one repository-relative file path |
| `fetch_artifacts` | Retrieve full source code for search results |
| `get_artifact_relationships` | Expand call graph, inheritance, and references for one artifact |
| `get_artifact_query_schema` | Inspect ArtifactQuery metadata schema |
| `query_artifact_metadata` | Run read-only metadata analytics |
| `chat` | Stateless slower synthesized codebase Q\&A, only when explicitly requested |
| `get_data_sources` | List available repositories and workspaces, optionally relevance-filtered by a task `query` |
## Installing the CodeAlive Skill
For workflow guidance and multi-step exploration patterns, also install the CodeAlive skill:
```bash theme={null}
npx skills add CodeAlive-AI/codealive-skills@codealive-context-engine
```
Or manually copy the skill to OpenClaw's skills directory:
| Scope | Path |
| ------- | ---------------------------------------------- |
| Project | `skills/codealive-context-engine/` |
| User | `~/.openclaw/skills/codealive-context-engine/` |
The skill and MCP server complement each other: the MCP server provides tool access, the skill teaches the agent effective query patterns and cost-aware workflows.
## Publishing to ClawHub
The CodeAlive Context Engine skill is also available on [ClawHub](https://clawhub.ai/), OpenClaw's skill marketplace:
```bash theme={null}
openclaw skills install codealive-context-engine
```
## Troubleshooting
1. Verify your API key is correct
2. Check that `openclaw.json` is valid JSON5 (watch for syntax errors)
3. Ensure `"transport": "streamable-http"` is set for the remote option
4. Check OpenClaw logs for MCP initialization errors
1. Confirm the `codealive` entry is inside `agents.main.mcpServers`
2. Restart OpenClaw if config auto-reload didn't trigger
3. Verify the API key has not expired
Ensure Docker is installed and running:
```bash theme={null}
docker pull ghcr.io/codealive-ai/codealive-mcp:main
```
For more solutions, see the [Troubleshooting Guide](/troubleshooting).
## Related Resources
Learn about Model Context Protocol
Install CodeAlive as an agent skill
Official OpenClaw documentation
OpenClaw skill marketplace
## 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).
# OpenCode
Source: https://docs.codealive.ai/integrations/mcp/opencode
Connect CodeAlive with OpenCode AI terminal assistant
## Overview
Connect CodeAlive with OpenCode — an open-source AI coding assistant that runs in your terminal. OpenCode uses its own JSON configuration format with a `type: remote` transport for HTTP connections.
**Quick install:** Run `npx @codealive/installer` to automatically configure CodeAlive for OpenCode.
See the [Installation Guide](/installation) for details.
## Prerequisites
* OpenCode installed ([github.com/opencode-ai/opencode](https://github.com/opencode-ai/opencode))
* CodeAlive account ([Sign up here](https://app.codealive.ai))
* Indexed repositories in your CodeAlive dashboard
## Setup
OpenCode reads configuration from `opencode.json` in your project root or home directory.
Add this to your `opencode.json`:
```json theme={null}
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"codealive": {
"type": "remote",
"url": "https://mcp.codealive.ai/api",
"enabled": true
}
}
}
```
OpenCode discovers OAuth automatically. Restart OpenCode and follow the browser prompt, or run `opencode mcp auth codealive` explicitly.
OpenCode uses `type: "remote"` for HTTP-based MCP servers, which is different from most other clients that use `type: "http"` or `type: "streamable-http"`.
Existing API-key configurations remain supported. To use one intentionally, set `"oauth": false` and add an `Authorization: Bearer ...` header.
Restart OpenCode to load the new MCP configuration.
Try these commands with OpenCode:
* "Show me all available repositories"
* "Find authentication code in my codebase"
* "Explain how the payment flow works"
## Docker Alternative
If you prefer running the MCP server locally:
```json theme={null}
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"codealive": {
"type": "stdio",
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "CODEALIVE_API_KEY=YOUR_API_KEY_HERE",
"ghcr.io/codealive-ai/codealive-mcp:main"
],
"enabled": true
}
}
}
```
## Usage
Once connected, OpenCode can:
* **Search your codebase** semantically across all indexed repositories
* **Answer architecture questions** with full project context
* **Find patterns and implementations** across multiple services
```
"Find all error handling patterns in the payment service"
"Explain how the user registration flow works"
"Search for database migration code across services"
```
## Troubleshooting
1. Verify the config file is named `opencode.json`
2. Check that `type` is set to `"remote"` (not `"http"`)
3. Ensure `"enabled": true` is set
4. Restart OpenCode
1. Run `opencode mcp auth codealive`
2. Inspect discovery with `opencode mcp debug codealive`
3. If you intentionally use the API-key fallback, verify the key is active and set `"oauth": false`
1. Check your network connection
2. Try the Docker STDIO option for local access
3. Verify the URL is `https://mcp.codealive.ai/api`
For more solutions, see the [Troubleshooting Guide](/troubleshooting).
## Related Resources
* [MCP Overview](/integrations/mcp)
* [Installation Guide](/installation)
* [Self-Hosting Guide](/integrations/mcp/self-hosting)
* [Agent Skills](/integrations/skills)
## 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).
# Other Agents
Source: https://docs.codealive.ai/integrations/mcp/other-agents
Connect CodeAlive with Roo Code, KodaCode, GigaCode, Goose, and more
## Overview
CodeAlive works with any MCP-compatible AI agent. This page covers setup for agents that use standard JSON configuration. For agents with unique setup requirements, see their dedicated pages.
## General Setup
All agents below follow the same pattern:
1. Get your API key from [app.codealive.ai](https://app.codealive.ai/settings/api-keys)
2. Find the agent's MCP config file
3. Add the CodeAlive server configuration
4. Restart the agent
**Quick install:** Run `npx @codealive/installer` to automatically detect and configure CodeAlive for supported agents.
See the [Installation Guide](/installation) for details.
## Agent Configurations
Roo Code reads a JSON settings file similar to Cline.
**Config file:** `mcp_settings.json` (Roo) or `cline_mcp_settings.json`
**Remote HTTP:**
```json theme={null}
{
"mcpServers": {
"codealive": {
"type": "streamable-http",
"url": "https://mcp.codealive.ai/api",
"headers": {
"Authorization": "Bearer YOUR_API_KEY_HERE"
}
}
}
}
```
**Docker (STDIO):**
```json theme={null}
{
"mcpServers": {
"codealive": {
"type": "stdio",
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "CODEALIVE_API_KEY=YOUR_API_KEY_HERE",
"ghcr.io/codealive-ai/codealive-mcp:main"
]
}
}
}
```
If your Roo build doesn't honor HTTP headers, use the Docker STDIO option.
Antigravity uses a Gemini-style config format.
**Config file:** `~/.gemini/antigravity/mcp_config.json`
```json theme={null}
{
"mcpServers": {
"codealive": {
"type": "streamable-http",
"url": "https://mcp.codealive.ai/api",
"headers": {
"Authorization": "Bearer YOUR_API_KEY_HERE"
}
}
}
}
```
KodaCode provides both IDE plugins and Koda CLI. They use different configuration files and MCP formats.
**Config file:** `~/.koda/config.yaml`
The IDE plugin documents command-based MCP servers. Run CodeAlive through Docker using STDIO:
```yaml theme={null}
mcpServers:
- name: "codealive"
command: "docker"
args:
- "run"
- "--rm"
- "-i"
- "-e"
- "CODEALIVE_API_KEY"
- "ghcr.io/codealive-ai/codealive-mcp:main"
env:
CODEALIVE_API_KEY: ${CODEALIVE_API_KEY}
```
Set `CODEALIVE_API_KEY` in the environment before starting the IDE, then open **Koda Settings → MCP**. A **Connected** status confirms the server is available. In Agent mode, open **Tools** to review the discovered CodeAlive tools and their approval policies.
* **User config:** `~/.kodacli/settings.json`
* **Workspace config:** `/.kodacli/settings.json`
Koda CLI supports Streamable HTTP with `httpUrl`:
```json theme={null}
{
"mcpServers": {
"codealive": {
"httpUrl": "https://mcp.codealive.ai/api",
"headers": {
"Authorization": "Bearer ${CODEALIVE_API_KEY}"
}
}
}
}
```
Set `CODEALIVE_API_KEY` in the terminal environment, restart Koda CLI, and run `/mcp` to inspect the connection and available tools.
See the [Koda IDE MCP guide](https://docs.kodacode.ru/plugin/advanced/mcp/index.html) and [Koda CLI configuration reference](https://docs.kodacode.ru/koda-cli/cli/configuration.html).
GigaCode uses the standard `mcpServers` object in its user configuration.
**Config file:** `~/.gigacode/settings.json`
GigaCode's public documentation does not currently specify a remote HTTP configuration format. Use CodeAlive's Docker STDIO transport:
```json theme={null}
{
"mcpServers": {
"codealive": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "CODEALIVE_API_KEY=YOUR_API_KEY_HERE",
"ghcr.io/codealive-ai/codealive-mcp:main"
]
}
}
}
```
Replace `YOUR_API_KEY_HERE`, save the file, and fully restart the IDE. Open GigaCode's agent mode and confirm that CodeAlive MCP tools are available before using them.
External MCP configuration is not covered by the current public GigaCode documentation. The config path and `mcpServers` format are corroborated by [Promptery's GigaCode installer](https://github.com/dzenlotus/promptery). If a newer GigaCode build exposes an MCP settings UI, prefer the UI-generated configuration.
See the [official GigaCode installation guide](https://gitverse.ru/features/gigacode/install/).
Goose uses a UI-based setup flow.
**Setup path:** Settings → MCP Servers → Add → choose Streamable HTTP
**Streamable HTTP configuration:**
* **Name:** `codealive`
* **Endpoint URL:** `https://mcp.codealive.ai/api`
* **Headers:** `Authorization: Bearer YOUR_API_KEY_HERE`
**Docker (STDIO) alternative:**
Add a STDIO extension with:
* **Command:** `docker`
* **Args:** `run --rm -i -e CODEALIVE_API_KEY=YOUR_API_KEY_HERE ghcr.io/codealive-ai/codealive-mcp:main`
Kilo Code uses a UI-based setup.
**Setup path:** Manage → Integrations → Model Context Protocol (MCP) → Add Server
**HTTP:**
```json theme={null}
{
"mcpServers": {
"codealive": {
"type": "streamable-http",
"url": "https://mcp.codealive.ai/api",
"headers": {
"Authorization": "Bearer YOUR_API_KEY_HERE"
}
}
}
}
```
**STDIO (Docker):**
```json theme={null}
{
"mcpServers": {
"codealive": {
"type": "stdio",
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "CODEALIVE_API_KEY=YOUR_API_KEY_HERE",
"ghcr.io/codealive-ai/codealive-mcp:main"
]
}
}
}
```
Qwen Code supports multiple transports (stdio/SSE/streamable-http).
**Config file:** `~/.qwen/settings.json`
**Streamable HTTP:**
```json theme={null}
{
"mcpServers": {
"codealive": {
"type": "streamable-http",
"url": "https://mcp.codealive.ai/api",
"requestOptions": {
"headers": {
"Authorization": "Bearer YOUR_API_KEY_HERE"
}
}
}
}
}
```
**Docker (STDIO):**
```json theme={null}
{
"mcpServers": {
"codealive": {
"type": "stdio",
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "CODEALIVE_API_KEY=YOUR_API_KEY_HERE",
"ghcr.io/codealive-ai/codealive-mcp:main"
]
}
}
}
```
Qwen Code wraps headers in `requestOptions` — different from most other clients.
Kiro does not yet support remote MCP servers natively. Use the `mcp-remote` workaround.
**Prerequisites:**
```bash theme={null}
npm install -g mcp-remote
```
**Config file:** `~/.kiro/settings/mcp.json` or `.kiro/settings/mcp.json` (workspace)
**Remote HTTP (via mcp-remote):**
```json theme={null}
{
"mcpServers": {
"codealive": {
"type": "stdio",
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.codealive.ai/api",
"--header",
"Authorization: Bearer ${CODEALIVE_API_KEY}"
],
"env": {
"CODEALIVE_API_KEY": "YOUR_API_KEY_HERE"
}
}
}
}
```
**Docker (STDIO):**
```json theme={null}
{
"mcpServers": {
"codealive": {
"type": "stdio",
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "CODEALIVE_API_KEY=YOUR_API_KEY_HERE",
"ghcr.io/codealive-ai/codealive-mcp:main"
]
}
}
}
```
Qoder uses a UI-based setup with SSE transport.
**Setup path:** User icon → Qoder Settings → MCP → My Servers → + Add (Agent mode)
**SSE (remote HTTP):**
```json theme={null}
{
"mcpServers": {
"codealive": {
"type": "sse",
"url": "https://mcp.codealive.ai/api",
"headers": {
"Authorization": "Bearer YOUR_API_KEY_HERE"
}
}
}
}
```
**STDIO (Docker):**
```json theme={null}
{
"mcpServers": {
"codealive": {
"type": "stdio",
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "CODEALIVE_API_KEY=YOUR_API_KEY_HERE",
"ghcr.io/codealive-ai/codealive-mcp:main"
]
}
}
}
```
JetBrains AI Assistant requires the `mcp-remote` workaround for remote HTTP MCP servers.
**Prerequisites:**
```bash theme={null}
npm install -g mcp-remote
```
**Setup path:** Settings/Preferences → AI Assistant → Model Context Protocol → Configure
```json theme={null}
{
"mcpServers": {
"codealive": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.codealive.ai/api",
"--header",
"Authorization: Bearer ${CODEALIVE_API_KEY}"
],
"env": {
"CODEALIVE_API_KEY": "YOUR_API_KEY_HERE"
}
}
}
}
```
See [JetBrains MCP Documentation](https://www.jetbrains.com/help/ai-assistant/mcp.html) for more details.
n8n connects via the AI Agent node with MCP tools.
**Setup:**
1. Add an **AI Agent** node to your workflow
2. Configure the agent with MCP tools:
* **Server URL:** `https://mcp.codealive.ai/api`
* **Authorization Header:** `Bearer YOUR_API_KEY_HERE`
3. The server automatically handles n8n's extra parameters (`sessionId`, `action`, `chatInput`, `toolCallId`)
**Example Workflow:**
```
Trigger → AI Agent (with CodeAlive MCP tools) → Process Response
```
n8n middleware is built-in — the server automatically strips n8n's extra parameters before processing tool calls.
## Troubleshooting
1. Verify your API key is correct
2. Check the config file location and JSON syntax
3. Ensure the `Authorization` header includes `Bearer ` prefix
4. Restart the agent completely
Use Docker STDIO instead — it works with every agent that supports MCP:
```json theme={null}
{
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "CODEALIVE_API_KEY=YOUR_API_KEY_HERE",
"ghcr.io/codealive-ai/codealive-mcp:main"
]
}
```
Some agents (Kiro, JetBrains AI) don't support remote HTTP natively. Install `mcp-remote`:
```bash theme={null}
npm install -g mcp-remote
```
Then use the STDIO config with `npx mcp-remote` as the command.
For more solutions, see the [Troubleshooting Guide](/troubleshooting).
## Related Resources
* [MCP Overview](/integrations/mcp)
* [Installation Guide](/installation)
* [Self-Hosting Guide](/integrations/mcp/self-hosting)
* [GitHub Repository](https://github.com/CodeAlive-AI/codealive-mcp)
## 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).
# Self-Hosting Guide
Source: https://docs.codealive.ai/integrations/mcp/self-hosting
Deploy CodeAlive MCP server on your own infrastructure
## Overview
Self-host the CodeAlive MCP server for complete control over your deployment. The MCP server can be deployed using Docker or from source code.
## Prerequisites
* CodeAlive API key from [app.codealive.ai](https://app.codealive.ai)
* Docker (for container deployment) or Python 3.11+ (for source deployment)
## Docker Deployment
The easiest way to self-host CodeAlive MCP:
```bash theme={null}
# Pull the latest image
docker pull ghcr.io/codealive-ai/codealive-mcp:main
# Run the container
docker run -d \
-p 8000:8000 \
--name codealive-mcp \
--restart unless-stopped \
ghcr.io/codealive-ai/codealive-mcp:main
```
### Docker Compose
Create `docker-compose.yml`:
```yaml theme={null}
version: '3.8'
services:
codealive-mcp:
image: ghcr.io/codealive-ai/codealive-mcp:main
container_name: codealive-mcp
ports:
- "8000:8000"
restart: unless-stopped
```
Run with:
```bash theme={null}
docker-compose up -d
```
Clients authenticate each HTTP request with
`Authorization: Bearer YOUR_API_KEY`; do not put one shared API key in the MCP
server environment.
## Source Code Deployment
Deploy from the GitHub repository:
```bash theme={null}
# Clone the repository
git clone https://github.com/CodeAlive-AI/codealive-mcp.git
cd codealive-mcp
# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install dependencies
pip install -e .
# Run the server
python src/codealive_mcp_server.py --transport http --host 0.0.0.0 --port 8000
```
### HTTP Host and Origin protection
Loopback hosts (`localhost`, `127.0.0.1`, `::1`) are accepted by default. If
clients reach the server through another hostname, add that exact host:
```bash theme={null}
export CODEALIVE_MCP_ALLOWED_HOSTS="mcp.codealive.yourcompany.com"
# Only for browser JavaScript callers; normal MCP clients do not send Origin.
export CODEALIVE_MCP_ALLOWED_ORIGINS="https://mcp.codealive.yourcompany.com"
python src/codealive_mcp_server.py --transport http --host 0.0.0.0 --port 8000
```
You can instead repeat `--allowed-host` and `--allowed-origin` on the command
line. Avoid wildcard allowlists on public deployments.
### OAuth 2.1 rollout
Remote HTTP deployments can enable browser authorization without removing legacy API-key
support. OAuth mode publishes MCP Protected Resource Metadata and exchanges each accepted MCP
token for a separate short-lived Tool API token; it never forwards the incoming bearer token.
```bash theme={null}
export CODEALIVE_MCP_OAUTH_ENABLED=true
export CODEALIVE_OAUTH_ISSUER="https://auth.your-codealive-instance.com/"
export CODEALIVE_MCP_RESOURCE="https://mcp.your-codealive-instance.com/api"
export CODEALIVE_TOOL_API_RESOURCE="urn:codealive:tool-api"
export CODEALIVE_OAUTH_INTERNAL_CLIENT_ID="codealive-mcp"
export CODEALIVE_OAUTH_INTERNAL_CLIENT_SECRET="use-a-secret-store"
```
The issuer, resources, internal client ID, and secret must exactly match the CodeAlive
Web.Server `McpOAuth` settings. The internal secret is mandatory and the MCP process fails
closed at startup if it is absent. Persist the Web.Server Data Protection key ring and
OpenIddict certificates across restarts and replicas. Roll out the Web.Server and MCP feature
flags together; neither half-enabled state is a valid steady state.
Rotate the internal credential with a new versioned client ID instead of changing the secret
under the existing ID. First deploy Web.Server with the new pair as
`InternalClientId`/`InternalClientSecret` and the old pair as
`PreviousInternalClientId`/`PreviousInternalClientSecret`. Then roll MCP replicas to the new pair
and remove the previous pair after rollout verification. This overlap prevents old and new
replicas from invalidating one another during a rolling deployment.
OAuth and API-key credential routing is explicit. A token that fails OAuth validation is not
retried as an API key, and an invalid API key is not retried as OAuth.
### Custom Port
To run on a different port:
```bash theme={null}
python src/codealive_mcp_server.py --transport http --host 0.0.0.0 --port 8080
```
## Connecting to Self-Hosted Instance
Once your server is running, configure your AI assistant to use the local URL:
### For Docker
```json theme={null}
{
"mcpServers": {
"codealive": {
"type": "http",
"url": "http://localhost:8000/api"
}
}
}
```
### For Custom Port
```json theme={null}
{
"mcpServers": {
"codealive": {
"type": "http",
"url": "http://localhost:8080/api"
}
}
}
```
## For Self-Hosted CodeAlive Backend
If you're running a self-hosted CodeAlive instance (not just the MCP server), configure the base URL:
### Docker
```bash theme={null}
docker run -d \
-p 8000:8000 \
-e CODEALIVE_BASE_URL=https://your-codealive-instance.com \
-e CODEALIVE_MCP_ALLOWED_HOSTS=mcp.your-codealive-instance.com \
--name codealive-mcp \
ghcr.io/codealive-ai/codealive-mcp:main
```
### Source Code
Set additional environment variable:
```bash theme={null}
export CODEALIVE_BASE_URL="https://your-codealive-instance.com"
export CODEALIVE_MCP_ALLOWED_HOSTS="mcp.your-codealive-instance.com"
python src/codealive_mcp_server.py --transport http --host 0.0.0.0 --port 8000
```
Use the deployment origin as the base URL. `https://host` is preferred. `https://host/api` is also accepted and normalized automatically by the latest MCP server and Claude Desktop extension.
## Basic Troubleshooting
Check:
* API key is correctly set
* Port 8000 is not already in use
* Docker daemon is running
View logs:
```bash theme={null}
docker logs codealive-mcp
```
Check:
* Server is running: `docker ps` or check Python process
* Correct URL in your AI assistant configuration
* Firewall allows connections to the port
Check:
* API key is valid and active
* Environment variable is set correctly
* For self-hosted backend, verify base URL is correct
## WSL2 Networking
This section applies when the MCP server runs inside WSL2 and you connect from Windows-side clients (Claude Desktop, Cursor, VS Code, etc.).
WSL2 runs in a Hyper-V virtual machine with its own network. By default, `localhost` inside WSL2 is **not** the same as `localhost` on Windows. HTTP MCP servers listening on `127.0.0.1` inside WSL2 won't be reachable from Windows clients.
**Fix 1: Enable mirrored networking** (Windows 11 22H2+)
Add to `%USERPROFILE%\.wslconfig`:
```ini theme={null}
[wsl2]
networkingMode=mirrored
```
Then restart WSL:
```bash theme={null}
wsl --shutdown
```
After this, `localhost` is shared between Windows and WSL2 — `http://localhost:8000/api` works from both sides.
**Fix 2: Use WSL2 VM IP**
Run inside WSL:
```bash theme={null}
hostname -I
```
Use the returned IP in your client config instead of `localhost`:
```json theme={null}
{
"mcpServers": {
"codealive": {
"type": "http",
"url": "http://172.x.x.x:8000/api"
}
}
}
```
Also add that exact WSL address to `CODEALIVE_MCP_ALLOWED_HOSTS`; otherwise the
HTTP request guard correctly rejects the non-loopback Host header.
The WSL2 VM IP can change after reboot. Mirrored networking is the more stable solution.
## Security Notes
* Never expose the MCP server directly to the internet
* Keep your API keys secure
* Use HTTPS in production environments
* Consider using a reverse proxy for additional security
## Related Resources
* [MCP Overview](/integrations/mcp)
* [GitHub Repository](https://github.com/CodeAlive-AI/codealive-mcp)
* [API Reference](/api-reference/toolapi/list-visible-data-sources)
# SourceCraft
Source: https://docs.codealive.ai/integrations/mcp/sourcecraft
Connect CodeAlive with SourceCraft Code Assistant and SourceCraft CLI
## Overview
SourceCraft provides two different AI clients with separate MCP configuration formats:
* **SourceCraft Code Assistant for VS Code** uses `mcpServers` and Streamable HTTP.
* **SourceCraft CLI** launches a bundled OpenCode agent with `src code` and uses OpenCode's `mcp` configuration.
Follow the section for the client you use. Configuring one does not configure the other.
## Prerequisites
* A CodeAlive account and [API key](https://app.codealive.ai/settings/api-keys)
* At least one indexed repository or workspace in CodeAlive
* SourceCraft Code Assistant for VS Code or SourceCraft CLI with OpenCode installed
## SourceCraft Code Assistant for VS Code
According to the current [SourceCraft documentation](https://sourcecraft.dev/portal/docs/en/code-assistant/operations/agent/mcp/using-mcp-in-ca) (verified Jul 2026), external MCP server configuration is supported only in the Visual Studio Code extension. The JetBrains plugin is available, but does not currently expose external MCP configuration.
In the Code Assistant chat panel, open **MCP servers** and enable **Enable MCP Servers**.
Select **Edit Global MCP** to open the global `mcp_settings.json` file.
Add the CodeAlive server under `mcpServers`:
```json theme={null}
{
"mcpServers": {
"codealive": {
"type": "streamable-http",
"url": "https://mcp.codealive.ai/api",
"headers": {
"Authorization": "Bearer YOUR_API_KEY_HERE"
},
"disabled": false
}
}
}
```
Replace `YOUR_API_KEY_HERE` with your CodeAlive API key.
Save the file, return to the MCP servers panel, and restart the `codealive` server. Expand the server entry to confirm that its tools were detected.
SourceCraft also supports a project-level `.codeassistant/mcp.json` file. Do not commit an API key to version control; prefer the global configuration when using a literal key.
## SourceCraft CLI with OpenCode
SourceCraft CLI installs an isolated OpenCode binary, but retains OpenCode's standard project configuration, plugins, rules, and tools. The setup below was verified with a project-level `opencode.json` used by `src code`.
Make your CodeAlive API key available to OpenCode in the terminal where you will run SourceCraft CLI.
```bash theme={null}
export CODEALIVE_API_KEY="YOUR_API_KEY_HERE"
```
```powershell theme={null}
$env:CODEALIVE_API_KEY="YOUR_API_KEY_HERE"
```
Create or update `opencode.json` at the repository root:
```json theme={null}
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"codealive": {
"type": "remote",
"url": "https://mcp.codealive.ai/api",
"enabled": true,
"headers": {
"Authorization": "Bearer {env:CODEALIVE_API_KEY}"
}
}
}
}
```
OpenCode replaces `{env:CODEALIVE_API_KEY}` at runtime, so the API key does not need to be stored in the project file.
From the repository root, verify that OpenCode can connect to CodeAlive, then start the agent:
```bash theme={null}
src code -- mcp list
src code
```
The two SourceCraft clients use different MCP schemas. Do not copy the VS Code `mcpServers` configuration into `opencode.json`, or the OpenCode `mcp` configuration into `mcp_settings.json`.
## Try It
Ask SourceCraft Code Assistant or SourceCraft CLI:
* "Show me all available repositories"
* "Find the authentication flow in the indexed repository"
* "Explain what calls this service and fetch the relevant implementations"
## Troubleshooting
1. Confirm that **Enable MCP Servers** is enabled
2. Check that the configuration is inside the top-level `mcpServers` object
3. Validate the JSON syntax and restart the `codealive` server
4. Confirm that you are using the VS Code extension; according to the SourceCraft documentation verified in Jul 2026, the JetBrains plugin does not expose external MCP configuration
1. Run the commands from the directory containing `opencode.json`
2. Confirm that the configuration uses `mcp`, not `mcpServers`
3. Confirm that `type` is `"remote"`
4. Run `src code -- mcp list` to inspect the connection status
1. Confirm that the API key is active in the [CodeAlive dashboard](https://app.codealive.ai/settings/api-keys)
2. For VS Code, include the `Bearer ` prefix in the `Authorization` header
3. For SourceCraft CLI, confirm that `CODEALIVE_API_KEY` is set in the same terminal session used to run `src code`
## Related Resources
* [SourceCraft MCP configuration](https://sourcecraft.dev/portal/docs/en/code-assistant/operations/agent/mcp/using-mcp-in-ca)
* [SourceCraft CLI quickstart](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/cli-quickstart)
* [OpenCode MCP documentation](https://opencode.ai/docs/mcp-servers/)
* [MCP Overview](/integrations/mcp)
* [Instructing Coding Agents](/guides/instructing-agents)
# VS Code + GitHub Copilot
Source: https://docs.codealive.ai/integrations/mcp/vscode
Connect CodeAlive with GitHub Copilot in VS Code using native MCP support
## Overview
GitHub Copilot now has native MCP (Model Context Protocol) support in VS Code! Connect CodeAlive to enhance Copilot with deep understanding of your entire codebase.
**Quick install:** Run `npx @codealive/installer` to automatically configure CodeAlive for VS Code.
See the [Installation Guide](/installation) for details.
## Prerequisites
* VS Code version 1.102 or higher
* GitHub Copilot Business or Enterprise subscription (MCP access controlled by organization administrators)
* CodeAlive account with API key ([Sign up here](https://app.codealive.ai))
* Indexed repositories in your CodeAlive dashboard
MCP is disabled by default in Copilot. Your organization administrator must enable it via policy settings.
## Setup
GitHub Copilot supports multiple MCP transports (stdio, HTTP Stream, SSE):
1. Open Command Palette (Cmd/Ctrl+Shift+P)
2. Run: **"GitHub Copilot: Add MCP Server"**
3. Choose **"HTTP Stream"** server type (recommended)
4. Enter configuration:
```json theme={null}
{
"servers": {
"codealive": {
"type": "http",
"url": "https://mcp.codealive.ai/api",
"headers": {
"Authorization": "Bearer YOUR_API_KEY_HERE"
}
}
}
}
```
Replace `YOUR_API_KEY_HERE` with your actual CodeAlive API key
Test in GitHub Copilot Chat:
* Open Copilot Chat (Cmd/Ctrl+I)
* Ask: "What repositories are available in CodeAlive?"
* Try: "Search for authentication code in my codebase"
## Using CodeAlive with Copilot
### In Copilot Chat
The MCP integration automatically provides context:
```
You: Explain how the user authentication works in this project
Copilot: [Uses CodeAlive to search for auth code]
[Provides explanation with actual code references]
```
### Enhanced Features
With CodeAlive connected, Copilot can:
* Search across your entire codebase
* Understand project architecture
* Find similar implementations
* Generate code matching your patterns
## Alternative: Local MCP Server
Run CodeAlive MCP locally with Docker:
```bash theme={null}
docker run -d \
-p 8000:8000 \
-e CODEALIVE_API_KEY=YOUR_API_KEY \
--name codealive-mcp \
ghcr.io/codealive-ai/codealive-mcp:main
```
Then configure MCP to use local server:
```json theme={null}
{
"servers": {
"codealive": {
"type": "http",
"url": "http://localhost:8000/api",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
```
## Configuration Options
### Workspace Settings
Add to `.vscode/settings.json`:
```json theme={null}
{
"github.copilot.enable": {
"*": true
},
"mcp.servers": {
"codealive": {
"type": "http",
"url": "https://mcp.codealive.ai/api",
"headers": {
"Authorization": "Bearer ${env:CODEALIVE_API_KEY}"
}
}
}
}
```
### Team Setup
For teams, use environment variables:
1. Add to `.vscode/settings.json`:
```json theme={null}
{
"mcp.servers.codealive.headers.Authorization": "Bearer ${env:CODEALIVE_API_KEY}"
}
```
2. Each team member sets:
```bash theme={null}
export CODEALIVE_API_KEY="their_api_key"
```
## Troubleshooting
**Common causes:**
* MCP is disabled by organization policy (default)
* Using Individual plan (requires Business/Enterprise)
* VS Code version \< 1.102
**Solutions:**
1. Contact your GitHub organization administrator to enable MCP
2. Upgrade to Copilot Business or Enterprise
3. Update VS Code to version 1.102+
4. Update GitHub Copilot extensions to latest versions
**Solutions:**
1. Verify MCP server is configured
2. Check API key is valid
3. Run "MCP: List Servers" to verify CodeAlive is listed
4. Try removing and re-adding the server
**Solutions:**
1. Regenerate API key in CodeAlive dashboard
2. Ensure "Bearer " prefix is included
3. Check for typos in configuration
4. Test API key with curl
For more solutions, see the [Troubleshooting Guide](/troubleshooting).
## Best Practices
Regularly sync repositories in CodeAlive dashboard
Be specific when asking Copilot to search
Let CodeAlive provide context for large codebases
Share workspace settings for team alignment
## Related Resources
* [GitHub Copilot Docs](https://docs.github.com/copilot)
* [MCP Overview](/integrations/mcp)
* [CodeAlive Dashboard](https://app.codealive.ai)
* [Self-Hosting Guide](/integrations/mcp/self-hosting)
## 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).
# Windsurf
Source: https://docs.codealive.ai/integrations/mcp/windsurf
Connect CodeAlive with Windsurf AI coding assistant
## Overview
Connect CodeAlive with Windsurf (by Codeium) to enhance your AI coding assistant with deep contextual understanding of your entire codebase. Windsurf uses a unique MCP configuration with `serverUrl` instead of `url`.
**Quick install:** Run `npx @codealive/installer` to automatically configure CodeAlive for Windsurf.
See the [Installation Guide](/installation) for details.
## Prerequisites
* Windsurf installed ([windsurf.com](https://windsurf.com))
* CodeAlive account with API key ([Sign up here](https://app.codealive.ai))
* Indexed repositories in your CodeAlive dashboard
## Setup
Windsurf reads MCP configuration from:
```
~/.codeium/windsurf/mcp_config.json
```
Create the file if it doesn't exist.
Add this to `~/.codeium/windsurf/mcp_config.json`:
```json theme={null}
{
"mcpServers": {
"codealive": {
"type": "streamable-http",
"serverUrl": "https://mcp.codealive.ai/api",
"headers": {
"Authorization": "Bearer YOUR_API_KEY_HERE"
}
}
}
}
```
Windsurf uses `serverUrl` (not `url`). Using the wrong key will silently fail.
```json theme={null}
{
"mcpServers": {
"codealive": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "CODEALIVE_API_KEY=YOUR_API_KEY_HERE",
"ghcr.io/codealive-ai/codealive-mcp:main"
]
}
}
}
```
Replace `YOUR_API_KEY_HERE` with your actual CodeAlive API key.
Close and reopen Windsurf to load the new MCP configuration.
In Windsurf's AI chat, try:
* "What repositories are available in CodeAlive?"
* "Search for authentication code in my codebase"
## Usage
Once connected, Windsurf's AI assistant can:
* **Search your codebase** semantically across all indexed repositories
* **Answer architecture questions** with full project context
* **Find patterns and implementations** across multiple services
```
"Find all API endpoints in the user service"
"Explain how the payment flow works"
"Show me error handling patterns"
```
## Troubleshooting
1. Verify you're using `serverUrl` (not `url`) in the config
2. Check that the config file is at `~/.codeium/windsurf/mcp_config.json`
3. Ensure the `type` is `streamable-http`
4. Restart Windsurf completely
1. Verify your API key is correct
2. Ensure the `Authorization` header includes `Bearer ` prefix
3. Try regenerating your API key in the [dashboard](https://app.codealive.ai)
For more solutions, see the [Troubleshooting Guide](/troubleshooting).
## Related Resources
* [MCP Overview](/integrations/mcp)
* [Installation Guide](/installation)
* [Self-Hosting Guide](/integrations/mcp/self-hosting)
* [Agent Skills](/integrations/skills)
## 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).
# Zed
Source: https://docs.codealive.ai/integrations/mcp/zed
Connect CodeAlive with the Zed Agent using remote MCP
## Overview
Zed supports remote MCP servers directly. Connect the Zed Agent to CodeAlive over HTTP to search indexed repositories and retrieve code context without running a local MCP process.
Older CodeAlive instructions used Docker because Zed previously supported only local STDIO servers. Current Zed releases support remote servers with a URL and custom HTTP headers.
## Prerequisites
* A current version of [Zed](https://zed.dev/download)
* A CodeAlive account and [API key](https://app.codealive.ai/settings/api-keys)
* At least one indexed repository or workspace in CodeAlive
* An LLM configured for the Zed Agent
## Remote MCP Setup
Open **Settings → AI → MCP Servers**, click **Add Server**, and choose **Add Remote Server**.
You can also run `agent: open settings`, select **MCP Servers**, or run `zed: open settings file` to edit the JSON directly.
Add CodeAlive under `context_servers` in your user `settings.json`:
```json theme={null}
{
"context_servers": {
"codealive": {
"url": "https://mcp.codealive.ai/api",
"headers": {
"Authorization": "Bearer YOUR_API_KEY_HERE"
}
}
}
}
```
Replace `YOUR_API_KEY_HERE` with your CodeAlive API key. Zed's remote MCP format does not require a `type` field.
Return to **Settings → AI → MCP Servers** and find `codealive`. A green indicator with the tooltip **Server is active** confirms that Zed loaded the server and discovered its tools.
Zed stores custom remote MCP headers in `settings.json`. Use the user settings file and do not commit an API key in project-level `.zed/settings.json`.
## Docker Alternative
If direct remote HTTP access is unavailable on your network, run CodeAlive through Docker using Zed's local MCP format:
```json theme={null}
{
"context_servers": {
"codealive": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "CODEALIVE_API_KEY=YOUR_API_KEY_HERE",
"ghcr.io/codealive-ai/codealive-mcp:main"
],
"env": {}
}
}
}
```
Docker must be installed and running before Zed starts this server.
## Tool Permissions
Zed asks for confirmation before tool calls by default. Review each CodeAlive tool call before approving it. If you customize Zed's permissions, MCP tool keys use this format:
```text theme={null}
mcp:codealive:
```
For example, `mcp:codealive:semantic_search` identifies the CodeAlive semantic search tool.
## Try It
Ask the Zed Agent:
* "Use CodeAlive to show me all available repositories"
* "Use CodeAlive semantic search to find the authentication flow"
* "Find callers of this service and fetch the relevant implementations"
Mentioning CodeAlive by name helps the model select its MCP tools. For consistent routing, add instructions telling the agent to prefer `semantic_search` and `grep_search` for indexed-code exploration.
## Troubleshooting
1. Check that `codealive` is inside the top-level `context_servers` object
2. Confirm that the URL is `https://mcp.codealive.ai/api`
3. Validate the JSON syntax and reopen **Settings → AI → MCP Servers**
4. Update Zed if **Add Remote Server** is not available
1. Confirm that the API key is active in the [CodeAlive dashboard](https://app.codealive.ai/settings/api-keys)
2. Ensure the `Authorization` value begins with `Bearer `
3. Check that the API key contains no surrounding spaces or copied quotation marks
1. Confirm that the server indicator is green
2. Mention CodeAlive explicitly in the prompt
3. Check that tool permissions do not deny `mcp:codealive:*`
4. Add CodeAlive routing guidance to your project or global agent instructions
## Related Resources
* [Zed MCP documentation](https://zed.dev/docs/ai/mcp)
* [MCP Overview](/integrations/mcp)
* [Instructing Coding Agents](/guides/instructing-agents)
* [Self-Hosting Guide](/integrations/mcp/self-hosting)
# Claude Code Plugin
Source: https://docs.codealive.ai/integrations/plugin-claude-code
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
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.
## 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
In Claude Code, run:
```
/plugin marketplace add CodeAlive-AI/codealive-skills
```
```
/plugin install codealive@codealive-marketplace
```
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"
```
Start a new Claude Code session and ask:
* "What CodeAlive repositories are available?"
* "Search for authentication code in my codebase"
## 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 |
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.
## 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
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
Run the setup script:
```bash theme={null}
python setup.py
```
Or set the environment variable:
```bash theme={null}
export CODEALIVE_API_KEY="your_key"
```
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
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."
For more solutions, see the [Troubleshooting Guide](/troubleshooting).
## Related Resources
Add MCP server alongside the plugin
Universal skill for all agents
Plugin source code
Manage your repositories
# Share the plugin with Codex CLI
Source: https://docs.codealive.ai/integrations/share-plugin-with-codex
Reuse the Claude Code plugin's skill from Codex CLI and other skill-aware agents, with a launchd agent that follows every plugin update.
## Overview
The [CodeAlive Claude Code plugin](/integrations/plugin-claude-code) ships the
`codealive-context-engine` skill along with a subagent and authentication
hook. Claude Code installs it into a versioned cache directory. Other
skill-aware agents — Codex CLI, Gemini CLI, Cursor, Windsurf — look for skills
in their own user directories and don't read the Claude Code plugin cache.
This guide sets up a one-time bridge so those agents pick up the exact same
skill files the plugin installs, and keeps following new versions every time
you run `claude plugin update`.
You only need this if you want a single source of truth for the skill across
multiple agents. If you use Codex (or another agent) in isolation, the simpler
option is to run the universal installer:
```bash theme={null}
npx skills add CodeAlive-AI/codealive-skills@codealive-context-engine
```
See the [Agent Skills & Plugins](/integrations/skills) page for details.
## How it works
A symlink from `~/.codex/skills/codealive-context-engine` points into the
plugin's versioned cache at `~/.claude/plugins/cache/codealive-marketplace/codealive//skills/codealive-context-engine`.
Codex CLI loads the skill through the symlink.
Each `claude plugin update` writes a new versioned directory and leaves the old
one in place, so the symlink's target becomes stale. A `launchd` agent watches
the parent cache directory and re-runs a short shell script that rewrites the
symlink to the highest version currently on disk.
## Prerequisites
* macOS with the [Claude Code plugin installed](/integrations/plugin-claude-code)
* Codex CLI (or another skill-aware agent)
* The `codealive-skills` repository cloned locally, so you can run the bridge scripts:
```bash theme={null}
git clone https://github.com/CodeAlive-AI/codealive-skills.git
```
## Install (macOS)
```bash theme={null}
cd codealive-skills/tools/plugin-bridge
./install-macos.sh
```
The installer renders `com.codealive.plugin-bridge.plist`, writes it to
`~/Library/LaunchAgents/`, bootstraps the agent, and creates the symlink
once synchronously so it's ready immediately.
```bash theme={null}
ls -la ~/.codex/skills/codealive-context-engine
```
The output should show a symlink pointing into
`~/.claude/plugins/cache/codealive-marketplace/codealive//skills/codealive-context-engine`.
```bash theme={null}
launchctl print "gui/$(id -u)/com.codealive.plugin-bridge" | head
```
You should see `state = waiting` (the expected idle state for a `WatchPaths`
agent) and the watched path listed.
From any shell, run:
```bash theme={null}
claude plugin update codealive@codealive-marketplace
```
Then re-check the symlink — it should now point at the newer version.
The bridge also writes a line per relink to `/tmp/codealive-plugin-bridge.log`.
## Targeting a different agent
The scripts default to Codex CLI. Every path is driven by an environment
variable, so you can point the bridge at any agent.
| Variable | Default |
| -------------------------- | --------------------------------------------------------- |
| `CODEALIVE_PLUGIN_CACHE` | `~/.claude/plugins/cache/codealive-marketplace/codealive` |
| `CODEALIVE_PLUGIN_SUBPATH` | `skills/codealive-context-engine` |
| `CODEALIVE_AGENT_LINK` | `~/.codex/skills/codealive-context-engine` |
Example for Gemini CLI:
```bash theme={null}
CODEALIVE_AGENT_LINK=~/.gemini/skills/codealive-context-engine ./install-macos.sh
```
`launchd` starts `update-symlink.sh` through `/bin/bash` and does not inherit
your interactive shell environment. If you customise a variable, either edit
the defaults inside `update-symlink.sh`, set them in `~/.zshenv` (which is
read by non-login bash on macOS when sourced explicitly), or add an
`EnvironmentVariables` dictionary to the plist before installing.
## Linux
A `systemd --user` path unit gives the equivalent behaviour. See the
[Linux section of the bridge README](https://github.com/CodeAlive-AI/codealive-skills/tree/main/tools/plugin-bridge#linux)
for ready-to-use unit files.
## Uninstall
```bash theme={null}
cd codealive-skills/tools/plugin-bridge
./uninstall-macos.sh
```
This removes the `launchd` agent. The existing symlink stays in place; delete
it manually if you want to remove it as well:
```bash theme={null}
rm ~/.codex/skills/codealive-context-engine
```
## Troubleshooting
Confirm the symlink resolves to a directory that contains `SKILL.md`:
```bash theme={null}
ls -la "$(readlink ~/.codex/skills/codealive-context-engine)"
```
If the link is dangling, check that the Claude Code plugin is installed
(`claude plugin list`) and that
`~/.claude/plugins/cache/codealive-marketplace/codealive/` contains at
least one version directory.
Inspect the bridge log:
```bash theme={null}
tail /tmp/codealive-plugin-bridge.log /tmp/codealive-plugin-bridge.err
```
Re-run the updater manually to confirm the logic:
```bash theme={null}
bash codealive-skills/tools/plugin-bridge/update-symlink.sh
```
If the manual run relinks correctly but the `launchd` agent didn't fire,
reload it:
```bash theme={null}
launchctl bootout "gui/$(id -u)/com.codealive.plugin-bridge" || true
launchctl bootstrap "gui/$(id -u)" ~/Library/LaunchAgents/com.codealive.plugin-bridge.plist
```
Another `launchd` job is already loaded under the same label. Boot it out
first:
```bash theme={null}
launchctl bootout "gui/$(id -u)/com.codealive.plugin-bridge"
./install-macos.sh
```
`claude plugin update` doesn't delete prior versions. The bridge always
picks the highest version by `sort -V`, so older directories don't affect
behaviour. Remove them manually if you want to reclaim disk space:
```bash theme={null}
ls ~/.claude/plugins/cache/codealive-marketplace/codealive
# keep the latest, remove anything older
```
For general integration issues, see the [Troubleshooting Guide](/troubleshooting).
## Related resources
Install the plugin this bridge depends on
Install the skill directly via the universal installer
Scripts, launchd template, and Linux unit files
Direct tool access for Codex via MCP
# Agent Skills & Plugins
Source: https://docs.codealive.ai/integrations/skills
Install CodeAlive skills for intelligent codebase exploration patterns
## Overview
CodeAlive offers three integration methods that complement each other:
**Provides tools.** Gives your agent direct access to the v3 Tool API set via the Model Context Protocol: `get_data_sources`, `semantic_search`, `grep_search`, repository ontology/tree/read tools, `fetch_artifacts`, `get_artifact_relationships`, ArtifactQuery tools, and stateless `chat`.
**Teaches workflows.** Teaches your agent effective query patterns, cost-aware tool selection, and multi-step exploration workflows.
**Bundles everything.** Includes the skill plus authentication hooks and a code exploration subagent. Claude Code only.
The skill and MCP server work best together: the MCP server provides the tools, and the skill teaches the agent how to use them effectively.
## Installing the Skill
The universal installer auto-detects your agents and installs the skill:
```bash theme={null}
npx @codealive/installer
```
Select "CodeAlive Skill" when prompted. See the [Installation Guide](/installation) for details.
Install the skill directly using the skills CLI:
```bash theme={null}
npx skills add CodeAlive-AI/codealive-skills@codealive-context-engine
```
This works with any agent that supports the [skills.sh](https://skills.sh/) standard.
Copy the `skills/codealive-context-engine` folder into your agent's skills directory:
| Agent | Project scope | User scope |
| -------------- | ------------------- | ----------------------------- |
| Claude Code | `.claude/skills/` | `~/.claude/skills/` |
| Cursor | `.cursor/skills/` | `~/.cursor/skills/` |
| GitHub Copilot | `.github/skills/` | `~/.copilot/skills/` |
| Windsurf | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` |
| Gemini CLI | `.gemini/skills/` | `~/.gemini/skills/` |
| Codex | `.codex/skills/` | `~/.codex/skills/` |
| Goose | `.goose/skills/` | `~/.config/goose/skills/` |
| Amp | `.agents/skills/` | `~/.config/agents/skills/` |
| Roo Code | `.roo/skills/` | `~/.roo/skills/` |
| OpenCode | `.opencode/skill/` | `~/.config/opencode/skill/` |
| OpenClaw | `skills/` | `~/.openclaw/skills/` |
## Installing the Claude Code Plugin
For Claude Code users, the plugin provides the best experience — it includes the skill plus Claude-specific enhancements.
In Claude Code, run:
```
/plugin marketplace add CodeAlive-AI/codealive-skills
```
```
/plugin install codealive@codealive-marketplace
```
The plugin includes:
* The CodeAlive Context Engine skill
* Authentication hooks for automatic API key injection
* A code exploration subagent for guided analysis
Already using the plugin in Claude Code and want another agent (for example Codex CLI) to load the same skill files? See [Share the plugin with Codex CLI](/integrations/share-plugin-with-codex) for a symlink-based bridge that follows every `claude plugin update`.
## Setup & Authentication
After installing, run the interactive setup:
```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 securely in your OS credential store.
For self-hosted CodeAlive, set `CODEALIVE_BASE_URL` to your deployment origin, for example `https://codealive.yourcompany.com`. `https://host/api` is also accepted and normalized automatically.
### API Key Resolution 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"` |
## Available Tools
The skill provides local scripts for the complete Tool API v3 workflow plus an offline version check:
| Tool | Script | Speed | Cost | Best For |
| -------------------------- | ------------------ | ------- | ---- | -------------------------------------------------------------------------------------- |
| **List Data Sources** | `datasources.py` | Instant | Free | Discovering indexed repos and workspaces |
| **Semantic Search** | `search.py` | Fast | Low | Finding relevant artifacts by meaning |
| **Grep Search** | `grep.py` | Fast | Low | Exact text and regex matches with line previews |
| **Fetch Artifacts** | `fetch.py` | Fast | Low | Retrieving full content for search results |
| **Artifact Relationships** | `relationships.py` | Fast | Low | Expanding call graph, inheritance, and references for one artifact |
| **Chat with Codebase** | `chat.py` | Slow | High | Synthesized answers, architectural explanations |
| **Get Version** | `get_version.py` | Instant | Free | Return the installed skill version as JSON without authentication or a network request |
Check the installed version locally:
```bash theme={null}
python scripts/get_version.py
# {"name": "codealive-context-engine", "version": "3.0.0"}
```
**Cost guidance:** `semantic_search` and `grep_search` should be the default starting point. Chat invokes an LLM on the server side, is stateless in v3, can take substantially longer than retrieval, and is usually unnecessary unless you specifically request a synthesized answer after search.
## Supported Agents
The skill works with 30+ agents that support the [skills.sh](https://skills.sh/) standard, including:
Cursor, GitHub Copilot, Windsurf, Gemini CLI, Codex, Goose, Amp, Roo Code, OpenCode, OpenClaw, Claude Code, and many more.
## Troubleshooting
Run the setup script:
```bash theme={null}
python setup.py
```
Or set the environment variable:
```bash theme={null}
export CODEALIVE_API_KEY="your_key"
```
1. Verify the skill files are in the correct directory for your agent
2. Check that the `SKILL.md` file exists in the skill folder
3. Restart your agent
The skill requires Python 3.8+. No third-party packages are needed — it uses only the standard library.
If the OS credential store fails:
* macOS: Ensure Keychain Access is unlocked
* Linux: Install `libsecret-tools` (`sudo apt install libsecret-tools`)
* Windows: Run as Administrator
* Fallback: Use the `CODEALIVE_API_KEY` environment variable
For more solutions, see the [Troubleshooting Guide](/troubleshooting).
## Related Resources
Universal installer for all components
Set up the MCP server for direct tool access
Skills source code
Agent skills standard
# Quickstart
Source: https://docs.codealive.ai/quickstart
Get started with CodeAlive in minutes
## Start Using CodeAlive in Three Simple Steps
Transform your AI coding experience with deep contextual understanding of your codebase.
Add at least one repository before connecting an assistant. Current remote MCP clients can use browser OAuth without an API key; API keys remain available for direct API, Docker, and compatibility setups. Chat and search become useful after your repository is indexed.
1. Visit [app.codealive.ai](https://app.codealive.ai) to create your account
2. Complete the registration process
Once logged in:
1. Navigate to the **Data Sources** section
2. Connect your GitHub, GitLab, or Bitbucket repositories
3. Select at least one repository to add to CodeAlive
4. CodeAlive will begin building your codebase knowledge graph
Once at least one repository has been added, you can create an API key right away. Initial indexing typically takes 5-15 minutes depending on repository size.
1. Navigate to **MCP & API** in the dashboard
2. Click **"+ Create API Key"**
3. Copy your key immediately (it won't be displayed again)
Save your API key securely. You will need it to connect your AI assistants, and it cannot be retrieved later.
Choose your preferred integration method:
### One-Command Setup
The installer auto-detects your AI agents and configures CodeAlive:
```bash theme={null}
npx @codealive/installer
```
Supports Claude Code, Cursor, VS Code, Windsurf, Cline, Codex, and more. See the [Installation Guide](/installation) for details.
### Model Context Protocol Setup
For an OAuth-capable remote MCP client:
```json theme={null}
{
"mcpServers": {
"codealive": {
"url": "https://mcp.codealive.ai/api"
}
}
}
```
Your client opens CodeAlive in a browser for sign-in and consent. If it does not prompt automatically, use its MCP login command. The agent-specific guides include exact steps and an API-key fallback.
See [MCP Integration](/integrations/mcp) for agent-specific instructions.
### Direct API Integration
Use CodeAlive's REST API directly:
```bash theme={null}
curl -X POST https://app.codealive.ai/api/tools/chat \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"question": "Explain the authentication flow. Prior context: none.",
"data_sources": ["your-repo-name"],
"output_format": "agentic"
}'
```
### Local Docker Setup
Run CodeAlive MCP server locally:
```bash theme={null}
docker run -p 8000:8000 \
-e CODEALIVE_API_KEY=YOUR_API_KEY \
ghcr.io/codealive-ai/codealive-mcp:main
```
Wait until your repository finishes indexing before expecting useful chat or search results.
Try these example queries:
* "Find all authentication-related code"
* "Show me error handling patterns in the payment service"
* "Locate database connection configurations"
Engage in deep technical discussions:
* "How does the user registration flow work?"
* "What are the potential security vulnerabilities in the API endpoints?"
* "Suggest improvements for the caching strategy"
Get AI-powered code reviews:
* "Review this pull request for best practices"
* "Check for potential performance issues"
* "Identify code duplication across the codebase"
## Integration Guides
One-command installer for all agents
Set up CodeAlive with Claude Code
Integrate CodeAlive into Cursor
Use CodeAlive with GitHub Copilot in VS Code
20+ agent integrations including Windsurf, Codex, Gemini CLI, and more
Explore the full API documentation
## Key Benefits
CodeAlive's context engine dramatically improves AI response times by providing pre-indexed, semantically organized code knowledge.
Analyze relationships across multiple repositories simultaneously, perfect for microservices architectures.
Support for all programming languages and frameworks in your tech stack.
## Troubleshooting
* Ensure you have proper access permissions to the repository
* Check that the repository is not empty
* For private repos, verify your GitHub/GitLab/Bitbucket integration is properly configured
* Verify you're using the correct API key from your dashboard
* Make sure you have added at least one repository before trying to create a key
* Check that your account is active
* Ensure proper formatting in your configuration (Bearer token in Authorization header)
* Initial repository indexing may take time for large codebases
* Check your network connection
* Contact [support@codealive.ai](mailto:support@codealive.ai) if issues persist
## Next Steps
Learn about CodeAlive's architecture
Optimize your CodeAlive setup
Get help from our team
# Tips & Tricks
Source: https://docs.codealive.ai/tips-and-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
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" |
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?"
```
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"
```
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.
## Search Optimization
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 |
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.
`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
## Workspace Organization
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.
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.
## Cost & Token Optimization
`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 |
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?" |
## Agent-Specific Tips
* 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
* 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
* Config uses `serverUrl` — not `url` — different from other agents
* Supports Streamable HTTP transport
* Check Windsurf's MCP settings page for connection status
* 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.
```
* 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
## What's Next
See real-world usage patterns
Solutions for common issues
# Troubleshooting
Source: https://docs.codealive.ai/troubleshooting
Solutions for common issues with CodeAlive
## Quick Diagnostics
Run these commands to quickly identify where the problem is:
**Test your API key:**
```bash theme={null}
curl -s -o /dev/null -w "%{http_code}" \
-X POST \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}' \
https://app.codealive.ai/api/tools/get_data_sources
```
Expected: `200`. If you get `401`, your API key is invalid or expired.
**Test remote MCP server:**
```bash theme={null}
curl -s -o /dev/null -w "%{http_code}" https://mcp.codealive.ai/api/
```
Expected: `200` or `405`. If the connection times out, check your network/firewall.
**Test local Docker container:**
```bash theme={null}
curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/api/
```
Expected: `200` or `405`. If connection refused, the container isn't running.
**List your data sources (verify repos are indexed):**
```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}' \
https://app.codealive.ai/api/tools/get_data_sources
```
Expected: a JSON array of your indexed repositories.
## FAQ and common issues
CodeAlive indexes source code, configuration, documentation, and other supported text-based files. It respects `.gitignore` and automatically removes common low-value content such as vendored dependencies, minified assets, and source maps. Binary or unsupported formats are skipped.
For tracked, project-specific content that should not appear in CodeAlive search, add its paths or patterns to `.codealiveignore` using `.gitignore` syntax. See [Prepare your repository](/code-preparation) for the supported-file rules and realistic examples.
**Symptoms:** Repository appears in dashboard but shows no indexed content, or indexing seems stuck.
**Solutions:**
1. Check that the repository is not empty and contains code files
2. Verify your GitHub/GitLab/Bitbucket connection is still authorized
3. Check repository permissions — CodeAlive needs read access
4. For large repositories, initial indexing can take 15+ minutes — check the status indicator in the dashboard
5. Try removing and re-adding the repository
**Symptoms:** `401 Unauthorized` responses, "invalid API key" errors.
**Solutions:**
1. Verify the key format — it should be passed as `Bearer YOUR_KEY` in the Authorization header
2. Make sure at least one repository has been added to your organization before creating the key
3. Generate a new key in the dashboard under **MCP & API** → **+ Create API Key**
4. Check for extra whitespace or line breaks when copying the key
5. Ensure the key hasn't been revoked — only active keys work
6. Test with curl:
```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}' \
https://app.codealive.ai/api/tools/get_data_sources
```
**Symptoms:** Agent can't find CodeAlive tools, connection errors, timeouts.
**Solutions:**
1. Verify the URL is exactly `https://mcp.codealive.ai/api/` (trailing slash matters for some agents)
2. Check your network — some corporate firewalls block MCP connections
3. Restart your AI agent after changing MCP configuration
4. For Docker: ensure the container is running with `docker ps`
5. For Docker: verify port mapping — default is `8000:8000`
**Symptoms:** AI agent doesn't use `semantic_search` / `grep_search` / `chat`, says tools aren't available.
**Solutions:**
1. Restart your AI agent — most agents only load MCP config at startup
2. Check config file syntax — a missing comma or bracket breaks the whole file
3. Verify the config file is in the right location (varies by agent — see [integration guides](/integrations/mcp))
4. In Cursor: check **Settings → Features → MCP** for server status
5. In VS Code: check **Output → MCP** panel for connection errors
6. In Claude Code: run `claude mcp list` to verify the server is registered
**Symptoms:** Queries take a long time or timeout.
**Solutions:**
1. Use more specific queries — broad searches across large codebases take longer
2. Use `semantic_search` or `grep_search` instead of `chat` for simple lookups
3. Scope searches to specific repositories instead of searching everything
4. For remote MCP: check your network latency to `mcp.codealive.ai`
5. Consider running Docker locally for lower latency:
```bash theme={null}
docker run -d -p 8000:8000 \
-e CODEALIVE_API_KEY=YOUR_API_KEY \
ghcr.io/codealive-ai/codealive-mcp:main
```
**Symptoms:** Container exits immediately, port conflicts, image pull failures.
**Solutions:**
1. **Port conflict:** Check if port 8000 is already in use:
```bash theme={null}
lsof -i :8000
```
Use a different port: `-p 9000:8000`
2. **API key not set:** The container requires `CODEALIVE_API_KEY` environment variable
3. **Image pull failure:** Ensure you can access `ghcr.io`:
```bash theme={null}
docker pull ghcr.io/codealive-ai/codealive-mcp:main
```
4. **Check logs:** `docker logs codealive-mcp` for specific error messages
**Symptoms:** Agent reports that `semantic_search`, `grep_search`, `chat`, or `get_data_sources` is not available.
**Solutions:**
1. Verify MCP is enabled in your agent — some agents require explicit opt-in
2. Check that the tool names are exact: `semantic_search`, `grep_search`, `chat`, `get_data_sources`
3. Ensure the MCP server is connected (see "MCP server not connecting" above)
4. Some agents cache tool lists — restart the agent to refresh
**Symptoms:** Search results don't match your query, too many results from wrong files.
**Solutions:**
1. Use more specific terms — include class names, function names, or module names
2. Scope the search to a specific repository if you have multiple indexed
3. Try `semantic_search` for architecture-level or intent-based queries
4. Try `grep_search` for exact function/class names, log lines, or regex lookups
5. Check that the repository index is up to date in the dashboard
## Getting Help
Report bugs and request features
Contact the CodeAlive team directly
Browse the full documentation
# Example Workflows
Source: https://docs.codealive.ai/workflows
Real-world patterns for using CodeAlive with AI coding agents
Discover how developers use CodeAlive to accelerate their daily work. Each workflow shows a realistic scenario with step-by-step instructions and example prompts you can copy directly into your AI agent.
## Workflows
**Scenario:** You just joined a team and need to understand a large, unfamiliar project quickly.
Add the project repository in your [CodeAlive dashboard](https://app.codealive.ai) and wait for indexing to complete.
Start with broad questions to understand the overall structure:
```
"What is the high-level architecture of this project?"
"What frameworks and libraries does this codebase use?"
"How is the code organized — what are the main modules?"
```
Narrow down to the most important files:
```
"Where is the main entry point of the application?"
"Show me the API route definitions"
"Where is the database schema defined?"
```
Understand how the team writes code:
```
"How is error handling done in this project?"
"What patterns are used for authentication?"
"Show me how services communicate with each other"
```
Start with `semantic_search` and `grep_search` for evidence gathering, then switch to `chat` only when you need synthesized architecture-level analysis.
**Scenario:** You need to find how a shared library or API is used across multiple services in a microservices architecture.
In your CodeAlive dashboard, group related repositories into a workspace (e.g., "platform-services").
Use semantic search to find usage patterns across all repos:
```
"Search for usage of the UserService API across all repositories"
"Find all implementations of the PaymentGateway interface"
"Show me how the shared auth library is imported and used"
```
Look for inconsistencies or patterns:
```
"Compare how error handling is done in the order-service vs payment-service"
"Are there any services not using the latest version of the shared client?"
"Find all places where the deprecated createUser method is still called"
```
Use `get_data_sources` first to see all available repositories and workspaces — pass your task as the `query` argument to get only the relevant ones. Scope searches with workspace names for faster, more relevant results.
**Scenario:** You need to review a pull request with full awareness of how the changes affect the broader codebase.
Ask CodeAlive about the code being modified:
```
"Explain how the authentication middleware works in this project"
"What calls the handlePayment function and what depends on its return value?"
```
Verify the PR follows existing conventions:
```
"How do other API endpoints in this project handle validation?"
"Show me how similar services are structured in this codebase"
"What error handling pattern is used in the controller layer?"
```
Look for potential issues:
```
"What other code would break if the User model schema changes?"
"Find all callers of this function to check if the new parameter is handled"
"Are there existing tests that cover this authentication flow?"
```
Use `semantic_search` and `grep_search` to find related code quickly, then `chat` to get a synthesized analysis of how the changes fit into the broader architecture.
**Scenario:** You need to add a new API endpoint (or service, component, etc.) that matches the team's existing conventions.
Search for existing patterns to follow:
```
"Show me an example API endpoint with full CRUD operations"
"How are controllers structured in this project?"
"Find a service that handles database transactions"
```
Ask CodeAlive to extract the conventions:
```
"What is the standard structure for a new API endpoint in this project?"
"What middleware is applied to protected routes?"
"How are request validation and error responses handled?"
```
Use the patterns as context for code generation:
```
"Create a new /api/orders endpoint following the same patterns as /api/products"
"Generate a service class for OrderService matching the structure of ProductService"
"Write tests for the OrderController using the same testing patterns as ProductController"
```
The search-then-generate flow produces much better results than asking for code from scratch. The AI sees your actual conventions, not generic best practices.
**Scenario:** You're tracking down a bug that spans multiple files or services and need to trace the execution path.
Start from the error message or symptom:
```
"Search for where 'PaymentProcessingError' is thrown"
"Find all places where the order status is updated to 'failed'"
"Show me the error handling chain for payment webhooks"
```
Follow the execution path through the codebase:
```
"Trace the flow from when a payment webhook arrives to when the order status is updated"
"What functions call processPayment and what happens with the return value?"
"Show me the middleware chain that runs before the payment endpoint"
```
Narrow down to the issue:
```
"Are there any race conditions in the payment processing flow?"
"Compare the error handling in processPayment with similar functions — is anything missing?"
"What happens if the database connection drops during a payment transaction?"
```
Use `grep_search` with specific error messages or function names for fast, targeted lookups and `semantic_search` for broader retrieval. Switch to `chat` only when you need the AI to reason about execution flow after search.
**Scenario:** You want to research in one AI agent and implement in another — with both sharing the same codebase context.
Use CodeAlive in Cursor, VS Code, or any connected agent to explore:
```
"How does the notification system work?"
"What would need to change to add email notifications?"
"Show me the existing notification channels and their implementations"
```
Open Claude Code (or any other agent) — CodeAlive provides the same context:
```
"Search for the NotificationService implementation"
"Create an EmailNotificationChannel following the pattern of SlackNotificationChannel"
```
Both agents query the same indexed codebase, so your research carries over naturally.
Use any connected agent to verify the changes fit:
```
"Does the new EmailNotificationChannel follow the same interface as other channels?"
"What tests exist for notification channels that I should replicate?"
```
CodeAlive acts as a shared knowledge layer. Index once, query from any agent. This is especially useful when different agents have different strengths — use Cursor for exploration and Claude Code for implementation, for example.
## What's Next
Get the most out of CodeAlive with practical tips
Set up CodeAlive with your AI agent