CocoIndex Code

https://github.com/cocoindex-io/cocoindex-code
Admin
An MCP server for indexing and querying codebases using semantic search with support for multiple...
Tokens:111,848
Snippets:817
Trust Score:8.9
License:Apache-2.0
Update:13 hours ago
Show doc for...
Tokens:
Raw
### Install cocoindex-code with uv

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/README.md

Install the full version of cocoindex-code using uv tool. The --upgrade flag ensures the latest version is installed.

```bash
uv tool install --upgrade 'cocoindex-code[full]'
```

--------------------------------

### Install pre-commit git hook with prek install

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/README.md

Installs a git hook so the same checks run automatically on every git commit. Optional but recommended for contributors.

```bash
uv run prek install
```

--------------------------------

### Quick start with docker compose (macOS/Windows)

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/README.md

Starts the container in one line without cloning the repo. Mounts your home directory and persists index data and model cache in a Docker volume.

```bash
docker compose -f <(curl -L https://raw.githubusercontent.com/cocoindex-io/cocoindex-code/refs/heads/main/docker/docker-compose.yml) up -d
```

--------------------------------

### Sync dev dependencies with uv sync

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/README.md

Installs all development dependencies required for linting, formatting, type checking, and tests. Requires uv to be installed first.

```bash
uv sync
```

--------------------------------

### Install cocoindex-code with full extra

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/EMBEDDINGS.md

Install cocoindex-code with the full extra to enable the sentence-transformers provider.

```bash
pip install "cocoindex-code[full]"
```

--------------------------------

### Install or upgrade cocoindex-code with uv

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/README.md

Use uv to install or upgrade cocoindex-code. This command handles both install and upgrade.

```bash
uv tool install --upgrade cocoindex-code
```

--------------------------------

### Install CocoIndex Code via pipx (full and slim)

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/skills/ccc/references/management.md

Two install styles: the [full] extra includes sentence-transformers for local embeddings, while the slim install requires a cloud embedding provider and API key.

```bash
pipx install 'cocoindex-code[full]'      # batteries included (local embeddings via sentence-transformers)
```

```bash
pipx install cocoindex-code              # slim (LiteLLM-only; requires a cloud embedding provider + API key)
```

--------------------------------

### Install Oh My Pi plugin

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/README.md

Installs the cocoindex-code plugin for Oh My Pi with project scope. Requires ccc on PATH (uv tool install --upgrade 'cocoindex-code[full]'). Restart the session after install; /reload-plugins does not reload extensions.

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

--------------------------------

### Full install for Grok plugin (skill + hook + MCP)

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/README.md

Installs the Grok plugin with skill, hook, and MCP components. --trust is required to activate hooks and MCP server. Prefer the GitHub shorthand for install; grok plugin install cocoindex-code can fail when no marketplace plugin matches that bare name.

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

--------------------------------

### global_settings.yml example

Source: https://github.com/cocoindex-io/cocoindex-code

Example user settings file at ~/.cocoindex_code/global_settings.yml. Base directory overridable with COCOINDEX_CODE_DIR. Editing this file restarts the daemon automatically on the next request.

```yaml
embedding:
  provider: sentence-transformers   # or "litellm" (provider omitted => "litellm")
  model: Snowflake/snowflake-arctic-embed-xs
  device: mps                       # cpu | cuda | mps; auto-detected when omitted
  min_interval_ms: 300              # pace LiteLLM requests; effective default 5
  mps_low_watermark_ratio: 0.4
  mps_high_watermark_ratio: 0.5
  indexing_params:                  # extra kwargs for embed() during indexing
    input_type: search_document     # litellm: input_type
  query_params:                     # extra kwargs for embed() at query time
    input_type: search_query        # sentence-transformers: prompt_name
envs:
  OPENAI_API_KEY: your-key          # injected into the daemon's environment
daemon:
  idle_timeout_minutes: 180         # 0 = never idle-exit
  keep_alive_with_mcp: true         # false = allow idle exit during MCP sessions
```

--------------------------------

### Install or upgrade cocoindex-code with pipx

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/README.md

Use pipx to install or upgrade cocoindex-code after fixing the Python installation. The first command installs, the second upgrades.

```bash
pipx install cocoindex-code       # first install
```

```bash
pipx upgrade cocoindex-code       # upgrade
```

--------------------------------

### Quick start with docker compose (Linux with PUID/PGID)

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/README.md

Same as the macOS/Windows command but sets PUID and PGID to align file ownership on bind-mounted paths with your host user.

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

--------------------------------

### Project settings.yml example

Source: https://github.com/cocoindex-io/cocoindex-code

Example configuration for the project settings file at `<project>/.cocoindex_code/settings.yml`. Shows include/exclude patterns, max file size, language overrides, and custom chunkers. Note that chunker edits require `ccc daemon restart`.

