### Read Concept Guide Hint

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

Follows a '[guide]' hint from search results to read a curated concept guide. Use this command when prompted by search output.

```bash
ccc guide <slug>
```

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

### List Available Guides

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

Use this command to list all available concept guides and their descriptions within the project. Run this when first orienting in an unfamiliar codebase.

```bash
ccc guide
```

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

### Guides YAML Schema Example

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

An example of the `.cocoindex_code/guides.yml` file structure. It includes default settings and a guide entry with a slug, description, and optional dependencies.

```yaml
defaults:
  enabled: true                     # disables all guides when false
  model: openai/gpt-5.4-nano        # falls back to summary.model when omitted
  session_budget: 200
  max_logical_depth: 3
  max_turns_per_session: 18

guides:
  - slug: memoization                          # [a-z0-9][a-z0-9-]*
    description: |
      What this guide covers, framed for the reader.
      Name the canonical starting files (e.g. "start with src/cache.py").
    deps: [other-slug]                         # optional; must not cycle
    max_turns_per_session: 28                  # optional per-entry overrides
```

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

### CLI Usage Examples

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/cli.md

Examples demonstrating how to use the `ccc` command and its subcommands for various operations.

```bash
ccc --help
```

```bash
ccc init --help
```

```bash
ccc init
```

```bash
ccc init --litellm-model "text-embedding-3-small"
```

```bash
ccc index
```

```bash
ccc search "your query"
```

```bash
ccc search authentication middleware
```

```bash
ccc search --lang python --lang typescript database connection
```

```bash
ccc search --path "src/utils/*" helper function
```

```bash
ccc search --offset 10 --limit 5 query handler
```

```bash
ccc search --refresh error handling
```

```bash
ccc status
```

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

### Complete Project Setup Flow

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/shared.md

An asynchronous function demonstrating the complete setup process for a project, including loading settings, creating an embedder, testing it, and initializing the Project object.

```python
import asyncio
from pathlib import Path
from cocoindex_code.shared import create_embedder, check_embedding
from cocoindex_code.settings import load_user_settings, load_project_settings
from cocoindex_code.project import Project

async def setup_project(project_root: Path):
    # Load settings
    user_settings = load_user_settings()
    project_settings = load_project_settings(project_root)
    
    # Create embedder
    embedder = create_embedder(user_settings.embedding)
    
    # Test embedder
    check = await check_embedding(embedder)
    if check.error:
        print(f"Embedding check failed: {check.error}")
        return None
    
    print(f"Embedding dimension: {check.dim}")
    
    # Create project
    from cocoindex_code.embedder_params import resolve_embedder_params
    params = resolve_embedder_params(user_settings.embedding)
    
    project = await Project.create(
        project_root=project_root,
        embedder=embedder,
        indexing_params=params.indexing,
        query_params=params.query,
    )
    
    return project

# Usage
project = asyncio.run(setup_project(Path("/path/to/project")))
```

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

### Global Settings Example

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

Example configuration for global settings, including embedding provider details and environment variables like API keys and base URLs.

```yaml
# ~/.cocoindex/global_settings.yml
embedding:
  provider: litellm
  model: text-embedding-3-small
  min_interval_ms: 50
  indexing_params:
    input_type: passage
  query_params:
    input_type: query

envs:
  OPENAI_API_KEY: sk-proj-...
  OPENAI_API_BASE: https://api.openai.com/v1
```

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

### Example Search Queries

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

Illustrative examples of search queries for common development tasks. These queries describe concepts rather than specific code syntax.

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

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

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

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

### Install Pre-commit Hooks

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

Install and enable pre-commit hooks for linting, formatting, type checking, and tests before each commit. This helps catch common issues early.

```bash
pip install pre-commit
pre-commit install
```

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

### Indexing Flow Example

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/protocol.md

Illustrates the sequence of requests and responses for the indexing process between client and daemon.

```text
Client                              Daemon
  |---- HandshakeRequest -------->  |
  |  <---- HandshakeResponse ----  |
  |---- IndexRequest ----------->  |
  |  <---- IndexWaitingNotice ---- |
  |  <---- IndexProgressUpdate --- |
  |  <---- IndexResponse --------  |
```

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

### Example Project Settings Configuration

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/settings.md

Demonstrates the structure of project-specific settings YAML, including include/exclude patterns, language overrides, and custom chunkers.

```yaml
include_patterns:
  - '**/*.py'
  - '**/*.ts'
  - '**/*.tsx'

exclude_patterns:
  - '**/.*'
  - '**/__pycache__'
  - '**/node_modules'

language_overrides:
  - ext: inc
    lang: php

chunkers:
  - ext: toml
    module: my_module:custom_toml_chunker
```

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

### Docker Compose Quick Start (macOS/Windows)

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

Use this command to quickly set up CocoIndex Code with Docker Compose on macOS or Windows. It fetches the compose file and starts the services in detached mode.

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

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

### Typer CLI Application Setup

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

Demonstrates the basic structure of a Typer CLI application, including defining commands, options, and arguments.

