Borrowing it
Nothing to install: this file belongs to chris-peterson/beacon. Take a copy, put it at the same path in your own repository, and replace the rules that are about this project with yours.
curl -O https://raw.githubusercontent.com/chris-peterson/beacon/main/AGENTS.mdgit clone --depth 1 https://github.com/chris-peterson/beaconWrote 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/instructions/chris-peterson/beacon/agents-md)<a href="https://agentmods.dev/instructions/chris-peterson/beacon/agents-md"><img src="https://agentmods.dev/badge/instructions/chris-peterson/beacon/agents-md/github.svg" alt="Measured on agentmods" height="20"></a>Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.
<a href="https://agentmods.dev/instructions/chris-peterson/beacon/agents-md"><img src="https://agentmods.dev/badge/instructions/chris-peterson/beacon/agents-md.svg" alt="Reviewed on agentmods" width="80" 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.03659 | $0.03659 |
| Opus 5.5 | $0.01464 | $0.01464 |
| Sonnet 5.5 | $0.00732 | $0.00732 |
| Haiku 4.5 | $0.00366 | $0.00366 |
Grade A, and why
beacon AGENTS.md 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 2d 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 — 157 lines — stays where its author put it; the contents beside it link to each section on GitHub.
beacon
Notes for AI coding agents working on beacon. What beacon does, requirement by requirement, is SPEC.md (published to the docs site as /spec); user-facing docs are README.md. This file holds what the spec doesn't: the boundaries, hot paths, and traps that shape the code. Cite a requirement id (STATUSLINE-03) rather than restating it here. When the spec and the code disagree, ask; don't silently choose one.
What beacon is
A Claude Code plugin, a sourceable zsh snippet, and a standalone CLI that surface session state two ways: a terminal-agnostic sessions view (wip / watch / serve) that reads across all sessions, and an iTerm2 render adapter that paints each pane. Both read the same per-session state files, the single source of record; neither inverts that into a daemon. See SPEC §1–2.
Three deliverables, hard boundaries
| Deliverable | Path | Owns |
|---|---|---|
| CLI | bin/beacon-iterm |
Translating subcommands to iTerm2 control operations: OSC sequences for painted surfaces, Apple Events (focus to raise a window, set-name to set the window title). Stateless. No Claude awareness. |
| Plugin | scripts/beacon, hooks/, commands/, rules/ |
Hook handlers, COR resolver for signals, slash command. rules/ holds ambient rules emitted at SessionStart by hooks/emit-rules.sh. Invokes the CLI for every iTerm2 write. |
| Shell | shell/beacon.zsh |
Project name / branch / cwd, refreshed every prompt. Emits its own SetUserVar OSC by raw printf; calls the CLI for set-name. Never goes through the plugin. |
The plugin and shell write to disjoint user-var slots so they never overwrite each other. Don't blur this boundary.
The CLI must remain unaware of Claude. It's usable from CI, ad-hoc terminal scripts, or future drivers (a tmux variant). Don't import plugin state into it.
Hot paths: keep fast
apply()inscripts/beaconruns on every Claude Code hook. Diff against the resolved-state snapshot before invoking the CLI._refresh_branch_chips_if_gitruns on every PostToolUse and is a gate before it is a publisher. The branch slots alone (three local git reads) are what a mid-turn push can afford;_publish_chipswholesale cannot, because it callsresolve_url(git, possiblygh/glab) and_tack_route_urls(atack treesubprocess). Keep the gate on the git subcommand: the bare wordgitwould fire on thestatus/log/diffcalls that are most of a session (HOOK-08c)._beacon_precmdinshell/beacon.zshruns on every prompt redraw and spawns no process of its own. Last-value sentinels gate every emit, onegit for-each-refyields every branch value, the origin URL is memoized per project root, and the helpers answer through_beacon_reply/_beacon_binfobecause each$(...)is a fork.- The shell emits every OSC by raw
printfto/dev/tty, with_beacon_b64as a zsh-native base64, so it costs no fork. Stdout would splice escape bytes intox=$(cd somedir; …), because zsh fireschpwdandprecmdinside command-substitution subshells._beacon_b64encodes to UTF-8 first (the branch display carries↑/↓) and pinsmultibyte/noksharraysfor its own scope, as_beacon_branch_infoand_beacon_precmdpin the options their array indexing assumes. Theshell-initblock (CMD-27) is cached so a new terminal usually spawns no python. beacon statuslinerenders per prompt, so it reads state and nothing else: neverresolve_url, never a forge (STATUSLINE-01/02). Forge data reaches it throughrefresh-links, which runs detached and writesdeliverables.linksonly, so it can't race a hook over the entries.
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.
- 2d ago Changed · +11 tokens per session e4435e535369
- 10d ago Changed · -20 lines · -6,375 tokens per session scan B → A cd0a3b6bf38e
- 18d ago Changed · +298 tokens per session f6e7eb3a080e
- 20d ago Changed f4e86d899abe
- 23d ago Changed · +36 tokens per session df2f44e93a05
- 25d ago Changed · +65 tokens per session e29434d329be
- 27d ago Changed · +216 tokens per session 7529f2bddaae
- 1mo ago Changed · +2 tokens per session 69c27ec996cf
- 1mo ago Changed · +32 tokens per session 6e6ce855e948
- 1mo ago First seen · 177 lines · 9,374 tokens per session scan B 4a1da8fa4a92
beacon AGENTS.md is an instructions file published in the GitHub repository chris-peterson/beacon (1 stars, last pushed today), licensed MIT. It adds 3,659 tokens to every session, about $0.0146 per session on Opus 5.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-31.
Other instructions, from other repositories
vscode buildNext.instructions.md
Working notes and architecture documentation for the new esbuild-based build system in build/next. Use when making changes to the new build pipeline (transpile/bundle commands, NLS plugin, source-map handling, resource copying, or self-hosting watch tasks).
next.js AGENTS.md
AGENTS.md instructions for vercel/next.js, covering next.js development guide, codebase structure, monorepo overview, core package: packages/next and other important packages.
vscode oss-third-party-notices.instructions.md
Instructions for microsoft/vscode, covering vs code oss third-party-notices pipeline, architecture, pipeline flow in ci, cache eligibility and rollout and applying the notice (cutover).
langchain AGENTS.md
AGENTS.md instructions for langchain-ai/langchain, covering global development guidelines for the langchain monorepo, corridor security analysis, project architecture and context, monorepo structure and development tools & commands.
vscode copilot-instructions.md
Copilot instructions for microsoft/vscode, covering vs code copilot instructions, project overview, root folders, core architecture (src/ folder) and built-in extensions (extensions/ folder).
deno copilot-instructions.md
Copilot instructions for denoland/deno, covering deno development guide for github copilot, network access, high level overview, key directories and key files to understand first.