claude-beacon

claude-beacon

🇬🇧 English · 🇩🇪 Deutsch

A beacon for your Claude Code sessions. The entire terminal background turns green when Claude is waiting for you, red while Claude is working — visible at a glance, even in your peripheral vision.

Maintained by ARETI GmbH · MIT License

---

Installation

In any Claude Code session:

/plugin marketplace add ARETI-GmbH/claude-beacon
/plugin install claude-beacon@areti-claude-plugins
/reload-plugins

That's it. From now on every waiting session automatically turns green, every working session turns red. Zero config, zero dependencies.

---

The problem

Multiple parallel Claude Code sessions = you lose track. Which one is waiting for input? Which one is still running? Which one has a permission prompt open? Clicking through tabs is inefficient.

The solution

The entire terminal background signals the state:

State	Color	When
🟩 Idle (green)	#1a4d1a	Claude is waiting for your input
🟥 Active (red)	#4d1a1a	Claude is working (tool calls, streaming, …)

It works via OSC-11 escape sequences — a standard terminal API supported natively by macOS Terminal.app, iTerm2, Ghostty, Alacritty, WezTerm, and Kitty. No extensions, no window manager hacks, no background service in the default mode — just bash and standard escape codes.

---

Commands

The plugin registers two slash commands:

/terminal-color — pick the idle color

Changes the color displayed while Claude is waiting. Your choice is stored in ~/.config/claude-beacon/color and survives plugin updates.

Interactive (open the picker):

/terminal-color

You get 6 presets plus a custom-hex option:

Symbol	Color	Hex
🟢	Green (default)	#1a4d1a
🔴	Red	#4d1a1a
🔵	Blue	#1a1a4d
🟡	Olive yellow	#4d4d1a
🟣	Purple	#3d1a4d
🟠	Orange	#4d2e1a
✏️	Custom hex	your choice

Direct (skip the picker):

/terminal-color blue
/terminal-color #2d4a8a

/beacon-focus — toggle focus mode

Focus mode for parallel sessions: unfocused windows glow dimmed, the clicked window glows in the full color and gets a ● Claude marker in its window title. You see at a glance which session you're currently in — without losing sight of the waiting ones.

/beacon-focus on       # enable
/beacon-focus off      # disable
/beacon-focus status   # show current state

⚠️ macOS permission required: Focus mode needs to detect which Terminal.app window is frontmost. On first start, macOS asks once for automation permission for Terminal.app (Apple Events via osascript). Click "Allow". The regular beacon mode works without any permission — focus mode is opt-in.

---

The four states in focus mode

With /beacon-focus on enabled you get four visually distinct states per session:

	Focused (clicked)	Unfocused
Idle (waiting)	bright green #1a4d1a	dim green #113211
Active (working)	bright red #4d1a1a	dim red #321111

The focused window additionally gets the ● Claude title marker.

Fine-tuning via env vars

• CLAUDE_BEACON_DIM_FACTOR — brightness of the dimmed variant (default 0.65, range 0.0–1.0)
• CLAUDE_BEACON_TITLE_MARKER — text of the title marker (default ● Claude)
• CLAUDE_BEACON_POLL — daemon poll interval in seconds (default 0.6)

The focus daemon is a lightweight background process (~600ms poll) that exits automatically once no Claude sessions are registered anymore.

---

How it works under the hood

The plugin registers hooks on six Claude Code events. idle.sh sends the green OSC-11 sequence; active.sh sends the red one.

Hook event	When	Color
Notification	Claude needs attention (permission prompt, idle warning)	🟩 green
Stop	Claude is done → waiting for user	🟩 green
StopFailure	Claude stopped with an error	🟩 green
PreToolUse	Claude is calling a tool (= working)	🟥 red
UserPromptSubmit	User just submitted input	🟥 red
SessionStart	New session starting	🟥 red

Why no SubagentStop?

SubagentStop fires when a subagent (Explore, code-reviewer, …) finishes — even if the main agent is still working. If we switched to green there, the screen would be wrongly colored while Claude keeps running tools.

Instead, PreToolUse acts as a continuous heartbeat: as long as Claude keeps calling any tool, red is held. Only when nothing happens at all (Stop / Notification) does the color switch back to green.

---

Testing terminal compatibility

To check whether your terminal supports OSC-11:

printf '\033]11;#1a4d1a\007'   # set green
printf '\033]111\007'           # reset to default

Should work in all modern terminals (see list above).

---

Updating