# Cocoindex Code

> A super light-weight embedded code search engine CLI (AST based) that just works - saves 70% token and improves speed for coding agent 🌟 Star if you like it!

- **Type:** MCP server
- **Install:** `agentstack add mcp-cocoindex-io-cocoindex-code`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [cocoindex-io](https://agentstack.voostack.com/s/cocoindex-io)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [cocoindex-io](https://github.com/cocoindex-io)
- **Source:** https://github.com/cocoindex-io/cocoindex-code
- **Website:** https://cocoindex.io/

## Install

```sh
agentstack add mcp-cocoindex-io-cocoindex-code
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

AST-based semantic code search that just works

A lightweight, effective **(AST-based)** semantic code search tool for your codebase. Built on [CocoIndex](https://github.com/cocoindex-io/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](#skill-recommended) or [MCP](#mcp-server).

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

[](https://discord.com/invite/zpA9S2DR7s)
[](https://github.com/cocoindex-io/cocoindex)
[](https://cocoindex.io/docs/getting_started/quickstart)
[](https://opensource.org/licenses/Apache-2.0)

[](https://pepy.tech/projects/cocoindex)
[](https://github.com/cocoindex-io/cocoindex/actions/workflows/CI.yml)
[](https://github.com/cocoindex-io/cocoindex/actions/workflows/release.yml)

🌟 Please help star [CocoIndex](https://github.com/cocoindex-io/cocoindex) if you like this project!

[Deutsch](https://readme-i18n.com/cocoindex-io/cocoindex-code?lang=de) |
[English](https://readme-i18n.com/cocoindex-io/cocoindex-code?lang=en) |
[Español](https://readme-i18n.com/cocoindex-io/cocoindex-code?lang=es) |
[français](https://readme-i18n.com/cocoindex-io/cocoindex-code?lang=fr) |
[日本語](https://readme-i18n.com/cocoindex-io/cocoindex-code?lang=ja) |
[한국어](https://readme-i18n.com/cocoindex-io/cocoindex-code?lang=ko) |
[Português](https://readme-i18n.com/cocoindex-io/cocoindex-code?lang=pt) |
[Русский](https://readme-i18n.com/cocoindex-io/cocoindex-code?lang=ru) |
[中文](https://readme-i18n.com/cocoindex-io/cocoindex-code?lang=zh)

## Get Started — zero config, let's go!

### Install

Using [pipx](https://pipx.pypa.io/stable/installation/):
```bash
pipx install 'cocoindex-code[full]'          # batteries included (local embeddings)
pipx upgrade cocoindex-code                  # upgrade
```

Using [uv](https://docs.astral.sh/uv/getting-started/installation/):
```bash
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](https://huggingface.co/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](#coding-agent-integration) — or jump to [Manual CLI Usage](#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:

```bash
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](https://docs.anthropic.com/en/docs/claude-code) and other skill-compatible agents.

#### Claude Code plugin marketplace

For Claude Code users, this repository is also a [plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces). Install the skill from inside Claude Code with:

```text
/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](#mcp-server) section below instead of using the bundled `.mcp.json`.

#### Grok plugin

For [Grok](https://github.com/xai-org/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` → 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):

```bash
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` hook from `cocoindex-code`, press `Space` to disable.
2. **MCP** — open `/mcps`, select `cocoindex-code`, press `Space` to disable; or persist in `~/.grok/config.toml`:

```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):

```toml
[compat.claude]
mcps = false

[compat.cursor]
mcps = false
```

### MCP Server

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

Claude Code

```bash
claude mcp add cocoindex-code -- ccc mcp
```

Codex

```bash
codex mcp add cocoindex-code -- ccc mcp
```

OpenCode

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

Or use opencode.json:
```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`:

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

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.

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.

```bash
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:** `ccc index` auto-initializes if you haven't run `ccc init` yet, so you can skip straight to indexing.

### 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 daemon status` | Show daemon version, uptime, and loaded projects |
| `ccc daemon restart` | Restart the background daemon |
| `ccc daemon stop` | Stop the daemon |

### Search Options

```bash
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.

```bash
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):

```bash
# macOS / Windows
docker compose -f  **Pick a different image:** set `COCOINDEX_CODE_IMAGE` to override the
> default. For example, the `:full` variant or GHCR:
> ```bash
> COCOINDEX_CODE_IMAGE=cocoindex/cocoindex-code:full docker compose up -d
> COCOINDEX_CODE_IMAGE=ghcr.io/cocoindex-io/cocoindex-code:latest docker compose up -d
> ```

### Or: `docker run`

Docker Desktop (macOS / Windows)

```bash
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
```

Linux (with PUID/PGID)

```bash
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:

```bash
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 Code

Register MCP from inside the target project so `$PWD` points there:

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

Or via `.mcp.json`:

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

> Note: use `-i` (not `-it`). The `-t` flag allocates a terminal, which
> interferes with MCP's JSON messaging over stdin/stdout — only add it for
> interactive `ccc` commands like `ccc init`.

Codex

```bash
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

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [cocoindex-io](https://github.com/cocoindex-io)
- **Source:** [cocoindex-io/cocoindex-code](https://github.com/cocoindex-io/cocoindex-code)
- **License:** Apache-2.0
- **Homepage:** https://cocoindex.io/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** yes
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-cocoindex-io-cocoindex-code
- Seller: https://agentstack.voostack.com/s/cocoindex-io
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.