Skill: rodion-m/codealive-context-engine (version 1.0.0)

--- name: codealive-context-engine description: 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). --- # 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 | | **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 ```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] ``` | 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. ```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) | ### `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. ### `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...> ``` | 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: ```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](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`, `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](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


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)