Beacon Plugin

Beacon

Turn Claude Code into Cursor. Semantic code search that understands your codebase — find code by meaning, not just string matching.

Quick Start · Usage · Models · Commands · Config · Examples

---

98.3% accuracy · 5x faster than grep Author's 20-query benchmark on one codebase. Numbers depend heavily on corpus and query style — measure on your own repo before relying on them. See Retrieval quality.

---

Quick Start

1. Install Ollama (local embeddings, free)

brew install ollama
ollama serve &
ollama pull qwen3-embedding:0.6b

2. Install the Beacon plugin

claude plugin marketplace add sagarmk/beacon-plugin
claude plugin install beacon@beacon-plugin

3. Start Claude Code

claude

That's it. On first session start, Beacon will:

1. Install npm dependencies automatically (native modules like better-sqlite3 — takes a few seconds)
2. Index your codebase in the background

No npm install, no manual setup. Just install and go.

Usage

After installing, Beacon indexes automatically on session start. Here's the essentials:

Force a full re-index

> /reindex

Deletes existing embeddings and rebuilds from scratch — useful after switching models or if the index gets stale.

Check index health

> /index

Beacon Index

● ● ● ● ●    qwen3-embedding:0.6b · Ollama (local)
● ● ● ● ●    1024 dims · 3.8 MB
● ● ● ● ●
● ● ● ● ●    Coverage: 100% (38/38 files)

              Indexed by extension
              ● .js  25 files
              ● .md  13 files

              Statistics
              Indexed files    38
              Total chunks     109
              Avg chunks/file  2.9
              Last sync        2 minutes ago

For a quick numeric summary:

> /index-status

{
  "files_indexed": 38,
  "total_chunks": 114,
  "last_sync": "2026-03-01T04:30:21.453Z",
  "embedding_model": "qwen3-embedding:0.6b",
  "embedding_endpoint": "http://localhost:11434/v1"
}

Search your codebase

> /search-code "authentication flow"

[
  {
    "file": "src/middleware/auth.ts",
    "lines": "12-45",
    "similarity": "0.82",
    "score": "0.74",
    "preview": "export async function verifyAuth(req, res, next) {\n  const token = req.headers.authorization?.split(' ')[1];\n  ..."
  },
  {
    "file": "src/routes/login.ts",
    "lines": "8-32",
    "similarity": "0.78",
    "score": "0.65",
    "preview": "router.post('/login', async (req, res) => {\n  const { email, password } = req.body;\n  ..."
  }
]

Hybrid search combines semantic similarity (understands meaning), BM25 keyword matching, identifier boosting, and a symbol reference graph — so searching "auth flow" finds code about authentication even if it never uses the word "auth".

Options: --top-k N (results count), --threshold F (min score), --path <dir> (scope to directory), --no-hybrid (pure vector search).

---

Tools Claude uses

Beacon ships an MCP server, so Claude picks the right tool for the question instead of grepping and hoping. Three of these never run the embedding model at all — they are indexed lookups over the symbol tables.