cocoindex-code

Unlike semantic search, ccc grep finds code by its structure using a by-example pattern that matches the syntax tree. It does not require an index, daemon, or embeddings and runs entirely locally. It uses metavariables with the \ sigil:

• \NAME: Captures one node.
• \(NAME*\): Captures a run of siblings.
• \_ or \*: Matches anonymously.

Patterns are matched per language; a single invocation scans all supported source files. Inside an initialized project, it honors .gitignore and include/exclude patterns.

Depending on your hardware, privacy needs, and codebase size, choose one of three paths:

1. Local Sentence-Transformers: Best for most users and laptops. It is the fastest (in-process), private, and works offline. Requires installing the [full] extra.
2. Cloud LiteLLM Remote: Best for large codebases or weak local hardware. Offers top performance with zero local resource usage, but involves per-token costs and data leaves your machine.
3. Local LiteLLM: Best for power users with shared GPU resources. Provides flexibility and unified model management but requires managing a separate server (like Ollama or llama.cpp).

Some embedding models require different settings for indexing documents versus querying them (asymmetric retrieval). You can configure these using indexing_params and query_params under the embedding key in global_settings.yml.

• indexing_params: Parameters used when embedding corpus content.
• query_params: Parameters used when embedding a user query.

Supported keys depend on the provider:

• LiteLLM: Uses input_type (e.g., search_document or search_query).
• SentenceTransformers: Uses prompt_name (e.g., passage or query).

ccc doctor validates both sides of the configuration independently to ensure both indexing and query modes are correctly configured.

embedding:
  provider: litellm
  model: cohere/embed-english-v3.0
  indexing_params:
    input_type: search_document
  query_params:
    input_type: search_query

The recommended way to use cocoindex-code is by installing the ccc skill. This allows coding agents (like Claude Code) to automatically handle initialization, indexing, and searching without manual configuration. The agent will automatically keep the index up to date as you work.

To install the skill, use:

npx skills add cocoindex-io/cocoindex-code

You can nudge the agent to use semantic search by asking questions like "find how user sessions are managed" or by typing /ccc to invoke the skill directly.

You can narrow down ccc search results using language filters or path glob patterns.

• By language (--lang): Use this flag multiple times to restrict results to specific languages.
• By path (--path): Restrict results to a glob pattern relative to the project root. If omitted, it defaults to the current working directory.

Examples:

You can install cocoindex-code using pipx or uv. There are two installation styles depending on whether you want local embeddings or a slim version that requires a cloud provider.

Installation Styles

• cocoindex-code[full] (Batteries-included): Includes sentence-transformers for local embeddings. No API key is required. The ccc init prompt defaults to Snowflake/snowflake-arctic-embed-xs.
• cocoindex-code (Slim): LiteLLM-only. Requires a cloud embedding provider and an API key. Use this to avoid the ~1 GB dependency of torch and transformers.

Commands

Using pipx:

pipx install 'cocoindex-code[full']          # batteries included (local embeddings)
pipx upgrade cocoindex-code                  # upgrade

Using uv:

uv tool install --upgrade 'cocoindex-code[full]'

pipx install 'cocoindex-code[full]'

The ccc CLI provides semantic search over your codebase and manages the code index. It is designed to find concepts, functionality, or behaviors rather than exact syntax matches.

Key Lifecycle Responsibilities:

• Initialization: If you encounter an initialization error (e.g., "Not in an initialized project directory"), run ccc init from the project root, then ccc index to build the index, and retry your command.
• Index Freshness: Run ccc index or ccc search --refresh when the index might be stale, such as at the start of a session or after significant code changes (new files, refactors, or renamed modules).

To update the MTEB Model Discovery Report with the latest live data from the MTEB dataset, use the find_best_models.py script. You can force a fresh run by using the --clear-cache flag.

uv run scripts/find_best_models.py --clear-cache --output MTEB-RANKINGS.md