CocoIndex Code: AST-Aware Semantic Code Search for AI Coding Agents

AST-Aware Chunking

Most code search tools chunk by line count — split every N lines and embed. This cuts through functions mid-way, producing ragged snippets that are hard for models to reason about.

cocoindex-code uses Tree-sitter to parse source code into an AST, then splits along semantic boundaries. A chunk is a complete function, class, or block — not an arbitrary line range. This means search results are self-contained units the agent can actually understand without additional context.

Incremental Re-Indexing

This is where the Rust core engine matters. When you save a file, cocoindex-code:

1. Diffs the file’s AST against the previously indexed version
2. Identifies which chunks changed, were added, or were deleted
3. Re-embeds only the changed chunks
4. Retires deleted chunks from the index

Everything else — untouched functions, unchanged files — reuses prior embeddings from cache. The embedding calls (the expensive part) are memoized, and typical workloads see 80–90% cache hits. Freshness after a save is sub-second, regardless of repo size.

This matters at scale. A 2M-file full rebuild costs real money in API calls and takes hours — by which time more commits have landed and the context is already stale. Incremental is the only way agents and corpus velocity can coexist.

Local-First Architecture

cocoindex-code doesn’t need a database server. Index data lives in SQLite (via LMDB) in your project’s .cocoindex_code/ directory. The default embedding model — Snowflake/snowflake-arctic-embed-xs — runs locally via SentenceTransformers. No API key, no data leaving your machine.

If you want better code-specific retrieval, swap to nomic-ai/CodeRankEmbed (137M params, ~1 GB VRAM, 8192-token context). Or point it at any of 100+ cloud providers via LiteLLM.

Install

1
# Full install — local embeddings, no API key needed
2
pipx install 'cocoindex-code[full]'
3

4
# Slim install — cloud embeddings via LiteLLM only (~450 MB smaller)
5
pipx install cocoindex-code

The [full] variant pulls in sentence-transformers and defaults to Snowflake/snowflake-arctic-embed-xs. The slim variant requires a cloud embedding provider and API key.

CLI Usage

1
ccc init                                # initialize project (creates settings)
2
ccc index                               # build the index
3
ccc search "authentication logic"       # natural-language search
4
ccc status                              # index stats

Search supports filtering:

1
ccc search --lang python --lang markdown schema
2
ccc search --path 'src/utils/*' query handler
3
ccc search --offset 10 --limit 5 database schema
4
ccc search --refresh database schema    # re-index first, then search

The background daemon starts automatically on first use and stays warm across sessions.

Agent Integration

There are two approaches:

Skill (recommended for Claude Code):

1
npx skills add cocoindex-io/cocoindex-code

The skill teaches the agent to handle initialization, indexing, and searching on its own. It keeps the index updated as you work. No ccc init or ccc index needed — the agent handles it.

MCP server (universal):

1
# Claude Code
2
claude mcp add cocoindex-code -- ccc mcp
3

4
# OpenAI Codex CLI
5
codex mcp add cocoindex-code -- ccc mcp
6

7
# OpenCode
8
opencode mcp add    # type=local, command=ccc mcp

Any MCP-compatible client — Cursor, Factory droid, Kilo Code — can connect to ccc mcp. The agent automatically decides when semantic search is useful: exploring unfamiliar code, fuzzy/conceptual matches, finding implementations without knowing exact names.

Docker

For teams wanting dependency-free setup:

1
docker compose -f docker/docker-compose.yml up -d

Two image variants: cocoindex/cocoindex-code:latest (slim, ~450 MB, cloud embeddings) and cocoindex/cocoindex-code:full (~5 GB, local embeddings included). A shell wrapper makes ccc feel native on the host.

Global Settings (~/.cocoindex_code/global_settings.yml)

1
embedding:
2
  provider: sentence-transformers
3
  model: Snowflake/snowflake-arctic-embed-xs
4
  device: mps              # auto-detected if omitted (cpu, cuda, mps)
5

6
envs:
7
  OPENAI_API_KEY: your-key   # only if not already in shell env

The daemon inherits your shell environment, so you only need envs for keys not already exported.

Project Settings (.cocoindex_code/settings.yml)

1
include_patterns:
2
  - "**/*.py"
3
  - "**/*.ts"
4
  - "**/*.rs"
5
  - "**/*.go"
6

7
exclude_patterns:
8
  - "**/.*"
9
  - "**/node_modules"
10
  - "**/dist"
11
  - "**/__pycache__"
12

13
language_overrides:
14
  - ext: inc
15
    lang: php

Both files are created automatically by ccc init. The .cocoindex_code/ directory is added to .gitignore.