```yaml
include_patterns:
  - "**/*.py"
  - "**/*.tsx"
  # ... DEFAULT_INCLUDED_PATTERNS (~60 entries: py, pyi, js, jsx, ts, tsx, mjs, cjs,
  #     rs, go, java, c, h, cpp, hpp, cc, cxx, hxx, hh, cs, dart, ex, exs, sql, sh,
  #     bash, zsh, md, mdx, txt, rst, php, lua, rb, swift, kt, kts, scala, r, html,
  #     htm, svelte, vue, css, scss, json, xml, yaml, yml, toml, sol, pas, dpr, dtd,
  #     f, f90, f95, f03)
exclude_patterns:
  - "**/.*"
  - "**/__pycache__"
  - "**/node_modules"
  - "**/target"
  - "**/build/assets"
  - "**/dist"
  - "**/vendor/*.*/*"
  - "**/vendor/*"
  - "**/.cocoindex_code"
max_file_size: 500KB            # bytes or unit-suffixed (B, KB, MB, GB; binary)
language_overrides:
  - ext: inc
    lang: php
chunkers:
  - ext: toml
    module: example_toml_chunker:toml_chunker
```

--------------------------------

### Initialize with a specific LiteLLM model

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/skills/ccc/references/management.md

Skips interactive prompts on first run by specifying a LiteLLM model. This is the only way to pick a LiteLLM model when stdin is not a TTY and using a slim install.

```bash
ccc init --litellm-model openai/text-embedding-3-small
```

--------------------------------

### Install cocoindex-code with pipx

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/README.md

Install the full version of cocoindex-code using pipx, which includes local embeddings. Upgrade with the same command.

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

--------------------------------

### Configure sentence-transformers in global_settings.yml

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/EMBEDDINGS.md

Example global_settings.yml configuration for the sentence-transformers provider. Set device to 'cuda' or 'mps' if you have a GPU.

```yaml
embedding:
  provider: sentence-transformers
  model: lightonai/LateOn-Code-edge
  device: cpu # Use 'cuda' or 'mps' if you have a GPU
```

--------------------------------

### Basic CLI commands: init, index, search

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/README.md

Initialize a project, build the index, and search. The background daemon starts automatically on first use. You can skip `ccc init` and go straight to `ccc index`; it auto-initializes new projects with default settings. Non-interactive runs still require a one-time `ccc init` first.

```bash
ccc init                                # initialize project (creates settings)
```

```bash
ccc index                               # build the index
```

```bash
ccc search "authentication logic"       # search!
```

--------------------------------

### Usage example for PacedLiteLLMEmbedder

Source: https://github.com/cocoindex-io/cocoindex-code

Example of instantiating PacedLiteLLMEmbedder with a Voyage model, a 300 ms minimum interval, and a default input_type. It embeds two code snippets and prints the shape and dtype of the first vector.

```python
from cocoindex_code.litellm_embedder import PacedLiteLLMEmbedder

embedder = PacedLiteLLMEmbedder("voyage/voyage-code-3", min_interval_ms=300, input_type="document")
vecs = await embedder.embed(["def foo(): pass", "class Bar: ..."])
print(vecs[0].shape, vecs[0].dtype)  # (dim,) float32
```

--------------------------------

### Install Python via Homebrew (macOS fix for sqlite3 error)

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/README.md

For macOS systems where the pre-installed Python lacks SQLite extension support, install Python through Homebrew to resolve the 'sqlite3.Connection object has no attribute enable_load_extension' error.

```bash
brew install python3
```

--------------------------------

### ccc search example queries

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/skills/ccc/SKILL.md

Example queries for semantic search: database connection pooling, user authentication flow, and error handling retry logic.

```bash
ccc search database connection pooling
```

```bash
ccc search user authentication flow
```

```bash
ccc search error handling retry logic
```

--------------------------------

### Install ccc skill via Claude Code plugin marketplace

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/README.md

Adds the same ccc skill from inside Claude Code with version pinning and /plugin marketplace update support. The repository also ships hooks/hooks.json and .mcp.json for Grok and Claude Code plugin installs that load those files.

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

--------------------------------

### OpenAI Embedding Model Configuration

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/skills/ccc/references/settings.md

Example configuration for using OpenAI embedding models with an API key.

```yaml
embedding:
  model: text-embedding-3-small
  min_interval_ms: 300
envs:
  OPENAI_API_KEY: your-api-key
```

--------------------------------

### Configure LiteLLM with llama.cpp

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/EMBEDDINGS.md

Configure LiteLLM to connect to a local llama.cpp server via the OpenAI-compatible interface. Start the server with llama-server --embedding -m your_model.gguf and set OPENAI_API_BASE to the server's address.

```yaml
embedding:
  provider: litellm
  model: openai/your-model-name
envs:
  OPENAI_API_BASE: http://localhost:8080/v1
  OPENAI_API_KEY: "not-needed"
```

--------------------------------

### Project.create usage example

Source: https://github.com/cocoindex-io/cocoindex-code

Shows how to create a Project instance using load_user_settings and create_embedder. The embedder is built from settings.embedding and passed with empty indexing/query params.