```python
import typer
from typing import Annotated

app = typer.Typer()

@app.command()
def main(
    name: Annotated[str, typer.Option("--name", "-n", help="The name to greet.")] = "World",
    formal: Annotated[bool, typer.Option("--formal", help="Use a formal greeting.")] = False,
):
    """A simple CLI app with Typer.
    """
    if formal:
        print(f"Hello Mr. {name}")
    else:
        print(f"Hello {name}")

if __name__ == "__main__":
    app()

```

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

### Install CocoIndex Code

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

Installs CocoIndex Code using pipx. Use '[full]' for local embeddings or the slim install for LiteLLM-only integration with cloud providers.

```bash
pipx install 'cocoindex-code[full]'
```

```bash
pipx install cocoindex-code
```

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

### Search Flow Example

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/protocol.md

Illustrates the sequence of requests and responses for a search operation between client and daemon.

```text
Client                              Daemon
  |---- HandshakeRequest -------->  |
  |  <---- HandshakeResponse ----  |
  |---- SearchRequest ----------->  |
  |  <---- IndexWaitingNotice ---- |
  |  <---- SearchResponse --------  |
```

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

### start_daemon

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/client.md

Start the cocoindex daemon as a background process.

```APIDOC
## start_daemon

### Description
Start the daemon as a background process.

Launches a new daemon process in the background with stdout/stderr redirected to the log file. The daemon listens on a Unix socket (or named pipe on Windows).

### Method
```python
def start_daemon() -> subprocess.Popen[bytes]
```

### Return Type
`subprocess.Popen[bytes]` — The process object; caller can detect early exit via `proc.poll()`

### Throws
- `OSError` — If the daemon process fails to start

### Example
```python
from cocoindex_code.client import start_daemon, _wait_for_daemon

proc = start_daemon()
_wait_for_daemon(proc=proc, timeout=30.0)
print("Daemon started")
```
```

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

### Install CocoIndex-code with full dependencies

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

Install the 'cocoindex-code' package with all dependencies, including those for local embeddings. This is recommended for a batteries-included experience.

```bash
pipx install 'cocoindex-code[full]'
```

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

### Example User Settings Configuration

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/settings.md

Illustrates the structure of the global user settings YAML file, including embedding and environment variable configurations.

```yaml
embedding:
  provider: sentence-transformers
  model: Snowflake/snowflake-arctic-embed-xs
  device: null
  min_interval_ms: null
  indexing_params: null
  query_params: null

envs:
  # Optional API keys and env vars
  OPENAI_API_KEY: sk-...
```

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

### Example: Simple Custom Chunker

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/chunking.md

An example of a simple custom chunker function that chunks a file by line.

```APIDOC
## Example: Simple Custom Chunker

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

def simple_line_chunker(path: Path, content: str) -> tuple[str | None, list[Chunk]]:
    """Chunk a file by line, one chunk per line."""
    chunks = []
    char_offset = 0
    
    for line_num, line in enumerate(content.split('\n'), start=1):
        if not line.strip():  # Skip empty lines
            char_offset += len(line) + 1
            continue
        
        start = TextPosition(
            byte_offset=char_offset,
            char_offset=char_offset,
            line=line_num,
            column=0
        )
        
        char_offset += len(line) + 1
        
        end = TextPosition(
            byte_offset=char_offset - 1,
            char_offset=char_offset - 1,
            line=line_num,
            column=len(line)
        )
        
        chunks.append(Chunk(
            text=line,
            start=start,
            end=end
        ))
    
    # None means use auto-detected language
    return None, chunks

# Type annotation for clarity
custom_chunker: ChunkerFn = simple_line_chunker
```
```

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

### Install CocoIndex-code using uv

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

Install or upgrade the 'cocoindex-code' package using the 'uv' tool. This command ensures the latest version is installed with full dependencies.

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

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

### Run `mcp` Command

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/cli.md

Starts the MCP server in stdio mode.

```bash
ccc mcp
```

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

### Missing Settings File Error Example

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

Illustrates the error message when global settings files are not found. This typically occurs if `ccc init` has not been run or if the files were deleted.

```bash
$ ccc search "query"
Error: Global settings not found: ~/.cocoindex/global_settings.yml
Run `ccc init` to create it with default settings.
```

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

### Example Usage of CodeChunk and QueryResult

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/schema.md

Demonstrates how to instantiate and use CodeChunk for indexing and QueryResult for displaying search results. Includes creating objects and printing formatted output.

```python
from cocoindex_code.schema import CodeChunk, QueryResult
import numpy as np

# Creating a CodeChunk during indexing
chunk = CodeChunk(
    id=12345,
    file_path="src/auth.py",
    language="python",
    content="def authenticate(user, password):\n    return verify(user, password)",
    start_line=42,
    end_line=43,
    embedding=np.array([0.1, 0.2, 0.3, ...], dtype=np.float32)
)

# Creating a QueryResult from search
result = QueryResult(
    file_path="src/auth.py",
    language="python",
    content="def authenticate(user, password):\n    return verify(user, password)",
    start_line=42,
    end_line=43,
    score=0.95
)

