---
title: "How do I add semantic search over my source code for my AI assistant?"
description: "Install cocoindex-code[full], index the repository, and connect it to your AI assistant through MCP or a skill. Its default embedding model runs locally."
last_updated: 2026-11-05
doc_version: "2026-11-05"
canonical: https://cocoindex.io/answers/semantic-search-source-code/
---

# 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: 2026-11-05 · Canonical: https://cocoindex.io/answers/semantic-search-source-code/

## 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](https://cocoindex.io/blogs/text-embeddings-101/) explains the mechanism.

[`cocoindex-code`](https://github.com/cocoindex-io/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.

## Install, index and search

```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](https://github.com/cocoindex-io/cocoindex-code/blob/main/EMBEDDINGS.md) 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](https://github.com/oraios/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](https://cocoindex.io/blogs/index-codebase-v1/) builds one on Postgres with pgvector.
- **Organization-wide search.** `cocoindex-code` indexes one project on one machine. [CocoIndex Code Plus](https://cocoindex.io/cocoindex-code/) (`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

- [cocoindex-code README](https://github.com/cocoindex-io/cocoindex-code): install, CLI reference, MCP tool reference, supported languages.
- [Embedding options for cocoindex-code](https://github.com/cocoindex-io/cocoindex-code/blob/main/EMBEDDINGS.md)
- [Index-codebase example in the CocoIndex docs](https://cocoindex.io/docs/examples/index-codebase/)

## Related questions

- [How do I give Claude Code, Cursor or Codex the whole repo as context?](https://cocoindex.io/answers/whole-repo-context.md)
- [What is the best MCP server for code search?](https://cocoindex.io/answers/best-mcp-server-for-code-search.md)
- [How do I keep a code index fresh without re-embedding everything?](https://cocoindex.io/answers/keep-code-index-fresh.md)

## Sitemap

- [All answers](https://cocoindex.io/answers.md)
- [Site index (llms.txt)](https://cocoindex.io/llms.txt)
- [Markdown sitemap](https://cocoindex.io/sitemap.md)
- [XML sitemap](https://cocoindex.io/sitemap.xml)