How do I add semantic search over my source code for my AI assistant?

Install cocoindex-code, index the repository, and connect it to the assistant. pipx install 'cocoindex-code[full]' installs the ccc CLI with local embedding support, so you need no API key. ccc index builds the index. ccc mcp then serves a search tool to MCP clients that launch a stdio server, and ccc search queries the same index from the terminal.

Checked Markdown version

What semantic search does with source code

Semantic search matches by meaning. An embedding model turns each piece of code into a vector, and a query returns the pieces whose vectors are closest to the vector of the query. A query such as “where do we validate the session token” can find a function that contains none of those words. Text embeddings 101: search by meaning explains the mechanism.

cocoindex-code is an open-source (Apache 2.0) implementation for code:

  • Syntax-aware chunks. For the languages it supports, Tree-sitter parses the file, and the tool tries to split it at function, class and method boundaries. Chunks target about 1,000 characters. The README lists 33 supported languages.
  • Locations. Each result has the file path, language, code, line numbers and a similarity score.
  • Embedded storage. The index lives in .cocoindex_code/ inside the project. In a git repository, ccc init adds that folder to .gitignore. There is no database to set up.
bash
pipx install 'cocoindex-code[full]'
# or with uv:
uv tool install --upgrade 'cocoindex-code[full]'
bash
cd your-repo
ccc index                                            # build the index
ccc search "authentication logic"                    # search
ccc search --lang python --lang markdown schema      # filter by language
ccc search --path 'src/utils/*' query handler        # filter by path
ccc search --refresh database schema                 # update the index first, then search

ccc index initializes a new project with default settings. On the first use on a machine, an interactive run asks which embedding model to use. Scripts and hooks need a one-time ccc init first. ccc doctor checks the settings, the daemon, the model and the index.

Connect the assistant

The README recommends the skill for Claude Code and other skill-compatible agents. The agent then runs the index and the search on its own:

bash
npx skills add cocoindex-io/cocoindex-code

Or connect through MCP:

bash
# Claude Code
claude mcp add cocoindex-code -- ccc mcp

# OpenAI Codex CLI
codex mcp add cocoindex-code -- ccc mcp

Cursor and other MCP clients that launch a stdio server take the generic entry. The client must start ccc mcp with the project as its working directory:

json
{
  "mcpServers": {
    "cocoindex-code": {
      "command": "ccc",
      "args": ["mcp"]
    }
  }
}

The MCP tool is search(query, limit, offset, refresh_index, languages, paths). limit defaults to 5, and refresh_index defaults to true.

Choose the embedding model

The [full] install defaults to Snowflake/snowflake-arctic-embed-xs, a SentenceTransformers model that runs locally. To use another model, edit ~/.cocoindex_code/global_settings.yml:

yaml
embedding:
  provider: sentence-transformers
  model: nomic-ai/CodeRankEmbed

A cloud model goes through LiteLLM, for example Voyage’s code model:

yaml
embedding:
  model: voyage/voyage-code-3
envs:
  VOYAGE_API_KEY: your-api-key

A different model has different vectors, so rebuild the index after you switch:

bash
ccc reset && ccc index

The slim install (cocoindex-code without [full]) leaves out the local model dependencies, about 1 GB. It needs a LiteLLM embedding provider: a cloud API with its key, or a local server such as Ollama. The embedding guide compares the options.

Limits, and when another tool fits better

  • Exact matches. Similarity search does not guarantee an exact match. For an exact identifier or a regular expression, use the assistant’s text search. For definitions and references, use a symbol tool such as Serena.
  • Your own pipeline. To choose the vector database, the chunk sizes or extra fields, build the index with the CocoIndex framework. Index your codebase for AI agents with CocoIndex V1 builds one on Postgres with pgvector.
  • Organization-wide search. cocoindex-code indexes one project on one machine. CocoIndex Code Plus (ccx) is a separate self-hosted product that indexes the repositories on your code hosts and adds symbol navigation and cited answers.
  • Very large repositories. A very large repository can reach the default 4 GiB index limit. The README’s troubleshooting section shows how to raise it with COCOINDEX_LMDB_MAP_SIZE.

Sources and further reading