# Display to user
print(f"{result.file_path}:{result.start_line}-{result.end_line}")
print(f"Score: {result.score:.3f}")
print(result.content)
```

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

### Run MCP Server

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/cli.md

Starts the MCP server in stdio mode, listening on stdin/stdout. This command is used when configured as an MCP server with agents.

```python
@app.command()
def mcp() -> None:
    pass
```

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

### Install cocoindex-code with pipx

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

Install or upgrade cocoindex-code using pipx. This is a recommended method for managing Python CLI tools.

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

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

### IndexRequest

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/protocol.md

Request to start or refresh indexing for a project.

```APIDOC
## IndexRequest

### Description
Request to start or refresh indexing for a project.

### Method
N/A (IPC Message)

### Endpoint
N/A (IPC Message)

### Parameters
#### Request Body
- **project_root** (str) - Required - Root directory of the project to index
```

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

### Initialize Project with LiteLLM Model

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

Initializes a CocoIndex Code project, skipping interactive prompts and specifying a LiteLLM model. Essential for non-interactive environments or slim installs.

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

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

### Environment Variables with Shell References

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

Example of setting environment variables, referencing shell variables for sensitive information like API keys.

```yaml
envs:
  OPENAI_API_KEY: ${OPENAI_API_KEY}  # Reference shell env vars
  COHERE_API_KEY: cohere_abc123
```

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

### Python Example: Using print_warning

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/client.md

Demonstrates how to use the print_warning function to display a warning message. Ensure the cocoindex_code.client module is imported.

```python
from cocoindex_code.client import print_warning

print_warning("Your embedding model may need configuration")
```

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

### DaemonStartError

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/client.md

Exception raised when the daemon process fails to start. This error includes the content of the daemon log file, if available, to aid in diagnosing startup issues.

```APIDOC
## DaemonStartError

### Description

Raised when the daemon process fails to start. Carries the daemon log content so callers can display it to the user for diagnostics.

### Exception Class

```python
class DaemonStartError(RuntimeError):
    def __init__(self, message: str, log: str | None = None) -> None:
        self.log = log
```

### Attributes

