hybrid-coco

Local, self-contained code intelligence for AI agents. Index your codebase once, query it deterministically with the hc CLI and hc_* MCP tools — one install, no external services.

hybrid-coco ships everything in one component: SQLite storage, tree-sitter parsers, CLI, MCP server, host-native hooks, awareness, and agent skills. No embeddings, no vector database, no Docker, no companion tools.

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 native file-read / search tools (Read/Grep, or the host's equivalent) 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_*)
                                                           │
                                                    host-native hooks
                                                    intercept Read/Grep
                                                    (or host equivalent)
                                                    > 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 / snippet: queries the index and returns structure or bounded source slices — not whole files
3. hc serve: exposes the same queries as MCP tools (hc_search, hc_symbol, hc_file_context, hc_snippet, hc_structure, hc_status)
4. Hooks: hc init registers host-native hooks that suggest hc_* tools whenever the agent is about to read or search an indexed file (hc init --host cursor|codex|opencode|devin, or --host all)

Benchmark

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

Baseline = recursive search plus reading whole files. 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 the hc package (uv, pipx, or pip), Claude Code hooks, and the short global instruction gate (hc install-instructions --host claude). It does not run hc init. Other hosts: hc install-instructions --host cursor|codex|opencode|devin or --host all. Requires Python 3.11+.

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 an agent host

cd your-project/
hc init                 # Claude Code (default)
hc init --host cursor
hc init --host codex
hc init --host opencode
hc init --host devin
hc init --host all      # every supported host

hc init does five things:

• Indexes the current directory (tree-sitter, SHA-256 incremental)
• Registers the MCP server in the host project config
• Installs host-native hooks that intercept Read and Grep (or the host's equivalent)
• Installs host-adapted agent skills (hybrid-coco, hc-init, hc-search) — same names, host-specific MCP paths, native tools, and hook events
• Activates the project the same way mnemo does: writes .hybrid-coco/project.json (version, deterministic id, agents) and copies the full protocol to .hybrid-coco/hybrid-coco.md. It does not append to project AGENTS.md / CLAUDE.md, and it does not write user-global instruction files. The short conditional protocol is installed once by install.sh / hc install-instructions.

Restart the agent host to activate.

3. Use from the agent

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 → line range
hc_structure("function", lang=["rust"])  # tree-sitter shape search
hc_snippet("src/git.rs", 45, 67)  # bounded source slice from disk
hc_file_context("src/git.rs")  # all symbols in a file, structured
hc_status()                    # index stats

Invocable skills: /hc-init (setup/repair without full-reindex storms), /hc-search (choose the right hc_* query). The main hybrid-coco skill covers when to prefer hc_* over the host's native read/search tools.

The hooks will remind the agent (via the host's hook protocol) whenever it is about to read an indexed file directly.

Agent hosts

Skills keep the same names on every host (hybrid-coco, hc-init, hc-search) so /hc-init and /hc-search still work. The SKILL.md body is host-adapted: MCP path, native tools to avoid, and only the hook events that host actually fires. Hooks never invent events a host does not support.

Instruction files follow the same split as mnemo: install globally, activate per project.

# global (once — install.sh / hc install-instructions)
~/.claude/CLAUDE.md                         ← short <!-- hybrid-coco:start --> gate
~/.cursor/rules/hybrid-coco.mdc             ← alwaysApply: true, same gate
~/.codex/AGENTS.md
~/.config/opencode/AGENTS.md
~/.config/devin/AGENTS.md

# project (`hc init`)
project/
├── .hybrid-coco/hybrid-coco.md   ← full protocol (gitignored with the index)
└── .hybrid-coco/project.json     ← {version, id, agents} — like mnemo's `.mnemo`

The global text is conditional: if .hybrid-coco/project.json is missing, skip hybrid-coco entirely. If the file exists but id is missing, empty, not a UUID, or not the uuid5 derived from the absolute project path, the runtime rewrites id in place — it does not invent version or agents, and it does not create a marker from scratch. Hooks use the same gate. hc init does not write project AGENTS.md, CLAUDE.md, or .cursor/rules/hybrid-coco.mdc, and does not touch the global instruction files. Re-running hc install-instructions refreshes the managed block without duplicating it.

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 snippet <PATH> <START> <END>
                         Read PATH lines START..END from disk (1-based, inclusive)
hc structure <KIND> [--path P] [--lang L]...
                         Structural search: function | method | class | import
hc doctor [PATH]         Diagnostics: index, schema, languages, MCP/hooks, versions
hc reset [PATH] [-f] [--all]
                         Delete index DB; --all also drops project MCP entries
hc serve                 Start MCP server (stdio)
hc hook <HOST> <EVENT>   Host lifecycle hook (JSON stdin/stdout)
hc install-instructions [--host NAME]...
                         Short conditional protocol in user-global instruction files
                         --host: claude (default), cursor, codex, opencode, devin, all
hc init [PATH] [--host NAME]...
                         Index + marker + .gitignore + register MCP/hooks/skills
                         --host: claude (default), cursor, codex, opencode, devin, all
hc sync-skills [--check] Maintainer: sync Claude skill mirrors from assets/skills/
                         to skills/ and plugin/skills/ (--check verifies CI parity)

--exclude accepts gitignore-style patterns and may be repeated. They are combined with exclude in .hybrid-coco/config.toml. If that file is missing, hc init, hc index, hc update, and hc doctor write the default and continue.

Project settings

If .hybrid-coco/config.toml is missing, hybrid-coco creates it with empty lists and keeps going. Edit the file afterwards to restrict paths or override languages. An existing invalid file is not overwritten — that fails until you fix it.

include = []
exclude = []
languages = {}

Example with restrictions:

include = ["src/**"]
exclude = ["**/generated/**"]

[languages]
".pyx" = "python"
".h" = "cpp"

• include: gitignore-style patterns. Empty list = no include restriction. Non-empty = only matching paths are indexed.
• exclude: gitignore-style patterns, merged with hc index --exclude.
• languages: extension → parser language (python, rust, cpp, …). Overrides the built-in extension map.

hc reset deletes the index database and leaves config.toml in place. hc doctor writes the default file if it is missing, and fails if the existing file is invalid.

Supported languages

Adding a language: one LanguageSpec in src/hybrid_coco/languages/registry.py, a parser module under src/hybrid_coco/parsers/, and tests in tests/test_languages.py.

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 the agent host. 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.

Boundaries

hybrid-coco is a single local component:

• SQLite storage in the project workspace
• tree-sitter parsers for symbol extraction
• CLI (hc) for indexing and querying
• MCP server (hc_*) for Claude Code, Cursor, Codex, OpenCode, Devin, and other MCP hosts
• hooks, awareness, and skills shipped with the package (hc init --host)

It does not require companion services, external proxies, background daemons, or additional infrastructure.

Development

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

Run tests:

uv run pytest

Layout (maintainers)

After editing Claude skills in src/hybrid_coco/assets/skills/:

hc sync-skills          # refresh skills/ and plugin/skills/
hc sync-skills --check  # verify mirrors (same check as CI)

Host-adapted skills under assets/hosts/<host>/skills/ are installed by hc init only — no repo mirror.

Run the benchmark against any indexed project:

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