Cocoindex Code

MCP开发工具

提供方 cocoindex-io

开发工具 未标注 API Key 社区 / 第三方 ClaudeCursorGemini CLICodex
查看接入方式

An MCP (Model Context Protocol) server for indexing and querying codebases using CocoIndex. Features semantic code search with natural language queries, incremental indexing for fast updates, multi-language support (Python, JavaScript/TypeScript, Rust, Go, Java, C/C++, C#, SQL, S

一句话选型结论

按资料字段整理

Cocoindex Code 属于开发工具类 MCP 服务器,传输方式未标注,API Key,可直接接入 Claude、Cursor、Gemini CLI 等,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类开发工具 传输方式未标注 鉴权API Key 部署方式未标注
GitHub 星标 未标注 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

开发工具
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

code search semantic search codebase indexing embeddings sqlite developer tools

支持客户端

适用场景

code searchsemantic searchcodebase

安装与配置

未标注 API Key
上游未给出传输方式
uv run --project /path/to/cocoindex-code cocoindex-code

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    按官方文档确认运行环境(常见为 Node.js 或 Python),装好后再执行安装命令。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
代码与仓库操作

在对话里直接查代码、提 issue、走 PR,省掉来回切工具。

本地命令与脚本

把构建、测试、格式化这类重复命令交给模型执行。

接口联调与测试

让模型调你的接口、跑一遍用例,快速定位问题。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude、Cursor、Gemini CLI,换客户端不用重新研究配置。

先想清楚的地方

  • 使用前要准备好API Key对应的凭据,并按最小权限配置。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在开发工具场景里让模型直接调用外部能力的人。
  • 已经在用 Claude、Cursor 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Cocoindex Code当前 未标注 未标注 未标注 有 未标注
Git 838e2ec1 12 stdio · 本地进程 本地部署 有 2026-05-17
Markitdown MCP 2c653a5f 1 stdio · 本地进程 本地部署 有 2026-05-17
JavaGuide 未标注 stdio · 本地进程 本地部署 有 2026-04-11
awesome-claude-skills 未标注 stdio · 本地进程 本地部署 有 2026-04-26
Context7 831acf40 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

开发工具
字段来自项目仓库与公开索引,中文说明由本站标注
提供方cocoindex-io上游标注的维护方 cocoindex-io
分类开发工具本站按上游分类展示
连接方式未标注上游未给出传输方式
鉴权方式API Key远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Cross-platform本地安装时用到的包标识与运行时
部署类型未标注上游给出的部署形态
最近核验未标注上游最后核验时间

详细介绍

38.1 KB
来自项目仓库与上游目录的原文,未做删改

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!

🌟 Please help star CocoIndex if you like this project!

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

Get Started — zero config, let's go!

Install

Using pipx:```bash
pipx install 'cocoindex-code[full]' # batteries included (local embeddings)
pipx upgrade cocoindex-code # upgrade


Using uv:```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.
- 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:```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 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:```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 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):```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` / `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`:```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


#### Oh My Pi plugin

Oh My Pi reads `.omp-plugin/marketplace.json` (preferred) and falls back to `.claude-plugin/marketplace.json`.```bash
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```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
}
}
}


Oh My Pi

Prefer the marketplace install above. Manual project MCP (`.omp/mcp.json`):```json
{
  "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.

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

> Note: ccc index never auto-initializes the directory that holds ccc's user settings directory: your home directory by default (~/.cocoindex_code holds the global settings and daemon files), or the parent of $COCOINDEX_CODE_DIR when that directory is named .cocoindex_code. A project there would cover every repo below it. The editor hooks skip that directory even if it is already a project. If an older ccc made your home directory a project (~/.cocoindex_code/settings.yml exists), run ccc reset --all in your home directory: it removes that project's settings and indexes and keeps your global settings. To index your whole home directory on purpose, run ccc init there.

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

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

### Or: `docker run`

Docker Desktop (macOS / Windows)```bash
docker run -d --name cocoindex-code \
  --volume &quot;$HOME:/workspace&quot; \
  --volume cocoindex-data:/var/cocoindex \
  -e COCOINDEX_CODE_HOST_PATH_MAPPING=&quot;/workspace=$HOME&quot; \
  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=&quot;$PWD&quot; cocoindex-code ccc &quot;$@&quot;
}

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
{
  &quot;mcpServers&quot;: {
    &quot;cocoindex-code&quot;: {
      &quot;type&quot;: &quot;stdio&quot;,
      &quot;command&quot;: &quot;docker&quot;,
      &quot;args&quot;: [
        &quot;exec&quot;,
        &quot;-i&quot;,
        &quot;-e&quot;,
        &quot;COCOINDEX_CODE_HOST_CWD=${PWD}&quot;,
        &quot;cocoindex-code&quot;,
        &quot;ccc&quot;,
        &quot;mcp&quot;
      ]
    }
  }
}

> 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 container and volumes —
indexes rebuild on your next `ccc index`, and the embedding model is
re-populated automatically on first start:```bash
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:```bash

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


&gt; **Security note:** mounting `$HOME` gives the container read/write access
&gt; to everything under it. If that&#x27;s too broad, bind-mount a narrower
&gt; directory instead (`COCOINDEX_HOST_WORKSPACE=/path/to/code`).

### Build the image locally```bash
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.
  • 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.```yaml
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)


&gt; **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&#x27;t need to duplicate it in `envs`. The `envs` field is only for values that aren&#x27;t in your environment.

&gt; **Apple Silicon memory safety:** MPS SentenceTransformer calls use CocoIndex&#x27;s isolated GPU subprocess, keeping the model loaded while isolating Metal allocations from the daemon. The low and high watermarks are ratios of PyTorch&#x27;s recommended maximum working set; they default here to `0.4` and `0.5`. CocoIndex retries MPS out-of-memory failures with progressively smaller batches, and cocoindex-code releases unused allocator cache after each index run. Explicit `COCOINDEX_RUN_GPU_IN_SUBPROCESS`, `PYTORCH_MPS_LOW_WATERMARK_RATIO`, and `PYTORCH_MPS_HIGH_WATERMARK_RATIO` environment variables take precedence over these defaults.

&gt; **Indexing concurrency:** Multiple projects may prepare indexes concurrently, while CocoIndex serializes their GPU calls through its single MPS subprocess. A search waits only when its own project still needs the initial index.

&gt; **Idle timeout:** the background daemon holds the embedding model in RAM, so it exits after `daemon.idle_timeout_minutes` without client activity and is restarted automatically on your next `ccc` command or MCP search. By default, a live MCP session sends periodic heartbeats so the daemon remains warm while your coding agent is connected. Set `daemon.keep_alive_with_mcp: false` to let the daemon idle-exit during long-lived MCP sessions and release the model between real requests. Set `idle_timeout_minutes: 0` to keep the daemon running forever.

&gt; **Custom location:** set `COCOINDEX_CODE_DIR` to place `global_settings.yml` somewhere other than `~/.cocoindex_code/` — useful if you want the file to live alongside your projects (e.g. on a synced folder).

#### `indexing_params` / `query_params`

Some embedding models expose different modes for documents vs queries (asymmetric retrieval). For example, Cohere&#x27;s v3 models want `input_type: search_document` when embedding corpus content and `input_type: search_query` when embedding a user query; several SentenceTransformers models use `prompt_name: passage` / `prompt_name: query` for the same purpose. These knobs live under `indexing_params` and `query_params`:```yaml
embedding:
  provider: litellm
  model: cohere/embed-english-v3.0
  indexing_params:
    input_type: search_document
  query_params:
    input_type: search_query

ccc init populates these automatically for models it recognizes — including all Cohere v3, Voyage, Nvidia NIM, Gemini embedding (gemini/gemini-embedding-*, gemini/text-embedding-*, gemini/embedding-* — LiteLLM auto-maps input_type to Gemini's task_type), nomic-ai/CodeRankEmbed, nomic-ai/nomic-embed-code, nomic-ai/nomic-embed-text-v1/v1.5, mixedbread-ai/mxbai-embed-large-v1, and the Snowflake/snowflake-arctic-embed-* family — and prints the chosen defaults. For other models, it leaves a commented-out template under embedding: so you can fill it in by hand.

OpenAI embeddings (text-embedding-3-*, text-embedding-ada-002) are intentionally not in the list: they're symmetric and have no equivalent knob.

Accepted keys: prompt_name (sentence-transformers) and input_type (litellm). Other keys are rejected at daemon startup with a clear error. Note: dimensions is intentionally not exposed here — output dimension must be identical for indexing and query, so it's a model-wide setting rather than a per-side knob.

Doctor checks both sides. ccc doctor exercises the model once with indexing_params and once with query_params, reporting each as a separate Model Check (indexing) / Model Check (query) entry — so a misconfiguration on one side is diagnosable without hiding behind the other.

Legacy-bridge warning: if you're upgrading from an earlier version and your global_settings.yml uses nomic-ai/CodeRankEmbed or nomic-ai/nomic-embed-code without indexing_params / query_params, the daemon continues to apply the previous behavior (prompt_name: query at query time) and prints a one-time warning asking you to make the setting explicit. You can silence the warning by adding an empty block such as query_params: {}.

Project Settings (/.cocoindex_code/settings.yml)

Per-project. Controls which files to index.```yaml
include_patterns:
- "/*.py"
- "
/.js"
- "
/.ts"
- "/*.rs"
- "
/*.go"
# ... (sensible defaults for 28+ file types)

exclude_patterns:
- "/.*" # hidden directories
- "
/pycache"
- "/node_modules"
- "
/dist"
# ...

max_file_size: 500KB # skip files larger than this (default: no limit)

language_overrides:
- ext: inc # treat .inc files as PHP
lang: php

chunkers:
- ext: toml # use a custom chunker for .toml files
module: example_toml_chunker:toml_chunker


&gt; `.cocoindex_code/` is automatically added to `.gitignore` during init.

`max_file_size` keeps bundled or generated files out of the index without having
to enumerate them in `exclude_patterns`. It accepts a plain byte count
(`1048576`) or a size with a binary unit suffix: `B`, `KB`, `MB`, `GB`
(case-insensitive, so `500KB` and `500 kb` are the same). The limit is
inclusive, and omitting the key indexes files of any size. It applies wherever
project file matching does, so `ccc grep` skips the same files.

After editing `include_patterns`, `exclude_patterns`, `max_file_size`, or `language_overrides`:

- Run `ccc doctor` to preview which files match.
- Run `ccc index` or `ccc search --refresh ...` to update the existing index.
- You do not need to delete the index or restart the daemon for these file-matching changes.
- After any `language_overrides` change, the next run re-chunks all files, including files whose content did not change; the run reports them as reprocessed. Chunks whose text did not change keep their cached embeddings.

If you add or change custom `chunkers`, or edit a chunker module, restart the daemon (`ccc daemon restart`), then run `ccc index`. The daemon imports chunkers once at startup, so until it restarts it keeps running the old chunker code. The first run after the restart re-chunks all files, not only the ones the changed entry applies to; chunks whose text did not change keep their cached embeddings. A chunker counts as changed when its `module:` value changes or when the file of the module it names changes. Edits to other modules that file imports are not detected: after such an edit, also change the chunker&#x27;s own module file (for example, bump a version comment in it).

Use `chunkers` when you want to control how a file type is split into chunks before indexing.

`module: example_toml_chunker:toml_chunker` means:
- `example_toml_chunker` is a local Python module
- `toml_chunker` is the function inside that module

In practice, this usually means:
- you create a Python file in your project, for example `example_toml_chunker.py`
- you add a function in that file
- you point `settings.yml` at it with `module.path:function_name`

The function should use this signature:```python
from pathlib import Path
from cocoindex_code.chunking import Chunk

def my_chunker(path: Path, content: str) -&gt; tuple[str | None, list[Chunk]]:
    ...
  • path is the file being indexed
  • content is the full text of that file
  • return language_override as a string like &quot;toml&quot; if you want to override language detection
  • return None as language_override if you want to keep the detected language
  • return a list[Chunk] with the chunks you want stored in the index

See src/cocoindex_code/chunking.py for the public types and tests/example_toml_chunker.py for a complete example.

Embedding Models

With the [full] extra installed, ccc init defaults to a local SentenceTransformers model (Snowflake/snowflake-arctic-embed-xs) — no API key required. To use a different model, edit ~/.cocoindex_code/global_settings.yml.

> The envs entries below are only needed if the key isn't already in your shell environment — the daemon inherits your environment automatically.

Ollama (Local)```yaml
embedding:
model: ollama/nomic-embed-text


Set `OLLAMA_API_BASE` in `envs:` if your Ollama server is not at `http://localhost:11434`.

OpenAI```yaml
embedding:
  model: text-embedding-3-small
  min_interval_ms: 300                               # optional: override the 5ms LiteLLM default
envs:
  OPENAI_API_KEY: your-api-key

OpenAI-compatible (custom endpoint)

Many providers (vLLM, LM Studio, LocalAI, Together, Fireworks, DeepInfra, …) expose an OpenAI-compatible embedding API. Use the openai/ prefix and point OPENAI_BASE_URL at your endpoint:```yaml
embedding:
model: openai/your-model-name
envs:

…(正文过长,页面只展示前面部分,完整内容见仓库)
```

常见问题

7 问
答案由本站依据条目字段整理,不引用上游原文
Cocoindex Code 怎么安装?

在客户端按下面的安装命令接入:uv run --project /path/to/cocoindex-code cocoindex-code。装完在客户端配置里引用同一个包或端点。

Cocoindex Code 怎么在 Claude、Cursor、Gemini CLI 里配置?

它的传输方式未标注,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Cocoindex Code 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Cocoindex Code 需要 API Key 吗?

资料标注需要API Key认证,使用前准备好对应凭据,并按最小权限配置。

Cocoindex Code 支持哪些客户端?

资料标注支持 Claude、Cursor、Gemini CLI、Codex、Zed;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Cocoindex Code 能提供哪些能力?

资料显示能力标签包括 code search、semantic search、codebase、indexing、embeddings、sqlite。具体工具清单以官方文档为准。

Cocoindex Code 需要什么运行环境?

运行时为 Cross-platform。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 未标注。