Beacon for OpenCode

Semantic code search plugin for OpenCode — find code by meaning, not just strings.

Beacon indexes your codebase using embeddings and provides 15 powerful tools for semantic search, dependency analysis, code quality checks, and more.

Features

🔍 Core Search

• Semantic Search — Find code by meaning, not just keyword matching
• Hybrid Search — Vector + BM25 + identifier boosting for best recall
• Smart Context Injection — Auto-inject relevant code into context
• Query Expansion — Expand queries with synonyms (Turkish + English)
• Incremental Suggestions — Autocomplete for search queries

📊 Analysis

• File Relationship Graph — Who imports whom? Dependency tracking
• Change Impact Analysis — What breaks if I change this file?
• Pattern Search — Find API endpoints, DB queries, React components, etc.
• Code Smell Detection — Dead code, duplicates, complex functions
• Documentation Linking — Connect code to JSDoc, README, related docs

⏰ Advanced

• Temporal Search — Search within git history date ranges
• Multi-repo Search — Search across multiple repositories
• Semantic Diff — Compare files by meaning, not just syntax

Requirements

• OpenCode — Latest version
• Embedding API — One of:
  • Ollama (local, free) — nomic-embed-text-v2-moe or any Ollama embedding model
  • OpenAI — text-embedding-3-small or text-embedding-3-large
  • Any OpenAI-compatible API — Custom embedding endpoints

Ollama Setup (Local, Free)

# Install Ollama (if not installed)
curl -fsSL https://ollama.com/install.sh | sh

# Pull embedding model (768 dimensions, ~957 MB)
ollama pull nomic-embed-text-v2-moe

# Start Ollama service
sudo systemctl start ollama

OpenAI Setup

# Set your OpenAI API key
export OPENAI_API_KEY="sk-..."

Custom API Setup

Any OpenAI-compatible embedding API works. Just configure in global config (see below).

Installation

Option 1: NPM (Recommended)

# In your OpenCode project
npm install opencode-beacon

Then add to opencode.json:

{
  "plugin": ["opencode-beacon"]
}

Option 2: Local Plugin

# Clone to OpenCode plugins directory
git clone https://github.com/nixaut-codelabs/opencode-beacon.git ~/.config/opencode/plugins/beacon

# Install dependencies
cd ~/.config/opencode/plugins/beacon
npm install

Option 3: Manual

Copy plugin.ts and scripts/ to ~/.config/opencode/plugins/beacon/:

mkdir -p ~/.config/opencode/plugins/beacon
cp plugin.ts ~/.config/opencode/plugins/beacon/
cp -r scripts ~/.config/opencode/plugins/beacon/
cp package.json ~/.config/opencode/plugins/beacon/
cd ~/.config/opencode/plugins/beacon
npm install

Usage

Once installed, Beacon automatically indexes your codebase on session start. Use the 15 tools in OpenCode:

Search Tools

Tool	Description	Example
beacon_search	Semantic code search	"user authentication flow"
beacon_context	Smart context injection	"database connection setup"
beacon_expand	Query expansion	"giriş sistemi" → ["login", "auth"]
beacon_suggest	Autocomplete suggestions	"user ser" → ["userService", "user-service.ts"]

Analysis Tools

Tool	Description	Example
beacon_graph	File dependencies	file: "auth.ts", type: "dependents"
beacon_impact	Change impact analysis	file: "types.ts" → risk level
beacon_pattern	Pattern matching	pattern: "api-endpoint"
beacon_smell	Code smell detection	type: "dead_code"

Advanced Tools

Tool	Description	Example
beacon_temporal	Git history + search	query: "auth", since: "2024-01-01"
beacon_multi	Multi-repo search	query: "config", repos: "repo1,repo2"
beacon_diff	Semantic file comparison	file1: "a.ts", file2: "b.ts"
beacon_docs	Documentation linking	file: "auth.ts" → JSDoc, README

Utility Tools

Tool	Description
beacon_status	Health check
beacon_index	Index status
beacon_reindex	Force re-index

Configuration

Beacon uses a 3-tier config system: defaults → global → project (project wins).

Global Config (Recommended)

Platform-specific locations:

Platform	Path
Linux	~/.config/opencode/beacon.json
macOS	~/Library/Application Support/opencode/beacon.json
Windows	%APPDATA%/opencode/beacon.json

Example global config:

