Claude Code Glow: This macOS Tool Tells You When Claude Is Waiting

The Problem It Solves

When you're working with Claude Code, you often switch between your editor and other applications. The moment Claude finishes a task or needs permission for something, you have to either keep checking back or get interrupted by notifications. Both options break your flow.

Claude Code Glow solves this with ambient awareness: a soft orange glow appears around your screen edges whenever Claude is waiting for you. It's peripheral vision signaling—no notifications, no dock bouncing, no context switch required.

How It Works

The tool consists of two parts:

1. Hammerspoon Spoon (ClaudeGlow.spoon) - A Lua script that draws transparent gradient rectangles around all connected displays
2. Claude Code hooks - Modified settings.json that triggers the glow at specific moments

When Claude Code hits a blocking event (finished turn, permission prompt, AskUserQuestion, MCP elicitation), it calls hammerspoon://claudeglowon. When you respond, it calls hammerspoon://claudeglowoff.

Installation (3 Minutes)

# Prerequisites
brew install --cask hammerspoon
brew install jq

# Install Claude Code Glow
git clone https://github.com/noahkirsch/Claude-Code-Glow
cd Claude-Code-Glow
./install.sh

# Restart Claude Code

The installer:

• Copies the Spoon to ~/.hammerspoon/Spoons/
• Adds loader lines to ~/.hammerspoon/init.lua
• Merges hook wiring into ~/.claude/settings.json (with backup)
• Reloads Hammerspoon

It's safe to re-run—already applied steps are skipped.

Smart Event Filtering

Not all Claude Code events should trigger the glow. The default configuration in hooks.json is already filtered to only events that actually require your input:

Wired events:

• AskUserQuestion (Claude needs clarification)
• PermissionPrompt (needs approval to proceed)
• FinishedTurn (ready for your next instruction)

Notable exclusions:

• Notification events like idle_prompt and auth_success (informational only)
• SubagentStop (subagent completion doesn't need reaction)

This prevents false positives where you'd see the glow for non-blocking notifications.

Customization Options

Edit ~/.hammerspoon/init.lua before the :start() call:

hs.loadSpoon("ClaudeGlow")

-- Change color (default: orange)
spoon.ClaudeGlow.color = { red = 0.2, green = 0.7, blue = 1.0 } -- cyan

-- Adjust thickness (default: 42)
spoon.ClaudeGlow.thickness = 60 -- wider band

-- Smoother gradient (default: 24 layers)
spoon.ClaudeGlow.layers = 32

spoon.ClaudeGlow:start()

Auto-Clear Behavior

The glow automatically clears when you focus any terminal window. The default configuration recognizes these bundle IDs:

spoon.ClaudeGlow.terminalBundleIDs = {
    ["com.apple.Terminal"] = true,
    ["com.googlecode.iterm2"] = true,
    ["com.mitchellh.ghostty"] = true,
    ["org.alacritty"] = true,
    ["dev.warp.Warp-Stable"] = true,
    ["net.kovidgoyal.kitty"] = true,
    ["com.github.wez.wezterm"] = true,
    ["co.zeit.hyper"] = true,
    ["org.tabby"] = true,
    ["com.micro"] = true
}

You can modify this list to add, remove, or replace terminal applications.

Why This Matters for Your Workflow

Traditional notification systems force you to:

1. Process the notification (cognitive load)
2. Decide whether to switch context
3. Actually switch if needed

Claude Code Glow eliminates steps 1 and 2. The peripheral signal lets you know Claude is ready, but you can finish your current thought before switching. The creator reports at least 30% efficiency gains from reduced context switching.

Uninstallation

cd Claude-Code-Glow
./uninstall.sh

This removes the Spoon, loader lines, and hook entries while preserving backups.

Limitations

• macOS only (requires Hammerspoon)
• Requires terminal focus to clear (not keyboard input)
• Won't help if you're not looking at your screen

For developers who frequently context-switch while Claude processes, this tool provides exactly the right amount of signaling without disruption.