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
• Tools Overview
• When to Use
• Quick Start
• Tool Reference
• Data Sources
• Configuration

Tools Overview#

ToolScriptSpeedCostBest ForList Data Sourcesdatasources.pyInstantFreeDiscovering indexed repos and workspacesSearchsearch.pyFastLowFinding code locations, descriptions, identifiersFetch Artifactsfetch.pyFastLowRetrieving full content for search resultsChat with Codebasechat.pySlowHighSynthesized answers, architectural explanationsExploreexplore.pySlowHighMulti-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. 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#

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

5. Multi-step exploration#

bash

python scripts/explore.py "understand:user authentication" my-backend
python scripts/explore.py "debug:slow database queries" my-service

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]

OptionDescription--mode autoDefault. Intelligent semantic search — use 80% of the time--mode fastQuick lexical search for known terms--mode deepExhaustive search for complex cross-cutting queries. Resource-intensive--description-detail shortDefault. Brief description of each result--description-detail fullMore 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.

bash

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

ConstraintValueMax identifiers per request20Identifiers sourceidentifier field from search resultsIdentifier 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.

bash

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

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

explore.py — Smart Exploration#

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

bash

python scripts/explore.py <mode:query> <data_sources...>

ModePurposeunderstand:<topic>Search + explanationdependency:<library>Library usage and internalspattern:<pattern>Cross-project pattern discoveryimplement:<feature>Find similar features for guidancedebug:<issue>Trace symptom to root cause

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"

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.

ComponentWhat it providesThis skillQuery patterns, workflow guidance, cost-aware tool selectionMCP serverDirect 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