Cocoindex Code

すぐに使えるASTベースのセマンティックコード検索

コードベース向けの、軽量で効果的な**（ASTベース）**セマンティックコード検索ツールです。CocoIndexを基盤として構築されています。CocoIndexはRustベースの非常に高性能なデータ変換エンジンです。CLIから使用するか、SkillまたはMCPを介してClaude、Codex、Cursorなど、あらゆるコーディングエージェントと連携できます。

• トークンを瞬時に70％節約できます。
• セットアップは1分 — インストールしたらすぐに使えます。設定は不要です！

はじめましょう — 設定不要です。すぐ使えます！

インストール

pipxを使用する場合：

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

uvを使用する場合：

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

インストール方法は2種類あります。それぞれ、同じ名前のDockerイメージのバリアントに対応しています。

• cocoindex-code[full] — 必要なものがすべて含まれています。sentence-transformersを導入するため、ローカル埋め込みを（APIキーなしで）すぐに利用できます。ccc initの対話型プロンプトでは、デフォルトでSnowflake/snowflake-arctic-embed-xsが選択されます。
• cocoindex-code（slim）— LiteLLMのみです。クラウドの埋め込みプロバイダーとAPIキーが必要です。ローカル埋め込みの依存関係（torchとtransformersで約1 GB）が不要な場合に使用してください。

次に、コーディングエージェントとの連携を設定します。直接操作したい場合は、CLIの手動使用に進んでください。

コーディングエージェントとの連携

このリポジトリは単一のプラグインマーケットプレイス（.claude-plugin/marketplace.json）であり、Claude CodeとGrokの両方で使用されます。プラグインIDはどちらもcocoindex-code、スキルはどちらもcccです。Grokでは--trustを指定すると、同梱のフックとMCPサーバーを任意で有効にできます。Claude Codeユーザーは同じマーケットプレイスをインストールし、スキルのみを使用するか、必要に応じてプラグインからフックやMCPを読み込めます。

スキル（推奨）

ccc スキルをインストールすると、必要に応じてコーディングエージェントがセマンティック検索を自動的に使うようになります。

npx skills add cocoindex-io/cocoindex-code

これだけで完了です。ccc init や ccc index は必要ありません。このスキルにより、エージェントは初期化、インデックス作成、検索を自分で行えるようになります。作業中は、インデックスも自動的に最新の状態に保たれます。

役立つ場合、エージェントはセマンティック検索を自動的に使います。「ユーザーセッションがどのように管理されているか探して」のようにコードベースを検索するよう明示的に依頼するか、/ccc と入力してスキルを直接呼び出すこともできます。

Claude Code や、その他のスキル対応エージェントで動作します。

Claude Code プラグインマーケットプレイス

Claude Code ユーザー向けに、このリポジトリはプラグインマーケットプレイスとしても利用できます。Claude Code 内で次のコマンドを実行して、スキルをインストールします。

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

これには同じ ccc スキルが含まれており、バージョンを固定できるほか、更新には /plugin marketplace update を使えます。また、このリポジトリには Grok 向け（およびこれらのファイルを読み込む Claude Code プラグインのインストール向け）に hooks/hooks.json と .mcp.json も含まれています。スキルのみを使った検索を希望する Claude ユーザーは、スキルだけを利用し、同梱の .mcp.json を使う代わりに、下記のMCP サーバーセクションで MCP を手動で追加できます。

Grok プラグイン

Grok ユーザーは、Grok のプラグインシステムからインストールしてください。このプラグインには、次の 3 つのコンポーネントが含まれています。

Grok は Claude の enabledPlugins やプラグインキャッシュをインポートしません。すでに Claude Code で cocoindex を使っている場合も、別途インストールしてください。

完全インストール（スキル + フック + MCP）：

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

インストールには GitHub の省略記法（cocoindex-io/cocoindex-code）を使うことをおすすめします。該当するマーケットプレイスプラグインがその名前だけでは見つからず、grok plugin install cocoindex-code が失敗する場合があります。

Grok がプラグインのフックと MCP サーバーを有効にするには、--trust が必要です（スキルはプラグインが有効になると読み込まれます）。

スキルのみ（Claude Code と同じ構成。自動インデックス作成フックと MCP ツールはありません）：

上記の手順でインストールして有効にした後、オプションのコンポーネントを無効にします。

1. フック — /hooks を開き、cocoindex-code の SessionStart / PostToolUse フックを選択して、Space キーを押して無効にします。
2. MCP — /mcps を開き、cocoindex-code を選択して Space キーを押して無効にします。または、~/.grok/config.toml に設定を保存します。

