# cocoindex-io/cocoindex-code architecture

> Architecture diagram of the GitHub repository cocoindex-io/cocoindex-code, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cocoindex-io/cocoindex-code
- Repository: https://github.com/cocoindex-io/cocoindex-code

## Overview

Cocoindex Code provides AST-based semantic code search through the `ccc` CLI and MCP integrations. Users initialize project settings, index source files into an embedding-backed SQLite index, then search by natural-language query; a client connects to a shared daemon, which dispatches work to project indexing and query logic. The README also documents agent skill, automatic indexing hooks, literal grep, status/doctor, and custom chunkers. Edges reflect shown imports/calls or README-described integrations; some subsystem internals were not excerpted.

Main entry points: [`src/cocoindex_code/cli.py`](https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/cli.py) (CCC CLI), [`src/cocoindex_code/indexer.py`](https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/indexer.py) (Index flow), [`src/cocoindex_code/project.py`](https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/project.py) (Project manager), [`src/cocoindex_code/query.py`](https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/query.py) (Semantic query)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_skill["CCC agent skill<br/>[SKILL.md]"]
  node_hook["Auto-index hooks<br/>[hooks.json]"]
  node_omp["OMP extension<br/>[ccc-index.ts]"]
  node_cli["CCC CLI<br/>[cli.py]"]
  node_mcp["MCP server<br/>[server.py]"]
end

subgraph group_daemon["Daemon runtime"]
  node_client["Daemon client<br/>[client.py]"]
  node_protocol["IPC protocol<br/>[protocol.py]"]
  node_daemon_core["Daemon dispatcher<br/>[daemon.py]"]
  node_daemon_paths["Daemon paths<br/>[_daemon_paths.py]"]
  node_project["Project manager<br/>[project.py]"]
end

subgraph group_index["Indexing pipeline"]
  node_filewalk["Source file matcher<br/>[file_walk.py]"]
  node_indexer["Index flow<br/>[indexer.py]"]
  node_chunking["Custom chunkers<br/>[chunking.py]"]
  node_embedder["Embedding factory<br/>[shared.py]"]
  node_embed_defaults["Embedding defaults"]
  node_embed_params["Embedding parameters<br/>[embedder_params.py]"]
  node_litellm["LiteLLM embedder"]
  node_sqlite[("SQLite vector index")]
  node_cocoindex["CocoIndex engine"]
end

subgraph group_search["Search and configuration"]
  node_settings["Project settings<br/>[settings.py]"]
  node_query["Semantic query<br/>[query.py]"]
  node_grep["Literal grep<br/>[grep.py]"]
  node_schema["Query schema<br/>[schema.py]"]
end

node_user(("Developer or agent"))

node_user -->|"invokes"| node_skill
node_skill -->|"runs commands"| node_cli
node_user -->|"runs"| node_cli
node_hook -.->|"triggers indexing"| node_cli
node_omp -->|"triggers indexing"| node_cli
node_cli -->|"requests work"| node_client
node_mcp -->|"delegates requests"| node_client
node_client -->|"resolves socket"| node_daemon_paths
node_client -->|"encodes requests"| node_protocol
node_daemon_core -->|"decodes messages"| node_protocol
node_daemon_core -->|"dispatches project work"| node_project
node_daemon_core -->|"loads configuration"| node_settings
node_project -->|"builds index flow"| node_indexer
node_project -->|"runs search"| node_query
node_project -->|"configures runtime"| node_cocoindex
node_indexer -->|"selects source files"| node_filewalk
node_indexer -->|"uses chunkers"| node_chunking
node_indexer -->|"embeds chunks"| node_embedder
node_indexer -.->|"writes vectors"| node_sqlite
node_query -->|"embeds query"| node_embedder
node_query -->|"searches vectors"| node_sqlite
node_query -->|"uses result schema"| node_schema
node_embedder -->|"creates provider"| node_litellm
node_embed_params -->|"uses defaults"| node_embed_defaults
node_embed_params -->|"reads settings"| node_settings
node_cli -->|"runs literal search"| node_grep
node_grep -->|"walks matching files"| node_filewalk
node_user -->|"uses MCP search"| node_mcp

