# Codealive Context Engine

> Semantic code search and AI-powered codebase Q&A across indexed repositories. Use when understanding code beyond local files, exploring dependencies, discovering cross-project patterns, planning features, debugging, or onboarding. Queries like "How does X work?", "Show me Y patterns", "How is library Z used?". Provides search (fast, returns file locations and descriptions) and chat-with-codebase (slower, costs more, but returns synthesized answers). Use when this capability is needed.

- Skill: `tomevault-io/codealive-context-engine` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/codealive-context-engine`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/codealive-context-engine/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/codealive-context-engine

---


# CodeAlive Context Engine

Semantic code intelligence across your entire code ecosystem — current project, organizational repos, dependencies, and any indexed codebase.

## Authentication

All scripts require a CodeAlive API key. If any script fails with "API key not configured", help the user set it up:

**Option 1 (recommended):** Run the interactive setup and wait for the user to complete it:
```bash
python setup.py
```

**Option 2 (not recommended — key visible in chat history):** If the user pastes their API key directly in chat, save it via:
```bash
python setup.py --key THE_KEY
```

Do NOT retry the failed script until setup completes successfully.

## Table of Contents

- [Authentication](#authentication)
- [Tools Overview](#tools-overview)
- [When to Use](#when-to-use)
- [Quick Start](#quick-start)
- [Tool Reference](#tool-reference)
- [Data Sources](#data-sources)
- [Configuration](#configuration)

## Tools Overview

| Tool | Script | Speed | Cost | Best For |
|------|--------|-------|------|----------|
| **List Data Sources** | `datasources.py` | Instant | Free | Discovering indexed repos and workspaces |
| **Search** | `search.py` | Fast | Low | Finding code locations, descriptions, identifiers |
| **Fetch Artifacts** | `fetch.py` | Fast | Low | Retrieving full content for search results |
| **Artifact Relationships** | `relationships.py` | Fast | Low | Drilling into call graph, inheritance, references for one artifact |
| **Chat with Codebase** | `chat.py` | Slow | High | Synthesized answers, architectural explanations |

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

**Three-step workflow (search → triage → load real content):**
1. **Search** — find relevant code locations with descriptions and identifiers
2. **Triage** — use `description` ONLY to decide which results are worth a closer
   look. It is a pointer, NOT the source of truth. Do not draw conclusions from it.
3. **Get real content** — for every artifact you decide is relevant:
    - External repos (no local access): `python fetch.py <identifier>`
    - Current working repo: read the file at the shown path with your editor's
      file-read tool
    Treat only that real `content` as ground truth.

**Optional drill-down:** once you know an artifact matters, run
`python relationships.py <identifier>` to expand its call graph, inheritance,
or references.

## When to Use

**Use this skill for semantic understanding:**
- "How is authentication implemented?"
- "Show me error handling patterns across services"
- "How does this library work internally?"
- "Find similar features to guide my implementation"

**Use local file tools instead for:**
- Finding specific files by name or pattern
- Exact keyword search in the current directory
- Reading known file paths
- Searching uncommitted changes

## Quick Start

### 1. Discover what's indexed

```bash
python scripts/datasources.py
```

### 2. Search for code (fast, cheap)

```bash
python scripts/search.py "JWT token validation" my-backend
python scripts/search.py "error handling patterns" workspace:platform-team --mode deep
python scripts/search.py "authentication flow" my-repo --description-detail full
```

### 3. Fetch full content (for external repos)

```bash
python scripts/fetch.py "my-org/backend::src/auth.py::AuthService.login()"
```

### 4. Drill into an artifact's relationships (optional)

```bash
# Full call graph (default)
python scripts/relationships.py "my-org/backend::src/auth.py::AuthService.login()"

# Inheritance hierarchy for a class
python scripts/relationships.py "my-org/backend::src/models.py::User" --profile inheritanceOnly