[mcp_servers.cocoindex-code]
enabled = false

引き続き、インデックス作成はエージェントが ccc スキルを使って行います（古くなった場合は ccc index / ccc search --refresh を実行します）。Claude Code と同じです。

Claude/Cursor のユーザー設定から MCP サーバーがインポートされないようにするには（このプラグインとは無関係です）：

[compat.claude]
mcps = false

[compat.cursor]
mcps = false

Oh My Pi プラグイン

Oh My Pi は .omp-plugin/marketplace.json を読み込み（こちらが優先されます）、存在しない場合は .claude-plugin/marketplace.json にフォールバックします。

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

その後、セッションを再起動してください（/reload-plugins では拡張機能は再読み込みされません）。PATH に ccc が必要です（uv tool install --upgrade 'cocoindex-code[full]'）。

OMP は Claude の hooks/hooks.json コマンドフックを実行しません。TypeScript 拡張機能は、Claude/Grok の SessionStart と PostToolUse の組み合わせに相当する OMP の機能です。

スキルのみ（MCP なし、自動インデックス作成なし）：npx skills add cocoindex-io/cocoindex-code でスキルをインストールするか、シェルから ccc search / ccc index を実行してください。

MCP サーバー

または、ccc mcp を使用して MCP サーバーとして実行できます。

claude mcp add cocoindex-code -- ccc mcp

codex mcp add cocoindex-code -- ccc mcp

opencode mcp add

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "cocoindex-code": {
      "type": "local",
      "command": [
        "ccc", "mcp"
      ]
    }
  }
}

{
  "mcp": {
    "cocoindex-code": {
      "type": "local",
      "command": ["ccc", "mcp"],
      "enabled": true
    }
  }
}

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

設定すると、エージェントは、説明からコードを見つけるとき、慣れていないコードベースを調べるとき、あいまいな一致や概念的な一致を探すとき、正確な名前がわからない実装を特定するときなど、セマンティックコード検索が役立つ場面を自動的に判断します。

注： サブコマンドを付けない cocoindex-code コマンドも、後方互換性のため MCP サーバーとして引き続き動作します。初回実行時に環境変数から設定を自動作成します。

search(
    query: str,                          # Natural language query or code snippet
    limit: int = 5,                      # Maximum results (1-100)
    offset: int = 0,                     # Pagination offset
    refresh_index: bool = True,          # Refresh index before querying
    languages: list[str] | None = None,  # Filter by language (e.g. ["python", "typescript"])
    paths: list[str] | None = None,      # Filter by path glob (e.g. ["src/utils/*"])
)

CLI の手動使用

CLI を直接使用することもできます。手動で制御したい場合、設定変更後にインデックスを作成する場合、ステータスを確認する場合、またはエージェントを介さずに検索する場合に便利です。

ccc init                                # initialize project (creates settings)
ccc index                               # build the index
ccc search "authentication logic"       # search!

バックグラウンドデーモンは初回使用時に自動的に起動します。

ヒント： ccc init を省略し、直接 ccc index を実行できます。新しいプロジェクトはデフォルト設定で自動的に初期化されます。グローバル設定も存在しない場合（そのマシンでの初回使用時）、対話モードで実行すると ccc init と同じモデル設定の手順が表示されます。非対話モードでの実行（スクリプト、フック）では、事前に一度 ccc init を実行する必要があります。

注： ccc index は、ccc のユーザー設定ディレクトリを格納するディレクトリを自動初期化しません。デフォルトではホームディレクトリ（~/.cocoindex_code にグローバル設定とデーモンファイルが格納されます）、または $COCOINDEX_CODE_DIR のディレクトリ名が .cocoindex_code の場合はその親ディレクトリが対象です。そこをプロジェクトにすると、その配下にあるすべてのリポジトリが対象になります。エディターフックは、そのディレクトリがすでにプロジェクトになっていてもスキップします。古い ccc によってホームディレクトリがプロジェクトになっている場合（~/.cocoindex_code/settings.yml が存在する場合）は、ホームディレクトリで ccc reset --all を実行してください。そのプロジェクトの設定とインデックスが削除され、グローバル設定は保持されます。ホームディレクトリ全体を意図的にインデックス化するには、そこで ccc init を実行してください。

CLI リファレンス

検索オプション

ccc search database schema                           # basic search
ccc search --lang python --lang markdown schema      # filter by language
ccc search --path 'src/utils/*' query handler        # filter by path
ccc search --offset 10 --limit 5 database schema     # pagination
ccc search --refresh database schema                 # update index first, then search