```python
from pathlib import Path
from cocoindex_code.project import Project
from cocoindex_code.shared import create_embedder
from cocoindex_code.settings import load_user_settings

settings = load_user_settings()
embedder = create_embedder(settings.embedding)

project = await Project.create(
    Path("/repo"), embedder,
    indexing_params={}, query_params={},
)
```

--------------------------------

### Local Embedding Model Configuration

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/skills/ccc/references/settings.md

Example configuration for using local sentence-transformers models.

```yaml
embedding:
  provider: sentence-transformers
  model: Snowflake/snowflake-arctic-embed-xs        # default, lightweight
```

```yaml
embedding:
  provider: sentence-transformers
  model: nomic-ai/CodeRankEmbed                     # better code retrieval, needs GPU (~1 GB VRAM)
```

--------------------------------

### Oh My Pi: Manual project MCP configuration

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/README.md

Use this JSON in `.omp/mcp.json` to manually configure the cocoindex-code MCP server. Prefer the marketplace install instead.

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

--------------------------------

### client.search usage example

Source: https://github.com/cocoindex-io/cocoindex-code

Example of calling client.search with a query, language filter, and limit. Iterates over results printing file path, line range, language, and score.

```python
resp = client.search("/repo", "user session management", languages=["python"], limit=3)
for r in resp.results:
    print(f"{r.file_path}:{r.start_line}-{r.end_line} [{r.language}] score={r.score:.3f}")

```

--------------------------------

### Install ccc skill via npx

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/README.md

Adds the ccc skill to your coding agent so it automatically uses semantic search when needed. The agent handles initialization, indexing, and searching, so you don't need to run ccc init or ccc index yourself.

```bash
npx skills add cocoindex-io/cocoindex-code
```

--------------------------------

### ccc CLI commands

Source: https://github.com/cocoindex-io/cocoindex-code

Example commands for the ccc CLI covering initialization, indexing, searching, grepping, status, doctor, and daemon operations.

```bash
ccc init                            # interactive setup, then project settings
ccc index                           # index the whole tree (auto-init allowed)
ccc search "database connection pooling" --lang python --limit 5
ccc search --refresh --json "auth flow"
ccc grep 'def \NAME(\(ARGS*\)):' src/ --lang python
ccc status
ccc doctor -v
ccc daemon status
```

--------------------------------

### Example usage of build_matcher and iter_included_files

Source: https://github.com/cocoindex-io/cocoindex-code

Loads project settings, builds matcher, iterates included files. Also shows CocoIndex file source usage with localfs.walk_dir.

```python
from pathlib import Path
from cocoindex_code.file_walk import build_matcher, iter_included_files
from cocoindex_code.settings import load_project_settings

root = Path("/repo")
ps = load_project_settings(root)
matcher = build_matcher(root, ps.include_patterns, ps.exclude_patterns, ps.max_file_size)

for abs_path, rel in iter_included_files(root, root, matcher):
    print(abs_path)

# Indexer usage (CocoIndex file source):
from cocoindex.connectors import localfs
files = localfs.walk_dir(root, recursive=True, path_matcher=matcher)
```

--------------------------------

### client.index usage example

Source: https://github.com/cocoindex-io/cocoindex-code

Example of calling client.index with an on_progress callback that prints added and error counts. The response's success flag and message are checked to report indexing failure.

```python
from cocoindex_code import client

def show(progress):
    print(f"added={progress.num_adds} errors={progress.num_errors}")

resp = client.index("/path/to/repo", on_progress=show)
if not resp.success:
    print(f"indexing failed: {resp.message}")

```

--------------------------------

### Run daemon with optional idle timeout

Source: https://github.com/cocoindex-io/cocoindex-code

Starts the CocoIndex daemon. In production, call run_daemon() without arguments to read the timeout from global_settings.yml. For testing or in-process use, pass idle_timeout and idle_check_interval as timedelta values.

```python
from datetime import timedelta
from cocoindex_code.daemon import run_daemon

if __name__ == "__main__":
    # Production: read timeout from global_settings.yml
    run_daemon()
    # Test/in-process: seconds-scale idle timeout
    # run_daemon(idle_timeout=timedelta(seconds=5), idle_check_interval=timedelta(seconds=1))
```

--------------------------------

### Conceptual wiring example

Source: https://github.com/cocoindex-io/cocoindex-code

Illustrates how components are driven by CocoIndex: Project.create builds an App with indexer_main as root, and the environment provides context keys. Direct calls are not intended usage.

```python
import cocoindex as coco
from cocoindex_code.indexer import indexer_main, process_file
from cocoindex_code.shared import EMBEDDER, SQLITE_DB, CODEBASE_DIR

# Components are driven by CocoIndex: Project.create builds an App with
# `indexer_main` as the root function, and the environment provides the five
# context keys. Direct calls are not the intended usage:
#   await process_file(file, table, {".inc": "php"})
#   await indexer_main()
```

--------------------------------

### find_git_root

Source: https://github.com/cocoindex-io/cocoindex-code

Walks up from start to find the nearest directory containing a .git entry (directory for a normal repo, file for submodule/linked worktree). Returns None if start is not inside a git repo.

