CocoIndex Code
Embedded AST-based semantic and structural search for code agents.
- Source repo
- cocoindex-io/cocoindex-code
- Stars
- ★ 3k
- Last updated
- 2d ago
- License
- Apache-2.0
- Primary language
- Python
- FA score
- 66/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code · OpenAI API
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A developer joining an unfamiliar Python, TypeScript, or Rust repository who needs to find session handling from a natural-language description.
- Not a fit if
- Teams relying on Docker for local embeddings on macOS, where Metal GPU is unavailable
- Users who need ccc grep now; it requires a local CocoIndex build
- Source review
- 66/100 · Some gaps
What does this agent do, and when should you use it?
CocoIndex Code is an embedded semantic code-search CLI built on CocoIndex’s Rust indexing engine. Its ccc commands initialize a project, build or incrementally update an index, and return matching chunks with paths, languages, source, line numbers, and similarity scores. It can also run as the ccc mcp stdio server for Codex, Claude Code, OpenCode, and Kilo Code, while the installable ccc skill guides compatible coding agents to use the CLI. Project settings and index databases live by default under .cocoindex_code, and a background daemon starts on first use to keep the embedding model loaded. It supports native Python-based installation or a persistent Docker deployment.
ccc init creates global and project YAML settings and adds .cocoindex_code/ to .gitignore. ccc index builds or updates the semantic index; the documented behavior is to re-index changed files only. ccc search <query> performs similarity search with --lang, --path, --offset, --limit, and --refresh options. ccc grep <pattern> performs syntax-structure matching through CocoIndex code_match without an index, daemon, or embedding model. ccc mcp exposes search(query, limit, offset, refresh_index, languages, paths), returning matching code chunks and their metadata. Embeddings can come from local SentenceTransformers or cloud providers accessed through LiteLLM.
- A developer joining an unfamiliar Python, TypeScript, or Rust repository who needs to find session handling from a natural-language description.
- A Codex or Claude Code user who wants an MCP search tool to retrieve relevant code chunks during an agent session.
- A maintainer who does not know an implementation’s exact identifier and needs conceptual retrieval beyond text grep.
- A developer looking for function definitions, calls, or class shapes who can express the target as a ccc grep structural pattern.
- A team that wants a reproducible environment can run the persistent Docker container so its daemon and model cache remain warm.
How do you install or deploy this agent?
For local embeddings without an API key:
pipx install 'cocoindex-code[full]'Or:
uv tool install --upgrade 'cocoindex-code[full]'From the target repository, run:
ccc init
ccc index
ccc search "authentication logic"The [full] extra defaults to local Snowflake/snowflake-arctic-embed-xs. The slim cocoindex-code installation requires a cloud embedding provider and its API key.
How do you use this agent?
Search directly with ccc search "database schema". Filter languages with ccc search --lang python --lang markdown schema, or refresh first with ccc search --refresh "query handler". For structural search, use ccc grep 'def \NAME(\(ARGS*\)):'. Register the MCP server in Codex with codex mcp add cocoindex-code -- ccc mcp. The MCP search tool accepts query, limit, offset, refresh_index, languages, and paths. To install the agent skill, run npx skills add cocoindex-io/cocoindex-code.
What are this agent's strengths and limitations?
- Combines semantic retrieval with ccc grep AST structural search, which does not require an index or embeddings.
- Provides a documented stdio MCP server with a defined search tool for direct Codex and Claude Code integration.
- Supports local SentenceTransformers as well as multiple LiteLLM-backed cloud providers; the default local model needs no API key.
- Keeps indexes in the project and uses a background daemon to hold the model warm; the Docker option keeps that daemon alive across sessions.
- The full native install adds roughly 1 GB of torch and transformers dependencies, while the full Docker image is approximately 5 GB.
- The slim installation requires a cloud embedding provider and API key, adding network and provider-configuration dependencies.
- Changing embedding models requires ccc reset && ccc index because vector dimensions can differ.
- ccc grep depends on CocoIndex code_match; the documentation says a local CocoIndex build is needed until that feature is released.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| CocoIndex Code This agent | 66 · Some gaps | CLIFree + model costs | ★ 3k | 2d ago | Python | Codex · Claude Code · OpenAI API |
| Claude Context — Semantic Code Search MCP for AI Coding Agents | 59 · Major gaps | MCP serverFree + model costs | ★ 13k | 3mo ago | TypeScript | Codex · Claude Code · OpenAI API |
| AOCI-CODE — a Git-versioned cognition index for coding agents | 82 · Good | CLIFree + model costs | ★ 1.9k | 1d ago | Go | Codex · Claude Code |
| Arbor Research Optimizer | 63 · Some gaps | CLIFree + model costs | ★ 1.1k | 5d ago | Python | Codex · Claude Code · OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
The CLI, Skill, and MCP are centered on indexing and searching the current codebase. The README describes default working-directory scope, configuration, optional local or cloud embeddings, and Docker mount scope; it warns that mounting all of HOME grants the container read/write access. `ccc reset` has confirmation behavior with `-f` to skip it, but `ccc index`, MCP search refresh, and plugin edit hooks read or update the index, with no evidence of per-operation confirmation or a complete sensitive-data policy. Dependencies have version ranges but no supplied audit evidence. The daemon, model downloads, and cloud providers imply external effects that are only partly described. Reset can delete indexes and `--all` also removes settings; recovery requires rebuilding. Repository metadata names an author and repository, but publisher identity is unverified, so attribution is limited.
The README, Skill, CLI/MCP descriptions, and implementation excerpts broadly align on initialization, search, refresh, and daemon behavior; the static sample does not cover every implementation detail. The core CocoIndex dependency is constrained to the 1.0.x range, while other dependencies use lower bounds, and evidence about availability or compatibility coverage is limited. The CLI provides errors for missing settings, daemon startup failure, and search failure; MCP catches exceptions and returns a failure result. The excerpts do not support a thorough score for error recovery.
Documentation gives concrete developer scenarios for Claude Code, Grok, Oh My Pi, MCP, direct CLI, Docker, cloud embeddings, and local embeddings. Language and path filters, pagination, and Skill trigger conditions are explicit. Capability boundaries are partly documented: semantic search depends on an index and embeddings, while structural search runs locally but relies on an unreleased CocoIndex feature. Multiple install and runtime environments are covered, though Python, Docker, model size, and platform differences add adaptation costs.
The README is organized around installation, integrations, CLI, Docker, configuration, and features, with platform-specific setup, command examples, management guidance, and limitations. CLAUDE.md is repository contributor guidance, not product instructions. Command and plugin names are mostly stable, though the package, CLI, plugin, and legacy entry point coexist. The license file matches project metadata. The sample includes VCS versioning and a release workflow, but no clear user-facing changelog evidence. Security contact and fix scope are stated, while ongoing maintenance responsibility and response commitments are limited.
Search results provide file, language, code, line numbers, and similarity score; CLI/MCP support result limits, pagination, and filters. `ccc grep` adds structural search without requiring an index. The README claims token savings and quick setup, but the supplied evidence does not quantify those claims. Local embeddings require roughly 1 GB of dependencies or a roughly 5 GB Docker image; cloud use requires credentials, so the benefit depends on usage and resource costs.
Some README commands, options, and result fields correspond to the Skill, CLI, MCP implementation, package metadata, and test fixtures; CI and release workflows also support descriptions of project and release structure. The token-savings and setup-time claims are not verified by the supplied material. The sample covers only part of the code, and test fixtures do not establish that tests passed. Scores therefore reflect traceable static evidence without treating claims as verified outcomes.
- The Docker quick start mounts all of HOME with read/write access; use a narrower bind mount when that scope is too broad.
- Semantic search may send code to the configured cloud embedding provider. Review provider and credential settings; local embeddings use substantial storage and compute.
- `ccc reset --all` removes project settings, and structural search depends on a CocoIndex feature described as not yet released.
Maintain this project? Add the FARS badge to your README
[](https://followagents.com/en/agents/cocoindex-code)<a href="https://followagents.com/en/agents/cocoindex-code"><img src="https://followagents.com/badge/cocoindex-code.svg" alt="FARS review"></a>Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
What's Changed * fix(indexer): reprocess unchanged files when chunking config changes by @L4XB in https://github.com/cocoindex-io/cocoindex-code/pull/287 * fix(daemon): guard socket unlinking on shutdown by checking bound node identity by @pranav440 in https://github.com/cocoindex-io/cocoindex-code/pull/291 * fix(indexer): fingerprint chunkers at import time, pass language overrides as memo arg by @georgeh0 in https://github.com/cocoindex-io/cocoindex-code/pull/299 …View on GitHub ↗ -
Release notes excerpt
What's Changed * Add Oh My Pi marketplace catalog by @MickaelV0 in https://github.com/cocoindex-io/cocoindex-code/pull/277 * feat: add Elixir language support by @dclausen in https://github.com/cocoindex-io/cocoindex-code/pull/279 * feat(omp): session-start and post-edit index hooks by @MickaelV0 in https://github.com/cocoindex-io/cocoindex-code/pull/281 * chore(deps): bump transformers from 5.5.0 to 5.10.1 by @dependabot[bot] in https://github.com/cocoindex-io/cocoindex-code/pull/282 …View on GitHub ↗ -
Release notes excerpt
What's Changed * fix(search): surface daemon tracebacks and reject NULL KNN distances by @georgeh0 in https://github.com/cocoindex-io/cocoindex-code/pull/271 Full Changelog: https://github.com/cocoindex-io/cocoindex-code/compare/v0.2.40...v0.2.41View on GitHub ↗
FAQ
Do I need a cloud API or paid embedding model?
Does it read or send my source code?
Must the index be rebuilt manually after every edit?
What does MCP search return?
Thanks — we use this to improve the page.