デフォルトでは、ccc search は現在の作業ディレクトリ（プロジェクトルートからの相対パス）を対象に検索します。--path を使うと、検索範囲を変更できます。

構造検索（ccc grep）

ccc grep はテキストではなく構造でコードを検索します。例をもとにパターンを記述すると、書式、空白、間にあるトークンに左右されず、構文木に照らしてマッチングします（cocoindex の code_match 経由）。すべてローカルで実行されるため、インデックス、デーモン、埋め込みは不要です。

ccc grep 'def \NAME(\(ARGS*\)):'                      # every Python function def under the cwd
ccc grep 'foo(\(ARGS*\))' src/                        # calls to foo(...) anywhere under src/
ccc grep 'fn \NAME(\(A*\))' --lang rust               # restrict to one language
ccc grep 'class \NAME:' --path 'tests/**'            # restrict to a path glob
ccc grep 'TODO(\(A*\))' path/to/file.py               # a single file

メタ変数には \ のシジルを使います。\NAME は単一のノードをキャプチャし、\(NAME*\) は連続する兄弟ノードをキャプチャします。\_／\* は匿名でマッチします。パターンは言語ごとに照合されるため、1 回の実行ですべての対応ソースファイルをスキャンします（その他のファイルはスキップされます）。初期化済みのプロジェクト内では、ccc grep はプロジェクトの include／exclude パターンと .gitignore に従います。それ以外の場合は、指定されたパス以下にある対応ソースファイルをすべてスキャンします。

結果はすべてのマッチが最後に一括表示されるのではなく、各マッチが見つかるたびに、ファイル単位でターミナルにストリーミング表示されます（ファイルは並列で照合されるため、完了順に表示されます）。マッチしたファイルごとに該当する行範囲が表示されます。TTY では、パスに色が付き、行番号は薄く表示され、マッチ箇所を目立たせるために周囲の一致しないコンテキストも薄く表示されます。

注記： ccc grep は、cocoindex の構造検索機能 code_match を利用します。 リリース版の cocoindex にこの機能が含まれるまでは、ローカルの cocoindex ビルドに対して実行してください。

Docker

再現性が高く、依存関係のない環境を求めるチーム向けに Docker イメージを用意しています。ホストに Python、uv、システム依存関係をインストールする必要はありません。

推奨する方法は、永続コンテナを使うことです。一度起動すれば、docker exec で CLI コマンドを実行したり、MCP セッションを接続したりできます。コンテナ内のデーモンはセッション間も稼働し続けるため、埋め込みモデルを読み込むのは一度だけです。

イメージの選択

各リリースから、次の 2 種類のイメージが公開されています。

このセクションの以降の手順では :latest を使います。フル版を使う場合は、image:／docker run コマンドの :latest を :full に置き換えてください。

:full 版を実行する Mac ユーザー向け： Docker 内でのローカル埋め込み推論は CPU のみで実行されます。macOS 上の Docker は Apple の Metal（MPS）GPU にアクセスできないためです。ローカル埋め込みと高速な推論が必要な場合は、ネイティブ環境にインストールしてください：pipx install 'cocoindex-code[full]'。:latest（スリム版）には影響しません。LiteLLM はプロバイダー側でモデルを実行するため、Docker とネイティブ環境で違いはありません。

クイックスタート — docker compose up -d

1 行で起動できます。クローンは不要です（bash / zsh）：

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

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

または、docker/docker-compose.yml を取得し、そのファイルと同じ場所で docker compose up -d を実行します（Windows の cmd / PowerShell を含む、あらゆるシェルで動作します）。

デフォルトでは、ホームディレクトリがコンテナにマウントされます（特定のコードフォルダーだけに限定するには、COCOINDEX_HOST_WORKSPACE を設定してください）。インデックスデータと埋め込みモデルのキャッシュは、再起動後も Docker ボリュームに保持されます。ホスト上では、$HOME/.cocoindex_code/global_settings.yml にあるグローバル設定ファイルを参照・編集できます。編集内容は、次回の ccc コマンド実行時に反映されます。

別のイメージを選択する場合： COCOINDEX_CODE_IMAGE を設定して、デフォルトを上書きします。たとえば、:full バリアントや GHCR を使用できます：

COCOINDEX_CODE_IMAGE=cocoindex/cocoindex-code:full docker compose up -d
COCOINDEX_CODE_IMAGE=ghcr.io/cocoindex-io/cocoindex-code:latest docker compose up -d

