cocoindex-io/cocoindex-code

AST-based semantic code search that just works

A lightweight, effective (AST-based) semantic code search tool for your codebase. Built on CocoIndex — a Rust-based ultra performant data transformation engine. Use it from the CLI, or integrate with Claude, Codex, Cursor — any coding agent — via Skill or MCP.

• Instant token saving by 70%.
• 1 min setup — install and go, zero config needed!

Get Started — zero config, let's go!

Install

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]'

Two install styles — they mirror the Docker image variants of the same names:

• cocoindex-code[full] — batteries-included. Pulls in sentence-transformers so local embeddings (no API key required) work out of the box. The ccc init interactive prompt defaults to Snowflake/snowflake-arctic-embed-xs.
• cocoindex-code (slim) — LiteLLM-only; requires a cloud embedding provider and API key. Use when you don't want the local-embedding deps (~1 GB of torch + transformers).

Coding Agent Integration

This repository is a single plugin marketplace (.claude-plugin/marketplace.json) consumed by both Claude Code and Grok — same plugin id cocoindex-code, same ccc skill. Grok optionally activates the bundled hooks and MCP server with --trust; Claude Code users can install the same marketplace and rely on the skill alone or load hooks/MCP from the plugin as needed.

Skill (Recommended)

Install the ccc skill so your coding agent automatically uses semantic search when needed:

npx skills add cocoindex-io/cocoindex-code

That's it — no ccc init or ccc index needed. The skill teaches the agent to handle initialization, indexing, and searching on its own. It will automatically keep the index up to date as you work.

The agent uses semantic search automatically when it would be helpful. You can also nudge it explicitly — just ask it to search the codebase, e.g. "find how user sessions are managed", or type /ccc to invoke the skill directly.

Works with Claude Code and other skill-compatible agents.

Claude Code plugin marketplace

For Claude Code users, this repository is also a plugin marketplace. Install the skill from inside Claude Code with:

/plugin marketplace add cocoindex-io/cocoindex-code
/plugin install cocoindex-code@cocoindex-code

This bundles the same ccc skill, with version pinning and /plugin marketplace update for updates. The repository also ships hooks/hooks.json and .mcp.json for Grok (and Claude Code plugin installs that load those files); Claude users who want skill-only search can rely on the skill alone and add MCP manually in the MCP Server section below instead of using the bundled .mcp.json.

Grok plugin

For Grok users, install via Grok's plugin system. The plugin bundles three components:

| Component | Purpose | |-----------|---------| | Skill (skills/ccc/) | Agent runs ccc search / ccc index via the CLI (same as Claude Code above) | | Hook (hooks/hooks.json) | SessionStart + PostToolUse (Edit/Write/…) → incremental ccc index when .cocoindex_code/ exists | | MCP (.mcp.json) | ccc mcp stdio server — search tool with refresh_index=true by default |

Grok does not import Claude's enabledPlugins or plugin cache; install separately even if you already use cocoindex in Claude Code.

Full install (skill + hook + MCP):

grok plugin marketplace add cocoindex-io/cocoindex-code
grok plugin install cocoindex-io/cocoindex-code --trust
grok plugin enable cocoindex-code

Prefer the GitHub shorthand (cocoindex-io/cocoindex-code) for install — grok plugin install cocoindex-code can fail when no marketplace plugin matches that bare name.

--trust is required so Grok activates the plugin's hooks and MCP server (skills load when the plugin is enabled).

Skill-only (match Claude Code — no auto-index hook, no MCP tool):

Install and enable as above, then disable the optional components:

1. Hooks — open /hooks, select the SessionStart / PostToolUse hooks from cocoindex-code, press Space to disable. 2. MCP — open /mcps, select cocoindex-code, press Space to disable; or persist in ~/.grok/config.toml:

[mcp_servers.cocoindex-code]
enabled = false

The agent still owns indexing via the ccc skill (ccc index / ccc search --refresh when stale), same as Claude Code.

To avoid importing MCP servers from your Claude/Cursor user config (unrelated to this plugin):

[compat.claude]
mcps = false
[compat.cursor]
mcps = false

Oh My Pi plugin

Oh My Pi reads .omp-plugin/marketplace.json (preferred) and falls back to .claude-plugin/marketplace.json.

omp plugin marketplace add cocoindex-io/cocoindex-code
omp plugin install cocoindex-code@cocoindex-code --scope project

