| name | semantic-search |
| description | Primary code search — hybrid semantic + keyword + BM25 matching. Automatically intercepted as default search when Beacon index is healthy. |
| allowed-tools | ["Bash","Read"] |
Hybrid Code Search (Beacon)
This repo has a Beacon hybrid search index combining semantic embeddings, BM25 keyword matching, and identifier boosting. Beacon is enforced as the default search — grep is automatically intercepted and redirected to Beacon for queries it handles better.
How to search
node ${CLAUDE_PLUGIN_ROOT}/scripts/search.js "<query>"
Options
--top-k N — number of results (default: 10)--threshold F — minimum score cutoff (default: 0.35)--no-hybrid — disable hybrid, use pure vector search only
Multi-query batch
node ${CLAUDE_PLUGIN_ROOT}/scripts/search.js "auth flow" "session handling" "token refresh"
Single HTTP round-trip for all queries. Returns grouped results.
Output
JSON array of matches, each with:
file — file pathlines — line range (e.g. "45-78")similarity — vector cosine similarityscore — final hybrid score (when hybrid enabled)preview — first 300 chars of matched chunk
Grep intercept behavior
Grep is denied and redirected to Beacon unless one of these conditions is met:
| Grep passes through when... | Example |
|---|
| Pattern has regex metacharacters | function\s+\w+ |
| Targets a specific file | path: "src/lib/db.js" |
output_mode is "count" | Counting occurrences |
| Pattern is <= 3 characters | fs, db |
| Dotted identifier | fs.readFileSync, path.join |
Path-like pattern (contains / or \) | src/components |
output_mode is "content" | Viewing matching lines |
| Quoted string literal | "use strict", 'Content-Type' |
| Annotation/marker pattern | TODO, FIXME, @param, #pragma |
| URL-like pattern | http://, localhost:3000 |
| Beacon index is unhealthy | DB missing, empty, dimension mismatch |
| Intercept disabled via config | intercept.enabled: false |
To disable interception entirely, set intercept.enabled: false in .claude/beacon.json.
Workflow
- Search with Beacon → get candidate files + line ranges with scores
- Read top 2-3 files at the indicated line ranges for full context
- If needed, grep within those files for specifics (imports, call sites)
- Answer the user with file:line citations