または：docker run

docker run -d --name cocoindex-code \
  --volume "$HOME:/workspace" \
  --volume cocoindex-data:/var/cocoindex \
  -e COCOINDEX_CODE_HOST_PATH_MAPPING="/workspace=$HOME" \
  cocoindex/cocoindex-code:latest

docker run -d --name cocoindex-code \
  -e PUID=$(id -u) -e PGID=$(id -g) \
  --volume "$HOME:/workspace" \
  --volume cocoindex-data:/var/cocoindex \
  -e COCOINDEX_CODE_HOST_PATH_MAPPING="/workspace=$HOME" \
  cocoindex/cocoindex-code:latest

ccc コマンド用シェルラッパー

~/.bashrc / ~/.zshrc に貼り付けると、ホスト上で ccc をネイティブのように使え、現在のディレクトリに基づいて適切なプロジェクトが選択されます：

ccc() {
  docker exec -it -e COCOINDEX_CODE_HOST_CWD="$PWD" cocoindex-code ccc "$@"
}

これで、ワークスペース内の任意のプロジェクトに cd して、ccc init、ccc index、ccc search ...、ccc status などを実行できます。そのまま動作します。

コーディングエージェントを接続する

claude mcp add cocoindex-code -- docker exec -i \
  -e COCOINDEX_CODE_HOST_CWD="$PWD" cocoindex-code ccc mcp

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

codex mcp add cocoindex-code -- docker exec -i \
  -e COCOINDEX_CODE_HOST_CWD="$PWD" cocoindex-code ccc mcp

古いイメージからのアップグレード

以前のイメージでは、cocoindex-db と cocoindex-model-cache の個別のボリュームを使用していました。現在のイメージでは、これらを単一の cocoindex-data ボリュームに統合しています。新しいイメージを取得する前に、古いコンテナとボリュームを削除してください。インデックスは次回の ccc index 実行時に再構築され、埋め込みモデルは初回起動時に自動的に再配置されます：

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

環境変数による設定

-e を使って、docker run / compose に設定を渡します：

# Extra extensions (e.g. Typesafe Config, SBT build files)
-e COCOINDEX_CODE_EXTRA_EXTENSIONS="conf,sbt"

# Exclude build artefacts (Scala/SBT example)
-e COCOINDEX_CODE_EXCLUDE_PATTERNS='["**/target/**","**/.bloop/**","**/.metals/**"]'

# Set an API key
-e VOYAGE_API_KEY=your-key

セキュリティに関する注意： $HOME をマウントすると、その配下すべてに対する読み書きアクセスをコンテナに与えることになります。範囲が広すぎる場合は、代わりにより限定したディレクトリをバインドマウントしてください（COCOINDEX_HOST_WORKSPACE=/path/to/code）。

イメージをローカルでビルドする

docker build -t cocoindex-code:local -f docker/Dockerfile .

特長

• セマンティックコード検索：grep ではうまくいかない場合に、自然言語のクエリで関連するコードを検索し、すぐにトークンを節約できます。
• 超高性能：⚡ 超高性能な Rust インデックスエンジン を基盤としています。変更されたファイルのみを再インデックスするため、更新が高速です。
• 複数言語のサポート：Python、JavaScript/TypeScript、Rust、Go、Java、C/C++、C#、SQL、Shell などに対応しています。
• 組み込み型：ポータブルで、そのまま動作します。データベースのセットアップは不要です！
• 柔軟な埋め込みモデル：[full] エクストラを使ったローカルの SentenceTransformers（無料、API キー不要！）、または LiteLLM 経由で 100 以上のクラウドプロバイダーを利用できます。

設定

埋め込みモデルの選択と設定に関する詳しいガイドは、EMBEDDINGS.md を参照してください。

設定は 2 つの YAML ファイルに保存され、どちらも ccc init によって自動的に作成されます。

ユーザー設定（~/.cocoindex_code/global_settings.yml）

すべてのプロジェクトで共有されます。埋め込みモデルとデーモンの環境変数を制御します。

embedding:
  provider: sentence-transformers                    # or "litellm"
  model: Snowflake/snowflake-arctic-embed-xs
  device: mps                                        # optional: cpu, cuda, mps (auto-detected if omitted)
  min_interval_ms: 300                               # optional: pace LiteLLM embedding requests to reduce 429s; defaults to 5 for LiteLLM
  mps_low_watermark_ratio: 0.4                       # optional: PyTorch allocator soft limit
  mps_high_watermark_ratio: 0.5                      # optional: PyTorch allocator hard limit

  # Optional extra kwargs passed to the embedder, separately for indexing vs query.
  # `ccc init` auto-populates these for known models (e.g. Cohere, Voyage, Nvidia NIM,
  # nomic-ai code-retrieval models, Snowflake arctic-embed).
  # indexing_params:
  #   input_type: search_document        # litellm: input_type
  # query_params:
  #   input_type: search_query           # sentence-transformers: prompt_name

