CodeAlive Context Engine

Semantic code search and AI-powered codebase Q&A across indexed repositories. Use when understanding code beyond local files, exploring dependencies, discove...

Security Scan

The skill's code implements a remote CodeAlive API client that requires an API key, but the published metadata omits that requirement and the package will try to read local credential stores — the mismatch and credential handling warrant caution before installing.

Purpose & Capability

The skill name/description (semantic code search / codebase Q&A) matches the included scripts (search, fetch, chat, explore, datasources, api client). However the registry metadata declares no required environment variables or primary credential, while the code and SKILL.md clearly require a CodeAlive API key and optionally a CODEALIVE_BASE_URL override. That metadata omission is an inconsistency (either metadata is incomplete or the package is misdeclared).

Instruction Scope

SKILL.md instructs the user to run the bundled scripts and to run setup.py to configure an API key (or paste the key). The runtime code will also attempt to read the API key silently from OS credential stores (macOS Keychain, Linux secret-tool, or Windows Credential Manager). The scripts do not instruct collecting or sending unrelated local files, but automatic access to OS credential stores and a remote API means secrets are used and transmitted to the CodeAlive service — this behavior is consistent with the stated purpose but should be explicit in metadata/instructions and reviewed by the user.

Install Mechanism

No install spec or external downloads; this is an instruction-only skill with included Python scripts that use only the standard library and local subprocess/ctypes calls. No remote code is fetched by an installer and no packages are created or written to unusual system locations.

Credentials

The code expects a service credential (CODEALIVE_API_KEY) and allows CODEALIVE_BASE_URL to be set, but the registry metadata lists no required env vars. The client will also attempt to read credential stores to obtain the key. Requesting/using a single API key is reasonable for this purpose, but the metadata omission and the option to read OS key stores (including Windows credential APIs via ctypes) should be disclosed and reviewed. The SKILL.md also suggests pasting an API key into chat as an (explicitly discouraged) option — that is unsafe and should be avoided.

Persistence & Privilege

The skill is not marked always:true and does not claim to modify other skill or system configurations. Its runtime behavior does not request persistent privileged presence beyond using the API key and contacting the configured CodeAlive service.

What to consider before installing

This skill appears to implement the advertised code-search/chat functionality, but the package metadata misleadingly omits that an API key is required. Before installing or running it: - Do not paste your API key into chat or other public windows. Prefer the interactive setup, but inspect setup.py to see how/where the key is stored. - Review setup.py to confirm whether the key is stored in an OS credential store or written to disk in plaintext. If it writes to a local file, check the file location and permissions. - Confirm the service domain (default https://app.codealive.ai) is legitimate for your organization; if you must point to a different host, inspect CODEALIVE_BASE_URL use in the code. - Be aware the client will attempt to read the OS credential store (macOS Keychain, Linux secret-tool, Windows Credential Manager). If you prefer not to allow that, run the client with an explicit api_key parameter or set CODEALIVE_API_KEY in a controlled environment, and audit the code path that retrieves stored credentials. - Because the skill source and homepage are unknown and owner ID is opaque, treat it as untrusted until you verify the upstream project. If you rely on organizational secrets, prefer an approved/internal tool or ask the author for provenance and a security review. I recommend: inspect setup.py and any key-storage logic, confirm network endpoints, and ensure you do not expose secrets in chat before using the skill.

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:

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:

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

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

python scripts/datasources.py

2. Search for code (fast, cheap)

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)

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

4. Chat with codebase (slower, richer answers)

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

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

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.

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

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.

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)

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.

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.

explore.py — Smart Exploration

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

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

Mode	Purpose
understand:<topic>	Search + explanation
dependency:<library>	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:

python scripts/search.py "query" my-backend-api

Workspace — multiple repos, for cross-project patterns:

python scripts/search.py "query" workspace:backend-team

Multiple repositories:

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

export CODEALIVE_API_KEY="your_key_here"

macOS Keychain:

security add-generic-password -a "$USER" -s "codealive-api-key" -w "YOUR_API_KEY"

Linux (freedesktop secret-tool):

secret-tool store --label="CodeAlive API Key" service codealive-api-key

Windows Credential Manager:

cmdkey /generic:codealive-api-key /user:codealive /pass:"YOUR_API_KEY"

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

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.

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