Menu
Label a session's project/task on the iTerm2 badge, and check the beacon CLI wrapper is current on first use per session.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| 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 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.
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.
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.
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.
idle / working / waiting) — hooks own these transitions. The user may set status paused [<desc>] or status waiting [<desc>] themselves; you should not.