envs:                                                # extra environment variables for the daemon
  OPENAI_API_KEY: your-key                           # only needed if not already in your shell environment

daemon:
  idle_timeout_minutes: 180                          # optional: exit the daemon after this long without client activity (default 180, 0 = never)
  keep_alive_with_mcp: true                          # optional: keep the daemon warm while an MCP client is connected (default true)

注: デーモンはシェル環境を継承します。API キー（例：OPENAI_API_KEY）がすでに環境変数として設定されている場合、envs に重複して指定する必要はありません。envs フィールドは、環境に設定されていない値にのみ使用します。

Apple Silicon のメモリ安全性: MPS SentenceTransformer の呼び出しでは、CocoIndex の分離された GPU サブプロセスを使用します。これにより、モデルをロードしたまま、Metal のメモリ割り当てをデーモンから分離できます。メモリ使用量の下限と上限は、PyTorch が推奨する最大ワーキングセットに対する比率で、この設定ではそれぞれ 0.4 と 0.5 がデフォルトです。CocoIndex は MPS のメモリ不足エラーが発生すると、バッチサイズを段階的に小さくして再試行します。また、cocoindex-code は各インデックス実行後に未使用のアロケーターキャッシュを解放します。COCOINDEX_RUN_GPU_IN_SUBPROCESS、PYTORCH_MPS_LOW_WATERMARK_RATIO、PYTORCH_MPS_HIGH_WATERMARK_RATIO の環境変数を明示的に設定すると、これらのデフォルト値より優先されます。

インデックス作成の並行処理: 複数のプロジェクトでインデックスを並行して準備できますが、CocoIndex は単一の MPS サブプロセスを通じて GPU 呼び出しを順番に実行します。検索が待機するのは、そのプロジェクトで初回のインデックス作成がまだ必要な場合だけです。

アイドルタイムアウト: バックグラウンドデーモンは埋め込みモデルを RAM に保持するため、クライアントのアクティビティがない状態で daemon.idle_timeout_minutes の時間が経過すると終了し、次回の ccc コマンドまたは MCP 検索時に自動で再起動します。デフォルトでは、コーディングエージェントの接続中、アクティブな MCP セッションが定期的にハートビートを送信し、デーモンを稼働状態に保ちます。長時間続く MCP セッション中にデーモンをアイドル終了させ、実際のリクエストの間にモデルを解放するには、daemon.keep_alive_with_mcp: false を設定します。デーモンを終了せずに実行し続けるには、idle_timeout_minutes: 0 を設定します。

カスタムの保存場所: COCOINDEX_CODE_DIR を設定すると、global_settings.yml を ~/.cocoindex_code/ 以外の場所に配置できます。プロジェクトと同じ場所（同期フォルダーなど）にファイルを置きたい場合に便利です。

indexing_params / query_params

一部の埋め込みモデルは、ドキュメントとクエリで異なるモードを公開しています（非対称検索）。たとえば、Cohere の v3 モデルでは、コーパス内容を埋め込むときは input_type: search_document、ユーザークエリを埋め込むときは input_type: search_query を指定します。いくつかの SentenceTransformers モデルでは、同じ目的で prompt_name: passage / prompt_name: query を使用します。これらの設定項目は indexing_params と query_params の下にあります。

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

ccc init は、認識したモデルに対してこれらを自動的に設定します。対象には、すべての Cohere v3、Voyage、Nvidia NIM、Gemini 埋め込み（gemini/gemini-embedding-*、gemini/text-embedding-*、gemini/embedding-* — LiteLLM は input_type を Gemini の task_type に自動マッピングします）、nomic-ai/CodeRankEmbed、nomic-ai/nomic-embed-code、nomic-ai/nomic-embed-text-v1/v1.5、mixedbread-ai/mxbai-embed-large-v1、および Snowflake/snowflake-arctic-embed-* ファミリーが含まれ、選択されたデフォルト値を出力します。その他のモデルについては、embedding: の下にコメントアウトされたテンプレートを残すので、手動で記入できます。

OpenAI の埋め込み（text-embedding-3-*、text-embedding-ada-002）は意図的にこのリストに含まれていません。これらは対称的で、同等の設定項目が存在しないためです。

