Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx agentmods add skills/sagarmk/beacon-plugin/semantic-searchnpx skills add sagarmk/beacon-plugin --skill semantic-searchgit clone --depth 1 https://github.com/sagarmk/beacon-pluginWrote this? Show the measurements
A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.
[](https://agentmods.dev/skills/sagarmk/beacon-plugin/semantic-search)<a href="https://agentmods.dev/skills/sagarmk/beacon-plugin/semantic-search"><img src="https://agentmods.dev/badge/skills/sagarmk/beacon-plugin/semantic-search.svg" alt="Measured on agentmods" height="20"></a>What it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5.1 | $0.00032 | $0.00771 |
| Opus 5 | $0.00016 | $0.00385 |
| Sonnet 5 | $0.00006 | $0.00154 |
| Haiku 4.5 | $0.00003 | $0.00077 |
Grade A, and why
semantic-search scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 6d ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 80 lines — stays where its author put it; the contents beside it link to each section on GitHub.
Code Search (Beacon)
This repo has a Beacon index: semantic embeddings, BM25 keyword matching, and a symbol reference graph. Beacon exposes MCP tools you call directly — prefer them over shelling out.
Pick the tool by what you are actually asking
| You want | Use | Cost |
|---|---|---|
| Where a known symbol is defined | find_symbol(name) |
~0.01 ms, exact |
| Every call site of a symbol | find_references(name) |
~0.01 ms, exhaustive |
| A file's symbols / functions / structure, with line numbers | outline(file) |
~0.01 ms |
| Code matching a concept you can only describe | search_code(query) |
~200 ms, ranked |
| Literal text — regex, punctuation, exact case | Grep |
— |
The first three are indexed SQL lookups. If you already know the name, do not pay for a semantic search and get back a ranked top-10 for a question that has one exact answer.
find_references is exhaustive, search_code is a ranked sample. For
"what breaks if I change this", only find_references actually answers it.
search_code
search_code(query: "how are failed payments retried", top_k: 10, path: "src/billing/", mode: "hybrid")
mode: "hybrid"(default) — embeddings + BM25 + reference graphmode: "semantic"— embeddings onlymode: "lexical"— keyword only; no embedding model, much fasterpath— restrict to a repo-relative prefix
Results carry file, lines, score, and a preview. Read the file at those
line ranges for real context — the preview is a fragment, not the answer.
When Beacon cannot help
find_symbol returning nothing means the symbol is not indexed — it may live
in a dependency, be constructed dynamically, or differ in case. Fall back to
Grep. Grep is also the right tool for text inside strings and comments, which
the reference extractor deliberately strips.
If tools report an empty symbol graph, the index predates symbol extraction —
run /reindex.
Fallback CLI
If the MCP tools are unavailable:
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 6d ago First seen · 80 lines · 32 tokens per session scan A bdf00651a01d
semantic-search is a skill published in the GitHub repository sagarmk/beacon-plugin (43 stars, last pushed 16d ago), licensed MIT. It adds 32 tokens to every session and 771 once invoked, about $0.0002 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.
Other skills, from other repositories
vera
Code search over the current repository. Before reading files to answer "where is X", "how does Y work", "find Z", or "what calls W", run vera search " " or vera references first. Use vera grep for exact strings and regex, vera structural for definitions, routes, and env reads. Do not read multiple files hoping to…
cortex-distill
Distill raw session records into refined Notes and Projects. Use when the user says "提煉", "整理 raw", "distill", or "distill raw records".
cortex-broadcast
Propagate insights from a distilled Raw into related existing Notes/Projects pages through conversational per-page edits.
cortex-query
Search and retrieve content from the cortexes vault — the user's external memory. Use when the user explicitly asks to search or recall the vault ("查 cortex", "之前有記過", "cortex 裡有沒有", "check my notes", "what did I write about", /cortexes:query), or when the using-cortex skill routes a request here after one of its four…
cortex-takeoff
Create or resume a session takeoff baton — a curated, ephemeral, git-ignored hand-off note that lets the next Claude session continue a long-running task. A repo can hold several batons at once, one per work line (topic). Use when the user says "交接", "takeoff", "交棒", "context 快滿了交接給下個 session", "hand off to next…
cortex-evolve
Save knowledge to the cortex vault. Use when the user says "存到 cortex", "記一下", "save to cortex", "記到筆記", "cortex evolve", or when the session-suggest hook recommends saving content. Handles Notes and Projects.