\n Turn OpenCode into Beacon-style semantic search.
\n Semantic code search that understands your codebase — find code by meaning, not just string matching.\n
\n Quick Start · Usage · Models · Commands · Config\n
\n\n---\n\nThis project is an OpenCode port/adaptation of the original Beacon plugin by `sagarmk`.\n\n- Original project: `https://github.com/sagarmk/beacon-plugin`\n- Original local source: `beacon-plugin/`\n- OpenCode migration target: `open-beacon-plugin/`\n\nLicensed under the MIT License. See `LICENSE`.\n\nThe README structure and product language here intentionally follow the original Beacon README closely, with the integration details rewritten for OpenCode.\n\n---\n\n## Quick Start\n\n### 1. Install Ollama (local embeddings, free)\n\n```bash\nbrew install ollama\nollama serve &\nollama pull nomic-embed-text\n```\n\n### 2. Configure the OpenCode plugin\n\nYou can enable the plugin in either place:\n\n- global: `~/.config/opencode/opencode.json` for all projects\n- project-local: `opencode.json` in the repo root for one project only\n\nAdd the plugin entry to whichever config you want to use:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"plugin\": [\"@bluepaun/open-beacon-plugin\"]\n}\n```\n\nOpenCode installs npm plugins automatically with Bun at startup.\n\n### 3. Add Open Beacon config\n\nOpen Beacon has its own config file separate from `opencode.json`:\n\n- global: `~/.config/opencode/open-beacon.json` for shared defaults across projects\n- project-local: `.opencode/open-beacon.json` in the repo root for project-specific overrides\n\nRecommended setup:\n\nGlobal `~/.config/opencode/open-beacon.json`\n\n```json\n{\n \"embedding\": {\n \"api_base\": \"http://localhost:11434/v1\",\n \"model\": \"nomic-embed-text\",\n \"api_key_env\": \"\",\n \"dimensions\": 768,\n \"batch_size\": 10,\n \"query_prefix\": \"search_query: \"\n }\n}\n```\n\nProject-local `.opencode/open-beacon.json`\n\n```json\n{\n \"storage\": {\n \"path\": \".opencode/.beacon\"\n }\n}\n```\n\nYou can use either file by itself, or both together. Project-local values override global ones.\n\n### 4. Start OpenCode\n\nThat is it. On session start, Open Beacon can:\n1. **Index your codebase** automatically in the background\n2. **Re-embed changed files** as you edit\n3. **Use hybrid search** across semantic similarity and keyword matching\n\n## Usage\n\nAfter installing, Open Beacon can index automatically on session start. Here are the essentials:\n\n### Force a full re-index\n\nUse the `beacon_reindex` tool.\n\nDeletes existing embeddings and rebuilds from scratch — useful after switching models or if the index gets stale.\n\n### Check index health\n\nUse the `beacon_index` tool.\n\nExample response shape:\n\n```json\n{\n \"index\": {\n \"files_indexed\": 38,\n \"total_chunks\": 109,\n \"eligible_files\": 38,\n \"coverage_percent\": 100,\n \"avg_chunks_per_file\": 2.9\n },\n \"sync\": {\n \"status\": \"idle\",\n \"last_sync\": \"2026-03-01T04:30:21.453Z\"\n },\n \"config\": {\n \"model\": \"nomic-embed-text\",\n \"provider\": \"ollama\"\n }\n}\n```\n\nFor a quick numeric summary, use `beacon_index_status`.\n\n```json\n{\n \"files_indexed\": 38,\n \"total_chunks\": 114,\n \"last_sync\": \"2026-03-01T04:30:21.453Z\",\n \"embedding_model\": \"nomic-embed-text\",\n \"embedding_endpoint\": \"http://localhost:11434/v1\"\n}\n```\n\n### Search your codebase\n\nUse `beacon_search` with a natural-language query:\n\n```text\nauthentication flow\n```\n\nTypical response:\n\n```json\n[\n {\n \"file\": \"src/middleware/auth.ts\",\n \"lines\": \"12-45\",\n \"similarity\": \"0.820\",\n \"score\": \"0.740\",\n \"preview\": \"export async function verifyAuth(req, res, next) { ... }\"\n },\n {\n \"file\": \"src/routes/login.ts\",\n \"lines\": \"8-32\",\n \"similarity\": \"0.780\",\n \"score\": \"0.650\",\n \"preview\": \"router.post('/login', async (req, res) => { ... }\"\n }\n]\n```\n\nHybrid search combines **semantic similarity**, **BM25 keyword matching**, and **identifier boosting** — so searching `auth flow` can still find code about authentication even if it never uses the word `auth`.\n\nOptions: `topK`, `threshold`, `path`, and `hybrid=false` for pure vector-style ranking.\n\n---\n\n## Embedding Models\n\nOpen Beacon runs on **open-source models by default** — no API keys, no cloud costs, fully local via [Ollama](https://ollama.com).\n\n| Model | Dims | Context | Speed | Best for |\n|-------|------|---------|-------|----------|\n| **nomic-embed-text** (default) | 768 | 8192 | Fast | General-purpose, great code search |\n| **mxbai-embed-large** | 1024 | 512 | Fast | Higher accuracy, larger vectors |\n| **snowflake-arctic-embed:l** | 1024 | 512 | Medium | Strong retrieval benchmarks |\n| **all-minilm** | 384 | 512 | Very fast | Lightweight, low resource usage |\n\nTo switch models, pull with Ollama and update your config:\n\n```bash\nollama pull mxbai-embed-large\n```\n\n```json\n// .opencode/open-beacon.json\n{\n \"embedding\": {\n \"model\": \"mxbai-embed-large\",\n \"dimensions\": 1024,\n \"query_prefix\": \"\"\n }\n}\n```\n\nThen run `beacon_reindex` to rebuild with the new model.\n\n### Cloud Providers\n\nFor cloud-hosted embeddings, create `.opencode/open-beacon.json` in your repo:\n\n