Claude Code Terminal Signals
fguinez/claude-code-terminal-signals
Glifos e cores visuais para identificar sessões Claude Code bloqueadas
Ver no GitHubHook que adiciona sinais visuais em abas do terminal para sessões Claude Code. Exibe glifos de atenção (✦ pergunta, ✿ permissão) quando Claude aguarda sua ação, além de cores únicas por sessão para diferenciar múltiplas abas instantaneamente.
Instalação
npx convez-ai fguinez/claude-code-terminal-signals1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Gerenciar múltiplas sessões Claude Code em paralelo
- Identificar rapidamente quais sessões aguardam sua resposta
- Distinguir visualmente diferentes sessões por cor única
- Melhorar produtividade ao reduzir tempo de busca entre abas
Veredito

Solução prática e minimalista que resolve um problema real de UX em fluxos com múltiplas sessões Claude Code simultâneas. Implementação limpa via hooks, mas requer zsh para feature completa e está vinculada ao ecossistema Claude Code específico.
README
A tradução para o português deste README ainda está na fila.
claude-code-terminal-signals
Tell your Claude Code sessions apart at a glance — straight from the terminal tab bar.
Two small, independent features:
- Attention glyphs — when a session is waiting on you, its tab gets a glyph prefix so you can spot it across a sea of tabs, alongside the conversation name (not the folder):
✦ <name>— Claude is asking a clarifying question (AskUserQuestion)✿ <name>— Claude is waiting for you to approve a tool/permission
- Unique bar color per session — every new interactive
claudesession opens with a different/color, so tabs are visually distinct at a glance.
Demo
Two sessions need you (✦, ✿) and two don't (⠋, ✳) — and each is a different color. You can tell which is which without opening any of them.
Mockup illustrating the states. To drop in a real recording, save a GIF/PNG to
docs/and point this![...]()at it.
Tab states at a glance
By default, Claude Code already labels the tab with the conversation's AI-generated title and animates a working/idle indicator — so you can tell sessions apart by what they're about, not just by folder. This repo extends that to the two states where Claude is blocked on you:
| Prefix | State | Source |
|---|---|---|
⠋ — moving braille dot (animated) | Working / generating | Claude Code (built-in) |
✳ | Finished — idle, waiting for your next message | Claude Code (built-in) |
✦ | Asking a clarifying question (AskUserQuestion) | this repo |
✿ | Waiting for you to approve a permission | this repo |
All four show alongside the conversation name. This repo only emits ✦ / ✿, via an OSC 0 title escape returned from a hook ({"terminalSequence":"]0;…"}). The working (moving dot) and finished (✳) indicators are Claude Code's built-in tab status, set through its own title mechanism (process-level / OSC 2) — a different path than the hook's, which is why they coexist. Those native glyphs aren't officially documented and may vary by version/terminal; they're listed here only so the full vocabulary lives in one place. The per-session color (feature 2) is independent of all of these.
Why
When you run several Claude Code sessions in split terminals/tabs, they all look the same and you can't tell which one is blocked on your input. Claude's native tab title shows the conversation name + a working spinner — but the moment a session asks a question or requests permission, there was no at-a-glance cue, and some title hooks would even fall back to showing the folder name. This fixes both: a clear glyph when a session needs you, with its real conversation name, plus a distinct color per session.
Requirements
- Claude Code (
claudeCLI). - python3 — used by the title hook (JSON parsing) and the installer.
- zsh — required only for the per-session color feature. The attention-glyph hooks are shell-agnostic.
- macOS or Linux. (The glyphs use OSC title escapes supported by iTerm2, Terminal.app, the VS Code integrated terminal, Warp, etc.)
Install
git clone https://github.com/fguinez/claude-code-terminal-signals.git
cd claude-code-terminal-signals
./install.sh
Then:
- Restart Claude Code (or start a new session) so the hooks load.
source ~/.zshrc(or open a new terminal) to enable per-session colors.
Options:
./install.sh --no-color # only the attention glyphs (hooks)
./install.sh --no-hooks # only the per-session color wrapper
./install.sh --dir PATH # custom install dir (default: ~/.claude/terminal-signals)
The installer is idempotent and non-destructive: it backs up settings.json before editing and only touches the hook entries it owns (anything referencing term-title.sh / term-perm.sh), so it won't disturb other hooks you have (e.g. peon-ping).
Manual install
If you'd rather wire it up yourself:
-
Copy
hooks/term-title.shandhooks/term-perm.shsomewhere (keep them together —term-perm.shcallsterm-title.shfrom its own directory). Make them executable. -
Add these entries to
~/.claude/settings.json(merge into existinghooks):{ "hooks": { "PreToolUse": [ { "matcher": "AskUserQuestion", "hooks": [{ "type": "command", "command": "sh \"/ABS/PATH/term-title.sh\" \"✦\"" }] } ], "PermissionRequest": [ { "hooks": [{ "type": "command", "command": "sh \"/ABS/PATH/term-perm.sh\"" }] } ] } } -
For colors, source the wrapper from
~/.zshrc:source "/ABS/PATH/shell/claude-session-color.zsh"
How it works
Attention glyphs
Claude Code lets a hook return a terminalSequence that it writes to the terminal. On the two events where Claude is blocked on you:
AskUserQuestion(PreToolUse) →term-title.shemits✦ <name>.PermissionRequest→term-perm.shpicks the glyph (✦for anAskUserQuestion,✿for a real permission prompt) and hands off toterm-title.sh.
<name> is resolved the same way Claude names the tab natively, in priority order:
- A manual
/rename(stored in~/.claude/sessions/<pid>.json). - The AI-generated conversation title (
{"type":"ai-title",...}entries in the session transcript), located viatranscript_pathor bysession_id. - The working directory's folder name (last-resort fallback).
This is the key fix over a naive title hook: questions/permissions show the conversation name, not the folder.
Unique bar color per session
shell/claude-session-color.zsh defines a claude() wrapper. On an interactive launch it:
- reaps lock dirs under
~/.claude/session-colors/whose owning PID is dead, - picks a random color with no live lock (palette:
red blue green yellow purple orange pink cyan), takes an atomicmkdirlock, - launches the real binary with
claude "/color <color>"(Claude auto-runs the slash command on startup), and releases the lock on exit.
It passes straight through (no color) when headless (-p/--print), when there's no TTY, or when you already gave your own prompt — so it never clobbers your input. If all 8 colors are taken, it repeats one at random.
Note:
/coloris in-memory only (Claude doesn't persist it to disk), so the color is reassigned on each launch. There's no--colorflag; the slash-command-on-startup trick is the supported path.
Uninstall
./uninstall.sh # remove hooks + color wrapper (keeps installed files)
./uninstall.sh --purge # also delete the install dir and color lock dir
Customizing
- Glyphs: edit the
✦/✿characters interm-perm.sh(and the"✦"argument in yoursettings.jsonPreToolUseentry). Any single grapheme works. - Color palette / count: edit the
colors=(...)array inclaude-session-color.zsh. Only the colors Claude's/coloraccepts are valid:red, blue, green, yellow, purple, orange, pink, cyan, default(magentais not valid). - Title length: the hook caps the name at 60 chars; tweak in
term-title.sh.
Compatibility notes
- The color wrapper is zsh-only. Bash users would need to port the
claude()function (the lock logic is portable; the array/glob syntax is zsh-specific). - Plays nicely alongside peon-ping (sounds + working/ready status). The installer front-loads its hook entries so the attention glyph wins over other title-writing hooks for those two events.
License
MIT — see LICENSE.