Skip to content
Back to search

cocoindex-code

MarketplaceWorks with Claude CodeGitHub

AST-based semantic code search for Claude Code, Grok, Cursor, and any skill-compatible coding agent — install in one command.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/cocoindex-io/cocoindex-code with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/cocoindex-io/cocoindex-code'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/cocoindex-io-cocoindex-code/badge.svg)](/listings/cocoindex-io-cocoindex-code)

HTML

<a href="/listings/cocoindex-io-cocoindex-code"><img src="/api/listings/cocoindex-io-cocoindex-code/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Using [pipx](https://pipx.pypa.io/stable/installation/):

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

Using [uv](https://docs.astral.sh/uv/getting-started/installation/):

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 28 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "cocoindex-code",
  3. "version": "1.0.0",
  4. "description": "AST-based semantic code search for Claude Code, Grok, Cursor, and any skill-compatible coding agent — install in one command.",
  5. "owner": {
  6. "name": "CocoIndex",
  7. "email": "hi@cocoindex.io"
  8. },
  9. "plugins": [
  10. {
  11. "name": "cocoindex-code",
  12. "source": "./",
  13. "description": "Semantic code search — ccc skill, optional SessionStart index hook, and MCP server (Grok: disable hook/MCP for skill-only).",
  14. "category": "development",
  15. "tags": [
  16. "semantic-search",
  17. "code-search",
  18. "ast",
  19. "indexing",
  20. "rag",
  21. "skill"
  22. ],
  23. "homepage": "https://github.com/cocoindex-io/cocoindex-code",
  24. "repository": "https://github.com/cocoindex-io/cocoindex-code",
  25. "license": "Apache-2.0"
  26. }
  27. ]
  28. }
