cocoindex-io/cocoindex-code

cocoindex‑code – AST‑based semantic code search

What it is – A lightweight command‑line tool (and plugin) that lets you search a codebase by meaning rather than exact text. It builds an index from the abstract‑syntax‑trees (ASTs) of your source files using the Rust‑based CocoIndex engine, then answers natural‑language queries with relevant code snippets.

Why it matters – By understanding the structure of code, the tool can find matches even when identifiers or formatting differ, saving up to ~70 % of token usage for LLM‑powered agents that need to look up code.

---

Key features (as described in the README)

• AST‑based semantic search – indexes code structure, not just raw text.
• Two install flavors:
  • cocoindex-code[full] – bundles a local sentence‑transformers model (no API key needed).
  • cocoindex-code (slim) – uses LiteLLM cloud providers for embeddings.
• One‑minute zero‑config setup – ccc init (or the skill) creates defaults automatically.
• CLI commands – ccc init, ccc index, ccc search, ccc grep (structural pattern search), status, diagnostics, daemon control, etc.
• Agent integration – provides a skill (ccc) and optional hooks and MCP server that can be consumed by Claude Code, Grok, Oh My Pi, Codex, OpenCode, Kilo Code, etc.
• Docker images – cocoindex/cocoindex-code:latest (slim, cloud embeddings) and :full (local embeddings) for reproducible, dependency‑free deployments.
• MCP tool – exposes a search tool with parameters for query, result limit, language/path filters, and optional index refresh.
• Structural search (ccc grep) – pattern‑by‑example matching using the same AST engine, no index required.

---

Quick start (CLI)

# install via pipx (full variant includes local embeddings)
pipx install 'cocoindex-code[full]'
# or the slim variant
pipx install cocoindex-code

# initialise a project (creates .cocoindex_code/settings.yml)
ccc init
# build the index (runs a background daemon automatically)
ccc index
# search by description
ccc search "authentication logic"

The tool will auto‑initialise on first use, and a daemon keeps the index warm.

---

Agent / plugin usage

1. Skill (recommended) – add the skill to a coding agent:

   npx skills add cocoindex-io/cocoindex-code
   

   The agent then runs ccc init, ccc index, and ccc search on its own, updating the index as you edit files.
2. Claude Code – install via Claude’s plugin marketplace (/plugin marketplace add …).
3. Grok – install the plugin which bundles the skill, a session‑start/post‑tool‑use hook (auto‑index), and an MCP server (ccc mcp).
4. Oh My Pi – similar installation path; the plugin also provides a TypeScript hook for incremental indexing.
5. MCP server – run ccc mcp and register it with any agent that supports MCP (Claude, Codex, OpenCode, Kilo, etc.). The exposed search tool accepts natural‑language queries and optional filters.

---

Docker deployment

# one‑liner for any OS (pulls compose file from GitHub)
# macOS / Windows
docker compose -f <(curl -L https://raw.githubusercontent.com/cocoindex-io/cocoindex-code/main/docker/docker-compose.yml) up -d
# Linux (preserves file ownership)
PUID=$(id -u) PGID=$(id -g) docker compose -f <(curl -L https://raw.githubusercontent.com/cocoindex-io/cocoindex-code/main/docker/docker-compose.yml) up -d

The container runs the daemon and stores index data in a Docker volume. A shell wrapper can forward ccc commands into the container:

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

---

When to use which variant

Variant	Size	Embedding source	Best for
cocoindex-code:latest (slim)	~450 MB	LiteLLM cloud providers (OpenAI, Gemini, etc.)	Most users, minimal image, works with any API key
cocoindex-code:full	~5 GB	Local sentence‑transformers model (e.g., snowflake-arctic-embed-xs)	Offline environments or when you prefer not to expose an API key

---

TL;DR

• Install with pipx install 'cocoindex-code[full]' (or the slim variant).
• Run ccc init && ccc index once.
• Search via ccc search "…" or let a coding agent invoke the ccc skill/MCP.
• Optional Docker image for team‑wide, reproducible setups.

The project is a genuine, open‑source AI‑powered tool for semantic code search, tightly integrated with modern LLM coding assistants.