Beacon

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 · 20-query benchmark on a real codebase

Quick Start

1. Install Ollama (local embeddings, free)

brew install ollama
ollama serve &
ollama pull nomic-embed-text

2. Install the Beacon plugin

claude plugin marketplace add sagarmk/Claude-Code-Beacon-Plugin
claude plugin install beacon@claude-code-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

● ● ● ● ●    nomic-embed-text · Ollama (local)
● ● ● ● ●    768 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": "nomic-embed-text",
  "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, and identifier boosting — 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).

Embedding Models

Beacon runs on open-source models by default — no API keys, no cloud costs, fully local via Ollama.

To switch models, pull with Ollama and update your config:

ollama pull mxbai-embed-large

// .claude/beacon.json
{
  "embedding": {
    "model": "mxbai-embed-large",
    "dimensions": 1024,
    "query_prefix": ""
  }
}

Then run /reindex to rebuild with the new model.

Cloud Providers

For cloud-hosted embeddings, create .claude/beacon.json in your repo:

export OPENAI_API_KEY="sk-..."

{
  "embedding": {
    "api_base": "https://api.openai.com/v1",
    "model": "text-embedding-3-small",
    "api_key_env": "OPENAI_API_KEY",
    "dimensions": 1536,
    "batch_size": 100,
    "query_prefix": ""
  }
}

export VOYAGE_API_KEY="pa-..."

{
  "embedding": {
    "api_base": "https://api.voyageai.com/v1",
    "model": "voyage-code-3",
    "api_key_env": "VOYAGE_API_KEY",
    "dimensions": 1024,
    "batch_size": 50,
    "query_prefix": ""
  }
}

pip install litellm
litellm --model vertex_ai/text-embedding-004 --port 4000

{
  "embedding": {
    "api_base": "http://localhost:4000/v1",
    "model": "vertex_ai/text-embedding-004",
    "api_key_env": "LITELLM_API_KEY",
    "dimensions": 1024,
    "batch_size": 50,
    "query_prefix": ""
  }
}

Any server implementing the OpenAI /v1/embeddings API will work. Set api_base, model, dimensions, and optionally api_key_env in .claude/beacon.json.

Commands

Beacon indexes your codebase automatically on session start and re-embeds files as you edit — no manual steps needed.

Search

Index

Config

Beacon also provides a code-explorer agent and a semantic-search skill that Claude can invoke automatically.

• Understands your questions — ask "where is the auth flow?" and get lib/auth.ts, not every file containing "auth"
• Query expansion — searches for "auth" automatically find code mentioning "authentication", "authorize", and "login"
• Stays in sync automatically — hooks handle full index, incremental re-embedding on edits, and garbage collection
• Resilient — retries with backoff on transient failures, auto-recovers from DB corruption, debounces GC
• Works with any embedding provider — Ollama (local/free), OpenAI, Voyage AI, LiteLLM, or any OpenAI-compatible API
• Gives Claude better context — slash commands, a code-explorer agent, and a grep-nudge hook for smarter search

Beacon uses Claude Code hooks to stay in sync with your codebase:

Default configuration (config/beacon.default.json):

{
  "embedding": {
    "api_base": "http://localhost:11434/v1",
    "model": "nomic-embed-text",
    "api_key_env": "",
    "dimensions": 768,
    "batch_size": 10,
    "query_prefix": "search_query: "
  },
  "chunking": {
    "strategy": "hybrid",
    "max_tokens": 512,
    "overlap_tokens": 50
  },
  "indexing": {
    "include": ["**/*.ts", "**/*.tsx", "**/*.js", "..."],
    "exclude": ["node_modules/**", "dist/**", "..."],
    "max_file_size_kb": 500,
    "auto_index": true,
    "max_files": 10000,
    "concurrency": 4
  },
  "search": {
    "top_k": 10,
    "similarity_threshold": 0.35,
    "hybrid": {
      "enabled": true,
      "weight_vector": 0.4,
      "weight_bm25": 0.3,
      "weight_rrf": 0.3,
      "doc_penalty": 0.5,
      "identifier_boost": 1.5,
      "debug": false
    }
  },
  "storage": {
    "path": ".claude/.beacon"
  }
}

Per-repo overrides

Create .claude/beacon.json in any repo to override defaults. Values are deep-merged with the default config:

{
  "embedding": {
    "api_base": "https://api.openai.com/v1",
    "model": "text-embedding-3-small",
    "api_key_env": "OPENAI_API_KEY",
    "dimensions": 1536
  },
  "indexing": {
    "include": ["**/*.py"],
    "max_files": 5000
  }
}

Storage

Beacon stores its SQLite database at .claude/.beacon/embeddings.db (configurable via storage.path). This file is auto-generated and safe to delete — run /reindex to rebuild. The database uses sqlite-vec for vector search and FTS5 for keyword matching.

What if Ollama is down?

Beacon degrades gracefully when the embedding server is unreachable — it never blocks your session. Embedding requests automatically retry with backoff (1s, 4s) before giving up.

Start Ollama at any time and run /run-indexer to catch up.

Manual indexing

Checking index health

Run /index for a visual overview with a coverage bar, file list, and provider info. For a quick numeric summary, use /index-status — it shows file count, chunk count, and last sync time.

Things to look for:

• Low coverage % — files may be excluded by glob patterns or exceeding max_file_size_kb
• Sync status errors — usually means the embedding server was unreachable during the last sync
• Stale sync warnings — the index hasn't been updated recently; run /run-indexer to refresh

Verifying search

Run /search-code with a test query to confirm search is working. If results include "FTS-only" in debug output, the embedding server is unreachable — search still works but without semantic matching (keyword/BM25 only).

Examples

See EXAMPLES.md for real-world use cases — intent-based search, codebase navigation, identifier tracking, and auto-sync — each with concrete before/after comparisons.

License

MIT