cocoindex-code: an AST-based code search CLI for coding agents
A super light-weight embedded code search engine CLI (AST based) that just works - improves speed and efficiency for coding agent 🌟 Star if you like it!
At a glance
- What is it?
- cocoindex-code wraps CocoIndex into a `ccc` CLI that indexes a repository, returns AST-aware search results, and plugs into Claude Code or Grok through a skill, hooks or an MCP server. It is a good fit if you want semantic code search without writing a config file; it is the wrong tool if your team cannot run a local embedding model or will not keep an index on disk.
- Who is it for?
- Adopt cocoindex-code if you drive Claude Code or Grok and want semantic code search without a config file: the `ccc` skill handles `ccc init` and `ccc index` for you. Do not adopt it if you cannot run a local embedding model and do not want a cloud embedding provider, or if you need a query language with filters rather than natural-language search.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 7 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem: agents burn context on grep-shaped searches
A coding agent that wants to know how user sessions are managed has two bad options. It can read files until it finds the answer, which spends context on code it will not use. Or it can run a text search and get back matches that are syntactically similar but semantically unrelated. cocoindex-code targets that gap. The README describes it as a "lightweight, effective (AST-based) semantic code search tool for your codebase", and the stated goal is "Instant token saving by 70%". That figure comes from the project's own README, not from an independent measurement, so treat it as a claim rather than a verified number. The intended user is someone running a coding agent on a repository large enough that naive file reading is expensive, and who wants the agent to reach for semantic search on its own. The README also frames the setup cost as "1 min setup - install and go, zero config needed", which is the real pitch: not a better search algorithm, but a search tool an agent can adopt without a human writing a config file first.
What the index actually is: CocoIndex, ASTs and local embeddings
cocoindex-code is a thin CLI over CocoIndex, which the README calls a "Rust-based ultra performant data transformation engine". The repository topics list tree-sitter alongside ast, so parsing is AST-based rather than line-based, and the search layer is embedding-based rather than keyword-based. The README does not spell out the embedding model in the body text, but the install section names the default: the `ccc init` interactive prompt defaults to Snowflake/snowflake-arctic-embed-xs, pulled in through sentence-transformers when you install the `full` extra. That is the mechanism in one sentence: parse source into syntax units, embed them locally, and let the agent query by meaning. The index lives in a `.cocoindex_code/` directory, which the README references as the trigger condition for incremental reindexing. The README does not document the on-disk format or the size of that directory, so if repository footprint matters to you, that is something to check yourself after the first `ccc index` run. The Python repository is the CLI and integration layer; the Rust engine underneath is a separate project, cocoindex-io/cocoindex, which the README links and asks you to star.
Installing it: pipx, uv and the full versus slim split
The README gives two install paths. With pipx: `pipx install 'cocoindex-code[full]'` followed by `pipx upgrade cocoindex-code`. With uv: `uv tool install --upgrade 'cocoindex-code[full]'`. The extra matters. `cocoindex-code[full]` is described as "batteries-included" and pulls in sentence-transformers so local embeddings work with no API key. The slim `cocoindex-code` package is "LiteLLM-only; requires a cloud embedding provider and API key", and the README recommends it when you do not want the roughly 1 GB of torch and transformers that the local path brings. That is the first real decision a team has to make, and it is a dependency-weight decision, not a feature decision. Note the README's own framing that the two install styles "mirror the Docker image variants of the same names", which suggests the same split exists on the container side. The README does not list the exact Python version supported, so check the package metadata before assuming your interpreter qualifies.
Wiring it into Claude Code or Grok: skill, hooks, MCP
The recommended integration is the skill, installed with `npx skills add cocoindex-io/cocoindex-code`. The README says that after this, "no `ccc init` or `ccc index` needed" because the skill teaches the agent to initialize, index and search on its own, and to keep the index current. You can also invoke it explicitly with `/ccc` or by asking the agent to search the codebase. For Claude Code there is a second path through the plugin marketplace: `/plugin marketplace add cocoindex-io/cocoindex-code` then `/plugin install cocoindex-code@cocoindex-code`, which the README says adds version pinning and `/plugin marketplace update`. Grok users install with `grok plugin marketplace add cocoindex-io/cocoindex-code`, `grok plugin install cocoindex-io/cocoindex-code --trust`, then `grok plugin enable cocoindex-code`. The `--trust` flag is required for Grok to activate hooks and the MCP server. The README explicitly warns that Grok "does not import Claude's `enabledPlugins` or plugin cache", so a team running both agents installs twice. The three Grok components are the skill in `skills/ccc/`, a hook file at `hooks/hooks.json` that fires on `SessionStart` and `PostToolUse` for Edit and Write operations to run an incremental `ccc index` when `.cocoindex_code/` exists, and `.mcp.json` which exposes a `search` tool with `refresh_index=true` by default. The README also notes a rough edge: prefer the `cocoindex-io/cocoindex-code` shorthand for Grok installs, because `grok plugin install cocoindex-code` can fail when no marketplace plugin matches the bare name.
Where the design strains: hooks, trust and unstated limits
The hook design is the part worth scrutinizing. Reindexing after every Edit or Write is convenient, and the README scopes it to incremental indexing when `.cocoindex_code/` exists, but the README does not state how long an incremental pass takes on a large repository or whether it can queue up behind rapid edits. It also does not say what happens when the hook fails, or whether a failed reindex leaves the index stale rather than absent. Those are the questions a team should answer before enabling hooks on a shared machine, because a silently stale index is worse for an agent than no index at all. The second strain is the trust boundary: Grok requires `--trust` to activate hooks and MCP, which is a deliberate gate, and the README's skill-only path for Grok asks you to open `/hooks` and disable the optional components. The README snippet is truncated at that point, so the exact steps for disabling hooks are not fully visible in the supplied material. The third strain is the dependency split itself. If a team cannot run local embeddings and does not want a cloud embedding provider, the slim package is not a lighter version of the same tool, it is a different deployment with an external API dependency and a key to manage.
How it differs from ripgrep, ctags and a plain MCP filesystem server
The closest everyday alternative is ripgrep. ripgrep matches text; it has no notion of what a symbol means, so a search for session handling returns every file containing the word session, including tests, fixtures and vendored copies. cocoindex-code instead parses with tree-sitter and ranks by embedding similarity, so the query is natural language and the ranking is semantic. The cost of that difference is everything ripgrep does not need: an index directory, an embedding model, a first `ccc index` pass, and a reindex step after edits. A second alternative is a language server or ctags index exposed to the agent over MCP. Those give precise symbol lookup and go-to-definition, which is a different question from "find how user sessions are managed". If your agent's failures are mostly about jumping to a known symbol, a ctags or LSP-backed MCP server is a better match and has no embedding dependency. If the failures are about finding code the agent does not yet know the name of, cocoindex-code's approach fits the problem. The README positions the tool against that second failure mode, and the token-saving claim is really a claim about retrieval precision, not about search speed.
Licence, releases and what maintenance looks like
cocoindex-code is Apache-2.0, the same licence the README badge points to. Apache-2.0 is permissive and includes an explicit patent grant, but this is not legal advice and your organisation's policy on bundled model weights and transitive dependencies is a separate question from the licence of the CLI itself. Note that the `full` extra pulls sentence-transformers and torch, and the default embedding model is a Hugging Face artifact with its own licence terms; the README does not state those terms, so check them if redistribution matters to you. On release cadence, the supplied release list shows v0.2.41 on 2026-08-07, v0.2.40 on 2026-08-06 and v0.2.39 on 2026-07-24, with the last push to the default branch on 2026-09-08. That is a fast patch cadence on a 0.x version, which means API and CLI surface can move between minor releases. The README documents `pipx upgrade cocoindex-code` and `uv tool install --upgrade` for the CLI, and `/plugin marketplace update` for the Claude Code plugin path, so upgrades are covered. What the README does not cover is index migration: if a future release changes the embedding model or the on-disk format under `.cocoindex_code/`, it is not stated whether an existing index is rebuilt automatically or must be deleted. That is the upgrade risk to watch, and it is the reason to pin the plugin version rather than track the latest release on every machine.
Editorial conclusion
Adopt cocoindex-code if you drive Claude Code or Grok and want semantic code search without a config file: the `ccc` skill handles `ccc init` and `ccc index` for you. Do not adopt it if you cannot run a local embedding model and do not want a cloud embedding provider, or if you need a query language with filters rather than natural-language search. Before rolling it out, verify the `cocoindex-code` slim versus `cocoindex-code[full]` install path on one machine, check what `.cocoindex_code/` adds to your repository size, and confirm that your agent's hook and MCP behaviour matches the plugin table in the README.
Community notes