beacon

name	beacon
description	Label a session's project/task on the iTerm2 badge, and check the beacon CLI wrapper is current on first use per session.
disable-model-invocation	true

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.