cocoindex-code

CocoIndex Code provides AST-based semantic search for your codebase, built on the CocoIndex Rust data transformation engine. Use it from the CLI or connect Claude, Codex, Cursor, and other coding agents through a Skill or MCP.

• 70% token savings.
• 1 min setup with default settings.

Star CocoIndex if you find it useful.

Deutsch | English | Español | français | 日本語 | 한국어 | Português | Русский | 中文

Get Started

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).

Next, set up your coding agent integration — or jump to Manual CLI Usage if you prefer direct control.

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

The skill teaches the agent to handle initialization, indexing, and searching, so you don't need to run ccc init or ccc index yourself. The agent keeps 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/settings.yml exists (never in the directory holding ccc's user settings, ~ by default)
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/settings.yml exists (never in the directory holding ccc's user settings, ~ by default)
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 Code

claude mcp add cocoindex-code -- ccc mcp

Codex

codex mcp add cocoindex-code -- ccc mcp

OpenCode

opencode mcp add

Enter MCP server name: cocoindex-code Select MCP server type: local Enter command to run: ccc mcp

Or use opencode.json:

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

Kilo Code

Add a local MCP server in ~/.config/kilo/kilo.jsonc, kilo.jsonc, or .kilo/kilo.jsonc:

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

Oh My Pi

Prefer the marketplace install above. Manual project MCP (.omp/mcp.json):

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

Once configured, the agent can use semantic search to find code by description, explore unfamiliar codebases, and locate implementations without 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.

MCP Tool Reference

When running as an MCP server (ccc mcp), the following tool is exposed:

search — Search the codebase using semantic similarity.

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/*"])
)

Returns matching code chunks with file path, language, code content, line numbers, and similarity score.

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.