```APIDOC
## find_git_root

### Description
Walks up from `start` to the nearest directory holding a `.git` entry — a directory for a normal repo, or a *file* for a submodule / linked worktree. Returns `None` when `start` is not inside a git repo. Used by grep to anchor `.gitignore` resolution at the real repo root when grepping a subdirectory outside an initialized cocoindex project.

### Method
Function call

### Signature
```python
def find_git_root(start: Path) -> Path | None:
```

### Parameters
- **start** (Path) - Required - The starting directory to search from

### Returns
- **Path | None** - The nearest directory containing a .git entry, or None if not inside a git repo
```

--------------------------------

### Build and Test Commands (uv)

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/CLAUDE.md

Commands for installing dependencies, running tests, type checking, linting, formatting, and the full CI suite using uv and prek. Docker E2E tests are excluded by default and require `pytest -m docker_e2e`.

```bash
uv sync                                # Install all dev dependencies
uv run pytest tests/                   # Run all tests
uv run pytest tests/test_settings.py  # Run a single test file
uv run pytest tests/ -k test_name     # Run tests matching a name
uv run mypy .                          # Type check Python code
uv run ruff check .                    # Lint
uv run ruff format .                   # Format
uv run prek run --all-files            # Full CI suite (lint, format, mypy, pytest)
```

--------------------------------

### Restart the daemon with ccc daemon restart

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/skills/ccc/references/management.md

Restarts the daemon, useful if it gets into a bad state.

```bash
ccc daemon restart
```

--------------------------------

### Grep usage example

Source: https://github.com/cocoindex-io/cocoindex-code

Shows how to run a Grep search and render matches. Emits warnings and prints 'pattern invalid for every language found' if the pattern is unusable, or 'No matches found.' if no matches.

```python
from pathlib import Path
from threading import Lock
from cocoindex_code.grep import FileMatches, Grep, GrepRequest, GrepWarning, render_file

req = GrepRequest(
    pattern=r"def \NAME(\(ARGS*\)):",
    root=Path("src"),
    languages=frozenset({"python"}),
    path_glob=None,
)
grep_run = Grep(req)
lock = Lock()
matches = 0

def emit(item: FileMatches | GrepWarning) -> None:
    global matches
    if isinstance(item, GrepWarning):
        print(f"warning: {item.message}")
        return
    with lock:
        print(render_file(item, color=False))
        matches += 1

grep_run.run(emit)

if grep_run.unusable:
    print(f"pattern invalid for every language found: {grep_run.failed_languages}")
elif matches == 0:
    print("No matches found.")
```

--------------------------------

### find_git_root function signature

Source: https://github.com/cocoindex-io/cocoindex-code

Walks up from start to nearest directory with a .git entry (directory for repo, file for submodule/worktree). Returns None if not in a git repo.

```python
def find_git_root(start: Path) -> Path | None:
```

--------------------------------

### Remove old container and volumes before upgrading

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/README.md

Run before pulling the new image. Drops the old container and the separate `cocoindex-db` and `cocoindex-model-cache` volumes, which are consolidated into a single `cocoindex-data` volume in the current image. Indexes rebuild on the next `ccc index`; the embedding model is re-populated automatically on first start.

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

--------------------------------

### Set COCOINDEX_LMDB_MAP_SIZE in global settings

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/README.md

Raise the LMDB map size ceiling to 32 GiB by setting the COCOINDEX_LMDB_MAP_SIZE environment variable in the global settings file. The value is in bytes and is read when the daemon starts.

```yaml
# ~/.cocoindex_code/global_settings.yml
envs:
  COCOINDEX_LMDB_MAP_SIZE: "34359738368"   # 32 GiB (= 32 * 1024^3)
```

--------------------------------

### Example: query_codebase usage

Source: https://github.com/cocoindex-io/cocoindex-code

Shows how to call query_codebase inside a Project's environment. Embeds the query, searches with language filter, and prints results with file path, line range, language, and score.

```python
import cocoindex as coco
from cocoindex_code.query import query_codebase
from cocoindex_code.settings import target_sqlite_db_path
from pathlib import Path

# Inside a Project's environment (project.env):
project_root = Path("/repo")
results = await query_codebase(
    query="how are users authenticated",
    target_sqlite_db_path=target_sqlite_db_path(project_root),
    env=project.env,
    limit=5,
    languages=["python"],
)
for r in results:
    print(f"{r.file_path}:{r.start_line}-{r.end_line} [{r.language}] score={r.score:.3f}")
```

--------------------------------

### Pass configuration via environment variables to docker run/compose

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/README.md

Use `-e` with `docker run` or compose to set configuration. Examples: `COCOINDEX_CODE_EXTRA_EXTENSIONS` adds extra extensions (e.g., `conf,sbt`), `COCOINDEX_CODE_EXCLUDE_PATTERNS` excludes build artefacts (JSON array), and `VOYAGE_API_KEY` sets an API key. Security note: mounting `$HOME` gives the container read/write access to everything under it; bind-mount a narrower directory instead (`COCOINDEX_HOST_WORKSPACE=/path/to/code`).

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

