hybrid-coco

Local code intelligence for AI agents. Index your codebase once, query it deterministically: ~94% fewer tokens than grep + cat.

hybrid-coco builds a local SQLite index of your source code using tree-sitter, exposes it via a CLI and an MCP server, and integrates with Claude Code via hooks. No embeddings, no vector database, no Docker. One install command.

pip install hybrid-coco && hc init

The problem it solves

When Claude reads a file to find one function, it pays for the entire file:

# Without hybrid-coco
Read("src/gitlab_helpers.py")             >  12,140 tokens  (whole file)

# With hybrid-coco
hc_file_context("src/gitlab_helpers.py")  >  297 tokens  (symbols only)  < 97.6% savings

The hook intercepts Read and Grep calls and suggests the equivalent hc_* tool. Same answer, fraction of the tokens.

How it works

Source files  ──tree-sitter──►  SQLite + FTS5  ──►  CLI (hc)
                                     │
                                     └──────────────►  MCP server (hc_*)
                                                           │
                                                    Claude Code hooks
                                                    intercept Read/Grep
                                                    > suggest hc_* tools

1. hc index .: parses every source file with tree-sitter, extracts symbols (functions, classes, methods, imports) with their signatures, docstrings, and line numbers into a FTS5 trigram index
2. hc query / symbol / file-context: queries the index and returns only what's relevant, not the whole file
3. hc serve: exposes the same queries as MCP tools (hc_search, hc_symbol, hc_file_context, hc_status) for Claude Code
4. Hooks: hc init registers PreToolUse/PostToolUse hooks that suggest hc_* tools whenever Claude is about to Read or Grep an indexed file

Benchmark

Measured on a real Rust codebase: 76 files, 2,242 symbols:

Traditional = grep -rn + cat. hybrid-coco = hc symbol + hc query + hc file-context.

Quickstart

1. Install

Option A: One-line installer (recommended)

curl -fsSL https://raw.githubusercontent.com/jmeiracorbal/hybrid-coco/main/install.sh | bash

Installs hc, configures Claude Code hooks, and adds the awareness file. Requires Python 3.11+ (detects uv, pipx, or pip automatically).

Option B: Claude Code plugin

claude plugin marketplace add jmeiracorbal/hybrid-coco
claude plugin install hybrid-coco@hybrid-coco

Registers the MCP server and hooks automatically. Requires hc in PATH — install the package first:

pip install hybrid-coco   # or: uv tool install hybrid-coco

2. Index your project and register with Claude Code

cd your-project/
hc init

hc init does three things:

• Indexes the current directory (tree-sitter, SHA-256 incremental)
• Registers the MCP server in .claude/settings.json
• Installs global hooks in ~/.claude/hooks/ that intercept Read and Grep

Restart Claude Code to activate.

3. Use from Claude Code

The MCP tools are now available in every conversation:

hc_search("savings_pct")       # FTS5 search over names, signatures, docstrings
hc_symbol("TimedExecution")    # exact/prefix symbol lookup
hc_file_context("src/git.rs")  # all symbols in a file, structured
hc_status()                    # index stats

The hooks will remind you (via stderr) whenever Claude is about to read an indexed file directly.

CLI reference

hc index [PATH] [--exclude PATTERN]...
                         Index PATH (default: cwd); optional exclude patterns
hc update [PATH] [--exclude PATTERN]...
                         Re-index only changed files (SHA-256 diff)
hc status [PATH]         Index stats: files, symbols by kind, last update
hc query <TEXT> [--path P] [--lang L]... [--offset N] [--limit N]
                         FTS5 search; optional path/lang filters and pagination
hc symbol <NAME> [--path P] [--lang L]... [--offset N] [--limit N]
                         Exact name lookup, then prefix; same filters as query
hc file-context <PATH>   All symbols in PATH grouped by kind (~97% savings vs cat)
hc doctor [PATH]         Diagnostics: index, schema, languages, MCP/hooks, versions
hc reset [PATH] [-f] [--all]
                         Delete index DB; --all also drops project MCP entry
hc serve                 Start MCP server (stdio)
hc init [PATH]           Index + .gitignore entry + register MCP + install hooks

--exclude accepts gitignore-style patterns and may be repeated.

Supported languages

Adding a language requires implementing a ~100-line parser in src/hybrid_coco/parsers/.

Design decisions

SQLite + FTS5, not a vector database: deterministic results, zero infrastructure, single file. Trigram search covers partial matches and is fast enough for codebases up to ~100K files. Semantic (embedding) search can be layered on top via sqlite-vec without changing the schema.

tree-sitter, not regex: symbol extraction is grammar-aware. Signatures and docstrings are extracted structurally, not by pattern matching.

No server process: hc serve runs as a stdio MCP server launched on demand by Claude Code. There is no daemon to manage.

Incremental by default: hc update re-indexes only files whose SHA-256 has changed. Full re-index is only needed on first run or after .gitignore changes.

Using with gtk-ai

hybrid-coco and gtk-ai are independent tools that work well together:

• hybrid-coco: reduces tokens on code navigation (Read, Grep, file structure queries)
• gtk-ai: reduces tokens on command output (find, ls, git, grep and other Bash tools)

When used together, gtk-ai will by default compress all MCP tool output, including hc_* responses. To prevent that, add hc_ to GTK_MCP_PASSTHROUGH_PATTERNS in the gtk-ai hook script:

# ~/.claude/hooks/gtkai-post-tool-use.sh
export GTK_MCP_PASSTHROUGH_PATTERNS="hc_"

This tells gtk-ai to let hc_search, hc_symbol, hc_file_context, and hc_status responses through uncompressed. hybrid-coco already returns minimal output, so compressing it further would lose information.

Neither tool requires the other. Configure this only if you have both installed.

Relation to CocoIndex

hybrid-coco is inspired by CocoIndex but makes different trade-offs:

Development

git clone https://github.com/jmeiracorbal/hybrid-coco
cd hybrid-coco
uv sync
uv pip install -e .
hc --version

Run tests:

uv run pytest

Run the benchmark against any indexed project:

cd path/to/project && hc index .
python scripts/benchmark.py path/to/project