Then restart the session (/reload-plugins does not reload extensions). Requires ccc on PATH (uv tool install --upgrade 'cocoindex-code[full]').

| Component | Purpose | |-----------|---------| | Skill (skills/ccc/) | Agent runs ccc search / ccc index via the CLI | | Hook (extensions/ccc-index.ts via package.json#omp.extensions) | session_start + post-edit tool_result → incremental ccc index when .cocoindex_code/ exists | | MCP (.mcp.json) | ccc mcp stdio server |

OMP does not execute Claude hooks/hooks.json command hooks. The TypeScript extension is the OMP equivalent of the Claude/Grok SessionStart + PostToolUse pair.

Skill-only (no MCP, no auto-index): install the skill via npx skills add cocoindex-io/cocoindex-code, or run ccc search / ccc index from the shell.

MCP Server

Alternatively, use ccc mcp to run as an MCP server:

claude mcp add cocoindex-code -- ccc mcp

codex mcp add cocoindex-code -- ccc mcp

opencode mcp add

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "cocoindex-code": {
      "type": "local",
      "command": [
        "ccc", "mcp"
      ]
    }
  }
}

{
  "mcp": {
    "cocoindex-code": {
      "type": "local",
      "command": ["ccc", "mcp"],
      "enabled": true
    }
  }
}

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

Once configured, the agent automatically decides when semantic code search is helpful — finding code by description, exploring unfamiliar codebases, fuzzy/conceptual matches, or locating implementations without knowing exact names.

Note: The cocoindex-code command (without subcommand) still works as an MCP server for backward compatibility. It auto-creates settings from environment variables on first run.

search(
    query: str,                          # Natural language query or code snippet
    limit: int = 5,                      # Maximum results (1-100)
    offset: int = 0,                     # Pagination offset
    refresh_index: bool = True,          # Refresh index before querying
    languages: list[str] | None = None,  # Filter by language (e.g. ["python", "typescript"])
    paths: list[str] | None = None,      # Filter by path glob (e.g. ["src/utils/*"])
)

Manual CLI Usage

You can also use the CLI directly — useful for manual control, running indexing after changing settings, checking status, or searching outside an agent.

ccc init                                # initialize project (creates settings)
ccc index                               # build the index
ccc search "authentication logic"       # search!

The background daemon starts automatically on first use.

Tip: You can skip ccc init and go straight to ccc index — it auto-initializes new projects with default settings. If global settings are missing too (first use on the machine), it walks you through the same model setup as ccc init when run interactively; non-interactive runs (scripts, hooks) still require a one-time ccc init first.

CLI Reference

| Command | Description | |---------|-------------| | ccc init | Initialize a project — creates settings files, adds .cocoindex_code/ to .gitignore | | ccc index | Build or update the index (auto-inits if needed). Shows streaming progress. | | ccc search | Semantic search across the codebase | | ccc grep [path] | Structural code search by example (no index needed) | | ccc status | Show index stats (chunk count, file count, language breakdown) | | ccc mcp | Run as MCP server in stdio mode | | ccc doctor | Run diagnostics — checks settings, daemon, model, file matching, and index health | | ccc reset | Delete index databases. --all also removes settings. -f skips confirmation. | | ccc version | Print the CLI version | | ccc daemon status | Show daemon version, uptime, and loaded projects | | ccc daemon restart | Restart the background daemon | | ccc daemon stop | Stop the daemon |

Search Options

ccc search database schema                           # basic search
ccc search --lang python --lang markdown schema      # filter by language
ccc search --path 'src/utils/*' query handler        # filter by path
ccc search --offset 10 --limit 5 database schema     # pagination
ccc search --refresh database schema                 # update index first, then search

By default, ccc search scopes results to your current working directory (relative to the project root). Use --path to override.

Structural Search (ccc grep)