- **log** (str | None) - Content of the daemon log file, if available
```

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

### Default MCP Server Instructions

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/server.md

This string defines the default instructions for the MCP server, guiding agents on when and how to utilize code search and codebase understanding tools. It emphasizes semantic search capabilities over simple text matching.

```python
_MCP_INSTRUCTIONS = (
    "Code search and codebase understanding tools."
    "\n"
    "Use when you need to find code, understand how something works,"
    " locate implementations, or explore an unfamiliar codebase."
    "\n"
    "Provides semantic search that understands meaning --"
    " unlike grep or text matching,"
    " it finds relevant code even when exact keywords are unknown."
)
```

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

### Docker Compose Quick Start (Linux)

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

This command is for Linux users to set up CocoIndex Code with Docker Compose. It aligns file ownership with the host user by setting PUID and PGID environment variables.

```bash
# Linux (aligns file ownership on bind-mounted paths with your host user)
PUID=$(id -u) PGID=$(id -g) docker compose -f <(curl -L https://raw.githubusercontent.com/cocoindex-io/cocoindex-code/refs/heads/main/docker/docker-compose.yml) up -d
```

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

### Gemini Embedding Model Configuration

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

Example for configuring the Gemini embedding model. Requires a GEMINI_API_KEY.

```yaml
embedding:
  model: gemini/gemini-embedding-001
envs:
  GEMINI_API_KEY: your-api-key
```

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

### should_wait_for_indexing

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/project.md

Checks if indexing has been started but not yet completed.

```APIDOC
## should_wait_for_indexing

### Description
Checks if indexing has been started but not yet completed.

### Method
`should_wait_for_indexing` (property)

### Parameters
None

### Return Type
`bool` — True if indexing is in progress

### Request Example
```python
if project.should_wait_for_indexing:
    print("Waiting for indexing to complete...")
```

### Response
#### Success Response (200)
- **bool** - True if indexing is in progress, False otherwise.
```

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

### Build and Test Commands with uv

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

Use 'uv run' to execute type checking with mypy and run tests with pytest. Ensure uv is installed for project management.

```bash
uv run mypy .

```

```bash
uv run pytest tests/

```

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

### Ensure Indexing Has Started

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/project.md

Spawns a background indexing task if not already running or completed. This method is safe to call multiple times and ensures indexing is initiated before proceeding.

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

```python
await project.ensure_indexing_started()
```

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

### Doctor Flow Example

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/protocol.md

Illustrates the sequence of requests and responses for a doctor check operation between client and daemon, showing multiple responses.

```text
Client                              Daemon
  |---- HandshakeRequest -------->  |
  |  <---- HandshakeResponse ----  |
  |---- DoctorRequest ----------->  |
  |  <---- DoctorResponse -------- |
  |  <---- DoctorResponse -------- |
```

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

### OpenAI Embedding Model Configuration

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

Example for configuring the OpenAI embedding model. Requires an OPENAI_API_KEY and optionally sets a minimum interval between requests.

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

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

### Check Sentence Transformers Installation

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/shared.md

Checks if the sentence_transformers package is available without loading its dependencies. Use this to determine if local embeddings can be used.

```python
from cocoindex_code.shared import is_sentence_transformers_installed

if is_sentence_transformers_installed():
    print("Local embeddings are available")
else:
    print("Use LiteLLM with API keys")
```

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

### Install Python via Homebrew on macOS

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

If encountering SQLite issues on macOS, install Python through Homebrew. This ensures a compatible Python installation for cocoindex-code.

```bash
brew install python3
```

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

### Restart Daemon Process

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/cli.md

Stops the current daemon process and starts a new instance. The command waits for the daemon to become ready after restarting.

```python
@daemon_app.command("restart")
def daemon_restart() -> None:
    pass
```

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

### Index Codebase

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

Builds or updates the semantic index for the codebase. Run this after significant code changes or at the start of a session to ensure index freshness.

```bash
ccc index
```

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

### Simple Custom Chunker Example

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/chunking.md

A simple custom chunker function that splits a file into chunks, with each chunk representing a single non-empty line. It returns None for the language override, indicating auto-detection.

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

def simple_line_chunker(path: Path, content: str) -> tuple[str | None, list[Chunk]]:
    """Chunk a file by line, one chunk per line."""
    chunks = []
    char_offset = 0
    
    for line_num, line in enumerate(content.split('\n'), start=1):
        if not line.strip():  # Skip empty lines
            char_offset += len(line) + 1
            continue
        
        start = TextPosition(
            byte_offset=char_offset,
            char_offset=char_offset,
            line=line_num,
            column=0
        )
        
        char_offset += len(line) + 1
        
        end = TextPosition(
            byte_offset=char_offset - 1,
            char_offset=char_offset - 1,
            line=line_num,
            column=len(line)
        )
        
        chunks.append(Chunk(
            text=line,
            start=start,
            end=end
        ))
    
    # None means use auto-detected language
    return None, chunks

# Type annotation for clarity
custom_chunker: ChunkerFn = simple_line_chunker
```

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

### Embedding Model Indexing and Query Parameters

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

Configure specific parameters for embedding documents and queries, especially for asymmetric retrieval models. This example shows settings for Cohere's v3 models using LiteLLM.

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

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

### Start CocoIndex Daemon Process

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/client.md

Launches the CocoIndex daemon as a background process. It redirects stdout/stderr to the log file and listens on a Unix socket or named pipe. The returned process object can be used to monitor the daemon's lifecycle.

```python
from cocoindex_code.client import start_daemon, _wait_for_daemon

proc = start_daemon()
_wait_for_daemon(proc=proc, timeout=30.0)
print("Daemon started")
```

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

### Doctor Check Failure Output Example

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

Shows an example of the output from the `ccc doctor` command when checks fail, indicating issues with the embedding model or API key configuration.

```text
[FAIL] Embedding Model
  ERROR: Model 'text-embedding-3-small' not available
  ERROR: OPENAI_API_KEY not set in environment
```

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

### Describe Project Root Overview

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

Retrieves a high-level overview summary for the entire project. Use when the directory path is known.

```bash
ccc describe .
```

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

### Define DaemonStartError

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

Raised when the daemon process fails to start. This can occur if the daemon exits before the socket is available, the socket does not appear within the timeout, or during the wait for the daemon after starting it. Includes daemon log content for diagnostics.

```python
class DaemonStartError(RuntimeError):
    def __init__(self, message: str, log: str | None = None) -> None:
        self.log = log
        super().__init__(message)
```

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

### Initialize Project

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

Initialize a new CocoIndex project. Optionally specify a LiteLLM model or force initialization to skip warnings.

```bash
ccc init [--litellm-model MODEL] [-f|--force]
```

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

### Create MCP Server Instance

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/server.md

Use this function to create a lightweight MCP server that delegates search operations to the daemon. The server exposes a `search` tool for querying code.

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

# Create the server for a project
mcp = create_mcp_server("/path/to/project")

# The server is now ready to be used via stdio with fastmcp
# This would typically run via:
# asyncio.run(mcp.run_stdio_async())
```

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

### find_project_root

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/settings.md

Searches for the project root directory by traversing up from a given starting directory.

```APIDOC
## `find_project_root`

### Description
Find project root by walking up from a directory.

### Signature
```python
def find_project_root(cwd: Path) -> Path | None
```

### Parameters
#### Path Parameters
- **cwd** (Path) - Required - Starting directory (usually current working directory)

### Returns
`Path | None` — Root directory if found, None otherwise

### Details
Walks up looking for `.cocoindex_code/` marker directory.
```

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

### Read File Summary Hint

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

Follows a '[summary]' hint from search results to read a file or directory summary. Use this command when prompted by search output.

```bash
ccc describe <path>
```

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

### Upgrade CocoIndex Code

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

Upgrades an existing CocoIndex Code installation to the latest version.

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

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

### Multiple Database Path Mappings

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

Configure multiple comma-separated database path mappings. Mappings are resolved in order, with the first match winning.

```bash
COCOINDEX_CODE_DB_PATH_MAPPING=/workspace=/db-files,/workspace2=/db-files2
```

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

### create_mcp_server

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/server.md

Creates a lightweight MCP server that delegates to the daemon for actual search operations. The server exposes a single `search` tool that accepts natural language queries or code snippets and returns matching code chunks with similarity scores.

```APIDOC
## create_mcp_server

### Description
Creates a lightweight MCP server that delegates to the daemon. The server exposes a single `search` tool that accepts natural language queries or code snippets and returns matching code chunks with similarity scores.

### Method
`create_mcp_server(project_root: str) -> FastMCP`

### Parameters
#### Path Parameters
- **project_root** (str) - Required - Root directory of the project to index and search

### Tool: `search`

#### Parameters
- **query** (str) - Required - Natural language query or code snippet to search for
- **limit** (int) - Optional - Default: 5 - Maximum number of results to return (1-100)
- **offset** (int) - Optional - Default: 0 - Number of results to skip for pagination
- **refresh_index** (bool) - Optional - Default: True - Whether to incrementally update the index before searching
- **languages** (list[str] | None) - Optional - Default: None - Filter by programming language(s), e.g. `["python", "typescript"]`
- **paths** (list[str] | None) - Optional - Default: None - Filter by file path pattern(s) using GLOB wildcards (`*` and `?`)

### Tool Returns
`SearchResultModel` with:
- **success** (bool) - Whether the search completed successfully
- **results** (list[CodeChunkResult]) - List of matching code chunks
- **total_returned** (int) - Number of results returned
- **offset** (int) - Offset used in the query
- **message** (str | None) - Error message if `success=False`

### Example
```python
from cocoindex_code.server import create_mcp_server
import asyncio

# Create the server for a project
mcp = create_mcp_server("/path/to/project")

# The server is now ready to be used via stdio with fastmcp
# This would typically run via:
# asyncio.run(mcp.run_stdio_async())
```
```

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

### IndexRequest Definition

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/protocol.md

Defines the request to start or refresh the indexing process for a specified project directory.

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

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

### Specific File Exclusion Patterns

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

Illustrates common exclusion patterns for build directories, caches, and vendor folders.

```yaml
exclude_patterns:
  - '**/.*'  # Hidden files/dirs
  - '**/__pycache__'  # Python cache
  - '**/node_modules'  # NPM deps
  - '**/vendor/**'  # PHP vendor
  - '**/build'  # Build output
```

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

### daemon_status

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/client.md

Get the current status of the cocoindex daemon process, including its version, uptime, and loaded projects.

```APIDOC
## daemon_status

### Description
Get status of the daemon process.

### Method
```python
def daemon_status() -> DaemonStatusResponse
```

### Return Type
`DaemonStatusResponse` with:
- `version: str` — Daemon version string
- `uptime_seconds: float` — Seconds since daemon started
- `projects: list[DaemonProjectInfo]` — List of loaded projects with their indexing state

### Throws
- `RuntimeError` — If daemon communication fails

### Example
```python
from cocoindex_code.client import daemon_status

status = daemon_status()
print(f"Daemon v{status.version} | Uptime: {status.uptime_seconds:.1f}s")
print(f"Loaded projects: {len(status.projects)}")
```
```

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

### Get Host Path Mappings

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/settings.md

Retrieves and parses the host path mappings from the COCOINDEX_CODE_HOST_PATH_MAPPING environment variable.

```python
def get_host_path_mappings() -> list[PathMapping]
```

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

### Index Project with Progress Updates

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/client.md

Initiates project indexing and streams progress updates via callbacks. Use this when you need to monitor the indexing process in real-time. It blocks until indexing is complete.

```python
from cocoindex_code.client import index
from cocoindex_code.protocol import IndexingProgress

def on_progress(progress: IndexingProgress) -> None:
    print(f"Added: {progress.num_adds}, Deleted: {progress.num_deletes}")

response = index("/path/to/project", on_progress=on_progress)
if response.success:
    print("Indexing completed")
else:
    print(f"Indexing failed: {response.message}")
```

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

### Get Database Path Mappings

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/settings.md

Retrieves and parses the database path mappings from the COCOINDEX_CODE_DB_PATH_MAPPING environment variable.

```python
def get_db_path_mappings() -> list[PathMapping]
```

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

### Voyage Code-Optimized Embedding Model

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

Example for configuring the Voyage AI code-optimized embedding model. Requires a VOYAGE_API_KEY.

```yaml
embedding:
  model: voyage/voyage-code-3
envs:
  VOYAGE_API_KEY: your-api-key
```

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

### default_project_settings()

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/settings.md

Creates default project settings, initialized with built-in file inclusion and exclusion patterns.

```APIDOC
## default_project_settings

### Description
Create default project settings with built-in patterns.

### Returns
`ProjectSettings` with default include/exclude patterns
```

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

### LiteLLM Models URL Constant

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/cli.md

This constant holds the URL for supported LiteLLM embedding models, referenced during interactive setup.

```python
_LITELLM_MODELS_URL = "https://docs.litellm.ai/docs/embedding/supported_embedding"
```

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

### Print Project Header

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/cli.md

Prints the project root directory to the console for display purposes.

```python
def print_project_header(project_root: str) -> None:
    pass
```

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

### Get Daemon Status

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/cli.md

Displays the status of the daemon process, including its version, uptime, and a list of loaded projects with their indexing state.

```python
@daemon_app.command("status")
def daemon_status() -> None:
    pass
```

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

### Save Initial User Settings

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/settings.md

Saves initial user settings, with an option to indicate if default values were applied.

```python
def save_initial_user_settings(
    embedding: EmbeddingSettings,
    defaults_applied: bool = False,
) -> Path
```

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

### Initialize Project Index

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

Initializes a new CocoIndex Code project by setting up configuration files and testing the embedding model. Skips interactive prompts if global settings already exist.

```bash
ccc init
```

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

### Ollama Local Embedding Model

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

Configure ccc to use an embedding model served by Ollama locally. This requires Ollama to be installed and running.

```yaml
embedding:
  model: ollama/nomic-embed-text
```

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

### main

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/server.md

Backward-compatible entry point for the `cocoindex-code` CLI command. It auto-detects or creates settings from environment variables, then delegates to the daemon, supporting `serve` and `index` subcommands.

```APIDOC
## main

### Description
Backward-compatible entry point for the `cocoindex-code` CLI command. Auto-detects or creates settings from environment variables, then delegates to the daemon. Supports two subcommands: `serve` (default) — Runs the MCP server in stdio mode, and `index` — Builds or refreshes the index and reports statistics.

### Method
`main() -> None`

### Environment Variables
- `COCOINDEX_CODE_ROOT_PATH` — Project root directory
- `COCOINDEX_CODE_EXCLUDED_PATTERNS` — JSON list of patterns to exclude from indexing
- `COCOINDEX_CODE_EXTRA_EXTENSIONS` — Comma-separated file extensions with optional language mapping (format: `ext` or `ext:language`)
- `COCOINDEX_CODE_EMBEDDING_MODEL` — Embedding model name (supports legacy `sbert/` prefix for sentence-transformers models)
- `COCOINDEX_CODE_DEVICE` — Device for sentence-transformers (e.g., `"cuda"`, `"cpu"`)

### Example
```python
from cocoindex_code.server import main

# Run the MCP server (default)
main()

# Or from CLI:
# cocoindex-code serve
# cocoindex-code index
```
```

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

### Load Project Settings

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/settings.md

Loads project-specific settings from a YAML file. Requires the project root path. Throws FileNotFoundError or ValueError on issues.

```python
def load_project_settings(project_root: Path | str) -> ProjectSettings
```

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

### ensure_indexing_started

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/project.md

Spawns a background indexing task if not already running or done. Returns immediately if a task is already running or if initial indexing is complete. Safe to call multiple times.

```APIDOC
## ensure_indexing_started

### Description
Spawns a background indexing task if not already running or done. Returns immediately if a task is already running or if initial indexing is complete. Safe to call multiple times.

### Method
`ensure_indexing_started`

### Parameters
None

### Request Example
```python
await project.ensure_indexing_started()
```

### Response
None
```

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

### load_project_settings

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/settings.md

Loads project-specific settings from a YAML configuration file.

```APIDOC
## `load_project_settings`

### Description
Load project settings from YAML.

### Signature
```python
def load_project_settings(project_root: Path | str) -> ProjectSettings
```

### Throws
- `FileNotFoundError` — If settings file doesn't exist
- `ValueError` — If settings are invalid
```

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

### Add to .gitignore

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/cli.md

Adds the '/.cocoindex_code/' entry to the .gitignore file if it doesn't exist. Creates the file if necessary. This function is useful during project setup.

```python
def add_to_gitignore(project_root: Path) -> None
```

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

### Initialize Project Command

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/cli.md

Command to initialize a new cocoindex-code project. It creates necessary configuration files and updates `.gitignore`. Use `--litellm-model` to specify an embedding model and `--force` to bypass warnings.

```python
@app.command()
def init(
    litellm_model: str | None = _typer.Option(..., "--litellm-model"),
    force: bool = _typer.Option(False, "-f", "--force"),
) -> None
```

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

### Run `reset` Command

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/cli.md

Execute the reset command to clear index data. Use --all to also remove settings and .gitignore, and -f to force the operation without confirmation.

```bash
ccc reset
ccc reset --all -f
```

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

### Add MCP Server using OpenCode CLI

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

Configure an MCP server interactively via the OpenCode CLI. You will be prompted for the server name, type, and command.

```bash
opencode mcp add
```

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

### Get Vector Index SQLite DB Path

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/settings.md

Retrieves the path to the vector index SQLite database, applying path mappings if configured.

```python
def target_sqlite_db_path(project_root: Path) -> Path
```

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

### Local Sentence-Transformers Embedding Model

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

Example for configuring a local embedding model using the sentence-transformers provider. No API key is needed for local models.

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

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

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

### Map Host Paths for Display

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

Configure environment variables to map host paths for display in CLI output. This is particularly useful for Docker exec wrappers to present user-friendly paths.

```bash
export COCOINDEX_CODE_HOST_PATH_MAPPING="/container=/home/user/project"
```

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

### save_initial_user_settings

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/settings.md

Saves initial user settings, with an option to indicate if default values were applied.

```APIDOC
## `save_initial_user_settings`

### Description
Save initial user settings with optional defaults applied notification.

### Signature
```python
def save_initial_user_settings(
    embedding: EmbeddingSettings,
    defaults_applied: bool = False,
) -> Path
```
```

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

### Describe File Summary

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

Retrieves a concise summary of a specific file's public API, contracts, and role. Use when the file path is known.

```bash
ccc describe src/auth/session.py
```

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

### Add MCP Server using Codex

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

Use this command to add a new MCP server configuration using the Codex model.

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

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

### Python Exception Class: DaemonStartError

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/client.md

Defines the DaemonStartError class, raised when the daemon process fails to start. It can optionally store the content of the daemon log file for diagnostics.

```python
class DaemonStartError(RuntimeError):
    def __init__(self, message: str, log: str | None = None) -> None:
        self.log = log
```

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

### ProjectSettings Configuration

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/settings.md

Project-level configuration including file inclusion/exclusion patterns, language overrides, and custom chunkers.

```APIDOC
## ProjectSettings

### Description
Project-level configuration.

### Fields
- **include_patterns** (list[str]) - Optional - Default: `DEFAULT_INCLUDED_PATTERNS` - File glob patterns to include in indexing
- **exclude_patterns** (list[str]) - Optional - Default: `DEFAULT_EXCLUDED_PATTERNS` - File glob patterns to exclude
- **language_overrides** (list[LanguageOverride]) - Optional - Default: `[]` - Custom extension → language mappings
- **chunkers** (list[ChunkerMapping]) - Optional - Default: `[]` - Custom chunker registrations
```

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

### check_embedding

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/shared.md

Runs a test embedding to verify the embedder's functionality and reports its dimension or any errors encountered. This function is crucial for validating embedder setup during initialization and for diagnostic purposes.

```APIDOC
## check_embedding

### Description
Run a test embedding and report dimension or error.

### Parameters
- **embedder** (Embedder) - Required - Embedder to test
- **params** (dict[str, Any] | None) - Optional - Extra kwargs to spread into embed() call

### Returns
- `EmbeddingCheckResult` - Contains either `dim` (success) or `error` (failure message)

### Notes
Tests the embedder with "hello world" string. Never raises exceptions. Returns dimension if successful, error message if failed (truncated to 500 chars). Used by doctor command and init flow.

### Example
```python
from cocoindex_code.shared import create_embedder, check_embedding
from cocoindex_code.settings import EmbeddingSettings

settings = EmbeddingSettings(
    provider="litellm",
    model="text-embedding-3-small",
)
embedder = create_embedder(settings)
result = await check_embedding(embedder)

if result.error is None:
    print(f"Embedding dimension: {result.dim}")
else:
    print(f"Embedding check failed: {result.error}")
```
```

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

### Project Settings Path Function

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/settings.md

Determines the file path for project-specific settings within a given project root directory.

```python
def project_settings_path(project_root: Path | str) -> Path:
```

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

### Add CocoIndex-code skill to coding agent

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

Install the 'ccc' skill for your coding agent to enable automatic semantic search integration. This method handles initialization, indexing, and searching automatically.

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

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

### Control Search Pagination CLI

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

Performs a semantic search with custom pagination settings for limit and offset.

```bash
ccc search --offset 10 --limit 5 database schema
```

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

### Get CocoIndex Daemon Environment Variables

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/client.md

Retrieves environment variables and path mappings configured within the CocoIndex daemon. This can be helpful for debugging or understanding the daemon's operational context.

```python
from cocoindex_code.client import daemon_env

env_info = daemon_env()
print(f"Environment variables: {env_info.env_names}")
```

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

### Run Indexing with Progress Callback

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/project.md

Acquires the index lock, runs indexing, and releases it. Accepts an optional progress callback to report updates during the indexing process.

```python
async def run_index(
    self,
    on_progress: Callable[[IndexingProgress], None] | None = None,
    on_started: asyncio.Event | None = None,
) -> None
```

```python
import asyncio
from cocoindex_code.protocol import IndexingProgress

def on_progress(progress: IndexingProgress) -> None:
    print(f"Progress: {progress.num_adds} added")

await project.run_index(on_progress=on_progress)
```

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

### Get CocoIndex Daemon Status

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/client.md

Retrieves the current status of the CocoIndex daemon, including its version, uptime, and loaded projects. This is useful for monitoring and verifying the daemon's operational state.

```python
from cocoindex_code.client import daemon_status

status = daemon_status()
print(f"Daemon v{status.version} | Uptime: {status.uptime_seconds:.1f}s")
print(f"Loaded projects: {len(status.projects)}")
```

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

### Find Project Root

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/cli.md

Locates the project root directory by walking up from the current working directory. Exits with an error if global settings are not found or the root cannot be determined.

```python
from pathlib import Path

def require_project_root() -> Path:
    pass
```

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

### Get Project Indexing Status

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/client.md

Retrieves the current indexing status and statistics for a given project. Use this to check if indexing is in progress, the number of indexed chunks and files, and the language distribution.

```python
from cocoindex_code.client import project_status

status = project_status("/path/to/project")
print(f"Chunks: {status.total_chunks}, Files: {status.total_files}")
print(f"Languages: {status.languages}")
```

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

### Main CLI Application Instance

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/cli.md

The root Typer application instance for the `ccc` command. It serves as the entry point for all subcommands.

```python
app: _typer.Typer = _typer.Typer(
    name="ccc",
    help="CocoIndex Code — index and search codebases.",
    no_args_is_help=True,
)
```

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

### Run cocoindex-code CLI

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/server.md

This function serves as a backward-compatible entry point for the cocoindex-code CLI. It handles environment variable migration and delegates to the daemon for `serve` or `index` subcommands.

```python
from cocoindex_code.server import main

# Run the MCP server (default)
main()

# Or from CLI:
# cocoindex-code serve
# cocoindex-code index
```

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

### Load Gitignore Specification

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/settings.md

Loads and compiles .gitignore patterns for a specified directory. Returns None if no .gitignore file is found.

```python
def load_gitignore_spec(
    directory: Path,
) -> GitIgnoreSpec | None
```

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

### Create Embedder Instance

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/shared.md

Creates an embedder instance based on provided settings. For LiteLLM, it forwards indexing_params to the constructor; for sentence-transformers, these params are ignored.

```python
from cocoindex_code.shared import create_embedder
from cocoindex_code.settings import EmbeddingSettings

# Local embedder
settings = EmbeddingSettings(
    provider="sentence-transformers",
    model="Snowflake/snowflake-arctic-embed-xs",
)
embedder = create_embedder(settings)

# LiteLLM embedder with defaults
settings = EmbeddingSettings(
    provider="litellm",
    model="text-embedding-3-small",
)
embedder = create_embedder(
    settings,
    indexing_params={"input_type": "passage"}
)
```

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

### Stop CocoIndex Daemon Gracefully

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/client.md

Stops the CocoIndex daemon using a multi-stage process, starting with a graceful shutdown request and escalating to SIGTERM/SIGKILL if necessary. This function also cleans up associated socket and PID files.

```python
from cocoindex_code.client import stop_daemon

stop_daemon()
print("Daemon stopped")
```

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

### CODEBASE_DIR Context Key

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/shared.md

Context key for the project's root directory, represented as a pathlib.Path object.

```python
CODEBASE_DIR = coco.ContextKey[pathlib.Path]("codebase")
```

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

### Map Database Paths

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

Export environment variables to map database paths between container and host systems. This is essential for Docker or containerized environments where paths may differ.

```bash
export COCOINDEX_CODE_DB_PATH_MAPPING="/container/project=/host/project"
export COCOINDEX_CODE_DB_PATH_MAPPING="/proj1=/host1,/proj2=/host2"
```

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

### create

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/project.md

Factory method to create a new project instance with explicit embedder and per-call parameters. It initializes the CocoIndex environment, sets up necessary providers, and can create directories if they don't exist.

```APIDOC
## `create`

Create a project with explicit embedder and per-call params.

### Description
Creates a new project instance. Project-level settings and .gitignore are NOT cached; the indexer loads them fresh from disk on every run so user edits take effect without restarting the daemon.

### Method Signature
```python
@staticmethod
async def create(
    project_root: Path,
    embedder: Embedder,
    indexing_params: dict[str, Any],
    query_params: dict[str, Any],
    chunker_registry: dict[str, ChunkerFn] | None = None,
)
```

### Parameters
#### Path Parameters
- **project_root** (Path) - Required - Root directory of the codebase
- **embedder** (Embedder) - Required - Embedding model instance (sentence-transformers or LiteLLM)
- **indexing_params** (dict[str, Any]) - Required - Extra kwargs for `embedder.embed()` during indexing (e.g., `{"prompt_name": "passage"}`)
- **query_params** (dict[str, Any]) - Required - Extra kwargs for `embedder.embed()` during queries
- **chunker_registry** (dict[str, ChunkerFn] | None) - Optional - Custom chunker mappings by file suffix (e.g., `{'.toml': my_chunker_fn}`)

### Return Type
`Project` — A fully initialized project instance

### Side Effects
- Creates `.cocoindex_code/` and database directories if they don't exist
- Initializes the CocoIndex environment and app
- Sets up context providers for embedder, database, and chunker registry

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

# Load settings
user_settings = load_user_settings()
embedder = create_embedder(user_settings.embedding)

# Create project
project = await Project.create(
    project_root=Path("/path/to/project"),
    embedder=embedder,
    indexing_params={},
    query_params={},
)

# Use project
await project.run_index()
results = await project.search("my query")

# Cleanup
project.close()
```
```

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

### Get Project Index Status

Source: https://github.com/cocoindex-io/cocoindex-code/blob/main/_autodocs/api-reference/project.md

Retrieves current index statistics, including whether indexing is running, total chunks and files, language breakdown, and index existence. This method queries the SQLite database and does not require indexing to be complete.

```python
def get_status(self) -> ProjectStatusResponse
```

```python
status = project.get_status()
print(f"Chunks: {status.total_chunks}, Files: {status.total_files}")
```