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:
CODEBLOCK0

Option 2 (not recommended — key visible in chat history): If the user pastes their API key directly in chat, save it via:
CODEBLOCK1

Do NOT retry the failed script until setup completes successfully.

Table of Contents

• - Authentication
• Tools Overview
• When to Use
• Quick Start
• Tool Reference
• Data Sources
• Configuration

Tools Overview

Tool	Script	Speed	Cost	Best For
List Data Sources	INLINECODE0	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 | | Chat with Codebase | chat.py | Slow | High | Synthesized answers, architectural explanations | | Explore | explore.py | Slow | High | Multi-step discovery workflows |

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:

1. 1. Search — find relevant code locations with descriptions and identifiers
2. Review — examine the descriptions to understand what each result contains
3. Get content — use fetch.py for external repos or Read() for local files

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

CODEBLOCK2

2. Search for code (fast, cheap)

CODEBLOCK3

3. Fetch full content (for external repos)

CODEBLOCK4

4. Chat with codebase (slower, richer answers)

CODEBLOCK5

5. Multi-step exploration

CODEBLOCK6

Tool Reference

datasources.py — List Data Sources

CODEBLOCK7

search.py — Semantic Code Search

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

CODEBLOCK8

Option	Description
INLINECODE9	Default. Intelligent semantic search — use 80% of the time
INLINECODE10

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 |

Getting content: Search returns descriptions and identifiers. For the current repo, use Read() on the file paths. For external repos, use fetch.py with the identifiers.

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.

CODEBLOCK9

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

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.

CODEBLOCK10

Option	Description
INLINECODE21	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.

explore.py — Smart Exploration

Combines search and chat-with-codebase in multi-step workflows. Useful for complex investigations.

CODEBLOCK11

Mode	Purpose
INLINECODE25	Search + explanation
INLINECODE26

Library usage and internals |
| pattern:<pattern> | Cross-project pattern discovery |
| implement:<feature> | Find similar features for guidance |
| debug:<issue> | Trace symptom to root cause |

Data Sources

Repository — single codebase, for targeted searches:
CODEBLOCK12

Workspace — multiple repos, for cross-project patterns:
CODEBLOCK13

Multiple repositories:
CODEBLOCK14

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. 1. CODEALIVE_API_KEY environment variable
2. OS credential store (macOS Keychain / Linux secret-tool / Windows Credential Manager)

Environment variable (all platforms):
CODEBLOCK15

macOS Keychain:
CODEBLOCK16

Linux (freedesktop secret-tool):
CODEBLOCK17

Windows Credential Manager:
CODEBLOCK18

Base URL (optional, defaults to https://app.codealive.ai):
CODEBLOCK19

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. 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, 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 multi-step workflows like explore.py.

Detailed Guides

For advanced usage, see reference files:

• - Query Patterns — effective query writing, anti-patterns, language-specific examples
• Workflows — step-by-step workflows for onboarding, debugging, feature planning, and more