ccc grep finds code by structure, not text — you write a by-example pattern and it matches the syntax tree (via cocoindex's code_match), so formatting, whitespace, and intervening tokens don't matter. It runs entirely locally: no index, daemon, or embeddings required.

ccc grep 'def \NAME(\(ARGS*\)):'                      # every Python function def under the cwd
ccc grep 'foo(\(ARGS*\))' src/                        # calls to foo(...) anywhere under src/
ccc grep 'fn \NAME(\(A*\))' --lang rust               # restrict to one language
ccc grep 'class \NAME:' --path 'tests/**'            # restrict to a path glob
ccc grep 'TODO(\(A*\))' path/to/file.py               # a single file

Metavariables use the \ sigil: \NAME captures one node, \(NAME*\) a run of siblings, \_/\* match anonymously. The pattern is matched per language, so a single invocation scans every supported source file (others are skipped). Inside an initialized project, ccc grep honors the project's include/exclude patterns and .gitignore; otherwise it scans all supported source files under the path.

Results stream to the terminal file-by-file as each match is found (in completion order, since files are matched in parallel) rather than all at once at the end. Each matching file shows its matched line range; under a TTY the path is colored, line numbers are dimmed, and the unmatched context around a match is dimmed so the match stands out.

Note: ccc grep relies on cocoindex's structural code_match feature.

Until it ships in a released cocoindex, run against a local cocoindex build.

Docker

A Docker image is available for teams who want a reproducible, dependency-free setup — no Python, uv, or system dependencies required on the host.

The recommended approach is a persistent container: start it once, and use docker exec to run CLI commands or connect MCP sessions to it. The daemon inside stays warm across sessions, so the embedding model is loaded only once.

Choosing an image

Two variants are published from each release:

| Tag | Size | Embedding backends | When to pick | |---|---|---|---| | cocoindex/cocoindex-code:latest (slim, default) | ~450 MB | LiteLLM (cloud: OpenAI, Voyage, Gemini, Ollama, …) | Most users. Cloud-backed embeddings, smaller image, fast pulls. | | cocoindex/cocoindex-code:full | ~5 GB | sentence-transformers (local) + LiteLLM | When you want local embeddings without an API key, or an offline-ready container. Heavier because of torch + transformers. |

The rest of this section uses :latest — substitute :full in the image: / docker run commands if you want the full variant.

Mac users running the :full variant: local embedding inference is

CPU-only inside Docker, because Docker on macOS can't access Apple's Metal

(MPS) GPU. If you want local embeddings and fast inference, install

natively instead: pipx install 'cocoindex-code[full]'. The :latest

(slim) variant is unaffected — LiteLLM runs the model on the provider's

side, so Docker vs. native makes no difference.

Quick start — docker compose up -d

Bring it up in one line — no clone needed (bash / zsh):

# macOS / Windows
docker compose -f <(curl -L https://raw.githubusercontent.com/cocoindex-io/cocoindex-code/refs/heads/main/docker/docker-compose.yml) up -d
Linux (aligns file ownership on bind-mounted paths with your host user)
PUID=$(id -u) PGID=$(id -g) docker compose -f <(curl -L https://raw.githubusercontent.com/cocoindex-io/cocoindex-code/refs/heads/main/docker/docker-compose.yml) up -d

Or grab docker/docker-compose.yml and run docker compose up -d next to it (works on any shell, including Windows cmd / PowerShell).

By default your home directory is mounted into the container (set COCOINDEX_HOST_WORKSPACE to narrow this to a specific code folder). Index data and the embedding model cache persist in a Docker volume across restarts. Your global settings file at $HOME/.cocoindex_code/global_settings.yml is visible and editable on the host; edits take effect on your next ccc command.

Pick a different image: set COCOINDEX_CODE_IMAGE to override the

default. For example, the :full variant or GHCR:

> COCOINDEX_CODE_IMAGE=cocoindex/cocoindex-code:full docker compose up -d

Or: docker run

docker run -d --name cocoindex-code \
  --volume "$HOME:/workspace" \
  --volume cocoindex-data:/var/cocoindex \
  -e COCOINDEX_CODE_HOST_PATH_MAPPING="/workspace=$HOME" \
  cocoindex/cocoindex-code:latest

docker run -d --name cocoindex-code \
  -e PUID=$(id -u) -e PGID=$(id -g) \
  --volume "$HOME:/workspace" \
  --volume cocoindex-data:/var/cocoindex \
  -e COCOINDEX_CODE_HOST_PATH_MAPPING="/workspace=$HOME" \
  cocoindex/cocoindex-code:latest

Shell wrapper for ccc commands

Paste this into ~/.bashrc / ~/.zshrc so ccc feels native on the host and picks up the right project based on your current directory:

ccc() {
  docker exec -it -e COCOINDEX_CODE_HOST_CWD="$PWD" cocoindex-code ccc "$@"
}

Now cd into any project under your workspace and run ccc init, ccc index, ccc search ..., ccc status, etc. — it just works.

Connect your coding agent

claude mcp add cocoindex-code -- docker exec -i \
  -e COCOINDEX_CODE_HOST_CWD="$PWD" cocoindex-code ccc mcp

{
  "mcpServers": {
    "cocoindex-code": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "-e",
        "COCOINDEX_CODE_HOST_CWD=${PWD}",
        "cocoindex-code",
        "ccc",
        "mcp"
      ]
    }
  }
}

codex mcp add cocoindex-code -- docker exec -i \
  -e COCOINDEX_CODE_HOST_CWD="$PWD" cocoindex-code ccc mcp

Upgrading from an older image

Earlier images used separate cocoindex-db and cocoindex-model-cache volumes; the current image consolidates them into a single cocoindex-data volume. Before pulling the new image, drop the old container and volumes — indexes rebuild on your next ccc index, and the embedding model is re-populated automatically on first start:

docker rm -f cocoindex-code
docker volume rm cocoindex-db cocoindex-model-cache

Configuration via environment variables

Pass configuration to docker run / compose with -e:

# Extra extensions (e.g. Typesafe Config, SBT build files)
-e COCOINDEX_CODE_EXTRA_EXTENSIONS="conf,sbt"
Exclude build artefacts (Scala/SBT example)
-e COCOINDEX_CODE_EXCLUDE_PATTERNS='["/target/","/.bloop/","/.metals/"]'
Set an API key
-e VOYAGE_API_KEY=your-key

Security note: mounting $HOME gives the container read/write access

to everything under it. If that's too broad, bind-mount a narrower

directory instead (COCOINDEX_HOST_WORKSPACE=/path/to/code).

Build the image locally

docker build -t cocoindex-code:local -f docker/Dockerfile .

Features

• Semantic Code Search: Find relevant code using natural language queries when grep doesn't work well, and save tokens immediately.
• Ultra Performant: ⚡ Built on top of ultra performant Rust indexing engine. Only re-indexes changed files for fast updates.
• Multi-Language Support: Python, JavaScript/TypeScript, Rust, Go, Java, C/C++, C#, SQL, Shell, and more.
• Embedded: Portable and just works, no database setup required!
• Flexible Embeddings: Local SentenceTransformers via the [full] extra (free, no API key!) or 100+ cloud providers via LiteLLM.

Configuration

For a detailed guide on choosing and configuring embedding models, see EMBEDDINGS.md.

Configuration lives in two YAML files, both created automatically by ccc init.

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

Shared across all projects. Controls the embedding model and environment variables for the daemon.

embedding:
  provider: sentence-transformers                    # or "litellm"
  model: Snowflake/snowflake-arctic-embed-xs
  device: mps                                        # optional: cpu, cuda, mps (auto-detected if omitted)
  min_interval_ms: 300                               # optional: pace LiteLLM embedding requests to reduce 429s; defaults to 5 for LiteLLM
  mps_low_watermark_ratio: 0.4                       # optional: PyTorch allocator soft limit
  mps_high_watermark_ratio: 0.5                      # optional: PyTorch allocator hard limit
# Optional extra kwargs passed to the embedder, separately for indexing vs query.
  # ccc init auto-populates these for known models (e.g. Cohere, Voyage, Nvidia NIM,
  # nomic-ai code-retrieval models, Snowflake arctic-embed).
  # indexing_params:
  #   input_type: search_document        # litellm: input_type
  # query_params:
  #   input_type: search_query           # sentence-transformers: prompt_name
envs:                                                # extra environment variables for the daemon
  OPENAI_API_KEY: your-key                           # only needed if not already in your shell environment
daemon:
  idle_timeout_minutes: 180                          # optional: exit the daemon after this long without client activity (default 180, 0 = never)
  keep_alive_with_mcp: true                          # optional: keep the daemon warm while an MCP client is connected (default true)

Note: The daemon inherits your shell environment. If an API key (e.g. OPENAI_API_KEY) is already set as an environment variable, you don't need to duplicate it in envs. The envs field is only for values that aren't in your environment.

Apple Silicon memory safety: MPS SentenceTransformer calls use CocoIndex's isolated GPU subprocess, keeping the model loaded while i