# codealive-context-engine

Adopt this skill: https://proskills.md/skills/other/codealive-ai-codealive-skills-skills-codealive-context-engine

Page: https://proskills.md/skills/other/codealive-ai-codealive-skills-skills-codealive-context-engine
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/codealive-context-engine/SKILL.md
size: 8034
upstream: https://github.com/codealive-ai/codealive-skills/blob/main/skills/codealive-context-engine/SKILL.md

````text
---
name: codealive-context-engine
description: Semantic search, grep, and Q&A across codebases and documentation indexed in CodeAlive. Use when the user mentions "CodeAlive", asks to list or get data sources, list indexed repositories, search code or docs across remote repos, fetch artifact content, or trace call graphs across repositories.
---

# 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. With `--query "task"`, runs an AI relevance filter (low cost, not instant) returning only the relevant sources |
| **Semantic Search** | `search.py` | Fast | Low | Default discovery — finds code by meaning (concepts, behavior, architecture) |
| **Grep Search** | `grep.py` | Fast | Low | Finds code containing a specific string or regex (identifiers, literals, patterns) |
| **Repository Ontology** | `ontology.py` | Fast | Low | High-level orientation for exactly one repository |
| **File Tree** | `tree.py` | Fast | Free | Bounded repository tree inspection |
| **Read File** | `read_file.py` | Fast | Free | Read one repository-relative file path, optionally with a line range |
| **Fetch Artifacts** | `fetch.py` | Fast | Free | Retrieve full content for search result identifiers |
| **Artifact Relationships** | `relationships.py` | Fast | Free | Full call graph, inheritance, or symbol references for one artifact |
| **ArtifactQuery Schema** | `schema.py` | Fast | Free | Inspect supported metadata query entities, fields, and examples |
| **Artifact Metadata Query** | `metadata.py` | Fast | Low | Read-only aggregate/query analytics across indexed repositories |
| **Chat with Codebase** | `chat.py` | Slow | High | Stateless synthesized Q&A. Call ONLY when the user explicitly asks. |
| **Get Version** | `get_version.py` | Instant | Free | Return the installed CodeAlive skill version as JSON; no API key or network call required |

**Cost guidance:** `semantic_search` and `grep_search` are the default starting point — fast and cheap. Use `fetch_artifacts` to load full source and `get_artifact_relationships` to trace call graphs. All four tools are low-cost.

**Chat is not recommended:** `chat.py` invokes an LLM on the server side, can take substantially longer than retrieval, and is significantly more expensive per call. It is stateless in v3: include prior findings, artifact identifiers, assumptions, scope, and constraints in each question. Do NOT call it unless the user has explicitly requested it (e.g. "use chat", "call the chat tool"). Phrases like "ask CodeAlive" or "search CodeAlive" do NOT qualify — they refer to search tools.

**Repairable tool errors:** Treat a returned `<tool_error>` as a failed call,
not as an empty successful result. Follow its `<try>` guidance, repair the
arguments, and retry only when the `<retry>` field permits it. Tool API v3
always preserves the same error in `obj.error` for JSON-mode automation.

**Highest-confidence guidance:** If your agent supports subagents and the task needs maximum reliability or depth, prefer a subagent-driven workflow that combines `ontology.py`, `search.py`, `grep.py`, `fetch.py`, `tree.py`/`read_file.py`, `relationships.py`, `metadata.py`, and local file reads.

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

**Drill into `relationships.py` when the fetch preview isn't enough.** The
`fetch.py` response already previews up to 3 outgoing + 3 incoming calls for
function-like artifacts, so the call graph alone is rarely a reason to run
`relationships.py` after a full fetch of a small artifact. Reach for it when:

- **You need all incoming callers** — the fetch preview is capped at 3.
  The full incoming list also surfaces test coverage (incoming from test
  files).
- **You need the inheritance tree** — `--profile inheritanceOnly` returns
  ancestors + descendants (interface implementations, subclasses, base-class
  chains). The preview doesn't include inheritance.
- **You need symbol references** — `--profile referencesOnly` for places
  that reference a type or identifier.
- **The artifact is too large to fetch into context** — the call graph is a
  cheaper summary than pulling the full source.