--------------------------------

### index(project_root, on_progress, on_waiting)

Source: https://github.com/cocoindex-io/cocoindex-code

Starts indexing for a project root and blocks until the daemon streams a final IndexResponse. Progress updates and waiting notices are forwarded to the provided callbacks.

```APIDOC
## index(project_root, on_progress, on_waiting)

### Description
Starts indexing for `project_root` and blocks until the daemon streams a final `IndexResponse`. `project_root` is first normalized through `normalize_input_path()` (host→container path mapping). The daemon streams zero or more `IndexProgressUpdate` frames (each carries an `IndexingProgress` snapshot) and possibly an `IndexWaitingNotice` (another index run holds the project lock); these are forwarded to `on_progress` / `on_waiting`.

### Method
Function call

### Endpoint
`client.index(project_root, on_progress=None, on_waiting=None)`

### Parameters
#### Path Parameters
- **project_root** (str) - Required - Project root directory (container-form path accepted; reverse host mapping applied)

#### Query Parameters
- **on_progress** (`Callable[[IndexingProgress], None] | None`) - Optional - Called for each streaming `IndexingProgress` snapshot
- **on_waiting** (`Callable[[], None] | None`) - Optional - Called when the daemon reports another indexing is in progress

### Response
#### Success Response
- **success** (bool) - Whether indexing succeeded
- **message** (str | None) - Error message when the run failed

#### Error Response
- **RuntimeError** - If the connection is lost during indexing, or when the daemon replies with an `ErrorResponse`.

### Request Example
```python
from cocoindex_code import client

def show(progress):
    print(f"added={progress.num_adds} errors={progress.num_errors}")

resp = client.index("/path/to/repo", on_progress=show)
if not resp.success:
    print(f"indexing failed: {resp.message}")
```
```

--------------------------------

### Search response JSON

Source: https://github.com/cocoindex-io/cocoindex-code

Example response from the MCP `search` tool, showing a successful result with one code chunk. Fields include success, results, total_returned, offset, and message.

```json
{
  "success": true,
  "results": [
    {
      "file_path": "src/db/pool.py",
      "language": "python",
      "content": "class ConnectionPool:\n    ...",
      "start_line": 12,
      "end_line": 30,
      "score": 0.842
    }
  ],
  "total_returned": 1,
  "offset": 0,
  "message": null
}
```

--------------------------------

### Search request JSON

Source: https://github.com/cocoindex-io/cocoindex-code

Example request payload for the MCP `search` tool, equivalent to `client.index` semantics. Includes query, limit, offset, refresh_index, languages, and paths filters.

```json
{
  "query": "database connection pooling",
  "limit": 5,
  "offset": 0,
  "refresh_index": true,
  "languages": ["python"],
  "paths": ["src/*"]
}
```

--------------------------------

### ensure_indexing_started signature

Source: https://github.com/cocoindex-io/cocoindex-code

Starts background indexing and returns once the task holds the project lock. Safe to call repeatedly; only the first call spawns a task. Used by SearchRequest to trigger the first index pass.

```python
async def ensure_indexing_started(self) -> None:
```

--------------------------------

### Initialize a project with ccc init

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/skills/ccc/references/management.md

Run from the project root. On first run, prompts for embedding provider and model, then tests the model. Subsequent runs skip prompts. Creates global and project settings files.

```bash
ccc init
```

--------------------------------

### ccc grep structural search examples

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/README.md

Find code by structure using metavariables with the `\` sigil: `\NAME` captures one node, `\(NAME*\)` a run of siblings, `\_`/`\*` match anonymously. Runs locally without index or daemon. Honors project include/exclude patterns and `.gitignore` inside an initialized project. Relies on cocoindex's `code_match` feature; until it ships, run against a local cocoindex build.

```bash
ccc grep 'def \NAME(\(ARGS*\)):'                      # every Python function def under the cwd
```

```bash
ccc grep 'foo(\(ARGS*\))' src/                        # calls to foo(...) anywhere under src/
```

```bash
ccc grep 'fn \NAME(\(A*\))' --lang rust               # restrict to one language
```

```bash
ccc grep 'class \NAME:' --path 'tests/**'            # restrict to a path glob
```

```bash
ccc grep 'TODO(\(A*\))' path/to/file.py               # a single file
```

--------------------------------

### OpenCode: Add MCP server interactively

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/README.md

Run `opencode mcp add` and enter the server name, type, and command as prompted. Alternatively, use the provided opencode.json configuration.

```bash
opencode mcp add
```

--------------------------------

### is_sentence_transformers_installed function signature

Source: https://github.com/cocoindex-io/cocoindex-code

Checks if sentence-transformers is installed using `importlib.util.find_spec` (not `import`) to avoid the slow torch-loading import as a side effect. Drives `ccc init`'s provider options and non-TTY fallbacks.

```python
def is_sentence_transformers_installed() -> bool:
```

--------------------------------

### Docker run for Docker Desktop (macOS/Windows)

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/README.md

Runs the container with Docker Desktop, mounting the home directory and a named volume for index data.

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

--------------------------------

### iter_included_files function signature

Source: https://github.com/cocoindex-io/cocoindex-code

Walks start recursively, yielding (absolute_path, path_relative_to_base) for included files, pruning excluded directories. Both start and base must be absolute.

```python
def iter_included_files(
    start: Path,
    base: Path,
    matcher: FilePathMatcher,
) -> Iterator[tuple[Path, PurePath]]:
```

--------------------------------

### Project.create

Source: https://github.com/cocoindex-io/cocoindex-code

Function-level option to create a project with specified settings.

```APIDOC
## Project.create

