agentlights

Color your Claude Code terminal pane when Claude is waiting on you.

If you run multiple Claude Code sessions in split terminal panes and lose track of which pane is idle and waiting on input, agentlights gives each pane a subtle background tint the moment its Claude finishes a turn — so you can tell at a glance which pane needs you. It's a tiny shell script wired into Claude Code's hooks; no daemon, no plugin, no IPC.

Install

npx agentlights init

That's it. This wires three Claude Code hooks (Stop, UserPromptSubmit, SessionEnd) and installs a small shell script at ~/.claude/agentlights/colorize.sh. Existing hooks in your ~/.claude/settings.json are preserved — agentlights appends, never overwrites.

Verify

npx agentlights test

Your pane background should turn a subtle indigo for 3 seconds, then return to default. If it does, you're set.

Customize the color

export AGENTLIGHTS_WAITING_COLOR=#3a2a40

Any hex color works. Add it to your shell rc to make it permanent.

Uninstall

npx agentlights uninstall

Removes only the hooks and files agentlights added.

How it works

Claude Code's Stop hook fires when Claude finishes a turn. agentlights' hook script writes an OSC 11 escape sequence (a standard ANSI control code) to the pane's terminal, which tells Ghostty (and most modern terminals) to repaint the background. UserPromptSubmit and SessionEnd hooks emit OSC 111 to reset.

Claude Code runs hooks in a detached session with no controlling terminal, so /dev/tty isn't available. The hook script therefore resolves the pane's real terminal device by walking up the process tree to the claude process that owns it, then writes the escape there. Each terminal pane is independently signaled because each hook's ancestor is its own per-pane claude process. No daemon, no IPC, no Ghostty plugin.

Compatibility

agentlights uses OSC 11 / OSC 111, which most modern terminals support.

| Terminal | Status | |---|---| | Ghostty | Verified | | iTerm2 | Likely works — verification needed | | kitty | Likely works — verification needed | | WezTerm | Likely works — verification needed | | Alacritty | Likely works — verification needed |

If npx agentlights test works in a terminal not yet marked Verified, please open an issue so the table can be updated. PRs welcome.

Troubleshooting

npx agentlights doctor

Verifies the script is present, executable, and up to date, that the hooks are wired, and prints your configured color. If you upgraded from an older version, run npx agentlights init again to refresh the installed script.

If your pane isn't being colored inside a terminal multiplexer (tmux, screen) or another unusual setup, you can point the hook at a specific terminal device explicitly:

export AGENTLIGHTS_TTY=$(tty)

License

MIT