click node_skill "https://github.com/cocoindex-io/cocoindex-code/blob/main/skills/ccc/SKILL.md"
click node_hook "https://github.com/cocoindex-io/cocoindex-code/blob/main/hooks/hooks.json"
click node_omp "https://github.com/cocoindex-io/cocoindex-code/blob/main/extensions/ccc-index.ts"
click node_cli "https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/cli.py"
click node_mcp "https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/server.py"
click node_client "https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/client.py"
click node_protocol "https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/protocol.py"
click node_daemon_core "https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/daemon.py"
click node_daemon_paths "https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/_daemon_paths.py"
click node_project "https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/project.py"
click node_settings "https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/settings.py"
click node_filewalk "https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/file_walk.py"
click node_indexer "https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/indexer.py"
click node_chunking "https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/chunking.py"
click node_embedder "https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/shared.py"
click node_embed_defaults "https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/embedder_defaults.py"
click node_embed_params "https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/embedder_params.py"
click node_litellm "https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/litellm_embedder.py"
click node_query "https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/query.py"
click node_grep "https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/grep.py"
click node_schema "https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/schema.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_skill,node_hook,node_omp,node_cli,node_mcp toneBlue
class node_client,node_protocol,node_daemon_core,node_daemon_paths,node_project toneAmber
class node_filewalk,node_indexer,node_chunking,node_embedder,node_embed_defaults,node_embed_params,node_litellm,node_sqlite,node_cocoindex toneMint
class node_settings,node_query,node_grep,node_schema toneRose
class node_user toneIndigo
```

## Components

### User interfaces

- [CCC agent skill](https://github.com/cocoindex-io/cocoindex-code/blob/main/skills/ccc/SKILL.md): `skills/ccc/SKILL.md`
- [Auto-index hooks](https://github.com/cocoindex-io/cocoindex-code/blob/main/hooks/hooks.json): `hooks/hooks.json`
- [OMP extension](https://github.com/cocoindex-io/cocoindex-code/blob/main/extensions/ccc-index.ts): `extensions/ccc-index.ts`
- [CCC CLI](https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/cli.py): `src/cocoindex_code/cli.py`
- [MCP server](https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/server.py): `src/cocoindex_code/server.py`

### Daemon runtime

- [Daemon client](https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/client.py): `src/cocoindex_code/client.py`
- [IPC protocol](https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/protocol.py): `src/cocoindex_code/protocol.py`
- [Daemon dispatcher](https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/daemon.py): `src/cocoindex_code/daemon.py`
- [Daemon paths](https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/_daemon_paths.py): `src/cocoindex_code/_daemon_paths.py`
- [Project manager](https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/project.py): `src/cocoindex_code/project.py`

### Indexing pipeline

- [Source file matcher](https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/file_walk.py): `src/cocoindex_code/file_walk.py`
- [Index flow](https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/indexer.py): `src/cocoindex_code/indexer.py`
- [Custom chunkers](https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/chunking.py): `src/cocoindex_code/chunking.py`
- [Embedding factory](https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/shared.py): `src/cocoindex_code/shared.py`
- [Embedding defaults](https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/embedder_defaults.py): `src/cocoindex_code/embedder_defaults.py`
- [Embedding parameters](https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/embedder_params.py): `src/cocoindex_code/embedder_params.py`
- [LiteLLM embedder](https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/litellm_embedder.py): `src/cocoindex_code/litellm_embedder.py`
- **SQLite vector index**
- **CocoIndex engine**

### Search and configuration

- [Project settings](https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/settings.py): `src/cocoindex_code/settings.py`
- [Semantic query](https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/query.py): `src/cocoindex_code/query.py`
- [Literal grep](https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/grep.py): `src/cocoindex_code/grep.py`
- [Query schema](https://github.com/cocoindex-io/cocoindex-code/blob/main/src/cocoindex_code/schema.py): `src/cocoindex_code/schema.py`

### Other components

- **Developer or agent**

## Connections

- Developer or agent → CCC agent skill: invokes (evidence: `README.md`)
- CCC agent skill → CCC CLI: runs commands (evidence: `README.md`)
- Developer or agent → CCC CLI: runs (evidence: `README.md`)
- Auto-index hooks → CCC CLI: triggers indexing (evidence: `README.md`)
- OMP extension → CCC CLI: triggers indexing (evidence: `README.md`)
- CCC CLI → Daemon client: requests work (evidence: `src/cocoindex_code/cli.py`)
- MCP server → Daemon client: delegates requests (evidence: `src/cocoindex_code/server.py`)
- Daemon client → Daemon paths: resolves socket (evidence: `src/cocoindex_code/_daemon_paths.py`)
- Daemon client → IPC protocol: encodes requests (evidence: `src/cocoindex_code/client.py`)
- Daemon dispatcher → IPC protocol: decodes messages (evidence: `src/cocoindex_code/daemon.py`)
- Daemon dispatcher → Project manager: dispatches project work (evidence: `src/cocoindex_code/daemon.py`)
- Daemon dispatcher → Project settings: loads configuration (evidence: `src/cocoindex_code/daemon.py`)
- Project manager → Index flow: builds index flow (evidence: `src/cocoindex_code/project.py`)
- Project manager → Semantic query: runs search (evidence: `src/cocoindex_code/project.py`)
- Project manager → CocoIndex engine: configures runtime (evidence: `src/cocoindex_code/project.py`)
- Index flow → Source file matcher: selects source files (evidence: `src/cocoindex_code/indexer.py`)
- Index flow → Custom chunkers: uses chunkers (evidence: `src/cocoindex_code/indexer.py`)
- Index flow → Embedding factory: embeds chunks (evidence: `src/cocoindex_code/indexer.py`)
- Index flow → SQLite vector index: writes vectors
- Semantic query → Embedding factory: embeds query (evidence: `src/cocoindex_code/query.py`)
- Semantic query → SQLite vector index: searches vectors (evidence: `src/cocoindex_code/query.py`)
- Semantic query → Query schema: uses result schema (evidence: `src/cocoindex_code/query.py`)
- Embedding factory → LiteLLM embedder: creates provider (evidence: `src/cocoindex_code/shared.py`)
- Embedding parameters → Embedding defaults: uses defaults (evidence: `src/cocoindex_code/embedder_params.py`)
- Embedding parameters → Project settings: reads settings (evidence: `src/cocoindex_code/embedder_params.py`)
- CCC CLI → Literal grep: runs literal search (evidence: `src/cocoindex_code/cli.py`)
- Literal grep → Source file matcher: walks matching files (evidence: `src/cocoindex_code/grep.py`)
- Developer or agent → MCP server: uses MCP search (evidence: `README.md`)