受け付けられるキー: prompt_name（sentence Transformers）および input_type（litellm）。その他のキーは、デーモンの起動時に明確なエラーとともに拒否されます。注: dimensions はここでは意図的に公開されていません。出力次元はインデックス作成時とクエリ時で同一でなければならないため、これは片側ごとの設定項目ではなくモデル全体の設定です。

Doctor は両側をチェックします。 ccc doctor は、モデルを indexing_params で一度、query_params で一度実行し、それぞれを別々の Model Check (indexing) / Model Check (query) エントリとして報告します。そのため、片側の設定ミスがもう片方に隠れることなく診断できます。

レガシーブリッジの警告: 以前のバージョンからアップグレードし、global_settings.yml で nomic-ai/CodeRankEmbed または nomic-ai/nomic-embed-code を indexing_params / query_params なしで使用している場合、デーモンは以前の動作（クエリ時に prompt_name: query）を適用し続け、設定を明示するよう求める一度限りの警告を出力します。query_params: {} のような空のブロックを追加することで、警告を黙らせることができます。

プロジェクト設定（<project>/.cocoindex_code/settings.yml）

プロジェクトごとの設定です。インデックスを作成するファイルを指定します。

include_patterns:
  - "**/*.py"
  - "**/*.js"
  - "**/*.ts"
  - "**/*.rs"
  - "**/*.go"
  # ... (sensible defaults for 28+ file types)

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

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

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

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

.cocoindex_code/ は、初期化時に .gitignore に自動で追加されます。

max_file_size を使うと、exclude_patterns に列挙しなくても、バンドルファイルや生成ファイルをインデックスから除外できます。バイト数（1048576）または二進単位の接尾辞（B、KB、MB、GB）を付けたサイズを指定できます（大文字と小文字は区別されないため、500KB と 500 kb は同じです）。上限値は含まれます。このキーを省略すると、サイズに関係なくファイルがインデックスに登録されます。プロジェクトのファイルマッチングが適用されるすべての場所で有効になるため、ccc grep でも同じファイルがスキップされます。

include_patterns、exclude_patterns、max_file_size、または language_overrides を編集した後は、次の操作を行います。

• ccc doctor を実行して、一致するファイルを確認します。
• ccc index または ccc search --refresh ... を実行して、既存のインデックスを更新します。
• これらのファイルマッチング設定の変更では、インデックスを削除したり、デーモンを再起動したりする必要はありません。
• language_overrides を変更すると、次回の実行時に、内容が変更されていないファイルも含め、すべてのファイルが再度チャンク化されます。実行結果では、これらのファイルは再処理済みとして報告されます。テキストに変更のないチャンクでは、キャッシュ済みの埋め込みが保持されます。

カスタムの chunkers を追加または変更した場合、あるいはチャンクモジュールを編集した場合は、デーモンを再起動（ccc daemon restart）してから、ccc index を実行します。デーモンがチャンクをインポートするのは起動時の一度だけなので、再起動するまでは古いチャンクコードが使われます。再起動後の最初の実行では、変更した設定が適用されるファイルだけでなく、すべてのファイルが再度チャンク化されます。テキストに変更のないチャンクでは、キャッシュ済みの埋め込みが保持されます。module: の値が変わった場合、または指定されたモジュールのファイルが変更された場合、そのチャンクは変更されたと見なされます。そのファイルがインポートする他のモジュールへの編集は検出されません。そのような編集をした後は、チャンク自身のモジュールファイルも変更してください（たとえば、ファイル内のバージョンコメントを更新します）。

ファイルの種類ごとに、インデックス作成前のチャンク分割方法を制御するには chunkers を使います。

module: example_toml_chunker:toml_chunker は、次のことを意味します。

• example_toml_chunker はローカルの Python モジュールです。
• toml_chunker は、そのモジュール内の関数です。

通常は、次の手順で設定します。

• プロジェクト内に、たとえば example_toml_chunker.py のような Python ファイルを作成します。
• そのファイル内に関数を追加します。
• module.path:function_name 形式で settings.yml から参照します。

関数は、次のシグネチャを使います。

from pathlib import Path
from cocoindex_code.chunking import Chunk

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

• path は、インデックス作成中のファイルです。
• content は、そのファイルの全文です。
• 言語検出を上書きする場合は、language_override として "toml" のような文字列を返します。
• 検出された言語をそのまま使う場合は、language_override として None を返します。
• インデックスに保存するチャンクを list[Chunk] で返します。

