Beacon

Skill chris-peterson/beacon/skills/beacon

Label a session's project/task on the iTerm2 badge, and check the beacon CLI wrapper is current on first use per session.From its SKILL.md

Install

npx -y skills add chris-peterson/beacon --skill beacon

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

3.1 KB, 709 tokens by cl100k_base, as published. Nobody here has run it

beacon — labeling and CLI freshness backstop

beacon is a session-awareness tool that displays the current project, task, and status on the iTerm2 terminal. Hooks own status transitions; the shell owns project / branch resolution. Your job is to fill the gaps hooks cannot observe — nothing more.

Before first invocation in a session

Compare beacon --version against the plugin version in ${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json. If they differ, surface a one-line note and offer /beacon:beacon install to refresh the shell wrapper. If beacon isn't on PATH, skip silently.

Surface map — what each field paints

When the user asks you to label a session, pick the field by the surface they're pointing at:

Field	Surfaces
`project`	Badge text — leading chip (the per-pane label in iTerm2) and status-bar project chip
`task`	Badge text — `: <task>` suffix after project, and `beacon show`
`status`	Badge color (via `idle` / `working` / `waiting` / `paused`) — hooks own non-paused transitions; the user may set any value plus an optional description

The badge reads project: task when both are set, just project when task is absent. If the user says "label this session X" without distinguishing the project from the unit of work, set project — it's the leading, stable identifier. Reserve task for the specific work-in-progress within that project.

When to invoke beacon

Proactive task upkeep is governed by the keep-session-labeled ambient rule (emitted at SessionStart from rules/), not this skill: keep the session's task current as the work focus shifts so the fleet view has signal, defer to tack when a route is bound, and don't re-set it every turn. This skill covers the user-driven labeling below.

Badge labeling. When the user wants the badge to show a custom project label, run:

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/beacon" set project "<label>"

This overrides the git-derived project on the badge text via BADGE-12. To revert, run beacon clear project.

For the unit of work within the project (e.g. ai-sdlc: perms reads as project ai-sdlc, task perms), set the two fields separately:

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/beacon" set project "ai-sdlc"
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/beacon" set task "perms"

The plugin renders both on the badge (BADGE-03). Clear individually with beacon clear project / beacon clear task.

When NOT to invoke beacon

Do not set status (idle / working / waiting) — hooks own these transitions. The user may set status paused [<desc>] or status waiting [<desc>] themselves; you should not.
Do not re-label on every turn. Once is enough; let it persist.
Do not narrate beacon invocations to the user. Run the command silently.

What ships with it

Read from the repository

Just SKILL.md. No reference files, no scripts.