cocoindex-code 0.2.42__tar.gz → 0.2.43__tar.gz

{cocoindex_code-0.2.42 → cocoindex_code-0.2.43}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cocoindex-code
-Version: 0.2.42
+Version: 0.2.43
 Summary: MCP server for indexing and querying codebases using CocoIndex
 Project-URL: Homepage, https://github.com/cocoindex-io/cocoindex-code
 Project-URL: Repository, https://github.com/cocoindex-io/cocoindex-code
@@ -47,15 +47,15 @@ Description-Content-Type: text/markdown
 </p>
 
 
-<h1 align="center">AST-based semantic code search that just works</h1>
+<h1 align="center">AST-based semantic code search</h1>
 
 ![effect](https://github.com/user-attachments/assets/cb3a4cae-0e1f-49c4-890b-7bb93317ab60)
 
 
-A lightweight, effective **(AST-based)** semantic code search tool for your codebase. Built on [CocoIndex](https://github.com/cocoindex-io/cocoindex) — a Rust-based ultra performant data transformation engine. Use it from the CLI, or integrate with Claude, Codex, Cursor — any coding agent — via [Skill](#skill-recommended) or [MCP](#mcp-server).
+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).
 
-- Instant token saving by 70%.
-- **1 min setup** — install and go, zero config needed!
+- 70% token savings.
+- 1 min setup with default settings.
 
 <div align="center">
 
@@ -69,7 +69,7 @@ A lightweight, effective **(AST-based)** semantic code search tool for your code
 [![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)
 
 
-🌟 Please help star [CocoIndex](https://github.com/cocoindex-io/cocoindex) if you like this project!
+Star [CocoIndex](https://github.com/cocoindex-io/cocoindex) if you find it useful.
 
 [Deutsch](https://readme-i18n.com/cocoindex-io/cocoindex-code?lang=de) |
 [English](https://readme-i18n.com/cocoindex-io/cocoindex-code?lang=en) |
@@ -84,7 +84,9 @@ A lightweight, effective **(AST-based)** semantic code search tool for your code
 </div>
 
 
-## Get Started — zero config, let's go!
+<a id="get-started--zero-config-lets-go"></a>
+
+## Get Started
 
 ### Install
 
@@ -117,7 +119,7 @@ Install the `ccc` skill so your coding agent automatically uses semantic search
 npx skills add cocoindex-io/cocoindex-code
 ```
 
-That's it — no `ccc init` or `ccc index` needed. The skill teaches the agent to handle initialization, indexing, and searching on its own. It will automatically keep the index up to date as you work.
+The 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.
 
 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.
 
@@ -141,7 +143,7 @@ For [Grok](https://github.com/xai-org/grok) users, install via Grok's plugin sys
 | Component | Purpose |
 |-----------|---------|
 | **Skill** (`skills/ccc/`) | Agent runs `ccc search` / `ccc index` via the CLI (same as Claude Code above) |
-| **Hook** (`hooks/hooks.json`) | `SessionStart` + `PostToolUse` (Edit/Write/…) → incremental `ccc index` when `.cocoindex_code/` exists |
+| **Hook** (`hooks/hooks.json`) | `SessionStart` + `PostToolUse` (Edit/Write/…) → incremental `ccc index` when `.cocoindex_code/settings.yml` exists (never in the directory holding ccc's user settings, `~` by default) |
 | **MCP** (`.mcp.json`) | `ccc mcp` stdio server — `search` tool with `refresh_index=true` by default |
 
 Grok does **not** import Claude's `enabledPlugins` or plugin cache; install separately even if you already use cocoindex in Claude Code.
@@ -196,7 +198,7 @@ Then restart the session (`/reload-plugins` does not reload extensions). Require
 | Component | Purpose |
 |-----------|---------|
 | **Skill** (`skills/ccc/`) | Agent runs `ccc search` / `ccc index` via the CLI |
-| **Hook** (`extensions/ccc-index.ts` via `package.json#omp.extensions`) | `session_start` + post-edit `tool_result` → incremental `ccc index` when `.cocoindex_code/` exists |
+| **Hook** (`extensions/ccc-index.ts` via `package.json#omp.extensions`) | `session_start` + post-edit `tool_result` → incremental `ccc index` when `.cocoindex_code/settings.yml` exists (never in the directory holding ccc's user settings, `~` by default) |
 | **MCP** (`.mcp.json`) | `ccc mcp` stdio server |
 
 OMP does **not** execute Claude `hooks/hooks.json` command hooks. The TypeScript extension is the OMP equivalent of the Claude/Grok SessionStart + PostToolUse pair.
@@ -205,6 +207,9 @@ Skill-only (no MCP, no auto-index): install the skill via `npx skills add cocoin
 
 ### MCP Server
 
+<!-- Ownership marker for the official MCP registry. It must match "name" in server.json. Keep the next line. -->
+<!-- mcp-name: io.github.cocoindex-io/cocoindex-code -->
+
 Alternatively, use `ccc mcp` to run as an MCP server:
 
 <details>
@@ -284,7 +289,7 @@ Prefer the marketplace install above. Manual project MCP (`.omp/mcp.json`):
 ```
 </details>
 
-Once configured, the agent automatically decides when semantic code search is helpful — finding code by description, exploring unfamiliar codebases, fuzzy/conceptual matches, or locating implementations without knowing exact names.
+Once configured, the agent can use semantic search to find code by description, explore unfamiliar codebases, and locate implementations without exact names.
 
 > **Note:** The `cocoindex-code` command (without subcommand) still works as an MCP server for backward compatibility. It auto-creates settings from environment variables on first run.
 
@@ -323,6 +328,8 @@ The background daemon starts automatically on first use.
 
 > **Tip:** You can skip `ccc init` and go straight to `ccc index` — it auto-initializes new projects with default settings. If global settings are missing too (first use on the machine), it walks you through the same model setup as `ccc init` when run interactively; non-interactive runs (scripts, hooks) still require a one-time `ccc init` first.
 
+> **Note:** `ccc index` never auto-initializes the directory that holds ccc's user settings directory: your home directory by default (`~/.cocoindex_code` holds the global settings and daemon files), or the parent of `$COCOINDEX_CODE_DIR` when that directory is named `.cocoindex_code`. A project there would cover every repo below it. The editor hooks skip that directory even if it is already a project. If an older ccc made your home directory a project (`~/.cocoindex_code/settings.yml` exists), run `ccc reset --all` in your home directory: it removes that project's settings and indexes and keeps your global settings. To index your whole home directory on purpose, run `ccc init` there.
+
 ### CLI Reference
 
 | Command | Description |
@@ -475,8 +482,8 @@ ccc() {
 }
 ```
 
-Now `cd` into any project under your workspace and run `ccc init`, `ccc index`,
-`ccc search ...`, `ccc status`, etc. — it just works.
+Now `cd` into a project under your workspace and run `ccc init`, `ccc index`,
+`ccc search ...`, or `ccc status`.
 
 ### Connect your coding agent
 
@@ -565,11 +572,11 @@ docker build -t cocoindex-code:local -f docker/Dockerfile .
 ```
 
 ## Features
-- **Semantic Code Search**: Find relevant code using natural language queries when grep doesn't work well, and save tokens immediately.
-- **Ultra Performant**: ⚡ Built on top of ultra performant [Rust indexing engine](https://github.com/cocoindex-io/cocoindex). Only re-indexes changed files for fast updates.
+- **Semantic Code Search**: Find relevant code using natural language queries when grep doesn't work well.
+- **Incremental indexing**: The [Rust indexing engine](https://github.com/cocoindex-io/cocoindex) re-indexes only changed files.
 - **Multi-Language Support**: Python, JavaScript/TypeScript, Rust, Go, Java, C/C++, C#, SQL, Shell, and more.
-- **Embedded**: Portable and just works, no database setup required!
-- **Flexible Embeddings**: Local SentenceTransformers via the `[full]` extra (free, no API key!) or 100+ cloud providers via LiteLLM.
+- **Embedded storage**: No database setup required.
+- **Embedding providers**: Local SentenceTransformers via the `[full]` extra, with no API key, or 100+ cloud providers via LiteLLM.
 
 ## Configuration
 
@@ -685,8 +692,9 @@ After editing `include_patterns`, `exclude_patterns`, `max_file_size`, or `langu
 - Run `ccc doctor` to preview which files match.
 - Run `ccc index` or `ccc search --refresh ...` to update the existing index.
 - You do not need to delete the index or restart the daemon for these file-matching changes.
+- After any `language_overrides` change, the next run re-chunks all files, including files whose content did not change; the run reports them as reprocessed. Chunks whose text did not change keep their cached embeddings.
 
-If you add or change custom `chunkers`, restart the daemon first so the chunker registry is reloaded, then run `ccc index`.
+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).
 
 Use `chunkers` when you want to control how a file type is split into chunks before indexing.
 
@@ -938,7 +946,7 @@ Both source and target must be absolute paths. If no mapping matches, the defaul
 
 ## Troubleshooting
 
-Run `ccc doctor` to diagnose common issues. It checks your settings, daemon health, embedding model, file matching, and index status — all in one command.
+Run `ccc doctor` to check your settings, daemon health, embedding model, file matching, and index status.
 
 ### `sqlite3.Connection object has no attribute enable_load_extension`
 
@@ -950,7 +958,7 @@ Some Python installations (e.g. the one pre-installed on macOS) ship with a SQLi
 brew install python3
 ```
 
-Then re-install cocoindex-code (see [Get Started](#get-started--zero-config-lets-go) for install options):
+Then re-install cocoindex-code (see [Get Started](#get-started) for install options):
 
 Using pipx:
 ```bash
@@ -965,7 +973,7 @@ uv tool install --upgrade cocoindex-code
 
 ### `MDB_MAP_FULL: Environment mapsize limit reached`
 
-The index is stored in an LMDB database whose maximum size is fixed when the daemon starts. The default ceiling is **4 GiB**, which is plenty for most projects but can be exhausted by very large codebases (tens of thousands of files), especially with high-dimensional embedding models like `nomic-ai/CodeRankEmbed`.
+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`.
 
 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:
 
@@ -1015,15 +1023,15 @@ export COCOINDEX_DISABLE_USAGE_TRACKING=1
 ```
 
 ## Large codebase / Enterprise
-[CocoIndex](https://github.com/cocoindex-io/cocoindex) is an ultra efficient indexing engine that also works on large codebases at scale for enterprises. In enterprise scenarios it is a lot more efficient to share indexes with teammates when there are large or many repos. We also have advanced features like branch dedupe etc designed for enterprise users.
+Teams indexing large or multiple repositories can share [CocoIndex](https://github.com/cocoindex-io/cocoindex) indexes across developers. Enterprise features include deduplication across branches.
 
-> Indexing a very large codebase and hitting `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.
+> 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.
 
-If you need help with remote setup, please email our maintainer linghua@cocoindex.io, happy to help!
+For help with remote setup, email linghua@cocoindex.io.
 
 ## Contributing
 
-We welcome contributions! This project uses [uv](https://docs.astral.sh/uv/getting-started/installation/) for development, and every PR is gated on the same lint, format, type-check, and test suite in CI. **Please run these checks locally before opening a PR** — failing pre-commit checks are the most common cause of red CI on incoming PRs.
+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.
 
 ### 1. Install the dev dependencies
 

{cocoindex_code-0.2.42 → cocoindex_code-0.2.43}/README.md

@@ -3,15 +3,15 @@
 </p>
 
 
-<h1 align="center">AST-based semantic code search that just works</h1>
+<h1 align="center">AST-based semantic code search</h1>
 
 ![effect](https://github.com/user-attachments/assets/cb3a4cae-0e1f-49c4-890b-7bb93317ab60)
 
 
-A lightweight, effective **(AST-based)** semantic code search tool for your codebase. Built on [CocoIndex](https://github.com/cocoindex-io/cocoindex) — a Rust-based ultra performant data transformation engine. Use it from the CLI, or integrate with Claude, Codex, Cursor — any coding agent — via [Skill](#skill-recommended) or [MCP](#mcp-server).
+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).
 
-- Instant token saving by 70%.
-- **1 min setup** — install and go, zero config needed!
+- 70% token savings.
+- 1 min setup with default settings.
 
 <div align="center">
 
@@ -25,7 +25,7 @@ A lightweight, effective **(AST-based)** semantic code search tool for your code
 [![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)
 
 
-🌟 Please help star [CocoIndex](https://github.com/cocoindex-io/cocoindex) if you like this project!
+Star [CocoIndex](https://github.com/cocoindex-io/cocoindex) if you find it useful.
 
 [Deutsch](https://readme-i18n.com/cocoindex-io/cocoindex-code?lang=de) |
 [English](https://readme-i18n.com/cocoindex-io/cocoindex-code?lang=en) |
@@ -40,7 +40,9 @@ A lightweight, effective **(AST-based)** semantic code search tool for your code
 </div>
 
 
-## Get Started — zero config, let's go!
+<a id="get-started--zero-config-lets-go"></a>
+
+## Get Started
 
 ### Install
 
@@ -73,7 +75,7 @@ Install the `ccc` skill so your coding agent automatically uses semantic search
 npx skills add cocoindex-io/cocoindex-code
 ```
 
-That's it — no `ccc init` or `ccc index` needed. The skill teaches the agent to handle initialization, indexing, and searching on its own. It will automatically keep the index up to date as you work.
+The 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.
 
 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.
 
@@ -97,7 +99,7 @@ For [Grok](https://github.com/xai-org/grok) users, install via Grok's plugin sys
 | Component | Purpose |
 |-----------|---------|
 | **Skill** (`skills/ccc/`) | Agent runs `ccc search` / `ccc index` via the CLI (same as Claude Code above) |
-| **Hook** (`hooks/hooks.json`) | `SessionStart` + `PostToolUse` (Edit/Write/…) → incremental `ccc index` when `.cocoindex_code/` exists |
+| **Hook** (`hooks/hooks.json`) | `SessionStart` + `PostToolUse` (Edit/Write/…) → incremental `ccc index` when `.cocoindex_code/settings.yml` exists (never in the directory holding ccc's user settings, `~` by default) |
 | **MCP** (`.mcp.json`) | `ccc mcp` stdio server — `search` tool with `refresh_index=true` by default |
 
 Grok does **not** import Claude's `enabledPlugins` or plugin cache; install separately even if you already use cocoindex in Claude Code.
@@ -152,7 +154,7 @@ Then restart the session (`/reload-plugins` does not reload extensions). Require
 | Component | Purpose |
 |-----------|---------|
 | **Skill** (`skills/ccc/`) | Agent runs `ccc search` / `ccc index` via the CLI |
-| **Hook** (`extensions/ccc-index.ts` via `package.json#omp.extensions`) | `session_start` + post-edit `tool_result` → incremental `ccc index` when `.cocoindex_code/` exists |
+| **Hook** (`extensions/ccc-index.ts` via `package.json#omp.extensions`) | `session_start` + post-edit `tool_result` → incremental `ccc index` when `.cocoindex_code/settings.yml` exists (never in the directory holding ccc's user settings, `~` by default) |
 | **MCP** (`.mcp.json`) | `ccc mcp` stdio server |
 
 OMP does **not** execute Claude `hooks/hooks.json` command hooks. The TypeScript extension is the OMP equivalent of the Claude/Grok SessionStart + PostToolUse pair.
@@ -161,6 +163,9 @@ Skill-only (no MCP, no auto-index): install the skill via `npx skills add cocoin
 
 ### MCP Server
 
+<!-- Ownership marker for the official MCP registry. It must match "name" in server.json. Keep the next line. -->
+<!-- mcp-name: io.github.cocoindex-io/cocoindex-code -->
+
 Alternatively, use `ccc mcp` to run as an MCP server:
 
 <details>
@@ -240,7 +245,7 @@ Prefer the marketplace install above. Manual project MCP (`.omp/mcp.json`):
 ```
 </details>
 
-Once configured, the agent automatically decides when semantic code search is helpful — finding code by description, exploring unfamiliar codebases, fuzzy/conceptual matches, or locating implementations without knowing exact names.
+Once configured, the agent can use semantic search to find code by description, explore unfamiliar codebases, and locate implementations without exact names.
 
 > **Note:** The `cocoindex-code` command (without subcommand) still works as an MCP server for backward compatibility. It auto-creates settings from environment variables on first run.
 
@@ -279,6 +284,8 @@ The background daemon starts automatically on first use.
 
 > **Tip:** You can skip `ccc init` and go straight to `ccc index` — it auto-initializes new projects with default settings. If global settings are missing too (first use on the machine), it walks you through the same model setup as `ccc init` when run interactively; non-interactive runs (scripts, hooks) still require a one-time `ccc init` first.
 
+> **Note:** `ccc index` never auto-initializes the directory that holds ccc's user settings directory: your home directory by default (`~/.cocoindex_code` holds the global settings and daemon files), or the parent of `$COCOINDEX_CODE_DIR` when that directory is named `.cocoindex_code`. A project there would cover every repo below it. The editor hooks skip that directory even if it is already a project. If an older ccc made your home directory a project (`~/.cocoindex_code/settings.yml` exists), run `ccc reset --all` in your home directory: it removes that project's settings and indexes and keeps your global settings. To index your whole home directory on purpose, run `ccc init` there.
+
 ### CLI Reference
 
 | Command | Description |
@@ -431,8 +438,8 @@ ccc() {
 }
 ```
 
-Now `cd` into any project under your workspace and run `ccc init`, `ccc index`,
-`ccc search ...`, `ccc status`, etc. — it just works.
+Now `cd` into a project under your workspace and run `ccc init`, `ccc index`,
+`ccc search ...`, or `ccc status`.
 
 ### Connect your coding agent
 
@@ -521,11 +528,11 @@ docker build -t cocoindex-code:local -f docker/Dockerfile .
 ```
 
 ## Features
-- **Semantic Code Search**: Find relevant code using natural language queries when grep doesn't work well, and save tokens immediately.
-- **Ultra Performant**: ⚡ Built on top of ultra performant [Rust indexing engine](https://github.com/cocoindex-io/cocoindex). Only re-indexes changed files for fast updates.
+- **Semantic Code Search**: Find relevant code using natural language queries when grep doesn't work well.
+- **Incremental indexing**: The [Rust indexing engine](https://github.com/cocoindex-io/cocoindex) re-indexes only changed files.
 - **Multi-Language Support**: Python, JavaScript/TypeScript, Rust, Go, Java, C/C++, C#, SQL, Shell, and more.
-- **Embedded**: Portable and just works, no database setup required!
-- **Flexible Embeddings**: Local SentenceTransformers via the `[full]` extra (free, no API key!) or 100+ cloud providers via LiteLLM.
+- **Embedded storage**: No database setup required.
+- **Embedding providers**: Local SentenceTransformers via the `[full]` extra, with no API key, or 100+ cloud providers via LiteLLM.
 
 ## Configuration
 
@@ -641,8 +648,9 @@ After editing `include_patterns`, `exclude_patterns`, `max_file_size`, or `langu
 - Run `ccc doctor` to preview which files match.
 - Run `ccc index` or `ccc search --refresh ...` to update the existing index.
 - You do not need to delete the index or restart the daemon for these file-matching changes.
+- After any `language_overrides` change, the next run re-chunks all files, including files whose content did not change; the run reports them as reprocessed. Chunks whose text did not change keep their cached embeddings.
 
-If you add or change custom `chunkers`, restart the daemon first so the chunker registry is reloaded, then run `ccc index`.
+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).
 
 Use `chunkers` when you want to control how a file type is split into chunks before indexing.
 
@@ -894,7 +902,7 @@ Both source and target must be absolute paths. If no mapping matches, the defaul
 
 ## Troubleshooting
 
-Run `ccc doctor` to diagnose common issues. It checks your settings, daemon health, embedding model, file matching, and index status — all in one command.
+Run `ccc doctor` to check your settings, daemon health, embedding model, file matching, and index status.
 
 ### `sqlite3.Connection object has no attribute enable_load_extension`
 
@@ -906,7 +914,7 @@ Some Python installations (e.g. the one pre-installed on macOS) ship with a SQLi
 brew install python3
 ```
 
-Then re-install cocoindex-code (see [Get Started](#get-started--zero-config-lets-go) for install options):
+Then re-install cocoindex-code (see [Get Started](#get-started) for install options):
 
 Using pipx:
 ```bash
@@ -921,7 +929,7 @@ uv tool install --upgrade cocoindex-code
 
 ### `MDB_MAP_FULL: Environment mapsize limit reached`
 
-The index is stored in an LMDB database whose maximum size is fixed when the daemon starts. The default ceiling is **4 GiB**, which is plenty for most projects but can be exhausted by very large codebases (tens of thousands of files), especially with high-dimensional embedding models like `nomic-ai/CodeRankEmbed`.
+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`.
 
 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:
 
@@ -971,15 +979,15 @@ export COCOINDEX_DISABLE_USAGE_TRACKING=1
 ```
 
 ## Large codebase / Enterprise
-[CocoIndex](https://github.com/cocoindex-io/cocoindex) is an ultra efficient indexing engine that also works on large codebases at scale for enterprises. In enterprise scenarios it is a lot more efficient to share indexes with teammates when there are large or many repos. We also have advanced features like branch dedupe etc designed for enterprise users.
+Teams indexing large or multiple repositories can share [CocoIndex](https://github.com/cocoindex-io/cocoindex) indexes across developers. Enterprise features include deduplication across branches.
 
-> Indexing a very large codebase and hitting `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.
+> 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.
 
-If you need help with remote setup, please email our maintainer linghua@cocoindex.io, happy to help!
+For help with remote setup, email linghua@cocoindex.io.
 
 ## Contributing
 
-We welcome contributions! This project uses [uv](https://docs.astral.sh/uv/getting-started/installation/) for development, and every PR is gated on the same lint, format, type-check, and test suite in CI. **Please run these checks locally before opening a PR** — failing pre-commit checks are the most common cause of red CI on incoming PRs.
+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.
 
 ### 1. Install the dev dependencies
 

{cocoindex_code-0.2.42 → cocoindex_code-0.2.43}/src/cocoindex_code/_daemon_paths.py

@@ -14,6 +14,7 @@ import tempfile
 import time
 from dataclasses import dataclass
 from pathlib import Path
+from typing import NamedTuple
 
 from .settings import user_settings_dir
 
@@ -79,6 +80,45 @@ def daemon_socket_path() -> str:
     return str(short)
 
 
+class SocketIdentity(NamedTuple):
+    """Identifies one socket file, telling a daemon's own apart from one a
+    replacement daemon has since bound at the same path (issue #288).
+
+    ``ctime_ns`` is part of it because ext4/overlayfs hand a freed inode
+    number straight to the next file: once the original socket is closed and
+    unlinked, a replacement's can have the same ``(dev, ino)``.
+    """
+
+    dev: int
+    ino: int
+    ctime_ns: int
+
+
+def socket_identity(path: str) -> SocketIdentity | None:
+    """Return the identity of the socket file at *path*, or None if absent. POSIX only."""
+    try:
+        st = os.stat(path)
+    except OSError:
+        return None
+    return SocketIdentity(st.st_dev, st.st_ino, st.st_ctime_ns)
+
+
+def unlink_socket_if_owned(path: str, identity: SocketIdentity | None) -> None:
+    """Remove the socket file at *path* only if it is still *identity*.
+
+    Leaves alone a socket a replacement daemon has bound there since. Not
+    atomic — POSIX has no unlink-if-inode — so a replacement binding between
+    the stat and the unlink is still lost, but that window is microseconds.
+    Best-effort — never raises.
+    """
+    if identity is None or socket_identity(path) != identity:
+        return
+    try:
+        os.unlink(path)
+    except OSError:
+        pass
+
+
 def daemon_pid_path() -> Path:
     """Return the path for the daemon's PID file."""
     return daemon_runtime_dir() / "daemon.pid"

{cocoindex_code-0.2.42 → cocoindex_code-0.2.43}/src/cocoindex_code/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.42'
-__version_tuple__ = version_tuple = (0, 2, 42)
+__version__ = version = '0.2.43'
+__version_tuple__ = version_tuple = (0, 2, 43)
 
 __commit_id__ = commit_id = None

cocoindex_code-0.2.43/src/cocoindex_code/chunking.py

@@ -0,0 +1,54 @@
+"""Public API for writing custom chunkers.
+
+Example usage::
+
+    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)]
+"""
+
+from __future__ import annotations
+
+import dataclasses as _dataclasses
+import pathlib as _pathlib
+from collections.abc import Callable as _Callable
+
+import cocoindex as _coco
+from cocoindex.resources.chunk import Chunk, TextPosition
+
+# Callable alias (not Protocol) — consistent with codebase style.
+# language_override=None keeps the language detected by detect_code_language.
+# path is not resolved (no syscall); call path.resolve() inside the chunker if needed.
+ChunkerFn = _Callable[[_pathlib.Path, str], tuple[str | None, list[Chunk]]]
+
+
+@_dataclasses.dataclass(frozen=True)
+class LoadedChunker:
+    """A chunker the daemon imported from a ``settings.yml`` entry.
+
+    Its memo key is ``(spec, module_sha256)``, never ``fn`` itself: cocoindex
+    fingerprints a function by its module and name only, so an edit to its body
+    would go unnoticed, and it cannot fingerprint lambdas or closures at all.
+    """
+
+    fn: ChunkerFn
+    #: The ``"module.path:callable"`` string from ``settings.yml``.
+    spec: str
+    #: sha256 of the module file named in ``spec``, as it was when imported. Helper
+    #: modules that file imports are not covered.
+    module_sha256: str
+
+    def __coco_memo_key__(self) -> tuple[str, str]:
+        return (self.spec, self.module_sha256)
+
+
+# Keyed by file suffix (e.g. ".toml"). Adding, removing or changing an entry
+# re-processes all files.
+CHUNKER_REGISTRY = _coco.ContextKey[dict[str, LoadedChunker]](
+    "chunker_registry", detect_change=True
+)
+
+__all__ = ["Chunk", "ChunkerFn", "CHUNKER_REGISTRY", "LoadedChunker", "TextPosition"]

{cocoindex_code-0.2.42 → cocoindex_code-0.2.43}/src/cocoindex_code/cli.py

@@ -26,6 +26,7 @@ from ._version import __version__
 from .settings import (
     DEFAULT_ST_MODEL,
     EmbeddingSettings,
+    auto_init_refusal,
     cocoindex_db_path,
     default_project_settings,
     find_parent_with_marker,
@@ -38,6 +39,7 @@ from .settings import (
     save_project_settings,
     target_sqlite_db_path,
     user_settings_path,
+    user_settings_root_note,
 )
 
 app = _typer.Typer(
@@ -81,13 +83,19 @@ def _apply_host_cwd() -> None:
 def require_project_root(*, auto_init: bool = False) -> Path:
     """Find the project root by walking up from CWD.
 
-    Checks global settings first (more fundamental), then project settings.
+    Reports missing global settings before a missing project (more fundamental).
     With ``auto_init``, a missing project is initialized with default settings
-    instead of failing. Missing global settings run the same interactive model
+    instead of failing, unless that would be the user settings root (refused
+    first). Missing global settings run the same interactive model
     setup as ``ccc init`` — but only on a TTY, since picking an embedding model
     is a consequential choice; non-interactive runs (scripts, hooks, agents)
     still exit with code 1 rather than silently committing to a default model.
     """
+    cwd = Path.cwd()
+    root = find_project_root(cwd)
+    # Decide where auto-init would write, and whether it may, before the interactive
+    # model setup below, so a refusal never comes after a wasted prompt.
+    new_root = _auto_init_root(cwd) if root is None and auto_init else None
     gs_path = user_settings_path()
     if not gs_path.is_file():
         if auto_init and sys.stdin.isatty():
@@ -99,27 +107,39 @@ def require_project_root(*, auto_init: bool = False) -> Path:
                 err=True,
             )
             raise _typer.Exit(code=1)
-    root = find_project_root(Path.cwd())
+    if new_root is not None:
+        _create_project_settings(new_root)
+        return new_root
     if root is None:
-        if auto_init:
-            return _auto_init_project(Path.cwd())
         _typer.echo(
             "Error: Not in an initialized project directory.\n"
             "Run `ccc init` in your project root to get started.",
             err=True,
         )
         raise _typer.Exit(code=1)
+    _note_if_user_settings_root(root)
     return root
 
 
-def _auto_init_project(cwd: Path) -> Path:
-    """Create default project settings without an explicit ``ccc init``.
+def _note_if_user_settings_root(root: Path) -> None:
+    """Tell the user when a repo below the user settings root resolves to it."""
+    note = user_settings_root_note(root, Path.cwd())
+    if note is not None:
+        _typer.echo(f"Note: {note}", err=True)
+
+
+def _auto_init_root(cwd: Path) -> Path:
+    """Return where ``ccc index`` may create default project settings, or exit.
 
     Anchors at the nearest parent git root when there is one, so running from
     a repo subdirectory initializes the repo root rather than the subdirectory.
+    Never the user settings root (see ``auto_init_refusal``).
     """
     root = find_parent_with_marker(cwd) or cwd
-    _create_project_settings(root)
+    refusal = auto_init_refusal(root)
+    if refusal is not None:
+        _typer.echo(f"Error: {refusal}", err=True)
+        raise _typer.Exit(code=1)
     return root
 
 

{cocoindex_code-0.2.42 → cocoindex_code-0.2.43}/src/cocoindex_code/client.py

@@ -21,12 +21,15 @@ from typing import NamedTuple
 import msgspec
 
 from ._daemon_paths import (
+    SocketIdentity,
     connection_family,
     daemon_log_path,
     daemon_pid_path,
     daemon_runtime_dir,
     daemon_socket_path,
     read_last_exit_marker,
+    socket_identity,
+    unlink_socket_if_owned,
 )
 from ._version import __version__
 from .protocol import (
@@ -642,6 +645,9 @@ def stop_daemon() -> None:
             pid = None
     except (FileNotFoundError, ValueError):
         pass
+    # The socket file of the daemon being stopped. Cleanup removes only that
+    # one, never a replacement daemon's bound there meanwhile (issue #288).
+    sock_identity = socket_identity(daemon_socket_path()) if sys.platform != "win32" else None
 
     # 1) Graceful StopRequest via socket (bypass auto-start)
     try:
@@ -677,17 +683,17 @@ def stop_daemon() -> None:
         except (ProcessLookupError, PermissionError):
             pass
 
-    _cleanup_stale_files(pid_path, pid)
+    _cleanup_stale_files(pid_path, pid, sock_identity)
 
 
-def _cleanup_stale_files(pid_path: Path, pid: int | None) -> None:
-    """Remove socket and PID file after the daemon has exited."""
-    if sys.platform != "win32":
-        sock = daemon_socket_path()
-        try:
-            Path(sock).unlink(missing_ok=True)
-        except Exception:
-            pass
+def _cleanup_stale_files(
+    pid_path: Path, pid: int | None, sock_identity: SocketIdentity | None
+) -> None:
+    """Remove socket and PID file after the daemon has exited.
+
+    The socket file is removed only while it is still *sock_identity*.
+    """
+    unlink_socket_if_owned(daemon_socket_path(), sock_identity)
     if pid is not None:
         try:
             stored = pid_path.read_text().strip()

{cocoindex_code-0.2.42 → cocoindex_code-0.2.43}/src/cocoindex_code/daemon.py

@@ -3,19 +3,25 @@
 from __future__ import annotations
 
 import asyncio
+import contextvars
+import hashlib
 import importlib
 import logging
 import os
 import signal
+import socket
 import sys
 import threading
 import time
 import traceback
+import weakref
 from collections.abc import AsyncIterator, Callable
+from concurrent.futures import Future, ThreadPoolExecutor
 from datetime import timedelta
 from multiprocessing.connection import Client, Connection, Listener
 from pathlib import Path
-from typing import Any
+from types import ModuleType
+from typing import Any, ParamSpec, TypeVar
 
 from ._daemon_paths import (
     clear_last_exit_marker,
@@ -24,10 +30,12 @@ from ._daemon_paths import (
     daemon_pid_path,
     daemon_runtime_dir,
     daemon_socket_path,
+    socket_identity,
+    unlink_socket_if_owned,
     write_last_exit_marker,
 )
 from ._version import __version__
-from .chunking import ChunkerFn as _ChunkerFn
+from .chunking import LoadedChunker
 from .embedder_params import resolve_embedder_params
 from .project import Project
 from .protocol import (
@@ -99,22 +107,41 @@ def _build_backward_compat_warning(
     )
 
 
-def _resolve_chunker_registry(mappings: list[ChunkerMapping]) -> dict[str, _ChunkerFn]:
-    """Resolve ``ChunkerMapping`` settings entries to a ``{suffix: fn}`` dict.
+# sha256 of each chunker module's file, taken when the daemon first got the module.
+# importlib returns the already loaded module on later imports (another project, or
+# the same one after `ccc reset`), and that module still runs the code that was
+# loaded, whatever the file holds now.
+_chunker_module_sha256: weakref.WeakKeyDictionary[ModuleType, str] = weakref.WeakKeyDictionary()
+
+
+def _module_sha256(mod: ModuleType) -> str:
+    digest = _chunker_module_sha256.get(mod)
+    if digest is None:
+        # Builtin modules have no file; their code only changes with Python itself.
+        file = getattr(mod, "__file__", None)
+        digest = hashlib.sha256(Path(file).read_bytes()).hexdigest() if file else ""
+        _chunker_module_sha256[mod] = digest
+    return digest
+
+
+def _resolve_chunker_registry(mappings: list[ChunkerMapping]) -> dict[str, LoadedChunker]:
+    """Import the chunkers from ``ChunkerMapping`` settings entries, keyed by suffix.
 
     Each ``mapping.module`` must be a ``"module.path:callable"`` string importable
-    from the current environment.
+    from the current environment. Each chunker records that string and a hash of
+    the module file it names, which is what makes a chunker edit re-process files.
     """
-    registry: dict[str, _ChunkerFn] = {}
+    registry: dict[str, LoadedChunker] = {}
     for cm in mappings:
         module_path, _, attr = cm.module.partition(":")
         if not attr:
             raise ValueError(f"chunker module {cm.module!r} must use 'module.path:callable' format")
         mod = importlib.import_module(module_path)
+        module_sha256 = _module_sha256(mod)
         fn = getattr(mod, attr)
         if not callable(fn):
             raise ValueError(f"chunker {cm.module!r}: {attr!r} is not callable")
-        registry[f".{cm.ext}"] = fn
+        registry[f".{cm.ext}"] = LoadedChunker(fn, spec=cm.module, module_sha256=module_sha256)
     return registry
 
 
@@ -161,13 +188,12 @@ class ProjectRegistry:
         if project_root not in self._projects:
             root = Path(project_root)
             project_settings = load_project_settings(root)
-            chunker_registry = _resolve_chunker_registry(project_settings.chunkers)
             project = await Project.create(
                 root,
                 self._embedder,
                 indexing_params=self.indexing_params,
                 query_params=self.query_params,
-                chunker_registry=chunker_registry,
+                chunker_registry=_resolve_chunker_registry(project_settings.chunkers),
                 clear_mps_cache_after_index=self._clear_mps_cache_after_index,
             )
             self._projects[project_root] = project
@@ -613,6 +639,77 @@ async def _dispatch(
 # Daemon main
 # ---------------------------------------------------------------------------
 
+_P = ParamSpec("_P")
+_T = TypeVar("_T")
+
+
+class EmptyContextThreadPoolExecutor(ThreadPoolExecutor):
+    """Thread pool whose worker threads start in an empty ``contextvars`` context.
+
+    ``submit()`` starts a worker thread when no idle one is free. On free-threaded
+    Python 3.14 (``sys.flags.thread_inherit_context``) that thread starts in a copy
+    of the submitter's context and keeps it for its whole life. A copy taken inside
+    a CocoIndex component references the project's CocoIndex environment, which is
+    only released once nothing references it, so it would outlive the project and
+    opening the project again in this process (as after ``ccc reset``) would fail.
+    Submitting from an empty context gives worker threads the empty context they
+    start with on GIL builds.
+    """
+
+    def submit(self, fn: Callable[_P, _T], /, *args: _P.args, **kwargs: _P.kwargs) -> Future[_T]:
+        return contextvars.Context().run(super().submit, fn, *args, **kwargs)
+
+
+if sys.platform != "win32":  # Windows uses named pipes via Listener
+
+    class _UnixListener:
+        """POSIX stand-in for ``multiprocessing.connection.Listener`` that removes
+        its socket file on ``close()`` only while the path still names it.
+
+        The stdlib listener unlinks its address on ``close()`` unconditionally, so
+        a displaced daemon shutting down would delete the socket a replacement
+        daemon had since bound at the same path, cutting clients off from it
+        (issue #288).
+        """
+
+        def __init__(self, path: str) -> None:
+            # Take over the path from a crashed or displaced daemon's socket file,
+            # which would otherwise make bind() fail.
+            try:
+                os.unlink(path)
+            except FileNotFoundError:
+                pass
+            self._path = path
+            self._sock = socket.socket(socket.AF_UNIX)
+            try:
+                self._sock.setblocking(True)
+                self._sock.bind(path)
+                self._sock.listen(1)  # same backlog as the stdlib Listener
+            except OSError:
+                self._sock.close()
+                raise
+            # A replacement binding the path in the instant between bind() and
+            # this stat would be recorded as ours; bind() itself can't report the
+            # file's identity, and the window is microseconds.
+            self._identity = socket_identity(path)
+
+        def accept(self) -> Connection:
+            conn, _ = self._sock.accept()
+            conn.setblocking(True)
+            return Connection(conn.detach())
+
+        def close(self) -> None:
+            # Unlink while the socket is still open: an open socket pins its
+            # inode, so a replacement's file can't have been given the same one.
+            unlink_socket_if_owned(self._path, self._identity)
+            # On Linux only shutdown() wakes a thread blocked in accept(); macOS
+            # wakes it on close() and rejects shutdown() of a listening socket.
+            try:
+                self._sock.shutdown(socket.SHUT_RDWR)
+            except OSError:
+                pass
+            self._sock.close()
+
 
 def run_daemon(
     *,
@@ -695,16 +792,14 @@ def run_daemon(
     )
 
     sock_path = daemon_socket_path()
-    if sys.platform != "win32":
-        try:
-            Path(sock_path).unlink(missing_ok=True)
-        except Exception:
-            pass
-
-    listener = Listener(sock_path, family=connection_family())
+    if sys.platform == "win32":
+        listener = Listener(sock_path, family=connection_family())
+    else:
+        listener = _UnixListener(sock_path)
     logger.info("Listening on %s", sock_path)
 
     loop = asyncio.new_event_loop()
+    loop.set_default_executor(EmptyContextThreadPoolExecutor())
     tasks: set[asyncio.Task[Any]] = set()
 
     reaper = IdleReaper(
@@ -816,14 +911,17 @@ def run_daemon(
         #    absence is how the client detects a crash.
         write_last_exit_marker(pid=os.getpid(), reason=shutdown_reason or "unknown")
 
-        # 1. Stop accepting new connections.  On Windows a blocked accept()
-        #    holds an open pipe instance that listener.close() can't release
-        #    (it only closes the queued next-instance handle), which would keep
-        #    the named pipe alive after exit — wake it with a dummy connection
-        #    so the accept thread closes it and exits.  POSIX doesn't need the
-        #    wake-up (listener.close() makes accept() raise), but it's harmless
-        #    there and keeps this path exercised on every platform rather than
-        #    only on Windows CI.
+        # 1. Stop accepting new connections and remove the socket file (if a
+        #    replacement daemon hasn't taken over the path).  On Windows a
+        #    blocked accept() holds an open pipe instance that listener.close()
+        #    can't release (it only closes the queued next-instance handle),
+        #    which would keep the named pipe alive after exit — wake it with a
+        #    dummy connection so the accept thread closes it and exits.  POSIX
+        #    doesn't need the wake-up (listener.close() makes accept() raise),
+        #    but it's harmless there and keeps this path exercised on every
+        #    platform rather than only on Windows CI.  If a replacement daemon
+        #    owns the path, the wake-up reaches it instead: one extra
+        #    connection, which only counts as activity there.
         shutting_down.set()
         try:
             Client(sock_path, family=connection_family()).close()
@@ -843,12 +941,7 @@ def run_daemon(
         registry.close_all()
         loop.close()
 
-        # 4. Remove socket and PID file.
-        if sys.platform != "win32":
-            try:
-                Path(sock_path).unlink(missing_ok=True)
-            except Exception:
-                pass
+        # 4. Remove the PID file.
         try:
             stored = pid_path.read_text().strip()
             if stored == str(os.getpid()):

{cocoindex_code-0.2.42 → cocoindex_code-0.2.43}/src/cocoindex_code/indexer.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from collections.abc import Mapping
 from pathlib import Path
 
 import cocoindex as coco
@@ -35,8 +36,13 @@ splitter = RecursiveSplitter()
 async def process_file(
     file: localfs.File,
     table: sqlite.TableTarget[CodeChunk],
+    language_overrides: Mapping[str, str],
 ) -> None:
-    """Process a single file: chunk, embed, and store."""
+    """Process a single file: chunk, embed, and store.
+
+    ``language_overrides`` maps a file suffix (``".inc"``) to a language. It is an
+    argument rather than read from settings here so that it is part of the memo key.
+    """
     embedder = coco.use_context(EMBEDDER)
     indexing_params = coco.use_context(INDEXING_EMBED_PARAMS)
 
@@ -49,11 +55,8 @@ async def process_file(
         return
 
     suffix = file.file_path.path.suffix
-    project_root = coco.use_context(CODEBASE_DIR)
-    ps = load_project_settings(project_root)
-    ext_lang_map = {f".{lo.ext}": lo.lang for lo in ps.language_overrides}
     language = (
-        ext_lang_map.get(suffix)
+        language_overrides.get(suffix)
         or detect_code_language(filename=file.file_path.path.name)
         or "text"
     )
@@ -61,7 +64,7 @@ async def process_file(
     chunker_registry = coco.use_context(CHUNKER_REGISTRY)
     chunker = chunker_registry.get(suffix)
     if chunker is not None:
-        language_override, chunks = chunker(Path(file.file_path.path), content)
+        language_override, chunks = chunker.fn(Path(file.file_path.path), content)
         if language_override is not None:
             language = language_override
     else:
@@ -120,6 +123,11 @@ async def indexer_main() -> None:
         path_matcher=matcher,
     )
 
+    language_overrides = {f".{lo.ext}": lo.lang for lo in ps.language_overrides}
     await coco.mount_each(
-        coco.component_subpath(coco.Symbol("process_file")), process_file, files.items(), table
+        coco.component_subpath(coco.Symbol("process_file")),
+        process_file,
+        files.items(),
+        table,
+        language_overrides,
     )

{cocoindex_code-0.2.42 → cocoindex_code-0.2.43}/src/cocoindex_code/project.py

@@ -3,16 +3,19 @@
 from __future__ import annotations
 
 import asyncio
+import contextvars
 import logging
 import sqlite3
-from collections.abc import AsyncIterator, Callable
+import weakref
+from collections.abc import AsyncIterator, Callable, Mapping
+from concurrent.futures import Future, ThreadPoolExecutor
 from pathlib import Path
-from typing import Any
+from typing import Any, ParamSpec, TypeVar
 
 import cocoindex as coco
 from cocoindex.connectors import sqlite as coco_sqlite
 
-from .chunking import CHUNKER_REGISTRY, ChunkerFn
+from .chunking import CHUNKER_REGISTRY, LoadedChunker
 from .indexer import indexer_main
 from .protocol import (
     IndexingProgress,
@@ -45,6 +48,36 @@ from .shared import (
 
 logger = logging.getLogger(__name__)
 
+_P = ParamSpec("_P")
+_T = TypeVar("_T")
+
+
+class _EmptyContextThreadPoolExecutor(ThreadPoolExecutor):
+    """A ``ThreadPoolExecutor`` whose worker threads start with an empty context.
+
+    On free-threaded Python a new thread starts with a copy of the context of the code
+    that started it (``sys.flags.thread_inherit_context``). The event loop's default
+    executor starts its workers lazily, often inside a CocoIndex component (the LocalFS
+    walker calls ``run_in_executor``). Such a worker keeps that component's context, which
+    references the project's ``Environment`` and through it the LMDB env, for as long as
+    the loop lives. The env then stays open after the project is closed, and loading the
+    project again fails with "environment already open in this program".
+    """
+
+    def submit(self, fn: Callable[_P, _T], /, *args: _P.args, **kwargs: _P.kwargs) -> Future[_T]:
+        # Worker threads are started from submit().
+        return contextvars.Context().run(super().submit, fn, *args, **kwargs)
+
+
+# Loops whose default executor is already an _EmptyContextThreadPoolExecutor.
+_loops_with_empty_context_executor: weakref.WeakSet[asyncio.AbstractEventLoop] = weakref.WeakSet()
+
+
+def _use_empty_context_default_executor(loop: asyncio.AbstractEventLoop) -> None:
+    if loop not in _loops_with_empty_context_executor:
+        loop.set_default_executor(_EmptyContextThreadPoolExecutor(thread_name_prefix="asyncio"))
+        _loops_with_empty_context_executor.add(loop)
+
 
 class Project:
     _env: coco.Environment
@@ -281,7 +314,7 @@ class Project:
         embedder: Embedder,
         indexing_params: dict[str, Any],
         query_params: dict[str, Any],
-        chunker_registry: dict[str, ChunkerFn] | None = None,
+        chunker_registry: Mapping[str, LoadedChunker] | None = None,
         clear_mps_cache_after_index: bool = False,
     ) -> Project:
         """Create a project with explicit embedder and per-call params.
@@ -299,7 +332,7 @@ class Project:
             query_params: Extra kwargs spread into ``embedder.embed()`` for the
                 query side.
             chunker_registry: Optional mapping of file suffix (e.g. ``".toml"``)
-                to a ``ChunkerFn``. When a suffix matches, the registered
+                to a ``LoadedChunker``. When a suffix matches, the registered
                 chunker is called instead of the built-in splitter.
             clear_mps_cache_after_index: Whether to release unused MPS allocator
                 memory in CocoIndex's GPU subprocess after each index run.
@@ -315,6 +348,10 @@ class Project:
 
         settings = coco.Settings.from_env(cocoindex_db)
 
+        # The environment runs its components on the running loop. Keep that loop's
+        # executor threads from holding on to the environment once this project is closed.
+        _use_empty_context_default_executor(asyncio.get_running_loop())
+
         context = coco.ContextProvider()
         context.provide(CODEBASE_DIR, project_root)
         context.provide(SQLITE_DB, coco_sqlite.connect(str(target_sqlite_db), load_vec=True))

{cocoindex_code-0.2.42 → cocoindex_code-0.2.43}/src/cocoindex_code/server.py

@@ -18,7 +18,7 @@ from mcp.server.mcpserver import MCPServer
 from pydantic import BaseModel, Field
 
 from ._version import __version__
-from .settings import DaemonSettings, load_user_settings
+from .settings import DaemonSettings, load_user_settings, user_settings_root_note
 
 _MCP_INSTRUCTIONS = (
     "Code search and codebase understanding tools."
@@ -56,6 +56,13 @@ class SearchResultModel(BaseModel):
     message: str | None = None
 
 
+def _with_note(message: str | None, note: str | None) -> str | None:
+    """Append *note* to a result message; MCP clients hide the server's stderr."""
+    if note is None:
+        return message
+    return f"{message}\nNote: {note}" if message else f"Note: {note}"
+
+
 # === Daemon-backed MCP server factory ===
 
 
@@ -125,7 +132,9 @@ def create_mcp_server(project_root: str) -> MCPServer:
         from . import client as _client
 
         loop = asyncio.get_event_loop()
+        note: str | None = None
         try:
+            note = user_settings_root_note(Path(project_root), Path.cwd())
             if refresh_index:
                 await loop.run_in_executor(None, lambda: _client.index(project_root))
             resp = await loop.run_in_executor(
@@ -154,10 +163,12 @@ def create_mcp_server(project_root: str) -> MCPServer:
                 ],
                 total_returned=resp.total_returned,
                 offset=resp.offset,
-                message=resp.message,
+                message=_with_note(resp.message, note),
             )
         except Exception as e:
-            return SearchResultModel(success=False, message=f"Query failed: {e!s}")
+            return SearchResultModel(
+                success=False, message=_with_note(f"Query failed: {e!s}", note)
+            )
 
     return mcp
 
@@ -225,10 +236,12 @@ def main() -> None:
     Auto-detects/creates settings from env vars, then delegates to daemon.
     """
     import argparse
+    import sys
 
     from .settings import (
         EmbeddingSettings,
         LanguageOverride,
+        auto_init_refusal,
         default_project_settings,
         default_user_settings,
         find_legacy_project_root,
@@ -251,12 +264,14 @@ def main() -> None:
     # --- Discover project root ---
     cwd = Path.cwd()
     project_root = find_project_root(cwd)
+    root_from_env = False
 
     if project_root is None:
         # Try env var
         env_root = os.environ.get("COCOINDEX_CODE_ROOT_PATH")
         if env_root:
             project_root = Path(env_root).resolve()
+            root_from_env = True
         else:
             # Use marker-based discovery
             legacy_root = find_legacy_project_root(cwd)
@@ -265,6 +280,14 @@ def main() -> None:
     # --- Auto-create project settings if needed ---
     proj_settings_file = project_settings_path(project_root)
     if not proj_settings_file.is_file():
+        # COCOINDEX_CODE_ROOT_PATH is a deliberate choice, like `ccc init`: only a
+        # root found by discovery is refused.
+        refusal = None if root_from_env else auto_init_refusal(project_root)
+        if refusal is not None:
+            sys.exit(
+                f"Error: {refusal} To serve a project from here, set"
+                " COCOINDEX_CODE_ROOT_PATH to its directory."
+            )
         ps = default_project_settings()
 
         # Migrate COCOINDEX_CODE_EXCLUDED_PATTERNS
@@ -320,8 +343,6 @@ def main() -> None:
     from .protocol import IndexingProgress
 
     if args.command == "index":
-        import sys
-
         from rich.console import Console
         from rich.live import Live
         from rich.spinner import Spinner

{cocoindex_code-0.2.42 → cocoindex_code-0.2.43}/src/cocoindex_code/settings.py

@@ -354,6 +354,54 @@ def project_settings_path(project_root: Path) -> Path:
     return project_root / _SETTINGS_DIR_NAME / _SETTINGS_FILE_NAME
 
 
+def is_user_settings_root(directory: Path) -> bool:
+    """Return whether *directory*'s ``.cocoindex_code`` is the user settings dir.
+
+    That is ``$HOME`` by default, ``/x`` with ``COCOINDEX_CODE_DIR=/x/.cocoindex_code``
+    (the Docker image's layout), and no directory with ``COCOINDEX_CODE_DIR=/x/ccc``.
+    A project there covers every directory below it, so ccc never creates one
+    automatically; ``ccc init`` run there by hand still does.
+    """
+    return (directory / _SETTINGS_DIR_NAME).resolve() == user_settings_dir().resolve()
+
+
+def auto_init_refusal(directory: Path) -> str | None:
+    """Return why *directory* must not be initialized automatically, or ``None``."""
+    if not is_user_settings_root(directory):
+        return None
+    shown = format_path_for_display(directory)
+    return (
+        f"{shown} has no project settings, and ccc does not create them there"
+        f" automatically: its {_SETTINGS_DIR_NAME} directory is ccc's user settings"
+        " directory, so a project there would cover every directory below it."
+        " Run ccc from inside a project instead. To index all of"
+        f" {shown}, run `ccc init` there."
+    )
+
+
+def user_settings_root_note(root: Path, start: Path) -> str | None:
+    """Explain why a repo containing *start* resolves to the user settings root.
+
+    Such a project is usually left over from an older ccc that auto-initialized
+    ``$HOME``: every repo below it without settings of its own resolves to it.
+    Returns ``None`` unless *root* is the user settings root and *start* lies in
+    a repo below it.
+    """
+    if not is_user_settings_root(root):
+        return None
+    repo = find_parent_with_marker(start)
+    if repo is None or repo == root:
+        return None
+    shown_root = format_path_for_display(root)
+    shown_repo = format_path_for_display(repo)
+    return (
+        f"{shown_repo} has no ccc project of its own, so the project in use is"
+        f" {shown_root}, whose .cocoindex_code directory is also ccc's user settings"
+        f" directory. If {shown_root} is not meant to be a project, run"
+        f" `ccc reset --all` there, then `ccc init` in {shown_repo}."
+    )
+
+
 def find_project_root(start: Path) -> Path | None:
     """Walk up from *start* looking for ``.cocoindex_code/settings.yml``.
 

{cocoindex_code-0.2.42 → cocoindex_code-0.2.43}/src/cocoindex_code/shared.py

@@ -37,7 +37,8 @@ Embedder = Union[
 EMBEDDER = coco.ContextKey[Embedder]("embedder", detect_change=True)
 SQLITE_DB = coco.ContextKey[sqlite.ManagedConnection]("index_db")
 CODEBASE_DIR = coco.ContextKey[pathlib.Path]("codebase")
-INDEXING_EMBED_PARAMS = coco.ContextKey[dict[str, Any]]("indexing_embed_params")
+INDEXING_EMBED_PARAMS = coco.ContextKey[dict[str, Any]]("indexing_embed_params", detect_change=True)
+# Read only at query time, outside any memoized function: nothing to invalidate.
 QUERY_EMBED_PARAMS = coco.ContextKey[dict[str, Any]]("query_embed_params")
 
 

cocoindex_code-0.2.42/src/cocoindex_code/chunking.py

@@ -1,29 +0,0 @@
-"""Public API for writing custom chunkers.
-
-Example usage::
-
-    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)]
-"""
-
-from __future__ import annotations
-
-import pathlib as _pathlib
-from collections.abc import Callable as _Callable
-
-import cocoindex as _coco
-from cocoindex.resources.chunk import Chunk, TextPosition
-
-# Callable alias (not Protocol) — consistent with codebase style.
-# language_override=None keeps the language detected by detect_code_language.
-# path is not resolved (no syscall); call path.resolve() inside the chunker if needed.
-ChunkerFn = _Callable[[_pathlib.Path, str], tuple[str | None, list[Chunk]]]
-
-# tracked=False: callables are not fingerprint-able; daemon restart re-indexes anyway.
-CHUNKER_REGISTRY = _coco.ContextKey[dict[str, ChunkerFn]]("chunker_registry")
-
-__all__ = ["Chunk", "ChunkerFn", "CHUNKER_REGISTRY", "TextPosition"]