公開型については src/cocoindex_code/chunking.py を、完全な例については tests/example_toml_chunker.py を参照してください。

埋め込みモデル

[full] エクストラをインストールすると、ccc init はローカルの SentenceTransformers モデル（Snowflake/snowflake-arctic-embed-xs）をデフォルトで使用します。API キーは不要です。別のモデルを使用するには、~/.cocoindex_code/global_settings.yml を編集してください。

以下の envs エントリが必要なのは、キーがシェル環境にまだ設定されていない場合のみです。デーモンは環境変数を自動的に継承します。

embedding:
  model: ollama/nomic-embed-text

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

embedding:
  model: openai/your-model-name
envs:
  OPENAI_BASE_URL: https://your-endpoint/v1
  OPENAI_API_KEY: your-api-key

embedding:
  model: azure/your-deployment-name
envs:
  AZURE_API_KEY: your-api-key
  AZURE_API_BASE: https://your-resource.openai.azure.com
  AZURE_API_VERSION: "2024-06-01"

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

embedding:
  model: mistral/mistral-embed
envs:
  MISTRAL_API_KEY: your-api-key

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

embedding:
  model: cohere/embed-v4.0
envs:
  COHERE_API_KEY: your-api-key

embedding:
  model: bedrock/amazon.titan-embed-text-v2:0
envs:
  AWS_ACCESS_KEY_ID: your-access-key
  AWS_SECRET_ACCESS_KEY: your-secret-key
  AWS_REGION_NAME: us-east-1

embedding:
  model: nebius/BAAI/bge-en-icl
envs:
  NEBIUS_API_KEY: your-api-key

LiteLLM がサポートするモデルはどれでも使用できます。LiteLLM モデルを使用する場合は、provider: litellm を設定してください（または provider を省略してください。sentence-transformers 以外のモデルでは LiteLLM がデフォルトです）。各プロバイダーが読み込む環境変数（API キー、ベース URL、リージョンなど）の全一覧については、LiteLLM のAPI キーの設定を参照してください。

ローカル SentenceTransformers モデル

provider: sentence-transformers を設定し、任意の SentenceTransformers モデルを使用してください（API キーは不要です）。

例 — 汎用テキストモデル：

embedding:
  provider: sentence-transformers
  model: nomic-ai/nomic-embed-text-v1.5

GPU 向けに最適化されたコード検索：

nomic-ai/CodeRankEmbed は、デフォルトモデルよりも大幅に優れたコード検索を実現します。パラメーター数は 137M で、約 1 GB の VRAM が必要です。コンテキストウィンドウは 8192 トークンです。

embedding:
  provider: sentence-transformers
  model: nomic-ai/CodeRankEmbed

注意： モデルを切り替えるには、ベクトルの次元が異なるため、コードベースを再インデックスする必要があります（ccc reset && ccc index）。

サポートされている言語

カスタムデータベースの保存場所

デフォルトでは、インデックスデータベース（cocoindex.db と target_sqlite.db）は設定ファイルと同じ <project>/.cocoindex_code/ に保存されます。Docker で実行する場合、ソースコードと設定ファイルはマウントされたボリュームに置いたまま、パフォーマンス向上のためデータベースをコンテナのネイティブファイルシステムに置くことをおすすめします（LMDB はマウントされたボリューム上では適切に動作しません）。

COCOINDEX_CODE_DB_PATH_MAPPING を設定すると、パスのプレフィックスに基づいてデータベースの保存場所を変更できます。

COCOINDEX_CODE_DB_PATH_MAPPING=/workspace=/db-files

このマッピングを使用すると、/workspace/myrepo にあるプロジェクトのデータベースは、/workspace/myrepo/.cocoindex_code/ ではなく /db-files/myrepo/ に保存されます。設定ファイルは元の場所に残ります。

複数のマッピングはカンマで区切って指定し、順に解決されます（最初に一致したものが適用されます）。

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

ソースパスとターゲットパスは、どちらも絶対パスである必要があります。一致するマッピングがない場合は、デフォルトの保存場所が使用されます。

トラブルシューティング

ccc doctor を実行すると、よくある問題を診断できます。設定、デーモンの状態、埋め込みモデル、ファイルのマッチング、インデックスの状態を、1 つのコマンドですべて確認できます。

sqlite3.Connection object has no attribute enable_load_extension

一部の Python インストール（macOS にプリインストールされているものなど）では、SQLite ライブラリの拡張機能が有効になっていません。

macOS での修正方法： Homebrew で Python をインストールします。