{
  "embedding": {
    "provider": "ollama",
    "api_base": "http://localhost:11434/v1",
    "model": "nomic-embed-text-v2-moe",
    "api_key_env": "",
    "dimensions": 768
  },
  "search": {
    "top_k": 10,
    "similarity_threshold": 0.25
  },
  "storage": {
    "path": ".opencode/.beacon"
  }
}

Project Config

Create .opencode/beacon.json in your project root to override global settings:

{
  "embedding": {
    "model": "text-embedding-3-small",
    "dimensions": 1536
  }
}

Embedding Providers

Ollama (Local, Free)

{
  "embedding": {
    "provider": "ollama",
    "api_base": "http://localhost:11434/v1",
    "model": "nomic-embed-text-v2-moe",
    "api_key_env": "",
    "dimensions": 768
  }
}

OpenAI

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

Set your API key: export OPENAI_API_KEY="sk-..."

Custom OpenAI-Compatible API

Any API that implements /v1/embeddings endpoint:

{
  "embedding": {
    "provider": "custom",
    "api_base": "https://your-api.com/v1",
    "model": "your-embedding-model",
    "api_key_env": "YOUR_API_KEY_ENV_VAR",
    "dimensions": 1024
  }
}

Slash Commands

Beacon adds these slash commands to OpenCode:

Command	Description
/beacon-search <query>	Semantic code search
/beacon-status	Show index status
/beacon-reindex	Force full re-index
/beacon-impact <file>	Analyze change impact
/beacon-smell	Detect code smells

Notifications

Beacon shows toast notifications when:

• Index is ready after session start
• Re-index completes
• Errors occur during sync

How It Works

1. Indexing — On session start, Beacon walks your codebase, chunks files, and generates embeddings via configured API
2. Storage — Embeddings stored in SQLite with sqlite-vec for fast vector search
3. Hybrid Search — Combines vector similarity, BM25 keyword matching, and identifier boosting
4. Incremental Updates — Only re-indexes changed files (tracked via git hash)
5. Auto-sync — Background sync on session start, incremental updates on file edits

Architecture

plugin.ts          → OpenCode plugin wrapper (15 tools)
scripts/
├── lib/
│   ├── db.js          → SQLite + sqlite-vec operations
│   ├── embedder.js    → OpenAI-compatible embedding API
│   ├── chunker.js     → Code chunking strategy
│   ├── graph.js       → Dependency graph builder
│   ├── patterns.js    → Code pattern definitions
│   ├── synonyms.js    → Query expansion (TR + EN)
│   └── ...
├── search.js          → Core semantic search
├── context.js         → Smart context injection
├── sync.js            → Full/diff-based indexing
└── ...

Performance

Metric	Value
Index speed	~100 files/sec (GPU), ~20 files/sec (CPU)
Search latency	<200ms (GPU), <500ms (CPU)
Memory usage	~50MB base, +1MB per 1000 chunks
Disk usage	~1MB per 1000 chunks

GPU Acceleration: If you have an AMD GPU with ROCm, Beacon automatically uses it for 5-10x faster embedding.

Examples

Find authentication code

User: "Where is the authentication logic?"
→ beacon_search(query="authentication logic")
→ Returns: auth.ts, middleware/auth-guard.ts, routes/login.ts

What breaks if I change types.ts?

User: "What files depend on types.ts?"
→ beacon_impact(file="types.ts")
→ Returns: 5 direct dependents, 12 transitive, risk: medium

Find all API endpoints

User: "Show me all API endpoints"
→ beacon_pattern(pattern="api-endpoint")
→ Returns: 23 endpoints across 8 files

Search recent changes

User: "What auth code changed this week?"
→ beacon_temporal(query="auth", since="2025-01-01")
→ Returns: 4 files changed in date range

Troubleshooting

"No index found"

Run beacon_reindex or restart OpenCode session.

"Ollama connection failed"

Ensure Ollama is running:

systemctl status ollama
sudo systemctl start ollama

Slow search

• Use GPU (ROCm) for 5-10x speedup
• Reduce search.top_k in config
• Increase search.similarity_threshold to filter more aggressively

Dimension mismatch

If you changed embedding models, run beacon_reindex to rebuild the index.

Contributing

Contributions welcome! Please:

1. Fork the repo
2. Create a feature branch
3. Test your changes
4. Submit a PR

Credits

• Original Beacon — sagarmk/beacon-plugin for Claude Code
• OpenCode Port — Community effort
• Ollama — Local embedding inference
• sqlite-vec — Vector search in SQLite

License

MIT © 2026 OpenCode Community

Original Beacon: MIT © 2026 Sagar MK