### Description
Function-level option to create a project with specified settings.

### Signature
`Project.create(project_root, embedder, indexing_params, query_params, chunker_registry=None, clear_mps_cache_after_index=False)`

### Parameters
- **project_root** (string) - Required - Root path of the project.
- **embedder** (EmbeddingSettings) - Required - Embedding settings.
- **indexing_params** (dict) - Required - Indexing parameters.
- **query_params** (dict) - Required - Query parameters.
- **chunker_registry** (object) - Optional - Chunker registry, defaults to None.
- **clear_mps_cache_after_index** (bool) - Optional - Whether to clear MPS cache after indexing, defaults to False.
```

--------------------------------

### Run model discovery script

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/EMBEDDINGS.md

Run the included discovery script to find the current best embedding models for your hardware.

```bash
uv run scripts/find_best_models.py
```

--------------------------------

### Example custom chunker implementation

Source: https://github.com/cocoindex-io/cocoindex-code

Example chunker function that returns a language override and a single chunk covering the entire content. Note that the path is not resolved; call path.resolve() inside the chunker if needed.

```python
from pathlib import Path
from cocoindex_code.chunking import Chunk, ChunkerFn, TextPosition

def my_chunker(path: Path, content: str) -> tuple[str | None, list[Chunk]]:
    pos = TextPosition(byte_offset=0, char_offset=0, line=1, column=0)
    return "mylang", [Chunk(text=content, start=pos, end=pos)]
```

--------------------------------

### Using create_mcp_server

Source: https://github.com/cocoindex-io/cocoindex-code

Shows how to instantiate the MCP server with a project root and hand it to an MCP client over stdio. The commented line indicates the intended usage.

```python
from cocoindex_code.server import create_mcp_server

mcp = create_mcp_server("/path/to/repo")
# mcp.run_stdio_async() — hand to an MCP client over stdio
```

--------------------------------

### Reset project index with ccc reset

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/skills/ccc/references/management.md

Removes databases but keeps settings. Prompts for confirmation; use -f to skip.

```bash
ccc reset
```

--------------------------------

### Run all pre-commit checks with prek

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/README.md

Runs the full hook suite across all files, exactly what CI runs. Includes trailing-whitespace/end-of-file fixes, Ruff lint and format, uv.lock validation, mypy type checking, and pytest. Fix any reported issues and re-run until it passes.

```bash
uv run prek run --all-files
```

--------------------------------

### _get_dim

Source: https://github.com/cocoindex-io/cocoindex-code

Probes the embedding dimension with a single request and caches the result. Used during indexing setup.

```APIDOC
## _get_dim

### Description
Probes the embedding dimension with a single request and caches the result. Used during indexing setup.

### Method
async

### Parameters
None

### Response
- **int** - The embedding dimension.
```

--------------------------------

### ProjectRegistry class definition and constructor

Source: https://github.com/cocoindex-io/cocoindex-code

Defines the ProjectRegistry class with its fields and constructor. The constructor accepts an optional embedder, indexing and query parameters, and a flag to clear MPS cache after indexing. In no-settings mode, _embedder is None and project operations raise a RuntimeError.

```python
class ProjectRegistry:
    _projects: dict[str, Project]
    _embedder: Embedder | None
    _clear_mps_cache_after_index: bool
    indexing_params: dict[str, Any]
    query_params: dict[str, Any]

    def __init__(
        self,
        embedder: Embedder | None,
        indexing_params: dict[str, Any] | None = None,
        query_params: dict[str, Any] | None = None,
        clear_mps_cache_after_index: bool = False,
    ) -> None:
```

--------------------------------

### IndexRequest struct

Source: https://github.com/cocoindex-io/cocoindex-code

Request to start indexing a project; carries the project root path.

```python
class IndexRequest(_msgspec.Struct, tag="index"):
    project_root: str
```

--------------------------------

### Docker run for Linux with PUID/PGID

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/README.md

Runs the container on Linux, setting PUID and PGID to match the host user for file ownership.

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

--------------------------------

### ProjectRegistry

Source: https://github.com/cocoindex-io/cocoindex-code

Function-level option to create a project registry with specified settings.

```APIDOC
## ProjectRegistry

### Description
Function-level option to create a project registry with specified settings.

### Signature
`ProjectRegistry(embedder, indexing_params=None, query_params=None, clear_mps_cache_after_index=False)`