README.md · README · 1,022 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img width="2428" alt="cocoindex code" src="https://github.com/user-attachments/assets/d05961b4-0b7b-42ea-834a-59c3c01717ca" />
  3. </p>
  4. <h1 align="center">AST-based semantic code search</h1>
  5. ![effect](https://github.com/user-attachments/assets/cb3a4cae-0e1f-49c4-890b-7bb93317ab60)
  6. CocoIndex Code provides AST-based semantic search for your codebase, built on the [CocoIndex](https://github.com/cocoindex-io/cocoindex) Rust data transformation engine. Use it from the CLI or connect Claude, Codex, Cursor, and other coding agents through a [Skill](#skill-recommended) or [MCP](#mcp-server).
  7. - 70% token savings.
  8. - 1 min setup with default settings.
  9. <div align="center">
  10. [![Discord](https://img.shields.io/discord/1314801574169673738?logo=discord&color=5B5BD6&logoColor=white)](https://discord.com/invite/zpA9S2DR7s)
  11. [![GitHub](https://img.shields.io/github/stars/cocoindex-io/cocoindex?color=5B5BD6)](https://github.com/cocoindex-io/cocoindex)
  12. [![Documentation](https://img.shields.io/badge/Documentation-394e79?logo=readthedocs&logoColor=00B9FF)](https://cocoindex.io/docs/getting_started/quickstart)
  13. [![License](https://img.shields.io/badge/license-Apache%202.0-5B5BD6?logoColor=white)](https://opensource.org/licenses/Apache-2.0)
  14. <!--[![PyPI - Downloads](https://img.shields.io/pypi/dm/cocoindex)](https://pypistats.org/packages/cocoindex) -->
  15. [![PyPI Downloads](https://static.pepy.tech/badge/cocoindex/month)](https://pepy.tech/projects/cocoindex)
  16. [![CI](https://github.com/cocoindex-io/cocoindex/actions/workflows/CI.yml/badge.svg?event=push&color=5B5BD6)](https://github.com/cocoindex-io/cocoindex/actions/workflows/CI.yml)
  17. [![release](https://github.com/cocoindex-io/cocoindex/actions/workflows/release.yml/badge.svg?event=push&color=5B5BD6)](https://github.com/cocoindex-io/cocoindex/actions/workflows/release.yml)
  18. Star [CocoIndex](https://github.com/cocoindex-io/cocoindex) if you find it useful.
  19. [Deutsch](https://readme-i18n.com/cocoindex-io/cocoindex-code?lang=de) |
  20. [English](https://readme-i18n.com/cocoindex-io/cocoindex-code?lang=en) |
  21. [Español](https://readme-i18n.com/cocoindex-io/cocoindex-code?lang=es) |
  22. [français](https://readme-i18n.com/cocoindex-io/cocoindex-code?lang=fr) |
  23. [日本語](https://readme-i18n.com/cocoindex-io/cocoindex-code?lang=ja) |
  24. [한국어](https://readme-i18n.com/cocoindex-io/cocoindex-code?lang=ko) |
  25. [Português](https://readme-i18n.com/cocoindex-io/cocoindex-code?lang=pt) |
  26. [Русский](https://readme-i18n.com/cocoindex-io/cocoindex-code?lang=ru) |
  27. [中文](https://readme-i18n.com/cocoindex-io/cocoindex-code?lang=zh)
  28. </div>
  29. <a id="get-started--zero-config-lets-go"></a>
  30. ## Get Started
  31. ### Install
  32. Using [pipx](https://pipx.pypa.io/stable/installation/):
  33. ```bash
  34. pipx install 'cocoindex-code[full]' # batteries included (local embeddings)
  35. pipx upgrade cocoindex-code # upgrade
  36. ```
  37. Using [uv](https://docs.astral.sh/uv/getting-started/installation/):
  38. ```bash
  39. uv tool install --upgrade 'cocoindex-code[full]'
  40. ```
  41. Two install styles — they mirror the Docker image variants of the same names:
  42. - `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).
  43. - `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).
  44. Next, set up your [coding agent integration](#coding-agent-integration) — or jump to [Manual CLI Usage](#manual-cli-usage) if you prefer direct control.
  45. ## Coding Agent Integration
  46. 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.
  47. ### Skill (Recommended)
  48. Install the `ccc` skill so your coding agent automatically uses semantic search when needed:
  49. ```bash
  50. npx skills add cocoindex-io/cocoindex-code
  51. ```
  52. The skill teaches the agent to handle initialization, indexing, and searching, so you don't need to run `ccc init` or `ccc index` yourself. The agent keeps the index up to date as you work.
  53. 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.
  54. Works with [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and other skill-compatible agents.
  55. #### Claude Code plugin marketplace
  56. 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:
  57. ```text
  58. /plugin marketplace add cocoindex-io/cocoindex-code
  59. /plugin install cocoindex-code@cocoindex-code
  60. ```
  61. 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`.
  62. #### Grok plugin
  63. For [Grok](https://github.com/xai-org/grok) users, install via Grok's plugin system. The plugin bundles three components:
  64. | Component | Purpose |
  65. |-----------|---------|
  66. | **Skill** (`skills/ccc/`) | Agent runs `ccc search` / `ccc index` via the CLI (same as Claude Code above) |
  67. | **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) |
  68. | **MCP** (`.mcp.json`) | `ccc mcp` stdio server — `search` tool with `refresh_index=true` by default |
  69. Grok does **not** import Claude's `enabledPlugins` or plugin cache; install separately even if you already use cocoindex in Claude Code.
  70. **Full install** (skill + hook + MCP):
  71. ```bash
  72. grok plugin marketplace add cocoindex-io/cocoindex-code
  73. grok plugin install cocoindex-io/cocoindex-code --trust
  74. grok plugin enable cocoindex-code
  75. ```
  76. 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.
  77. `--trust` is required so Grok activates the plugin's hooks and MCP server (skills load when the plugin is enabled).
  78. **Skill-only** (match Claude Code — no auto-index hook, no MCP tool):
  79. Install and enable as above, then disable the optional components:
  80. 1. **Hooks** — open `/hooks`, select the `SessionStart` / `PostToolUse` hooks from `cocoindex-code`, press `Space` to disable.
  81. 2. **MCP** — open `/mcps`, select `cocoindex-code`, press `Space` to disable; or persist in `~/.grok/config.toml`:
  82. ```toml
  83. [mcp_servers.cocoindex-code]
  84. enabled = false
  85. ```
  86. The agent still owns indexing via the `ccc` skill (`ccc index` / `ccc search --refresh` when stale), same as Claude Code.
  87. To avoid importing MCP servers from your Claude/Cursor user config (unrelated to this plugin):
  88. ```toml
  89. [compat.claude]
  90. mcps = false
  91. [compat.cursor]
  92. mcps = false
  93. ```
  94. #### Oh My Pi plugin
  95. [Oh My Pi](https://github.com/can1357/oh-my-pi) reads `.omp-plugin/marketplace.json` (preferred) and falls back to `.claude-plugin/marketplace.json`.
  96. ```bash
  97. omp plugin marketplace add cocoindex-io/cocoindex-code
  98. omp plugin install cocoindex-code@cocoindex-code --scope project
  99. ```
  100. Then restart the session (`/reload-plugins` does not reload extensions). Requires `ccc` on `PATH` (`uv tool install --upgrade 'cocoindex-code[full]'`).
  101. | Component | Purpose |
  102. |-----------|---------|
  103. | **Skill** (`skills/ccc/`) | Agent runs `ccc search` / `ccc index` via the CLI |
  104. | **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) |
  105. | **MCP** (`.mcp.json`) | `ccc mcp` stdio server |
  106. OMP does **not** execute Claude `hooks/hooks.json` command hooks. The TypeScript extension is the OMP equivalent of the Claude/Grok SessionStart + PostToolUse pair.
  107. 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.
  108. ### MCP Server
  109. <!-- Ownership marker for the official MCP registry. It must match "name" in server.json. Keep the next line. -->
  110. <!-- mcp-name: io.github.cocoindex-io/cocoindex-code -->
  111. Alternatively, use `ccc mcp` to run as an MCP server:
  112. <details>
  113. <summary>Claude Code</summary>
  114. ```bash
  115. claude mcp add cocoindex-code -- ccc mcp
  116. ```
  117. </details>
  118. <details>
  119. <summary>Codex</summary>
  120. ```bash
  121. codex mcp add cocoindex-code -- ccc mcp
  122. ```
  123. </details>
  124. <details>
  125. <summary>OpenCode</summary>
  126. ```bash
  127. opencode mcp add
  128. ```
  129. Enter MCP server name: `cocoindex-code`
  130. Select MCP server type: `local`
  131. Enter command to run: `ccc mcp`
  132. Or use opencode.json:
  133. ```json
  134. {
  135. "$schema": "https://opencode.ai/config.json",
  136. "mcp": {
  137. "cocoindex-code": {
  138. "type": "local",
  139. "command": [
  140. "ccc", "mcp"
  141. ]
  142. }
  143. }
  144. }
  145. ```
  146. </details>
  147. <details>
  148. <summary>Kilo Code</summary>
  149. Add a local MCP server in `~/.config/kilo/kilo.jsonc`, `kilo.jsonc`, or `.kilo/kilo.jsonc`:
  150. ```json
  151. {
  152. "mcp": {
  153. "cocoindex-code": {
  154. "type": "local",
  155. "command": ["ccc", "mcp"],
  156. "enabled": true
  157. }
  158. }
  159. }
  160. ```
  161. </details>
  162. <details>
  163. <summary>Oh My Pi</summary>
  164. Prefer the marketplace install above. Manual project MCP (`.omp/mcp.json`):
  165. ```json
  166. {
  167. "mcpServers": {
  168. "cocoindex-code": {
  169. "command": "ccc",
  170. "args": ["mcp"]
  171. }
  172. }
  173. }
  174. ```
  175. </details>
  176. Once configured, the agent can use semantic search to find code by description, explore unfamiliar codebases, and locate implementations without exact names.
  177. > **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.
  178. <details>
  179. <summary>MCP Tool Reference</summary>
  180. When running as an MCP server (`ccc mcp`), the following tool is exposed:
  181. **`search`** — Search the codebase using semantic similarity.
  182. ```
  183. search(
  184. query: str, # Natural language query or code snippet
  185. limit: int = 5, # Maximum results (1-100)
  186. offset: int = 0, # Pagination offset
  187. refresh_index: bool = True, # Refresh index before querying
  188. languages: list[str] | None = None, # Filter by language (e.g. ["python", "typescript"])
  189. paths: list[str] | None = None, # Filter by path glob (e.g. ["src/utils/*"])
  190. )
  191. ```
  192. Returns matching code chunks with file path, language, code content, line numbers, and similarity score.
  193. </details>
  194. ## Manual CLI Usage
  195. You can also use the CLI directly — useful for manual control, running indexing after changing settings, checking status, or searching outside an agent.
  196. ```bash
  197. ccc init # initialize project (creates settings)
  198. ccc index # build the index
  199. ccc search "authentication logic" # search!
  200. ```
  201. The background daemon starts automatically on first use.
  202. > **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.
  203. > **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.
  204. ### CLI Reference
  205. | Command | Description |
  206. |---------|-------------|
  207. | `ccc init` | Initialize a project — creates settings files, adds `.cocoindex_code/` to `.gitignore` |
  208. | `ccc index` | Build or update the index (auto-inits if needed). Shows streaming progress. |
  209. | `ccc search <query>` | Semantic search across the codebase |
  210. | `ccc grep <pattern> [path]` | Structural code search by example (no index needed) |
  211. | `ccc status` | Show index stats (chunk count, file count, language breakdown) |
  212. | `ccc mcp` | Run as MCP server in stdio mode |
  213. | `ccc doctor` | Run diagnostics — checks settings, daemon, model, file matching, and index health |
  214. | `ccc reset` | Delete index databases. `--all` also removes settings. `-f` skips confirmation. |
  215. | `ccc version` | Print the CLI version |
  216. | `ccc daemon status` | Show daemon version, uptime, and loaded projects |
  217. | `ccc daemon restart` | Restart the background daemon |
  218. | `ccc daemon stop` | Stop the daemon |
  219. ### Search Options
  220. ```bash
  221. ccc search database schema # basic search
  222. ccc search --lang python --lang markdown schema # filter by language
  223. ccc search --path 'src/utils/*' query handler # filter by path
  224. ccc search --offset 10 --limit 5 database schema # pagination
  225. ccc search --refresh database schema # update index first, then search
  226. ```
  227. By default, `ccc search` scopes results to your current working directory (relative to the project root). Use `--path` to override.
  228. ### Structural Search (`ccc grep`)
  229. `ccc grep` finds code by **structure**, not text — you write a by-example pattern
  230. and it matches the syntax tree (via cocoindex's `code_match`), so formatting,
  231. whitespace, and intervening tokens don't matter. It runs entirely locally: no
  232. index, daemon, or embeddings required.
  233. ```bash
  234. ccc grep 'def \NAME(\(ARGS*\)):' # every Python function def under the cwd
  235. ccc grep 'foo(\(ARGS*\))' src/ # calls to foo(...) anywhere under src/
  236. ccc grep 'fn \NAME(\(A*\))' --lang rust # restrict to one language
  237. ccc grep 'class \NAME:' --path 'tests/**' # restrict to a path glob
  238. ccc grep 'TODO(\(A*\))' path/to/file.py # a single file
  239. ```
  240. Metavariables use the `\` sigil: `\NAME` captures one node, `\(NAME*\)` a run of
  241. siblings, `\_`/`\*` match anonymously. The pattern is matched per language, so a
  242. single invocation scans every supported source file (others are skipped). Inside
  243. an initialized project, `ccc grep` honors the project's include/exclude patterns
  244. and `.gitignore`; otherwise it scans all supported source files under the path.
  245. Results stream to the terminal file-by-file as each match is found (in completion
  246. order, since files are matched in parallel) rather than all at once at the end.
  247. Each matching file shows its matched line range; under a TTY the path is colored,
  248. line numbers are dimmed, and the unmatched context around a match is dimmed so the
  249. match stands out.
  250. > **Note:** `ccc grep` relies on cocoindex's structural `code_match` feature.
  251. > Until it ships in a released cocoindex, run against a local cocoindex build.
  252. ## Docker
  253. A Docker image is available for teams who want a reproducible, dependency-free
  254. setup — no Python, `uv`, or system dependencies required on the host.
  255. The recommended approach is a **persistent container**: start it once, and use
  256. `docker exec` to run CLI commands or connect MCP sessions to it. The daemon
  257. inside stays warm across sessions, so the embedding model is loaded only once.
  258. ### Choosing an image
  259. Two variants are published from each release:
  260. | Tag | Size | Embedding backends | When to pick |
  261. |---|---|---|---|
  262. | `cocoindex/cocoindex-code:latest` (slim, default) | ~450 MB | LiteLLM (cloud: OpenAI, Voyage, Gemini, Ollama, …) | Most users. Cloud-backed embeddings, smaller image, fast pulls. |
  263. | `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. |
  264. The rest of this section uses `:latest` — substitute `:full` in the `image:` /
  265. `docker run` commands if you want the full variant.
  266. > **Mac users running the `:full` variant:** local embedding inference is
  267. > CPU-only inside Docker, because Docker on macOS can't access Apple's Metal
  268. > (MPS) GPU. If you want local embeddings and fast inference, install
  269. > natively instead: `pipx install 'cocoindex-code[full]'`. The `:latest`
  270. > (slim) variant is unaffected — LiteLLM runs the model on the provider's
  271. > side, so Docker vs. native makes no difference.
  272. ### Quick start — `docker compose up -d`
  273. Bring it up in one line — no clone needed (bash / zsh):
  274. ```bash
  275. # macOS / Windows
  276. docker compose -f <(curl -L https://raw.githubusercontent.com/cocoindex-io/cocoindex-code/refs/heads/main/docker/docker-compose.yml) up -d
  277. # Linux (aligns file ownership on bind-mounted paths with your host user)
  278. 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
  279. ```
  280. Or grab [`docker/docker-compose.yml`](./docker/docker-compose.yml) and run `docker compose up -d` next to it (works on any shell, including Windows cmd / PowerShell).
  281. By default your home directory is mounted into the container (set
  282. `COCOINDEX_HOST_WORKSPACE` to narrow this to a specific code folder). Index
  283. data and the embedding model cache persist in a Docker volume across
  284. restarts. Your global settings file at `$HOME/.cocoindex_code/global_settings.yml`
  285. is visible and editable on the host; edits take effect on your next `ccc` command.
  286. > **Pick a different image:** set `COCOINDEX_CODE_IMAGE` to override the
  287. > default. For example, the `:full` variant or GHCR:
  288. > ```bash
  289. > COCOINDEX_CODE_IMAGE=cocoindex/cocoindex-code:full docker compose up -d
  290. > COCOINDEX_CODE_IMAGE=ghcr.io/cocoindex-io/cocoindex-code:latest docker compose up -d
  291. > ```
  292. ### Or: `docker run`
  293. <details>
  294. <summary>Docker Desktop (macOS / Windows)</summary>
  295. ```bash
  296. docker run -d --name cocoindex-code \
  297. --volume "$HOME:/workspace" \
  298. --volume cocoindex-data:/var/cocoindex \
  299. -e COCOINDEX_CODE_HOST_PATH_MAPPING="/workspace=$HOME" \
  300. cocoindex/cocoindex-code:latest
  301. ```
  302. </details>
  303. <details>
  304. <summary>Linux (with <code>PUID</code>/<code>PGID</code>)</summary>
  305. ```bash
  306. docker run -d --name cocoindex-code \
  307. -e PUID=$(id -u) -e PGID=$(id -g) \
  308. --volume "$HOME:/workspace" \
  309. --volume cocoindex-data:/var/cocoindex \
  310. -e COCOINDEX_CODE_HOST_PATH_MAPPING="/workspace=$HOME" \
  311. cocoindex/cocoindex-code:latest
  312. ```
  313. </details>
  314. ### Shell wrapper for `ccc` commands
  315. Paste this into `~/.bashrc` / `~/.zshrc` so `ccc` feels native on the host
  316. and picks up the right project based on your current directory:
  317. ```bash
  318. ccc() {
  319. docker exec -it -e COCOINDEX_CODE_HOST_CWD="$PWD" cocoindex-code ccc "$@"
  320. }
  321. ```
  322. Now `cd` into a project under your workspace and run `ccc init`, `ccc index`,
  323. `ccc search ...`, or `ccc status`.
  324. ### Connect your coding agent
  325. <details>
  326. <summary>Claude Code</summary>
  327. Register MCP from inside the target project so `$PWD` points there:
  328. ```bash
  329. claude mcp add cocoindex-code -- docker exec -i \
  330. -e COCOINDEX_CODE_HOST_CWD="$PWD" cocoindex-code ccc mcp
  331. ```
  332. Or via `.mcp.json`:
  333. ```json
  334. {
  335. "mcpServers": {
  336. "cocoindex-code": {
  337. "type": "stdio",
  338. "command": "docker",
  339. "args": [
  340. "exec",
  341. "-i",
  342. "-e",
  343. "COCOINDEX_CODE_HOST_CWD=${PWD}",
  344. "cocoindex-code",
  345. "ccc",
  346. "mcp"
  347. ]
  348. }
  349. }
  350. }
  351. ```
  352. > Note: use `-i` (not `-it`). The `-t` flag allocates a terminal, which
  353. > interferes with MCP's JSON messaging over stdin/stdout — only add it for
  354. > interactive `ccc` commands like `ccc init`.
  355. </details>
  356. <details>
  357. <summary>Codex</summary>
  358. ```bash
  359. codex mcp add cocoindex-code -- docker exec -i \
  360. -e COCOINDEX_CODE_HOST_CWD="$PWD" cocoindex-code ccc mcp
  361. ```
  362. </details>
  363. ### Upgrading from an older image
  364. Earlier images used separate `cocoindex-db` and `cocoindex-model-cache`
  365. volumes; the current image consolidates them into a single `cocoindex-data`
  366. volume. Before pulling the new image, drop the old container and volumes —
  367. indexes rebuild on your next `ccc index`, and the embedding model is
  368. re-populated automatically on first start:
  369. ```bash
  370. docker rm -f cocoindex-code
  371. docker volume rm cocoindex-db cocoindex-model-cache
  372. ```
  373. ### Configuration via environment variables
  374. Pass configuration to `docker run` / compose with `-e`:
  375. ```bash
  376. # Extra extensions (e.g. Typesafe Config, SBT build files)
  377. -e COCOINDEX_CODE_EXTRA_EXTENSIONS="conf,sbt"
  378. # Exclude build artefacts (Scala/SBT example)
  379. -e COCOINDEX_CODE_EXCLUDE_PATTERNS='["**/target/**","**/.bloop/**","**/.metals/**"]'
  380. # Set an API key
  381. -e VOYAGE_API_KEY=your-key
  382. ```
  383. > **Security note:** mounting `$HOME` gives the container read/write access
  384. > to everything under it. If that's too broad, bind-mount a narrower
  385. > directory instead (`COCOINDEX_HOST_WORKSPACE=/path/to/code`).
  386. ### Build the image locally
  387. ```bash
  388. docker build -t cocoindex-code:local -f docker/Dockerfile .
  389. ```
  390. ## Features
  391. - **Semantic Code Search**: Find relevant code using natural language queries when grep doesn't work well.
  392. - **Incremental indexing**: The [Rust indexing engine](https://github.com/cocoindex-io/cocoindex) re-indexes only changed files.
  393. - **Multi-Language Support**: Python, JavaScript/TypeScript, Rust, Go, Java, C/C++, C#, SQL, Shell, and more.
  394. - **Embedded storage**: No database setup required.
  395. - **Embedding providers**: Local SentenceTransformers via the `[full]` extra, with no API key, or 100+ cloud providers via LiteLLM.
  396. ## Configuration
  397. For a detailed guide on choosing and configuring embedding models, see [EMBEDDINGS.md](EMBEDDINGS.md).
  398. Configuration lives in two YAML files, both created automatically by `ccc init`.
  399. ### User Settings (`~/.cocoindex_code/global_settings.yml`)
  400. Shared across all projects. Controls the embedding model and environment variables for the daemon.
  401. ```yaml
  402. embedding:
  403. provider: sentence-transformers # or "litellm"
  404. model: Snowflake/snowflake-arctic-embed-xs
  405. device: mps # optional: cpu, cuda, mps (auto-detected if omitted)
  406. min_interval_ms: 300 # optional: pace LiteLLM embedding requests to reduce 429s; defaults to 5 for LiteLLM
  407. mps_low_watermark_ratio: 0.4 # optional: PyTorch allocator soft limit
  408. mps_high_watermark_ratio: 0.5 # optional: PyTorch allocator hard limit
  409. # Optional extra kwargs passed to the embedder, separately for indexing vs query.
  410. # `ccc init` auto-populates these for known models (e.g. Cohere, Voyage, Nvidia NIM,
  411. # nomic-ai code-retrieval models, Snowflake arctic-embed).
  412. # indexing_params:
  413. # input_type: search_document # litellm: input_type
  414. # query_params:
  415. # input_type: search_query # sentence-transformers: prompt_name
  416. envs: # extra environment variables for the daemon
  417. OPENAI_API_KEY: your-key # only needed if not already in your shell environment
  418. daemon:
  419. idle_timeout_minutes: 180 # optional: exit the daemon after this long without client activity (default 180, 0 = never)
  420. keep_alive_with_mcp: true # optional: keep the daemon warm while an MCP client is connected (default true)
  421. ```
  422. > **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't need to duplicate it in `envs`. The `envs` field is only for values that aren't in your environment.
  423. > **Apple Silicon memory safety:** MPS SentenceTransformer calls use [CocoIndex's isolated GPU subprocess](https://github.com/cocoindex-io/cocoindex/blob/v1.0.18/python/cocoindex/_internal/runner.py), keeping the model loaded while isolating Metal allocations from the daemon. The low and high watermarks are ratios of PyTorch'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](https://docs.pytorch.org/docs/stable/generated/torch.mps.empty_cache.html) 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.
  424. > **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.
  425. > **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.
  426. > **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).
  427. #### `indexing_params` / `query_params`
  428. Some embedding models expose different modes for documents vs queries (asymmetric retrieval). For example, Cohere'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`:
  429. ```yaml
  430. embedding:
  431. provider: litellm
  432. model: cohere/embed-english-v3.0
  433. indexing_params:
  434. input_type: search_document
  435. query_params:
  436. input_type: search_query
  437. ```
  438. `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.
  439. OpenAI embeddings (`text-embedding-3-*`, `text-embedding-ada-002`) are intentionally not in the list: they're symmetric and have no equivalent knob.
  440. **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.
  441. **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.
  442. **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: {}`.
  443. ### Project Settings (`<project>/.cocoindex_code/settings.yml`)
  444. Per-project. Controls which files to index.
  445. ```yaml
  446. include_patterns:
  447. - "**/*.py"
  448. - "**/*.js"
  449. - "**/*.ts"
  450. - "**/*.rs"
  451. - "**/*.go"
  452. # ... (sensible defaults for 28+ file types)
  453. exclude_patterns:
  454. - "**/.*" # hidden directories
  455. - "**/__pycache__"
  456. - "**/node_modules"
  457. - "**/dist"
  458. # ...
  459. max_file_size: 500KB # skip files larger than this (default: no limit)
  460. language_overrides:
  461. - ext: inc # treat .inc files as PHP
  462. lang: php
  463. chunkers:
  464. - ext: toml # use a custom chunker for .toml files
  465. module: example_toml_chunker:toml_chunker
  466. ```
  467. > `.cocoindex_code/` is automatically added to `.gitignore` during init.
  468. `max_file_size` keeps bundled or generated files out of the index without having
  469. to enumerate them in `exclude_patterns`. It accepts a plain byte count
  470. (`1048576`) or a size with a binary unit suffix: `B`, `KB`, `MB`, `GB`
  471. (case-insensitive, so `500KB` and `500 kb` are the same). The limit is
  472. inclusive, and omitting the key indexes files of any size. It applies wherever
  473. project file matching does, so `ccc grep` skips the same files.
  474. After editing `include_patterns`, `exclude_patterns`, `max_file_size`, or `language_overrides`:
  475. - Run `ccc doctor` to preview which files match.
  476. - Run `ccc index` or `ccc search --refresh ...` to update the existing index.
  477. - You do not need to delete the index or restart the daemon for these file-matching changes.
  478. - 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.
  479. 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's own module file (for example, bump a version comment in it).
  480. Use `chunkers` when you want to control how a file type is split into chunks before indexing.
  481. `module: example_toml_chunker:toml_chunker` means:
  482. - `example_toml_chunker` is a local Python module
  483. - `toml_chunker` is the function inside that module
  484. In practice, this usually means:
  485. - you create a Python file in your project, for example `example_toml_chunker.py`
  486. - you add a function in that file
  487. - you point `settings.yml` at it with `module.path:function_name`
  488. The function should use this signature:
  489. ```python
  490. from pathlib import Path
  491. from cocoindex_code.chunking import Chunk
  492. def my_chunker(path: Path, content: str) -> tuple[str | None, list[Chunk]]:
  493. ...
  494. ```
  495. - `path` is the file being indexed
  496. - `content` is the full text of that file
  497. - return `language_override` as a string like `"toml"` if you want to override language detection
  498. - return `None` as `language_override` if you want to keep the detected language
  499. - return a `list[Chunk]` with the chunks you want stored in the index
  500. See [`src/cocoindex_code/chunking.py`](./src/cocoindex_code/chunking.py) for the public types and [`tests/example_toml_chunker.py`](./tests/example_toml_chunker.py) for a complete example.
  501. ## Embedding Models
  502. With the `[full]` extra installed, `ccc init` defaults to a local SentenceTransformers model ([Snowflake/snowflake-arctic-embed-xs](https://huggingface.co/Snowflake/snowflake-arctic-embed-xs)) — no API key required. To use a different model, edit `~/.cocoindex_code/global_settings.yml`.
  503. > The `envs` entries below are only needed if the key isn't already in your shell environment — the daemon inherits your environment automatically.
  504. <details>
  505. <summary>Ollama (Local)</summary>
  506. ```yaml
  507. embedding:
  508. model: ollama/nomic-embed-text
  509. ```
  510. Set `OLLAMA_API_BASE` in `envs:` if your Ollama server is not at `http://localhost:11434`.
  511. </details>
  512. <details>
  513. <summary>OpenAI</summary>
  514. ```yaml
  515. embedding:
  516. model: text-embedding-3-small
  517. min_interval_ms: 300 # optional: override the 5ms LiteLLM default
  518. envs:
  519. OPENAI_API_KEY: your-api-key
  520. ```
  521. </details>
  522. <details>
  523. <summary>OpenAI-compatible (custom endpoint)</summary>
  524. 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:
  525. ```yaml
  526. embedding:
  527. model: openai/your-model-name
  528. envs:
  529. OPENAI_BASE_URL: https://your-endpoint/v1
  530. OPENAI_API_KEY: your-api-key
  531. ```
  532. Don't append `/embeddings` to the base URL — LiteLLM handles that.
  533. </details>
  534. <details>
  535. <summary>Azure OpenAI</summary>
  536. ```yaml
  537. embedding:
  538. model: azure/your-deployment-name
  539. envs:
  540. AZURE_API_KEY: your-api-key
  541. AZURE_API_BASE: https://your-resource.openai.azure.com
  542. AZURE_API_VERSION: "2024-06-01"
  543. ```
  544. </details>
  545. <details>
  546. <summary>Gemini</summary>
  547. ```yaml
  548. embedding:
  549. model: gemini/gemini-embedding-001
  550. envs:
  551. GEMINI_API_KEY: your-api-key
  552. ```
  553. </details>
  554. <details>
  555. <summary>Mistral</summary>
  556. ```yaml
  557. embedding:
  558. model: mistral/mistral-embed
  559. envs:
  560. MISTRAL_API_KEY: your-api-key
  561. ```
  562. </details>
  563. <details>
  564. <summary>Voyage (Code-Optimized)</summary>
  565. ```yaml
  566. embedding:
  567. model: voyage/voyage-code-3
  568. envs:
  569. VOYAGE_API_KEY: your-api-key
  570. ```
  571. </details>
  572. <details>
  573. <summary>Cohere</summary>
  574. ```yaml
  575. embedding:
  576. model: cohere/embed-v4.0
  577. envs:
  578. COHERE_API_KEY: your-api-key
  579. ```
  580. </details>
  581. <details>
  582. <summary>AWS Bedrock</summary>
  583. ```yaml
  584. embedding:
  585. model: bedrock/amazon.titan-embed-text-v2:0
  586. envs:
  587. AWS_ACCESS_KEY_ID: your-access-key
  588. AWS_SECRET_ACCESS_KEY: your-secret-key
  589. AWS_REGION_NAME: us-east-1
  590. ```
  591. </details>
  592. <details>
  593. <summary>Nebius</summary>
  594. ```yaml
  595. embedding:
  596. model: nebius/BAAI/bge-en-icl
  597. envs:
  598. NEBIUS_API_KEY: your-api-key
  599. ```
  600. </details>
  601. Any [LiteLLM-supported model](https://docs.litellm.ai/docs/embedding/supported_embedding) works. When using a LiteLLM model, set `provider: litellm` (or omit `provider` — LiteLLM is the default for non-`sentence-transformers` models). For the full list of env vars each provider reads (API keys, base URLs, regions, …), see LiteLLM's [Setting API Keys](https://docs.litellm.ai/docs/set_keys).
  602. ### Local SentenceTransformers Models
  603. Set `provider: sentence-transformers` and use any [SentenceTransformers](https://www.sbert.net/) model (no API key required).
  604. **Example — general purpose text model:**
  605. ```yaml
  606. embedding:
  607. provider: sentence-transformers
  608. model: nomic-ai/nomic-embed-text-v1.5
  609. ```
  610. **GPU-optimised code retrieval:**
  611. [`nomic-ai/CodeRankEmbed`](https://huggingface.co/nomic-ai/CodeRankEmbed) delivers significantly better code retrieval than the default model. It is 137M parameters, requires ~1 GB VRAM, and has an 8192-token context window.
  612. ```yaml
  613. embedding:
  614. provider: sentence-transformers
  615. model: nomic-ai/CodeRankEmbed
  616. ```
  617. **Note:** Switching models requires re-indexing your codebase (`ccc reset && ccc index`) since the vector dimensions differ.
  618. ## Supported Languages
  619. | Language | Aliases | File Extensions |
  620. |----------|---------|-----------------|
  621. | c | | `.c` |
  622. | cpp | c++ | `.cpp`, `.cc`, `.cxx`, `.h`, `.hpp` |
  623. | csharp | csharp, cs | `.cs` |
  624. | css | | `.css`, `.scss` |
  625. | dart | | `.dart` |
  626. | dtd | | `.dtd` |
  627. | elixir | | `.ex`, `.exs` |
  628. | fortran | f, f90, f95, f03 | `.f`, `.f90`, `.f95`, `.f03` |
  629. | go | golang | `.go` |
  630. | html | | `.html`, `.htm` |
  631. | java | | `.java` |
  632. | javascript | js | `.js` |
  633. | json | | `.json` |
  634. | kotlin | | `.kt`, `.kts` |
  635. | lua | | `.lua` |
  636. | markdown | md | `.md`, `.mdx` |
  637. | pascal | pas, dpr, delphi | `.pas`, `.dpr` |
  638. | php | | `.php` |
  639. | python | | `.py` |
  640. | r | | `.r` |
  641. | ruby | | `.rb` |
  642. | rust | rs | `.rs` |
  643. | scala | | `.scala` |
  644. | solidity | | `.sol` |
  645. | sql | | `.sql` |
  646. | svelte | | `.svelte` |
  647. | swift | | `.swift` |
  648. | toml | | `.toml` |
  649. | tsx | | `.tsx` |
  650. | typescript | ts | `.ts` |
  651. | vue | | `.vue` |
  652. | xml | | `.xml` |
  653. | yaml | | `.yaml`, `.yml` |
  654. ### Custom Database Location
  655. By default, index databases (`cocoindex.db` and `target_sqlite.db`) live alongside settings in `<project>/.cocoindex_code/`. When running in Docker, you may want the databases on the container's native filesystem for performance (LMDB doesn't work well on mounted volumes) while keeping the source code and settings on a mounted volume.
  656. Set `COCOINDEX_CODE_DB_PATH_MAPPING` to remap database locations by path prefix:
  657. ```bash
  658. COCOINDEX_CODE_DB_PATH_MAPPING=/workspace=/db-files
  659. ```
  660. With this mapping, a project at `/workspace/myrepo` stores its databases in `/db-files/myrepo/` instead of `/workspace/myrepo/.cocoindex_code/`. Settings files remain in the original location.
  661. Multiple mappings are comma-separated and resolved in order (first match wins):
  662. ```bash
  663. COCOINDEX_CODE_DB_PATH_MAPPING=/workspace=/db-files,/workspace2=/db-files2
  664. ```
  665. Both source and target must be absolute paths. If no mapping matches, the default location is used.
  666. ## Troubleshooting
  667. Run `ccc doctor` to check your settings, daemon health, embedding model, file matching, and index status.
  668. ### `sqlite3.Connection object has no attribute enable_load_extension`
  669. Some Python installations (e.g. the one pre-installed on macOS) ship with a SQLite library that doesn't enable extensions.
  670. **macOS fix:** Install Python through [Homebrew](https://brew.sh/):
  671. ```bash
  672. brew install python3
  673. ```
  674. Then re-install cocoindex-code (see [Get Started](#get-started) for install options):
  675. Using pipx:
  676. ```bash
  677. pipx install cocoindex-code # first install
  678. pipx upgrade cocoindex-code # upgrade
  679. ```
  680. Using uv (install or upgrade):
  681. ```bash
  682. uv tool install --upgrade cocoindex-code
  683. ```
  684. ### `MDB_MAP_FULL: Environment mapsize limit reached`
  685. The index is stored in an LMDB database whose maximum size is fixed when the daemon starts. The default ceiling is **4 GiB**, which codebases with tens of thousands of files can exhaust, especially with high-dimensional embedding models like `nomic-ai/CodeRankEmbed`.
  686. Raise the ceiling with the `COCOINDEX_LMDB_MAP_SIZE` environment variable (value in **bytes**). LMDB only grows the file as data is written, so a high limit doesn't pre-allocate disk — it's safe to set it generously:
  687. ```yaml
  688. # ~/.cocoindex_code/global_settings.yml
  689. envs:
  690. COCOINDEX_LMDB_MAP_SIZE: "34359738368" # 32 GiB (= 32 * 1024^3)
  691. ```
  692. Or, if you prefer to set it in your shell environment (the daemon inherits it):
  693. ```bash
  694. export COCOINDEX_LMDB_MAP_SIZE=$((32 * 1024 * 1024 * 1024)) # 32 GiB
  695. ```
  696. The map size is read when the daemon starts, so restart it to pick up the change, then re-index:
  697. ```bash
  698. ccc daemon restart
  699. ccc index
  700. ```
  701. > This manual step is temporary. Once [cocoindex#2108](https://github.com/cocoindex-io/cocoindex/issues/2108) lands, the map size grows automatically when needed and `COCOINDEX_LMDB_MAP_SIZE` won't be necessary.
  702. ## Legacy: Environment Variables
  703. If you previously configured `cocoindex-code` via environment variables, the `cocoindex-code` MCP command still reads them and auto-migrates to YAML settings on first run. We recommend switching to the YAML settings for new setups.
  704. | Environment Variable | YAML Equivalent |
  705. |---------------------|-----------------|
  706. | `COCOINDEX_CODE_EMBEDDING_MODEL` | `embedding.model` in `global_settings.yml` |
  707. | `COCOINDEX_CODE_DEVICE` | `embedding.device` in `global_settings.yml` |
  708. | `COCOINDEX_CODE_ROOT_PATH` | Run `ccc init` in your project root instead |
  709. | `COCOINDEX_CODE_EXCLUDED_PATTERNS` | `exclude_patterns` in project `settings.yml` |
  710. | `COCOINDEX_CODE_EXTRA_EXTENSIONS` | `include_patterns` + `language_overrides` in project `settings.yml` |
  711. ## Telemetry
  712. `cocoindex-code` sends anonymous usage telemetry through CocoIndex so we can see how the tool is used in aggregate and prioritize improvements. The events identify themselves as `application: cocoindex-code`.
  713. We **do not** collect your source code, file paths, queries, search results, embeddings, settings, or any other content from your codebase or environment.
  714. To opt out, set:
  715. ```bash
  716. export COCOINDEX_DISABLE_USAGE_TRACKING=1
  717. ```
  718. ## Large codebase / Enterprise
  719. Teams indexing large or multiple repositories can share [CocoIndex](https://github.com/cocoindex-io/cocoindex) indexes across developers. Enterprise features include deduplication across branches.
  720. > If indexing fails with `MDB_MAP_FULL`, raise the LMDB map size. See [`MDB_MAP_FULL: Environment mapsize limit reached`](#mdb_map_full-environment-mapsize-limit-reached) under Troubleshooting.
  721. For help with remote setup, email linghua@cocoindex.io.
  722. ## Contributing
  723. We welcome contributions. This project uses [uv](https://docs.astral.sh/uv/getting-started/installation/) for development. CI checks lint, formatting, types, and tests for every PR. Run the same checks locally before opening a PR; failed pre-commit checks are the most common cause of red CI on incoming PRs.
  724. ### 1. Install the dev dependencies
  725. After installing [uv](https://docs.astral.sh/uv/getting-started/installation/), sync the project. This installs everything the checks need — including [prek](https://github.com/j178/prek), a fast pre-commit runner, plus Ruff, mypy, and pytest:
  726. ```bash
  727. uv sync
  728. ```
  729. ### 2. Run all checks before every PR
  730. Run the full hook suite across all files — this is exactly what CI runs:
  731. ```bash
  732. uv run prek run --all-files
  733. ```
  734. It runs trailing-whitespace/end-of-file fixes, Ruff lint (`--fix`) and format, `uv.lock` validation, mypy type checking, and the pytest suite. Fix anything it reports (Ruff auto-fixes most lint/format issues for you), re-run until it passes, then push.
  735. ### 3. (Optional) Run automatically on each commit
  736. To have the same checks run on every `git commit`, install the git hook once:
  737. ```bash
  738. uv run prek install
  739. ```
  740. For more details, see our [contributing guide](https://cocoindex.io/docs/contributing/guide).
  741. ## License
  742. Apache-2.0

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.