brew install python3

次に、cocoindex-code を再インストールします（インストール方法についてははじめにを参照してください）。

pipx を使用する場合：

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

uv を使用する場合（インストールまたはアップグレード）：

uv tool install --upgrade cocoindex-code

MDB_MAP_FULL: Environment mapsize limit reached

インデックスは LMDB データベースに保存されており、最大サイズはデーモンの起動時に固定されます。デフォルトの上限は 4 GiB で、ほとんどのプロジェクトには十分ですが、非常に大規模なコードベース（数万個のファイル）では上限に達することがあります。特に、nomic-ai/CodeRankEmbed のような高次元の埋め込みモデルを使用している場合に発生しやすくなります。

COCOINDEX_LMDB_MAP_SIZE 環境変数で上限を引き上げられます（値は バイト単位です）。LMDB はデータの書き込みに応じてファイルを拡張するため、上限を大きくしてもディスク領域が事前に割り当てられることはありません。余裕を持った値を設定しても安全です。

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

または、シェル環境に設定することもできます（デーモンはこの環境変数を継承します）。

export COCOINDEX_LMDB_MAP_SIZE=$((32 * 1024 * 1024 * 1024))   # 32 GiB

マップサイズはデーモンの起動時に読み込まれるため、変更を反映するにはデーモンを再起動してから、インデックスを再作成してください。

ccc daemon restart
ccc index

この手動での操作は一時的なものです。cocoindex#2108 が取り込まれると、必要に応じてマップサイズが自動的に拡張され、COCOINDEX_LMDB_MAP_SIZE は不要になります。

レガシー：環境変数

以前、環境変数で cocoindex-code を設定していた場合も、cocoindex-code の MCP コマンドは引き続き環境変数を読み取り、初回実行時に YAML 設定へ自動移行します。新しく設定する場合は、YAML 設定への切り替えをおすすめします。

テレメトリ

cocoindex-code は CocoIndex を通じて匿名の利用状況テレメトリを送信します。これにより、ツールの利用状況を全体的な傾向として把握し、改善の優先順位を決定できます。イベントでは application: cocoindex-code として識別されます。

ソースコード、ファイルパス、クエリ、検索結果、埋め込み、設定、その他コードベースや環境に関するコンテンツは収集しません。

オプトアウトするには、次のように設定します。

export COCOINDEX_DISABLE_USAGE_TRACKING=1

大規模なコードベース／エンタープライズ

CocoIndex は、エンタープライズ向けに大規模なコードベースを扱う場合にもスケールする、非常に効率的なインデックスエンジンです。エンタープライズのシナリオでは、リポジトリが大規模または多数ある場合、インデックスをチームメイトと共有すると、はるかに効率的です。また、ブランチの重複排除など、エンタープライズユーザー向けに設計された高度な機能も備えています。

非常に大規模なコードベースをインデックス作成中に MDB_MAP_FULL が発生しましたか？ LMDB のマップサイズを大きくしてください。トラブルシューティングの「MDB_MAP_FULL: Environment mapsize limit reached」をご覧ください。

リモートのセットアップにサポートが必要な場合は、メンテナーの [email protected] までメールでご連絡ください。喜んでお手伝いします！

コントリビューション

コントリビューションを歓迎します！このプロジェクトでは開発に uv を使用しており、すべての PR は CI で同じ lint、フォーマット、型チェック、テストのスイートに合格する必要があります。PR を作成する前に、これらのチェックをローカルで実行してください。受け取った PR で CI が失敗する最も一般的な原因は、pre-commit チェックの失敗です。

1. 開発用の依存関係をインストールする

uv をインストールしたら、プロジェクトを同期してください。これにより、チェックに必要なすべてのもの（高速な pre-commit ランナーの prek、Ruff、mypy、pytest など）がインストールされます。

uv sync

2. PR ごとにすべてのチェックを実行する

すべてのファイルを対象にフック一式を実行してください。これは CI で実行される内容とまったく同じです。

uv run prek run --all-files

末尾の空白やファイル末尾の修正、Ruff による lint（--fix）とフォーマット、uv.lock の検証、mypy による型チェック、pytest スイートが実行されます。報告された問題を修正し（Ruff が lint とフォーマットの問題の大半を自動修正します）、チェックに合格するまで再実行してから、プッシュしてください。

3. （任意）各コミットで自動実行する

git commit のたびに同じチェックを実行するには、git フックを一度インストールしてください。

uv run prek install

詳しくは、コントリビューションガイドをご覧ください。

ライセンス

Apache-2.0