### Parameters
- **embedder** (EmbeddingSettings) - Required - Embedding settings.
- **indexing_params** (dict) - Optional - Indexing parameters, defaults to None.
- **query_params** (dict) - Optional - Query parameters, defaults to None.
- **clear_mps_cache_after_index** (bool) - Optional - Whether to clear MPS cache after indexing, defaults to False.
```

--------------------------------

### Example: encode and decode protocol messages

Source: https://github.com/cocoindex-io/cocoindex-code

Shows how to encode a SearchRequest and decode it on the receiving side, then send an encoded response. Uses functions from cocoindex_code.protocol.

```python
from cocoindex_code.protocol import (
    encode_request, decode_response,
    HandshakeRequest, SearchRequest, SearchResponse, ErrorResponse,
)

wire = encode_request(SearchRequest(project_root="/repo", query="auth", limit=5))

# on the receiving side:
req = decode_request(wire)
if isinstance(req, SearchRequest):
    resp = SearchResponse(success=True, results=[], total_returned=0, offset=req.offset)
    send(encode_response(resp))
```

--------------------------------

### ProjectSettings

Source: https://github.com/cocoindex-io/cocoindex-code

Dataclass for project settings, consumed by load_project_settings, build_matcher, and indexer_main.

```APIDOC
## ProjectSettings

### Description
Dataclass for project settings, consumed by load_project_settings, build_matcher, and indexer_main.

### Constructor
`ProjectSettings(include_patterns=…defaults…, exclude_patterns=…defaults…, language_overrides=[], chunkers=[], max_file_size=None)`

### Parameters
- **include_patterns** (list) - Optional - Include patterns, defaults to predefined defaults.
- **exclude_patterns** (list) - Optional - Exclude patterns, defaults to predefined defaults.
- **language_overrides** (list) - Optional - Language overrides, defaults to empty list.
- **chunkers** (list) - Optional - Chunkers, defaults to empty list.
- **max_file_size** (int) - Optional - Maximum file size, defaults to None.
```

--------------------------------

### User Settings YAML (global_settings.yml)

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/README.md

Configuration for the embedding model and daemon environment, shared across all projects. Created automatically by `ccc init`. The `envs` field is only needed for values not already in your shell environment; the daemon inherits your shell environment. Optional fields include `device`, `min_interval_ms`, MPS watermarks, and daemon idle timeout settings.

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

--------------------------------

### ccc search filter by language

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/skills/ccc/SKILL.md

Restricts search results to specific languages using the repeatable --lang flag. This example filters to Python and Markdown files.

```bash
ccc search --lang python --lang markdown database schema
```

--------------------------------

### ccc init command definition

Source: https://github.com/cocoindex-io/cocoindex-code

Defines the `ccc init` command with options `--litellm-model` and `-f/--force`. Initializes the current directory as a project, skipping provider/model prompts when `--litellm-model` is given. Exits 1 if global settings exist with `--litellm-model`, if a parent marker exists without `--force`, or if the user cancels a prompt.

```python
@app.command()
def init(
    litellm_model: str | None = _typer.Option(None, "--litellm-model", help="Use the given LiteLLM model and skip provider/model prompts."),
    force: bool = _typer.Option(False, "-f", "--force", help="Skip parent directory warning"),
) -> None:
```

--------------------------------

### Configure indexing_params and query_params for asymmetric embedding models

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/README.md

Use this YAML to set per-side embedding parameters for asymmetric retrieval models, e.g., Cohere v3's input_type. `ccc init` auto-populates these for recognized models and prints defaults; for others it leaves a commented template. Accepted keys are `prompt_name` (sentence-transformers) and `input_type` (litellm); other keys are rejected at daemon startup. `dimensions` is intentionally not exposed here.

```yaml
embedding:
  provider: litellm
  model: cohere/embed-english-v3.0
  indexing_params:
    input_type: search_document
  query_params:
    input_type: search_query
```

--------------------------------

### Disable Grok plugin MCP server in config.toml

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/README.md

Persists disabling the cocoindex-code MCP server in ~/.grok/config.toml. Use this for skill-only Grok setup to match Claude Code behavior (no auto-index hook, no MCP tool).

```toml
[mcp_servers.cocoindex-code]
enabled = false
```

--------------------------------

### OpenAI embedding configuration

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/README.md

Configure OpenAI embedding model. Optional min_interval_ms overrides the 5ms LiteLLM default. Requires OPENAI_API_KEY.

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

```

--------------------------------

### Example usage of check_embedding

Source: https://github.com/cocoindex-io/cocoindex-code

Shows how to load user settings, create an embedder, and call `check_embedding` with query params. Prints the embedding dimension on success or the error message on failure.

```python
from cocoindex_code.shared import check_embedding, create_embedder
from cocoindex_code.settings import load_user_settings

settings = load_user_settings()
embedder = create_embedder(settings.embedding)

result = await check_embedding(embedder, {"prompt_name": "query"})
if result.error is None:
    print(f"embedding dim: {result.dim}")
else:
    print(f"failed: {result.error}")
```