**Analyzer noise:** outgoing calls occasionally include compiler-generated
helpers (`MoveNext`, `GetEnumerator`, closure invocations) from methods using
`foreach`/LINQ. Ignore outgoing hits that don't match the artifact's real
logic.

## When to Use

**Semantic search (default) — you describe behavior or concept:**
- "How is authentication implemented?"
- "Show me error handling patterns across services"
- "How does this library work internally?"
- "Find similar features to guide my implementation"

**Grep search — you know the exact text:**
- "Find all usages of `RepositoryDeleted`"
- "Where is `ConnectionString` configured?"
- "Search for `TODO: fix` across the codebase"
- Error messages, URLs, config keys, import paths, regex patterns

**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 --query "the user's task in natural language"
```

Recommended: pass the user's task as `--query` so the backend returns only the relevant
data sources, each with a `relevanceReason`. Omit `--query` to list everything (instant,
no AI filtering).

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

```bash
python scripts/search.py "JWT token validation" my-backend
python scripts/search.py "authentication flow" my-repo --path src/auth --ext .py
python scripts/grep.py "AuthService" my-repo
python scripts/grep.py "auth\\(" my-repo --regex
```

### 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 (not recommended — only if user explicitly asks)

```bash
pytho
````

## File: README.md
upstream: https://github.com/codealive-ai/codealive-skills/blob/main/README.md

````text
# CodeAlive Skills

Agent skills and Claude Code plugin for [CodeAlive](https://app.codealive.ai) — install via [skills.sh](https://skills.sh/) or as a Claude Code plugin.

## Available Skills

| Skill | Description |
|-------|-------------|
| [codealive-context-engine](skills/codealive-context-engine/) | Semantic code search and AI-powered codebase Q&A across indexed repositories |

## Installation

> **Claude Code users:** the recommended installation method is [Option 2 (Plugin)](#option-2-claude-code-plugin) — it includes the skill plus authentication hooks and a code exploration subagent.

### Option 1: Skills (universal — 30+ agents)

Works with Cursor, GitHub Copilot, Windsurf, Gemini CLI, Codex, Goose, Amp, Roo Code, OpenCode, OpenClaw, and [others](https://agentskills.io/).

```bash
npx skills add CodeAlive-AI/codealive-skills@codealive-context-engine
```

Or 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/` |

### Option 2: Claude Code Plugin

For Claude Code users, this repository also serves as a plugin marketplace with Claude-specific enhancements.

```
/plugin marketplace add CodeAlive-AI/codealive-skills
/plugin install codealive@codealive-marketplace
```

### Option 3: MCP Server

For deeper integration, install the [CodeAlive MCP server](https://github.com/CodeAlive-AI/codealive-mcp) — it gives your agent direct access to CodeAlive's tools via the Model Context Protocol. The skill and MCP server complement each other: the MCP server provides tool access, the skill teaches the agent how to use it effectively.

### Option 4: Share the Claude Code plugin with another agent

If you already use the Claude Code plugin and want Codex CLI, Gemini CLI, or another skill-aware agent to consume the exact same skill files, install the [plugin bridge](tools/plugin-bridge/) — a tiny `launchd` agent (macOS) or `systemd --user` path unit (Linux) that keeps a symlink from the other agent's skills directory into the plugin's versioned cache. It re-links automatically on `claude plugin update`.

```bash
cd tools/plugin-bridge
./install-macos.sh
```

See [`tools/plugin-bridge/README.md`](tools/plugin-bridge/README.md) for configuration and Linux instructions.

## Setup

After installing the skill, run the interactive setup:

```bash
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.

### 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`. The setup script accepts both `https://host` and `https://host/api`, but the origin form is preferred.

## Usage

Start your agent and ask naturally:

- *"How is authentication implemented?"*
- *"Find the exact regex or string match for this token parser"*
- *"Show me error handling patterns across services"*
- *"Find similar features to guide my implementation"*
- *"Show me who calls this handler and what it depends on"*

No special commands needed — the agent picks up the skill automatically.

To check the installed skill version without authentication or a network request:

```bash
python skills/codealive-context-engine/scripts/get_version.py
```

## License

MIT
````