# Calls + inheritance, raise the per-type cap
python scripts/relationships.py "my-org/backend::src/svc.py::Service" --profile allRelevant --max-count 200
```

### 5. Chat with codebase (slower, richer answers)

```bash
python scripts/chat.py "Explain the authentication flow" my-backend
python scripts/chat.py "What about security considerations?" --continue CONV_ID
```

## Tool Reference

### `datasources.py` — List Data Sources

```bash
python scripts/datasources.py              # Ready-to-use sources
python scripts/datasources.py --all        # All (including processing)
python scripts/datasources.py --json       # JSON output
```

### `search.py` — Semantic Code Search

Returns file paths, line numbers, descriptions, identifiers, and content sizes. Fast and cheap.

```bash
python scripts/search.py <query> <data_sources...> [options]
```

| Option | Description |
|--------|-------------|
| `--mode auto` | Default. Intelligent semantic search — use 80% of the time |
| `--mode fast` | Quick lexical search for known terms |
| `--mode deep` | Exhaustive search for complex cross-cutting queries. Resource-intensive |
| `--description-detail short` | Default. Brief description of each result |
| `--description-detail full` | More detailed description of each result |

**`description` is a triage pointer ONLY** — it tells you which artifacts are
worth a closer look. It is NOT the source of truth and you must NOT draw
conclusions from it. For every result you consider relevant, load the real
source: use `fetch.py <identifier>` for external repos, or your editor's
file-read tool on the path for repos in the current working directory. Treat
only that real `content` as ground truth.

### `fetch.py` — Fetch Artifact Content

Retrieves the full source code content for artifacts found via search. Use this for external repositories you cannot access locally.

```bash
python scripts/fetch.py <identifier1> [identifier2...]
```

| Constraint | Value |
|-----------|-------|
| Max identifiers per request | 20 |
| Identifiers source | `identifier` field from search results |
| Identifier format | `{owner/repo}::{path}::{symbol}` (symbols), `{owner/repo}::{path}` (files) |

For function-like artifacts the response includes a small **relationships
preview** (up to 3 outgoing/incoming calls per direction). To see the full
call graph, inheritance, or references, run `relationships.py` with the
artifact's identifier.

### `relationships.py` — Drill into an Artifact's Relationship Graph

Returns the full call graph (incoming/outgoing calls), inheritance hierarchy
(ancestors/descendants), or symbol references for a single artifact. This is
the drill-down tool — use it AFTER `search.py` or `fetch.py` once you have an
identifier and want to understand how the artifact relates to the rest of the
codebase.

```bash
python scripts/relationships.py <identifier> [--profile PROFILE] [--max-count N]
```

| Option | Description |
|--------|-------------|
| `--profile callsOnly` | Default. Outgoing + incoming calls |
| `--profile inheritanceOnly` | Ancestors + descendants |
| `--profile allRelevant` | Calls + inheritance (4 groups) |
| `--profile referencesOnly` | Symbol references |
| `--max-count N` | Max related artifacts per relationship type (1–1000, default 50) |
| `--json` | Emit the raw JSON response instead of the formatted view |

### `chat.py` — Chat with Codebase

Sends your question to an AI consultant that has full context of the indexed codebase. Returns synthesized, ready-to-use answers. Supports conversation continuity for follow-ups.

**This is more expensive than search** because it runs an LLM inference on the server side. Prefer search when you just need to locate code. Use chat when you need explanations, comparisons, or architectural analysis.

```bash
python scripts/chat.py <question> <data_sources...> [options]
```

| Option | Description |
|--------|-------------|
| `--continue <id>` | Continue a previous conversation (saves context and cost) |

**Conversation continuity:** Every response includes a `conversation_id`. Pass it with `--continue` for follow-up questions — this preserves context and is cheaper than starting fresh.

## Data Sources

**Repository** — single codebase, for targeted searches:
```bash
python scripts/search.py "query" my-backend-api
```

**Workspace** — multiple repos, for cross-project patterns:
```bash
python scripts/search.py "query" workspace:backend-team
```

**Multiple repositories:**
```bash
python scripts/search.py "query" repo-a repo-b repo-c
```

## Configuration

### Prerequisites

- Python 3.8+ (no third-party packages required — uses only stdlib)

### API Key Setup

The skill needs a CodeAlive API key. Resolution order:

1. `CODEALIVE_API_KEY` environment variable
2. OS credential store (macOS Keychain / Linux secret-tool / Windows Credential Manager)

**Environment variable (all platforms):**
```bash
export CODEALIVE_API_KEY="your_key_here"
```

**macOS Keychain:**
```bash
security add-generic-password -a "$USER" -s "codealive-api-key" -w "YOUR_API_KEY"
```

**Linux (freedesktop secret-tool):**
```bash
secret-tool store --label="CodeAlive API Key" service codealive-api-key
```

**Windows Credential Manager:**
```cmd
cmdkey /generic:codealive-api-key /user:codealive /pass:"YOUR_API_KEY"
```

**Base URL** (optional, defaults to `https://app.codealive.ai`):
```bash
export CODEALIVE_BASE_URL="https://your-instance.example.com"
```

For self-hosted CodeAlive, use your deployment origin. `https://your-instance.example.com` is preferred, but `https://your-instance.example.com/api` is also accepted and normalized automatically.

Get API keys at: https://app.codealive.ai/settings/api-keys

## Using with CodeAlive MCP Server

This skill works standalone, but delivers the best experience when combined with the [CodeAlive MCP server](https://github.com/CodeAlive-AI/codealive-mcp). The MCP server provides direct tool access via the Model Context Protocol, while this skill provides the workflow knowledge and query patterns to use those tools effectively.

| Component | What it provides |
|-----------|-----------------|
| **This skill** | Query patterns, workflow guidance, cost-aware tool selection |
| **MCP server** | Direct `codebase_search`, `fetch_artifacts`, `get_artifact_relationships`, `codebase_consultant`, `get_data_sources` tools |

When both are installed, prefer the MCP server's tools for direct operations and this skill's scripts for guided workflows.

## Detailed Guides

For advanced usage, see reference files:
- **[Query Patterns](references/query-patterns.md)** — effective query writing, anti-patterns, language-specific examples
- **[Workflows](references/workflows.md)** — step-by-step workflows for onboarding, debugging, feature planning, and more

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/codealive-ai) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-12 -->