--------------------------------

### Custom chunker function signature

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/README.md

Signature for a custom chunker function. Takes a file path and content, returns an optional language override and a list of Chunk objects. See src/cocoindex_code/chunking.py for public types and tests/example_toml_chunker.py for a complete example.

```python
from pathlib import Path
from cocoindex_code.chunking import Chunk

def my_chunker(path: Path, content: str) -> tuple[str | None, list[Chunk]]:
    ...

```

--------------------------------

### run_daemon

Source: https://github.com/cocoindex-io/cocoindex-code

Function to run the daemon with optional idle timeout settings.

```APIDOC
## run_daemon

### Description
Function to run the daemon with optional idle timeout settings.

### Signature
`run_daemon(idle_timeout=None, idle_check_interval=timedelta(minutes=1))`

### Parameters
- **idle_timeout** (int) - Optional - Idle timeout in minutes, defaults to None.
- **idle_check_interval** (timedelta) - Optional - Interval between idle checks, defaults to timedelta(minutes=1).
```

--------------------------------

### Project.create (static async factory)

Source: https://github.com/cocoindex-io/cocoindex-code

Creates a Project instance for a given project root, embedding model, and indexing/query parameters. It sets up the CocoIndex environment, context keys, and database paths.

```APIDOC
## Project.create (static async factory)

### Description
Creates a Project instance for a given project root, embedding model, and indexing/query parameters. It sets up the CocoIndex environment, context keys, and database paths.

### Method
Async static factory

### Signature
```python
@staticmethod
async def create(
    project_root: Path,
    embedder: Embedder,
    indexing_params: dict[str, Any],
    query_params: dict[str, Any],
    chunker_registry: Mapping[str, LoadedChunker] | None = None,
    clear_mps_cache_after_index: bool = False,
) -> Project:
```

### Parameters
- **project_root** (`Path`) - Required - Root directory of the codebase to index
- **embedder** (`Embedder`) - Required - Embedding model instance (`shared.Embedder` = `SentenceTransformerEmbedder | LiteLLMEmbedder`)
- **indexing_params** (`dict[str, Any]`) - Required - Extra kwargs spread into `embedder.embed()` during indexing (e.g. `{"prompt_name": "passage"}`); pass `{}` for none
- **query_params** (`dict[str, Any]`) - Required - Extra kwargs for the query side
- **chunker_registry** (`Mapping[str, LoadedChunker] | None`) - Optional - File suffix → chunker; matching suffixes bypass the built-in splitter
- **clear_mps_cache_after_index** (`bool`) - Optional - Release unused MPS allocator memory in CocoIndex's GPU subprocess after each index run

### Returns
- `Project` - The created Project instance

### Request Example
```python
from pathlib import Path
from cocoindex_code.project import Project
from cocoindex_code.shared import create_embedder
from cocoindex_code.settings import load_user_settings

settings = load_user_settings()
embedder = create_embedder(settings.embedding)

project = await Project.create(
    Path("/repo"), embedder,
    indexing_params={}, query_params={},
)
```
```

--------------------------------

### Register MCP with Claude Code via .mcp.json

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/README.md

Alternative configuration using a .mcp.json file to define the MCP server for Claude Code.

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

--------------------------------

### Run MCP stdio server programmatically with heartbeat loop

Source: https://github.com/cocoindex-io/cocoindex-code

Starts an MCP server over stdio using create_mcp_server and run_heartbeat_loop, then cancels the heartbeat task when the server exits. Use as a programmatic alternative to the CLI server.

```python
import asyncio
from cocoindex_code.server import create_mcp_server, run_heartbeat_loop

async def serve(root: str) -> None:
    mcp_server = create_mcp_server(root)
    bg = {asyncio.create_task(run_heartbeat_loop())}
    try:
        await mcp_server.run_stdio_async()
    finally:
        for t in bg:
            t.cancel()

asyncio.run(serve("/path/to/repo"))
```

--------------------------------

### run_heartbeat_loop function

Source: https://github.com/cocoindex-io/cocoindex-code

Periodically sends client.send_heartbeat() to prevent the daemon from idle-exiting during a live MCP session. Returns immediately if daemon.keep_alive_with_mcp is disabled or idle_timeout_minutes <= 0. Never starts or restarts a daemon. Reads settings from global_settings.yml.

```python
async def run_heartbeat_loop() -> None:
```

--------------------------------

### Configure LiteLLM with Voyage AI

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/EMBEDDINGS.md

Configure LiteLLM to use Voyage AI's voyage-4-large model for embeddings. Requires setting the VOYAGE_API_KEY environment variable.

```yaml
embedding:
  provider: litellm
  model: voyage/voyage-4-large
envs:
  VOYAGE_API_KEY: your-api-key-here
```

--------------------------------

### Check project index status with ccc status

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/skills/ccc/references/management.md

Shows whether indexing is ongoing and index statistics.

```bash
ccc status
```
Tokens:
Raw