opencode-hybrid-search

Fast hybrid code search for OpenCode. Combines local ripgrep with SQLite FTS indexing for efficient searching in large worktree-based repositories.

Quick Start

# Install the plugin
npm install opencode-hybrid-search

# Add to your OpenCode configuration
echo '{
  "plugin": ["opencode-hybrid-search"]
}' > opencode.json

# Install global Git hooks for automatic indexing
npx opencode-hybrid-search-install-hooks

Prerequisite: ripgrep (rg) must be installed and available on your PATH.

How It Works

Searching large repositories is expensive. This plugin exploits an asymmetry: most files in a worktree are identical to the default branch, while only a small subset changed.

Hybrid search strategy:

1. Index default-branch commits ahead of time (via Git hooks)
2. When searching from a worktree, detect if the branch is ahead of the default branch
3. Search only changed files locally with rg
4. Search unchanged files from the SQLite FTS index
5. Merge results into one grep-like response

This gives you most of the correctness of local grep with much lower cost on large repos.

Configuration

Add to your opencode.json:

{
  "plugin": ["opencode-hybrid-search"]
}

The plugin exposes a hybrid_grep tool that OpenCode will use automatically for file searches.

Git Hooks (Required for Indexing)

Install global hooks to keep the index fresh:

npx opencode-hybrid-search-install-hooks

This sets up hooks for post-checkout, post-merge, and post-rewrite events to automatically refresh the index.

⚠️ Important: This changes your global Git core.hooksPath. The installer will not overwrite an existing hooks directory.

Manual Refresh

If you prefer not to use global hooks, refresh manually:

npx opencode-hybrid-search-refresh --cwd /path/to/repo

Features

• Hybrid search: Local rg for changed files + SQLite FTS for unchanged files
• Worktree-aware: Shared index across worktrees for the same repo
• Transactional: Safe concurrent access (one writer, many readers)
• Fallback modes: Automatically falls back to local grep when hybrid search would be unsafe
• Regex verification: All indexed candidates are verified with the requested regex before returning
• Structured logging: Detailed metrics for search planning and execution

Storage

• Index stored outside repos in user cache directory
• One SQLite file per git repository (shared across worktrees)
• Only commits in ready state are used for queries

Limitations

• Some regex patterns intentionally force fallback to local grep to avoid false negatives
• Default-branch detection uses heuristics for unusual remote states
• Hook-driven indexing runs in-process; very large repos may need a future background service

Development

# Install dependencies
bun install

# Run tests
bun test

# Type check
bun run typecheck

# Build
bun run build

License

MIT