beacon — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited beacon (Plugin) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
At-a-glance awareness across concurrent Claude Code sessions — a terminal-agnostic fleet dashboard plus iTerm2 per-pane painting.
[Read the docs](https://chris-peterson.github.io/beacon/) for install, usage, and the full behavioral spec.
This README covers working on beacon. To install or use the released plugin, follow the docs site.
Working on beacon directly (no marketplace):
git clone https://github.com/chris-peterson/beacon ~/src/beacon
python3 ~/src/beacon/scripts/beacon installThis wires up the shell side just like /beacon:beacon install, but pointed at your clone. To get the plugin side (slash command, hooks, skill) loaded into Claude Code, use the marketplace install path — claude --plugin-dir may not register hooks reliably across versions.
The fleet dashboard (wip / watch / serve) needs only:
python3.The per-pane painting layer (badge, status bar, tab color; spec §4) additionally needs:
install detects iTerm.app and skips these steps when it's absent.The always-on serve service (beacon serve install) uses launchd on macOS, systemd user units on Linux.
| Path | What |
|---|---|
bin/beacon-iterm | Stateless CLI that translates subcommands to iTerm2 OSC sequences (D2) |
scripts/beacon | Plugin script — hook handlers, COR resolver, slash command, install (D3) |
shell/beacon.zsh | Sourceable zsh snippet — refreshes project / branch / cwd / URL on every prompt |
hooks/, commands/, skills/ | Claude Code plugin glue |
rules/ | Ambient rules emitted into context at SessionStart by hooks/emit-rules.sh |
dashboard/index.html | Self-contained reference fleet dashboard serve hosts at / |
iterm/profile.json.template | Beacon dynamic profile, including the status-bar layout |
docs/ | Docsify site sources; spec.md is the EARS-style behavioral spec (D1) |
just test # or:
python3 -m unittest discover -s tests -vThe suite is pure stdlib unittest — it loads scripts/beacon via importlib and mocks _cli and sys.platform, so the iTerm2 paint paths and the launchd/systemd/Windows branches are all exercised without a Mac. .github/workflows/test.yml runs it on an ubuntu / macos / windows × Python 3.9–3.13 matrix on every push and PR, which is what guards the cross-platform fallbacks (session-id seeding, watch polling) from regressing.
beacon ships as three deliverables with a hard boundary between them:
| ID | What | Form |
|---|---|---|
| D1 | Behavioral spec | docs/spec.md |
| D2 | beacon-iterm CLI | Stateless OSC-emitter executable |
| D3 | beacon Claude Code plugin | Hooks, slash command, skill, COR resolver, shell integration |
D3 invokes D2 for every iTerm2 surface change. D2 has no Claude awareness — it can be used from any caller, which keeps the seam clean for future render-target CLIs (beacon-tmux, beacon-kitty) or driver plugins.
The behavioral contract for hooks vs shell is documented in CLAUDE.md: the plugin owns status (and its optional description) and writes to its user-var slots; the shell owns project/branch/cwd/url and writes to disjoint slots; the CLI is unaware of either.
beacon wip / watch / serve (spec §3.8) are the terminal-agnostic fleet surface on D3 — they enumerate every session's state and render a snapshot (TTY, JSON, or localhost HTTP) for external dashboards rather than painting iTerm2, so they don't route through D2 and work in any terminal. beacon serve install keeps serve running under launchd/systemd. The per-session state-file directory is the single source of record: the iTerm2 paint and the fleet view both read it, and serve re-reads it per request, so they can't disagree.
MIT. See LICENSE.
~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.