Ccc

ccc - Semantic Code Search & Indexing

ccc is the CLI for CocoIndex Code, providing semantic search over the current codebase and index management.

Ownership

The agent owns the ccc lifecycle for the current project — initialization, indexing, and searching. Do not ask the user to perform these steps; handle them automatically.

• Initialization: If ccc search or ccc index fails with an initialization error (e.g., "Not in an initialized project directory"), run ccc init from the project root directory, then ccc index to build the index, then retry the original command.
• Index freshness: Keep the index up to date by running ccc index (or ccc search --refresh) when the index may be stale — e.g., at the start of a session, or after making significant code changes (new files, refactors, renamed modules). There is no need to re-index between consecutive searches if no code was changed in between.
• Installation: If ccc itself is not found (command not found), refer to management.md for installation instructions and inform the user.

Searching the Codebase

To perform a semantic search:

ccc search <query terms>

The query should describe the concept, functionality, or behavior to find, not exact code syntax. For example:

ccc search database connection pooling
ccc search user authentication flow
ccc search error handling retry logic

Filtering Results

• By language (--lang, repeatable): restrict results to specific languages.

  ccc search --lang python --lang markdown database schema

• By path (--path): restrict results to a glob pattern relative to project root. If omitted, defaults to the current working directory (only results under that subdirectory are returned).

  ccc search --path 'src/api/*' request validation

Pagination

Results default to the first page. To retrieve additional results:

ccc search --offset 5 --limit 5 database schema

If all returned results look relevant, use --offset to fetch the next page — there are likely more useful matches beyond the first page.

Working with Search Results

Search results include file paths and line ranges. To explore a result in more detail:

• Use the editor's built-in file reading capabilities (e.g., the Read tool) to load the matched file and read lines around the returned range for full context.
• When working in a terminal without a file-reading tool, use sed -n '<start>,<end>p' <file> to extract a specific line range.

Settings

To view or edit embedding model configuration, include/exclude patterns, or language overrides, see settings.md.

Management & Troubleshooting

For installation, initialization, daemon management, troubleshooting, and cleanup commands, see management.md.

ccc Management

Installation

Install CocoIndex Code via pipx. Two install styles:

pipx install 'cocoindex-code[full]'      # batteries included (local embeddings via sentence-transformers)
pipx install cocoindex-code              # slim (LiteLLM-only; requires a cloud embedding provider + API key)

The [full] extra pulls in sentence-transformers so the first-run default (local embeddings, no API key) works out of the box. The slim install is for environments where you don't want the torch/transformers deps and plan to use a LiteLLM-supported cloud provider instead.

To upgrade to the latest version:

pipx upgrade cocoindex-code

After installation, the ccc command is available globally.

Project Initialization

Run from the root directory of the project to index:

ccc init

First run (global settings don't exist yet) — ccc init prompts interactively for the embedding provider (sentence-transformers / litellm) and model, then runs a one-off test embed via the daemon to confirm the model works. Accept the defaults for the sentence-transformers path, or pick litellm and enter a model identifier.

Subsequent runs (global settings already exist) — prompts are skipped; only project settings and .gitignore are set up.

To skip the interactive prompts on the first run (e.g. in a script or container), pass --litellm-model MODEL:

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

This is also the only way to pick a LiteLLM model when stdin isn't a TTY and you've done a slim install.

ccc init creates:

• ~/.cocoindex_code/global_settings.yml (user-level, embedding config + env vars).
• .cocoindex_code/settings.yml (project-level, include/exclude patterns).

If .git exists in the directory, .cocoindex_code/ is automatically added to .gitignore.

Use -f to skip the confirmation prompt if ccc init detects a potential parent project root.

After initialization, edit the settings files if needed (see settings.md for format details), then run ccc index to build the initial index. If the model test printed [FAIL] during init, edit global_settings.yml (and optionally add API keys under the commented envs: block) and verify with ccc doctor before indexing.

Troubleshooting

Diagnostics

Run ccc doctor to check system health end-to-end:

ccc doctor

This checks global settings, daemon status, embedding model (runs a test embedding), and — if run from within a project — file matching (walks files using the same logic as the indexer) and index status. Results stream incrementally. Always points to daemon.log at the end for further investigation.

Checking Project Status

To view the current project's index status:

ccc status

This shows whether indexing is ongoing and index statistics.

Daemon Management

The daemon starts automatically on first use. To check its status:

ccc daemon status

This shows whether the daemon is running, its version, uptime, and loaded projects.

To restart the daemon (useful if it gets into a bad state):

ccc daemon restart

To stop the daemon:

ccc daemon stop

Cleanup

To reset a project's index (removes databases, keeps settings):

ccc reset

To fully remove all CocoIndex Code data for a project (including settings):

ccc reset --all

Both commands prompt for confirmation. Use -f to skip.

ccc Settings

Configuration lives in two YAML files, both created automatically by ccc init.

User-Level Settings (~/.cocoindex_code/global_settings.yml)

Shared across all projects. Controls the embedding model and extra environment variables for the daemon.

embedding:
  provider: sentence-transformers   # or "litellm" (default when provider is omitted)
  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

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

Fields

Embedding Model Examples

Local (sentence-transformers, no API key needed):

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

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

Ollama (local):

embedding:
  model: ollama/nomic-embed-text

OpenAI:

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

Gemini:

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

Voyage (code-optimized):

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

For the full list of supported cloud providers and model identifiers, see LiteLLM Embedding Models.

Important

Switching embedding models changes vector dimensions — you must re-index after changing the model:

ccc reset && ccc index

Project-Level Settings (<project>/.cocoindex_code/settings.yml)

Per-project. Controls which files to index. Created by ccc init and automatically added to .gitignore.

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

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

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

Fields

Editing Tips

• To index additional file types, append glob patterns to include_patterns (e.g. "**/*.proto").
• To exclude a directory, append to exclude_patterns (e.g. "**/generated").
• After editing, run ccc index to re-index with the new settings.