beaconlisted

# 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 iden